- establish a buffer for selection mode values



C SPECIFICATION


PARAMETERS

       _param1  Specifies the size of _param2.

       _param2  Returns the selection data.


DESCRIPTION

       glSelectBuffer  has two arguments: _param2 is a pointer to
       an array of unsigned integers, and _param1  indicates  the
       size  of  the array.  _param2 returns values from the name
       stack (see glInitNames, glLoadName, glPushName)  when  the
       rendering    mode   is   GL_SELECT   (see   glRenderMode).
       glSelectBuffer must be issued  before  selection  mode  is
       enabled,  and  it  must  not be issued while the rendering
       mode is GL_SELECT.

       A programmer can use selection to determine  which  primi-
       tives  are drawn into some region of a window.  The region
       is defined by the current modelview and perspective matri-
       ces.

       In  selection  mode,  no pixel fragments are produced from
       rasterization.  Instead, if a primitive or a raster  posi-
       tion intersects the clipping volume defined by the viewing
       frustum and the user-defined clipping planes, this  primi-
       tive  causes  a  selection  hit.   (With  polygons, no hit
       occurs if the polygon is culled.)  When a change  is  made
       to  the  name stack, or when glRenderMode is called, a hit
       record is copied to _param2  if  any  hits  have  occurred
       since   the   last   such  event  (name  stack  change  or
       glRenderMode call).  The hit record consists of the number
       of  names in the name stack at the time of the event, fol-
       lowed by the minimum and maximum depth values of all  ver-
       tices  that  hit since the previous event, followed by the
       name stack contents, bottom name first.

       Depth values (which are in the range [0,1]) are multiplied
       by 2^32 - 1, before being placed in the hit record.

       An  internal  index  into  _param2  is reset to 0 whenever
       selection mode is entered.  Each  time  a  hit  record  is
       copied  into _param2, the index is incremented to point to
       the cell just past the end of the block of  names  -  that
       is,  to  the  next  available  cell.  If the hit record is
       larger than the number of remaining locations in  _param2,
       as  much  data as can fit is copied, and the overflow flag
       is set.  If the name stack is empty when a hit  record  is
       copied,  that record consists of 0 followed by the minimum
       and maximum depth values.
       glBegin/glEnd primitives  and  calls  to  glRasterPos  can
       result in hits.


ERRORS

       GL_INVALID_VALUE is generated if _param1 is negative.

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

       GL_INVALID_OPERATION is  generated  if  glSelectBuffer  is
       executed  between  the execution of glBegin and the corre-
       sponding execution of glEnd.


ASSOCIATED GETS

       glGet with argument GL_NAME_STACK_DEPTH
       glGet with argument GL_SELECTION_BUFFER_SIZE
       glGetPointerv with argument GL_SELECTION_BUFFER_POINTER


SEE ALSO

       glFeedbackBuffer,  glInitNames,  glLoadName,   glPushName,
       glRenderMode



                                                                1