[clinton/guile-figl.git] / upstream-doc / man2 / xhtml / glSelectBuffer.xml

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
<!-- saved from url=(0013)about:internet -->
<?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" pref:renderer="mathplayer-dl"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>glSelectBuffer</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="glSelectBuffer"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glSelectBuffer — establish a buffer for selection mode values</p></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">void <b class="fsfunc">glSelectBuffer</b>(</code></td><td>GLsizei  </td><td><var class="pdparam">size</var>, </td></tr><tr><td> </td><td>GLuint *  </td><td><var class="pdparam">buffer</var><code>)</code>;</td></tr></table></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="parameters"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>size</code></em></span></dt><dd><p>
                    Specifies the size of <em class="parameter"><code>buffer</code></em>.
                </p></dd><dt><span class="term"><em class="parameter"><code>buffer</code></em></span></dt><dd><p>
                    Returns the selection data.
                </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p>
            <code class="function">glSelectBuffer</code> has two arguments:
            <em class="parameter"><code>buffer</code></em> is a pointer to an array of unsigned integers,
            and <em class="parameter"><code>size</code></em> indicates the size of the array.
            <em class="parameter"><code>buffer</code></em> returns values from the name stack
            (see <a class="citerefentry" href="glInitNames.xml"><span class="citerefentry"><span class="refentrytitle">glInitNames</span></span></a>, <a class="citerefentry" href="glLoadName.xml"><span class="citerefentry"><span class="refentrytitle">glLoadName</span></span></a>, <a class="citerefentry" href="glPushName.xml"><span class="citerefentry"><span class="refentrytitle">glPushName</span></span></a>)
            when the rendering mode is <code class="constant">GL_SELECT</code> (see <a class="citerefentry" href="glRenderMode.xml"><span class="citerefentry"><span class="refentrytitle">glRenderMode</span></span></a>).
            <code class="function">glSelectBuffer</code> must be issued before selection mode is enabled,
            and it must not be issued while the rendering mode is <code class="constant">GL_SELECT</code>.
        </p><p>
            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.
        </p><p>
            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 <a class="citerefentry" href="glRenderMode.xml"><span class="citerefentry"><span class="refentrytitle">glRenderMode</span></span></a> is called,
            a hit record is copied to <em class="parameter"><code>buffer</code></em> if any hits have occurred since the
            last such event
            (name stack change or
            <a class="citerefentry" href="glRenderMode.xml"><span class="citerefentry"><span class="refentrytitle">glRenderMode</span></span></a> 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.
        </p><p>
            Depth values (which are in the range [0,1]) are multiplied by 
            <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
                
                <mml:mrow>
                    <mml:msup><mml:mn>2</mml:mn>
                    <mml:mn>32</mml:mn>
                    </mml:msup>
                    <mml:mo>-</mml:mo>
                    <mml:mn>1</mml:mn>
                </mml:mrow>
            </mml:math>,
            before being placed in the hit record.
        </p><p>
            An internal index into <em class="parameter"><code>buffer</code></em> is reset to 0 whenever selection mode
            is entered.
            Each time a hit record is copied into <em class="parameter"><code>buffer</code></em>,
            the index is incremented to point to the cell just past the end
            of the block of names\(emthat is, to the next available cell
            If the hit record is larger than the number of remaining locations in <em class="parameter"><code>buffer</code></em>,
            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.
        </p><p>
            To exit selection mode, call <a class="citerefentry" href="glRenderMode.xml"><span class="citerefentry"><span class="refentrytitle">glRenderMode</span></span></a> with an argument
            other than <code class="constant">GL_SELECT</code>.
            Whenever <a class="citerefentry" href="glRenderMode.xml"><span class="citerefentry"><span class="refentrytitle">glRenderMode</span></span></a> is called while the render mode is <code class="constant">GL_SELECT</code>,
            it returns the number of hit records copied to <em class="parameter"><code>buffer</code></em>,
            resets the overflow flag and the selection buffer pointer,
            and initializes the name stack to be empty.
            If the overflow bit was set when <a class="citerefentry" href="glRenderMode.xml"><span class="citerefentry"><span class="refentrytitle">glRenderMode</span></span></a> was called,
            a negative hit record count is returned.
        </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p>
            The contents of <em class="parameter"><code>buffer</code></em> is undefined until <a class="citerefentry" href="glRenderMode.xml"><span class="citerefentry"><span class="refentrytitle">glRenderMode</span></span></a> is called
            with an argument other than <code class="constant">GL_SELECT</code>.
        </p><p>
            <a class="citerefentry" href="glBegin.xml"><span class="citerefentry"><span class="refentrytitle">glBegin</span></span></a>/<a class="citerefentry" href="glEnd.xml"><span class="citerefentry"><span class="refentrytitle">glEnd</span></span></a> primitives and calls to <a class="citerefentry" href="glRasterPos.xml"><span class="citerefentry"><span class="refentrytitle">glRasterPos</span></span></a>
            can result in hits.  <a class="citerefentry" href="glWindowPos.xml"><span class="citerefentry"><span class="refentrytitle">glWindowPos</span></span></a> will always generate a selection hit.
        </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="errors"></a><h2>Errors</h2><p>
            <code class="constant">GL_INVALID_VALUE</code> is generated if <em class="parameter"><code>size</code></em> is negative.
        </p><p>
            <code class="constant">GL_INVALID_OPERATION</code> is generated if <code class="function">glSelectBuffer</code> is called while the
            render mode is <code class="constant">GL_SELECT</code>,
            or if <a class="citerefentry" href="glRenderMode.xml"><span class="citerefentry"><span class="refentrytitle">glRenderMode</span></span></a> is called with argument <code class="constant">GL_SELECT</code> before
            <code class="function">glSelectBuffer</code> is called at least once.
        </p><p>
            <code class="constant">GL_INVALID_OPERATION</code> is generated if <code class="function">glSelectBuffer</code>
            is executed between the execution of <a class="citerefentry" href="glBegin.xml"><span class="citerefentry"><span class="refentrytitle">glBegin</span></span></a>
            and the corresponding execution of <a class="citerefentry" href="glEnd.xml"><span class="citerefentry"><span class="refentrytitle">glEnd</span></span></a>.
        </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="associatedgets"></a><h2>Associated Gets</h2><p>
            <a class="citerefentry" href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_NAME_STACK_DEPTH</code>
        </p><p>
            <a class="citerefentry" href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_SELECTION_BUFFER_SIZE</code>
        </p><p>
            <a class="citerefentry" href="glGetPointerv.xml"><span class="citerefentry"><span class="refentrytitle">glGetPointerv</span></span></a> with argument <code class="constant">GL_SELECTION_BUFFER_POINTER</code>
        </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p>
            <a class="citerefentry" href="glFeedbackBuffer.xml"><span class="citerefentry"><span class="refentrytitle">glFeedbackBuffer</span></span></a>,
            <a class="citerefentry" href="glInitNames.xml"><span class="citerefentry"><span class="refentrytitle">glInitNames</span></span></a>,
            <a class="citerefentry" href="glLoadName.xml"><span class="citerefentry"><span class="refentrytitle">glLoadName</span></span></a>,
            <a class="citerefentry" href="glPushName.xml"><span class="citerefentry"><span class="refentrytitle">glPushName</span></span></a>,
            <a class="citerefentry" href="glRenderMode.xml"><span class="citerefentry"><span class="refentrytitle">glRenderMode</span></span></a>
        </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p>
            Copyright <span class="trademark"></span>© 1991-2006
            Silicon Graphics, Inc. This document is licensed under the SGI
            Free Software B License. For details, see
            <a class="ulink" href="http://oss.sgi.com/projects/FreeB/" target="_top">http://oss.sgi.com/projects/FreeB/</a>.
        </p></div></div></body></html>
Commit	Line	Data
7faf1d71 AW	1	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
	2	<!-- saved from url=(0013)about:internet -->
	3	<?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" pref:renderer="mathplayer-dl"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>glSelectBuffer</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="glSelectBuffer"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glSelectBuffer — establish a buffer for selection mode values</p></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">void <b class="fsfunc">glSelectBuffer</b>(</code></td><td>GLsizei </td><td><var class="pdparam">size</var>, </td></tr><tr><td> </td><td>GLuint * </td><td><var class="pdparam">buffer</var><code>)</code>;</td></tr></table></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="parameters"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>size</code></em></span></dt><dd><p>
	4	Specifies the size of <em class="parameter"><code>buffer</code></em>.
	5	</p></dd><dt><span class="term"><em class="parameter"><code>buffer</code></em></span></dt><dd><p>
	6	Returns the selection data.
	7	</p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p>
	8	<code class="function">glSelectBuffer</code> has two arguments:
	9	<em class="parameter"><code>buffer</code></em> is a pointer to an array of unsigned integers,
	10	and <em class="parameter"><code>size</code></em> indicates the size of the array.
	11	<em class="parameter"><code>buffer</code></em> returns values from the name stack
	12	(see <a class="citerefentry" href="glInitNames.xml"><span class="citerefentry"><span class="refentrytitle">glInitNames</span></span></a>, <a class="citerefentry" href="glLoadName.xml"><span class="citerefentry"><span class="refentrytitle">glLoadName</span></span></a>, <a class="citerefentry" href="glPushName.xml"><span class="citerefentry"><span class="refentrytitle">glPushName</span></span></a>)
	13	when the rendering mode is <code class="constant">GL_SELECT</code> (see <a class="citerefentry" href="glRenderMode.xml"><span class="citerefentry"><span class="refentrytitle">glRenderMode</span></span></a>).
	14	<code class="function">glSelectBuffer</code> must be issued before selection mode is enabled,
	15	and it must not be issued while the rendering mode is <code class="constant">GL_SELECT</code>.
	16	</p><p>
	17	A programmer can use selection to determine which primitives
	18	are drawn into some region of a window.
	19	The region is defined by the current modelview and perspective matrices.
	20	</p><p>
	21	In selection mode, no pixel fragments are produced from rasterization.
	22	Instead,
	23	if a primitive or a raster position intersects the clipping
	24	volume defined by the viewing frustum
	25	and the user-defined clipping planes,
	26	this primitive causes a selection hit.
	27	(With polygons, no hit occurs if the polygon is culled.)
	28	When a change is made to the name stack,
	29	or when <a class="citerefentry" href="glRenderMode.xml"><span class="citerefentry"><span class="refentrytitle">glRenderMode</span></span></a> is called,
	30	a hit record is copied to <em class="parameter"><code>buffer</code></em> if any hits have occurred since the
	31	last such event
	32	(name stack change or
	33	<a class="citerefentry" href="glRenderMode.xml"><span class="citerefentry"><span class="refentrytitle">glRenderMode</span></span></a> call).
	34	The hit record consists of the number of names in the name stack at the
	35	time of the event, followed by the minimum and maximum depth values
	36	of all vertices that hit since the previous event,
	37	followed by the name stack contents,
	38	bottom name first.
	39	</p><p>
	40	Depth values (which are in the range [0,1]) are multiplied by
	41	<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
	42
	43	<mml:mrow>
	44	<mml:msup><mml:mn>2</mml:mn>
	45	<mml:mn>32</mml:mn>
	46	</mml:msup>
	47	<mml:mo>-</mml:mo>
	48	<mml:mn>1</mml:mn>
	49	</mml:mrow>
	50	</mml:math>,
	51	before being placed in the hit record.
	52	</p><p>
	53	An internal index into <em class="parameter"><code>buffer</code></em> is reset to 0 whenever selection mode
	54	is entered.
	55	Each time a hit record is copied into <em class="parameter"><code>buffer</code></em>,
	56	the index is incremented to point to the cell just past the end
	57	of the block of names\(emthat is, to the next available cell
	58	If the hit record is larger than the number of remaining locations in <em class="parameter"><code>buffer</code></em>,
	59	as much data as can fit is copied,
	60	and the overflow flag is set.
	61	If the name stack is empty when a hit record is copied,
	62	that record consists of 0 followed by the minimum and maximum depth values.
	63	</p><p>
	64	To exit selection mode, call <a class="citerefentry" href="glRenderMode.xml"><span class="citerefentry"><span class="refentrytitle">glRenderMode</span></span></a> with an argument
65	other than <code class="constant">GL_SELECT</code>.
66	Whenever <a class="citerefentry" href="glRenderMode.xml"><span class="citerefentry"><span class="refentrytitle">glRenderMode</span></span></a> is called while the render mode is <code class="constant">GL_SELECT</code>,
67	it returns the number of hit records copied to <em class="parameter"><code>buffer</code></em>,
68	resets the overflow flag and the selection buffer pointer,
69	and initializes the name stack to be empty.
70	If the overflow bit was set when <a class="citerefentry" href="glRenderMode.xml"><span class="citerefentry"><span class="refentrytitle">glRenderMode</span></span></a> was called,
71	a negative hit record count is returned.
72	</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p>
73	The contents of <em class="parameter"><code>buffer</code></em> is undefined until <a class="citerefentry" href="glRenderMode.xml"><span class="citerefentry"><span class="refentrytitle">glRenderMode</span></span></a> is called
74	with an argument other than <code class="constant">GL_SELECT</code>.
75	</p><p>
76	<a class="citerefentry" href="glBegin.xml"><span class="citerefentry"><span class="refentrytitle">glBegin</span></span></a>/<a class="citerefentry" href="glEnd.xml"><span class="citerefentry"><span class="refentrytitle">glEnd</span></span></a> primitives and calls to <a class="citerefentry" href="glRasterPos.xml"><span class="citerefentry"><span class="refentrytitle">glRasterPos</span></span></a>
77	can result in hits. <a class="citerefentry" href="glWindowPos.xml"><span class="citerefentry"><span class="refentrytitle">glWindowPos</span></span></a> will always generate a selection hit.
78	</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="errors"></a><h2>Errors</h2><p>
79	<code class="constant">GL_INVALID_VALUE</code> is generated if <em class="parameter"><code>size</code></em> is negative.
80	</p><p>
81	<code class="constant">GL_INVALID_OPERATION</code> is generated if <code class="function">glSelectBuffer</code> is called while the
82	render mode is <code class="constant">GL_SELECT</code>,
83	or if <a class="citerefentry" href="glRenderMode.xml"><span class="citerefentry"><span class="refentrytitle">glRenderMode</span></span></a> is called with argument <code class="constant">GL_SELECT</code> before
84	<code class="function">glSelectBuffer</code> is called at least once.
85	</p><p>
86	<code class="constant">GL_INVALID_OPERATION</code> is generated if <code class="function">glSelectBuffer</code>
87	is executed between the execution of <a class="citerefentry" href="glBegin.xml"><span class="citerefentry"><span class="refentrytitle">glBegin</span></span></a>
88	and the corresponding execution of <a class="citerefentry" href="glEnd.xml"><span class="citerefentry"><span class="refentrytitle">glEnd</span></span></a>.
89	</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="associatedgets"></a><h2>Associated Gets</h2><p>
90	<a class="citerefentry" href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_NAME_STACK_DEPTH</code>
91	</p><p>
92	<a class="citerefentry" href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_SELECTION_BUFFER_SIZE</code>
93	</p><p>
94	<a class="citerefentry" href="glGetPointerv.xml"><span class="citerefentry"><span class="refentrytitle">glGetPointerv</span></span></a> with argument <code class="constant">GL_SELECTION_BUFFER_POINTER</code>
95	</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p>
96	<a class="citerefentry" href="glFeedbackBuffer.xml"><span class="citerefentry"><span class="refentrytitle">glFeedbackBuffer</span></span></a>,
97	<a class="citerefentry" href="glInitNames.xml"><span class="citerefentry"><span class="refentrytitle">glInitNames</span></span></a>,
98	<a class="citerefentry" href="glLoadName.xml"><span class="citerefentry"><span class="refentrytitle">glLoadName</span></span></a>,
99	<a class="citerefentry" href="glPushName.xml"><span class="citerefentry"><span class="refentrytitle">glPushName</span></span></a>,
100	<a class="citerefentry" href="glRenderMode.xml"><span class="citerefentry"><span class="refentrytitle">glRenderMode</span></span></a>
101	</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p>
102	Copyright <span class="trademark"></span>© 1991-2006
103	Silicon Graphics, Inc. This document is licensed under the SGI
104	Free Software B License. For details, see
105	<a class="ulink" href="http://oss.sgi.com/projects/FreeB/" target="_top">http://oss.sgi.com/projects/FreeB/</a>.
106	</p></div></div></body></html>