Страницы справочника OS X

Эта страница руководства является частью версии 5.0 Инструментов XCode

Читать страницы руководства

GLFEEDBACKBUFFER(3G)                                                                    GLFEEDBACKBUFFER(3G)



NAME
       glFeedbackBuffer - controls feedback mode


C SPECIFICATION
       void glFeedbackBuffer( GLsizei size,
                              GLenum type,
                              GLfloat *buffer )


PARAMETERS
       size    Specifies the maximum number of values that can be written into buffer.

       type    Specifies  a  symbolic constant that describes the information that will be returned for each
               vertex.   GL_2D,  GL_3D,  GL_3D_COLOR,  GL_3D_COLOR_TEXTURE,  and   GL_4D_COLOR_TEXTURE   are
               accepted.

       buffer  Returns the feedback data.

DESCRIPTION
       The  glFeedbackBuffer  function controls feedback.  Feedback, like selection, is a GL mode.  The mode
       is selected by calling glRenderMode with GL_FEEDBACK.  When the GL is in feedback mode, no pixels are
       produced  by rasterization.  Instead, information about primitives that would have been rasterized is
       fed back to the application using the GL.

       glFeedbackBuffer has three arguments: buffer is a pointer to an array of floating-point  values  into
       which feedback information is placed.  size indicates the size of the array.  type is a symbolic con-stant constant
       stant describing the information that is fed back for each vertex.  glFeedbackBuffer must  be  issued
       before  feedback  mode  is  enabled  (by  calling  glRenderMode  with argument GL_FEEDBACK).  Setting
       GL_FEEDBACK without establishing the feedback buffer, or calling glFeedbackBuffer while the GL is  in
       feedback mode, is an error.

       When  glRenderMode  is  called while in feedback mode, it returns the number of entries placed in the
       feedback array, and resets the feedback array pointer  to  the  base  of  the  feedback  buffer.  The
       returned  value  never  exceeds  size.  If the feedback data required more room than was available in
       buffer, glRenderMode returns  a  negative  value.   To  take  the  GL  out  of  feedback  mode,  call
       glRenderMode with a parameter value other than GL_FEEDBACK.

       While in feedback mode, each primitive, bitmap, or pixel rectangle that would be rasterized generates
       a block of values that are copied into the feedback array.  If doing so would  cause  the  number  of
       entries  to  exceed  the maximum, the block is partially written so as to fill the array (if there is
       any room left at all), and an overflow flag is set.  Each block begins with  a  code  indicating  the
       primitive  type,  followed  by  values  that  describe  the primitive's vertices and associated data.
       Entries are also written for bitmaps and pixel rectangles.  Feedback occurs after polygon culling and
       glPolygonMode  interpretation  of  polygons  has  taken  place,  so  polygons that are culled are not
       returned in the feedback buffer.  It can also occur after polygons with more  than  three  edges  are
       broken up into triangles, if the GL implementation renders polygons by performing this decomposition.

       The  glPassThrough  command  can  be  used  to  insert  a  marker  into  the  feedback  buffer.   See
       glPassThrough.

       Following  is  the grammar for the blocks of values written into the feedback buffer.  Each primitive
       is indicated with a unique identifying value followed by some number of  vertices.   Polygon  entries
       include an integer value indicating how many vertices follow.  A vertex is fed back as some number of
       floating-point values, as determined by type.  Colors are fed back as four values in  RGBA  mode  and
       one value in color index mode.

              feedbackList <- feedbackItem feedbackList | feedbackItem

              feedbackItem <- point | lineSegment | polygon | bitmap | pixelRectangle | passThru

              point <- GL_POINT_TOKEN vertex

              lineSegment <- GL_LINE_TOKEN vertex vertex | GL_LINE_RESET_TOKEN vertex vertex

              polygon <- GL_POLYGON_TOKEN n polySpec

              polySpec <- polySpec vertex | vertex vertex vertex

              bitmap <- GL_BITMAP_TOKEN vertex

              pixelRectangle <- GL_DRAW_PIXEL_TOKEN vertex | GL_COPY_PIXEL_TOKEN vertex

              passThru <- GL_PASS_THROUGH_TOKEN value

              vertex <- 2d | 3d | 3dColor | 3dColorTexture | 4dColorTexture

              2d <- value value

              3d <- value value value

              3dColor  <- value value value color

              3dColorTexture <- value value value color tex

              4dColorTexture <- value value value value color tex

              color <- rgba | index

              rgba <- value value value value

              index <- value

              tex <- value value value value


       value is a floating-point number, and n is a floating-point integer giving the number of vertices in
       the polygon.  GL_POINT_TOKEN, GL_LINE_TOKEN, GL_LINE_RESET_TOKEN, GL_POLYGON_TOKEN, GL_BITMAP_TOKEN,
       GL_DRAW_PIXEL_TOKEN, GL_COPY_PIXEL_TOKEN and GL_PASS_THROUGH_TOKEN are symbolic floating-point con-
       stants.  GL_LINE_RESET_TOKEN is returned whenever the line stipple pattern is reset.  The data
       returned as a vertex depends on the feedback type.

       The following table gives the correspondence between type and the number of values per vertex.  k is
       1 in color index mode and 4 in RGBA mode.


        Type                   Coords      Color   Tex     Total # of Values
        GL_2D                 x, y                        2
        GL_3D                 x, y, z                     3
        GL_3D_COLOR           x, y, z     k               3+k
        GL_3D_COLOR_TEXTURE   x, y, z     k       4       7+k
        GL_4D_COLOR_TEXTURE   x, y, z, w  k       4       8+k


       Feedback vertex coordinates are in window coordinates, except w, which is in clip coordinates.  Feed-back Feedback
       back colors are lighted, if lighting is enabled.  Feedback texture coordinates are generated, if tex-ture texture
       ture coordinate generation is enabled.  They are always transformed by the texture matrix.

NOTES
       glFeedbackBuffer, when used in a display list, is not compiled into the display list but is executed
       immediately.

       When the GL_ARB_multitexture extension is supported, glFeedbackBuffer returns only the texture coor-dinates coordinates
       dinates of texture unit GL_TEXTURE0_ARB.

ERRORS
       GL_INVALID_ENUM is generated if type is not an accepted value.

       GL_INVALID_VALUE is generated if size is negative.

       GL_INVALID_OPERATION is generated if glFeedbackBuffer is called while the render mode is GL_FEEDBACK,
       or if glRenderMode is called with argument GL_FEEDBACK before glFeedbackBuffer is called at least
       once.

       GL_INVALID_OPERATION is generated if glFeedbackBuffer is executed between the execution of glBegin
       and the corresponding execution of glEnd.

ASSOCIATED GETS
       glGet with argument GL_RENDER_MODE
       glGet with argument GL_FEEDBACK_BUFFER_POINTER
       glGet with argument GL_FEEDBACK_BUFFER_SIZE
       glGet with argument GL_FEEDBACK_BUFFER_TYPE

SEE ALSO
       glBegin(3G), glLineStipple(3G), glPassThrough(3G), glPolygonMode(3G), glRenderMode(3G), glSelectBuffer(3G)




                                                                                        GLFEEDBACKBUFFER(3G)