glFeedbackBuffer(3gl)

1GLFEEDBACKBUFFER(3G)                                      GLFEEDBACKBUFFER(3G)
2
3
4

NAME

6       glFeedbackBuffer - controls feedback mode
7
8

C SPECIFICATION

10       void glFeedbackBuffer( GLsizei size,
11                              GLenum type,
12                              GLfloat *buffer )
13
14

PARAMETERS

16       size    Specifies the maximum number of values that can be written into
17               buffer.
18
19       type    Specifies a symbolic constant that  describes  the  information
20               that   will   be  returned  for  each  vertex.   GL_2D,  GL_3D,
21               GL_3D_COLOR, GL_3D_COLOR_TEXTURE, and  GL_4D_COLOR_TEXTURE  are
22               accepted.
23
24       buffer  Returns the feedback data.
25

DESCRIPTION

27       The glFeedbackBuffer function controls feedback.  Feedback, like selec‐
28       tion, is a GL mode.  The mode is selected by calling glRenderMode  with
29       GL_FEEDBACK.   When  the GL is in feedback mode, no pixels are produced
30       by rasterization.  Instead, information  about  primitives  that  would
31       have been rasterized is fed back to the application using the GL.
32
33       glFeedbackBuffer  has  three arguments: buffer is a pointer to an array
34       of floating-point values into which  feedback  information  is  placed.
35       size  indicates  the  size  of  the array.  type is a symbolic constant
36       describing  the  information  that  is  fed  back  for   each   vertex.
37       glFeedbackBuffer  must  be  issued  before feedback mode is enabled (by
38       calling glRenderMode with argument GL_FEEDBACK).   Setting  GL_FEEDBACK
39       without  establishing  the feedback buffer, or calling glFeedbackBuffer
40       while the GL is in feedback mode, is an error.
41
42       When glRenderMode is called while in feedback mode, it returns the num‐
43       ber  of  entries  placed in the feedback array, and resets the feedback
44       array pointer to the base of the feedback buffer.  The  returned  value
45       never  exceeds  size.  If the feedback data required more room than was
46       available in buffer, glRenderMode returns a negative  value.   To  take
47       the  GL  out of feedback mode, call glRenderMode with a parameter value
48       other than GL_FEEDBACK.
49
50       While in feedback mode, each primitive, bitmap, or pixel rectangle that
51       would  be  rasterized  generates a block of values that are copied into
52       the feedback array.  If doing so would cause the number of  entries  to
53       exceed  the  maximum,  the block is partially written so as to fill the
54       array (if there is any room left at all), and an overflow flag is  set.
55       Each  block  begins with a code indicating the primitive type, followed
56       by values that describe the primitive's vertices and  associated  data.
57       Entries  are  also  written for bitmaps and pixel rectangles.  Feedback
58       occurs after polygon culling and glPolygonMode interpretation of  poly‐
59       gons  has  taken place, so polygons that are culled are not returned in
60       the feedback buffer.  It can also occur after polygons with  more  than
61       three edges are broken up into triangles, if the GL implementation ren‐
62       ders polygons by performing this decomposition.
63
64       The glPassThrough command can be used to insert a marker into the feed‐
65       back buffer.  See glPassThrough.
66
67       Following  is  the  grammar  for  the blocks of values written into the
68       feedback buffer.  Each primitive is indicated with a unique identifying
69       value  followed by some number of vertices.  Polygon entries include an
70       integer value indicating how many vertices follow.   A  vertex  is  fed
71       back  as  some  number of floating-point values, as determined by type.
72       Colors are fed back as four values in RGBA mode and one value in  color
73       index mode.
74
75              feedbackList ← feedbackItem feedbackList | feedbackItem
76
77              feedbackItem ← point | lineSegment | polygon | bitmap | pixel‐
78              Rectangle | passThru
79
80              point ← GL_POINT_TOKEN vertex
81
82              lineSegment ← GL_LINE_TOKEN vertex vertex | GL_LINE_RESET_TOKEN
83              vertex vertex
84
85              polygon ← GL_POLYGON_TOKEN n polySpec
86
87              polySpec ← polySpec vertex | vertex vertex vertex
88
89              bitmap ← GL_BITMAP_TOKEN vertex
90
91              pixelRectangle ← GL_DRAW_PIXEL_TOKEN vertex |
92              GL_COPY_PIXEL_TOKEN vertex
93
94              passThru ← GL_PASS_THROUGH_TOKEN value
95
96              vertex ← 2d | 3d | 3dColor | 3dColorTexture | 4dColorTexture
97
98              2d ← value value
99
100              3d ← value value value
101
102              3dColor  ← value value value color
103
104              3dColorTexture ← value value value color tex
105
106              4dColorTexture ← value value value value color tex
107
108              color ← rgba | index
109
110              rgba ← value value value value
111
112              index ← value
113
114              tex ← value value value value
115
116
117       value is a floating-point number, and n is a floating-point integer
118       giving the number of vertices in the polygon.  GL_POINT_TOKEN,
119       GL_LINE_TOKEN, GL_LINE_RESET_TOKEN, GL_POLYGON_TOKEN, GL_BITMAP_TOKEN,
120       GL_DRAW_PIXEL_TOKEN, GL_COPY_PIXEL_TOKEN and GL_PASS_THROUGH_TOKEN are
121       symbolic floating-point constants.  GL_LINE_RESET_TOKEN is returned
122       whenever the line stipple pattern is reset.  The data returned as a
123       vertex depends on the feedback type.
124
125       The following table gives the correspondence between type and the num‐
126       ber of values per vertex.  k is 1 in color index mode and 4 in RGBA
127       mode.
128
129
130
131
132
133     ─────────────────────────────────────────────────────────────────────────────
134     Type                  Coordinates   Color   Texture   Total Number of Values
135     ─────────────────────────────────────────────────────────────────────────────
136     GL_2D                 x, y                                      2
137     GL_3D                 x, y, z                                   3
138     GL_3D_COLOR           x, y, z         k                        3+k
139     GL_3D_COLOR_TEXTURE   x, y, z,        k        4               7+k
140     GL_4D_COLOR_TEXTURE   x, y, z, w      k        4               8+k
141     ─────────────────────────────────────────────────────────────────────────────
142
143
144       Feedback vertex coordinates are in window coordinates, except w, which
145       is in clip coordinates.  Feedback colors are lighted, if lighting is
146       enabled.  Feedback texture coordinates are generated, if texture coor‐
147       dinate generation is enabled.  They are always transformed by the tex‐
148       ture matrix.
149

NOTES

151       glFeedbackBuffer, when used in a display list, is not compiled into the
152       display list but is executed immediately.
153
154       When the GL_ARB_multitexture extension is supported, glFeedbackBuffer
155       returns only the texture coordinates of texture unit GL_TEXTURE0_ARB.
156

ERRORS

158       GL_INVALID_ENUM is generated if type is not an accepted value.
159
160       GL_INVALID_VALUE is generated if size is negative.
161
162       GL_INVALID_OPERATION is generated if glFeedbackBuffer is called while
163       the render mode is GL_FEEDBACK, or if glRenderMode is called with argu‐
164       ment GL_FEEDBACK before glFeedbackBuffer is called at least once.
165
166       GL_INVALID_OPERATION is generated if glFeedbackBuffer is executed
167       between the execution of glBegin and the corresponding execution of
168       glEnd.
169

ASSOCIATED GETS

171       glGet with argument GL_RENDER_MODE
172       glGet with argument GL_FEEDBACK_BUFFER_POINTER
173       glGet with argument GL_FEEDBACK_BUFFER_SIZE
174       glGet with argument GL_FEEDBACK_BUFFER_TYPE
175