NAME

glSelectBuffer - establish a buffer for selection mode values

C SPECIFICATION

void ggllSSeelleeccttBBuuffffeerr( GLsizei _s_i_z_e,
                     GLuint _*_b_u_f_f_e_r )

PARAMETERS

_s_i_z_e
Specifies the size of _b_u_f_f_e_r.
_b_u_f_f_e_r
Returns the selection data.

DESCRIPTION

ggllSSeelleeccttBBuuffffeerr has two arguments: _b_u_f_f_e_r is a pointer to an array of unsigned integers, and _s_i_z_e indicates the size of the array. _b_u_f_f_e_r returns values from the name stack (see ggllIInniittNNaammeess, ggllLLooaaddNNaammee, ggllPPuusshhNNaammee) when the rendering mode is GGLL__SSEELLEECCTT (see ggllRReennddeerrMMooddee). ggllSSeelleeccttBBuuffffeerr must be issued before selection mode is enabled, and it must not be issued while the rendering mode is GGLL__SSEELLEECCTT.

A programmer can use selection to determine which primitives are drawn into some region of a window. The region is defined by the current modelview and perspective matrices.

In selection mode, no pixel fragments are produced from rasterization. Instead, if a primitive or a raster position intersects the clipping volume defined by the viewing frustum and the user-defined clipping planes, this primitive 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 ggllRReennddeerrMMooddee is called, a hit record is copied to _b_u_f_f_e_r if any hits have occurred since the last such event (name stack change or ggllRReennddeerrMMooddee call). The hit record consists of the number of names in the name stack at the time of the event, followed by the minimum and maximum depth values of all vertices 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 _b_u_f_f_e_r is reset to 0 whenever selection mode is entered. Each time a hit record is copied into _b_u_f_f_e_r, 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 _b_u_f_f_e_r, 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.

To exit selection mode, call ggllRReennddeerrMMooddee with an argument other than GGLL__SSEELLEECCTT. Whenever ggllRReennddeerrMMooddee is called while the render mode is GGLL__SSEELLEECCTT, it returns the number of hit records copied to _b_u_f_f_e_r, resets the overflow flag and the selection buffer pointer, and initializes the name stack to be empty. If the overflow bit was set when ggllRReennddeerrMMooddee was called, a negative hit record count is returned.

NOTES

The contents of _b_u_f_f_e_r is undefined until ggllRReennddeerrMMooddee is called with an argument other than GGLL__SSEELLEECCTT.

ggllBBeeggiinn/ggllEEnndd primitives and calls to ggllRRaasstteerrPPooss can result in hits.

ERRORS

GGLL__IINNVVAALLIIDD__VVAALLUUEE is generated if _s_i_z_e is negative.

GGLL__IINNVVAALLIIDD__OOPPEERRAATTIIOONN is generated if ggllSSeelleeccttBBuuffffeerr is called while the render mode is GGLL__SSEELLEECCTT, or if ggllRReennddeerrMMooddee is called with argument GGLL__SSEELLEECCTT before ggllSSeelleeccttBBuuffffeerr is called at least once.

GGLL__IINNVVAALLIIDD__OOPPEERRAATTIIOONN is generated if ggllSSeelleeccttBBuuffffeerr is executed between the execution of ggllBBeeggiinn and the corresponding execution of ggllEEnndd.

ASSOCIATED GETS

ggllGGeett with argument GGLL__NNAAMMEE__SSTTAACCKK__DDEEPPTTHH
ggllGGeett with argument GGLL__SSEELLEECCTTIIOONN__BBUUFFFFEERR__SSIIZZEE
ggllGGeettPPooiinntteerrvv with argument GGLL__SSEELLEECCTTIIOONN__BBUUFFFFEERR__PPOOIINNTTEERR

SEE ALSO

ggllFFeeeeddbbaacckkBBuuffffeerr((33GG)), ggllIInniittNNaammeess((33GG)), ggllLLooaaddNNaammee((33GG)), ggllPPuusshhNNaammee((33GG)), ggllRReennddeerrMMooddee((33GG))