Selection is used by a programmer to determine which primitives are drawn into some region of a window. The region is defined by the current model-view and perspective matrices.
Selection works by returning an array of integer-valued names. This array represents the current contents of the name stack. This stack is controlled with the commands
void InitNames ( void ) ;
void PopName ( void ) ;
void PushName ( uint name ) ;
void LoadName ( uint name ) ;
InitNames empties (clears) the name stack. PopName pops one name off the top of the name stack. PushName causes name to be pushed onto the name stack. LoadName replaces the value on the top of the stack with name. Loading a name onto an empty stack generates the error INVALID_OPERATION. Popping a name off of an empty stack generates STACK_UNDERFLOW; pushing a name onto a full stack generates STACK_OVERFLOW. The maximum allowable depth of the name stack is implementation dependent but must be at least 64.
In selection mode, no fragments are rendered into the framebuffer. The GL is placed in selection mode with
int RenderMode ( enum mode ) ;
mode is a symbolic constant: one of RENDER, SELECT, or FEEDBACK. RENDER is the default, corresponding to rendering as described until now. SELECT specifies selection mode, and FEEDBACK specifies feedback mode (described below). Use of any of the name stack manipulation commands while the GL is not in selection mode has no effect.
Selection is controlled using
void SelectBuffer ( sizei n, uint *buffer ) ;
*buffer is a pointer to an array of unsigned integers (called the selection array) to be potentially filled with names, and n is an integer indicating the maximum number of values that can be stored in that array. Placing the GL in selection mode before SelectBuffer has been called results in an error of INVALID_OPERATION as does calling SelectBuffer while in selection mode.
In selection mode, if a point, line, polygon, or the valid coordinates produced by a RasterPos command intersects the clip volume (section 2.11) then this primitive (or RasterPos command) causes a selection hit. In the case of polygons, no hit occurs if the polygon would have been culled, but selection is based on the polygon itself, regardless of the setting of PolygonMode . When in selection mode, whenever a name stack manipulation command is executed or RenderMode is called and there has been a hit since the last time the stack was manipulated or RenderMode was called, then a hit record is written into the selection array.
A hit record consists of the following items in order: a non-negative integer giving the number of elements on the name stack at the time of the hit, a minimum depth value, a maximum depth value, and the name stack with the bottommost element first. The minimum and maximum depth values are the minimum and maximum taken over all the window coordinate z values of each (post-clipping) vertex of each primitive that intersects the clipping volume since the last hit record was written. The minimum and maximum (each of which lies in the range ) are each multiplied by and rounded to the nearest unsigned integer to obtain the values that are placed in the hit record. No depth offset arithmetic (section 3.5.5) is performed on these values.
Hit records are placed in the selection array by maintaining a pointer into that array. When selection mode is entered, the pointer is initialized to the beginning of the array. Each time a hit record is copied, the pointer is updated to point at the array element after the one into which the topmost element of the name stack was stored. If copying the hit record into the selection array would cause the total number of values to exceed n, then as much of the record as fits in the array is written and an overflow flag is set.
Selection mode is exited by calling RenderMode with an argument value other than SELECT. Whenever RenderMode is called in selection mode, it returns the number of hit records copied into the selection array and resets the SelectBuffer pointer to its last specified value. Values are not guaranteed to be written into the selection array until RenderMode is called. If the selection array overflow flag was set, then RenderMode returns -1 and clears the overflow flag. The name stack is cleared and the stack pointer reset whenever RenderMode is called.
The state required for selection consists of the address of the selection array and its maximum size, the name stack and its associated pointer, a minimum and maximum depth value, and several flags. One flag indicates the current RenderMode value. In the initial state, the GL is in the RENDER mode. Another flag is used to indicate whether or not a hit has occurred since the last name stack manipulation. This flag is reset upon entering selection mode and whenever a name stack manipulation takes place. One final flag is required to indicate whether the maximum number of copied names would have been exceeded. This flag is reset upon entering selection mode. This flag, the address of the selection array, and its maximum size are GL client state.