Commit | Line | Data |
---|---|---|
7faf1d71 AW |
1 | <?xml version="1.0" encoding="UTF-8"?> |
2 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN" | |
3 | "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd"> | |
4 | <refentry id="glSelectBuffer"> | |
5 | <refmeta> | |
6 | <refmetainfo> | |
7 | <copyright> | |
8 | <year>1991-2006</year> | |
9 | <holder>Silicon Graphics, Inc.</holder> | |
10 | </copyright> | |
11 | </refmetainfo> | |
12 | <refentrytitle>glSelectBuffer</refentrytitle> | |
13 | <manvolnum>3G</manvolnum> | |
14 | </refmeta> | |
15 | <refnamediv> | |
16 | <refname>glSelectBuffer</refname> | |
17 | <refpurpose>establish a buffer for selection mode values</refpurpose> | |
18 | </refnamediv> | |
19 | <refsynopsisdiv><title>C Specification</title> | |
20 | <funcsynopsis> | |
21 | <funcprototype> | |
22 | <funcdef>void <function>glSelectBuffer</function></funcdef> | |
23 | <paramdef>GLsizei <parameter>size</parameter></paramdef> | |
24 | <paramdef>GLuint * <parameter>buffer</parameter></paramdef> | |
25 | </funcprototype> | |
26 | </funcsynopsis> | |
27 | </refsynopsisdiv> | |
28 | <!-- eqn: ignoring delim $$ --> | |
29 | <refsect1 id="parameters"><title>Parameters</title> | |
30 | <variablelist> | |
31 | <varlistentry> | |
32 | <term><parameter>size</parameter></term> | |
33 | <listitem> | |
34 | <para> | |
35 | Specifies the size of <parameter>buffer</parameter>. | |
36 | </para> | |
37 | </listitem> | |
38 | </varlistentry> | |
39 | <varlistentry> | |
40 | <term><parameter>buffer</parameter></term> | |
41 | <listitem> | |
42 | <para> | |
43 | Returns the selection data. | |
44 | </para> | |
45 | </listitem> | |
46 | </varlistentry> | |
47 | </variablelist> | |
48 | </refsect1> | |
49 | <refsect1 id="description"><title>Description</title> | |
50 | <para> | |
51 | <function>glSelectBuffer</function> has two arguments: | |
52 | <parameter>buffer</parameter> is a pointer to an array of unsigned integers, | |
53 | and <parameter>size</parameter> indicates the size of the array. | |
54 | <parameter>buffer</parameter> returns values from the name stack | |
55 | (see <citerefentry><refentrytitle>glInitNames</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glLoadName</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glPushName</refentrytitle></citerefentry>) | |
56 | when the rendering mode is <constant>GL_SELECT</constant> (see <citerefentry><refentrytitle>glRenderMode</refentrytitle></citerefentry>). | |
57 | <function>glSelectBuffer</function> must be issued before selection mode is enabled, | |
58 | and it must not be issued while the rendering mode is <constant>GL_SELECT</constant>. | |
59 | </para> | |
60 | <para> | |
61 | A programmer can use selection to determine which primitives | |
62 | are drawn into some region of a window. | |
63 | The region is defined by the current modelview and perspective matrices. | |
64 | </para> | |
65 | <para> | |
66 | In selection mode, no pixel fragments are produced from rasterization. | |
67 | Instead, | |
68 | if a primitive or a raster position intersects the clipping | |
69 | volume defined by the viewing frustum | |
70 | and the user-defined clipping planes, | |
71 | this primitive causes a selection hit. | |
72 | (With polygons, no hit occurs if the polygon is culled.) | |
73 | When a change is made to the name stack, | |
74 | or when <citerefentry><refentrytitle>glRenderMode</refentrytitle></citerefentry> is called, | |
75 | a hit record is copied to <parameter>buffer</parameter> if any hits have occurred since the | |
76 | last such event | |
77 | (name stack change or | |
78 | <citerefentry><refentrytitle>glRenderMode</refentrytitle></citerefentry> call). | |
79 | The hit record consists of the number of names in the name stack at the | |
80 | time of the event, followed by the minimum and maximum depth values | |
81 | of all vertices that hit since the previous event, | |
82 | followed by the name stack contents, | |
83 | bottom name first. | |
84 | </para> | |
85 | <para> | |
86 | Depth values (which are in the range [0,1]) are multiplied by | |
87 | <inlineequation><mml:math> | |
88 | <!-- eqn: 2 sup 32 - 1:--> | |
89 | <mml:mrow> | |
90 | <mml:msup><mml:mn>2</mml:mn> | |
91 | <mml:mn>32</mml:mn> | |
92 | </mml:msup> | |
93 | <mml:mo>-</mml:mo> | |
94 | <mml:mn>1</mml:mn> | |
95 | </mml:mrow> | |
96 | </mml:math></inlineequation>, | |
97 | before being placed in the hit record. | |
98 | </para> | |
99 | <para> | |
100 | An internal index into <parameter>buffer</parameter> is reset to 0 whenever selection mode | |
101 | is entered. | |
102 | Each time a hit record is copied into <parameter>buffer</parameter>, | |
103 | the index is incremented to point to the cell just past the end | |
104 | of the block of names\(emthat is, to the next available cell | |
105 | If the hit record is larger than the number of remaining locations in <parameter>buffer</parameter>, | |
106 | as much data as can fit is copied, | |
107 | and the overflow flag is set. | |
108 | If the name stack is empty when a hit record is copied, | |
109 | that record consists of 0 followed by the minimum and maximum depth values. | |
110 | </para> | |
111 | <para> | |
112 | To exit selection mode, call <citerefentry><refentrytitle>glRenderMode</refentrytitle></citerefentry> with an argument | |
113 | other than <constant>GL_SELECT</constant>. | |
114 | Whenever <citerefentry><refentrytitle>glRenderMode</refentrytitle></citerefentry> is called while the render mode is <constant>GL_SELECT</constant>, | |
115 | it returns the number of hit records copied to <parameter>buffer</parameter>, | |
116 | resets the overflow flag and the selection buffer pointer, | |
117 | and initializes the name stack to be empty. | |
118 | If the overflow bit was set when <citerefentry><refentrytitle>glRenderMode</refentrytitle></citerefentry> was called, | |
119 | a negative hit record count is returned. | |
120 | </para> | |
121 | </refsect1> | |
122 | <refsect1 id="notes"><title>Notes</title> | |
123 | <para> | |
124 | The contents of <parameter>buffer</parameter> is undefined until <citerefentry><refentrytitle>glRenderMode</refentrytitle></citerefentry> is called | |
125 | with an argument other than <constant>GL_SELECT</constant>. | |
126 | </para> | |
127 | <para> | |
128 | <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>/<citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry> primitives and calls to <citerefentry><refentrytitle>glRasterPos</refentrytitle></citerefentry> | |
129 | can result in hits. <citerefentry><refentrytitle>glWindowPos</refentrytitle></citerefentry> will always generate a selection hit. | |
130 | </para> | |
131 | </refsect1> | |
132 | <refsect1 id="errors"><title>Errors</title> | |
133 | <para> | |
134 | <constant>GL_INVALID_VALUE</constant> is generated if <parameter>size</parameter> is negative. | |
135 | </para> | |
136 | <para> | |
137 | <constant>GL_INVALID_OPERATION</constant> is generated if <function>glSelectBuffer</function> is called while the | |
138 | render mode is <constant>GL_SELECT</constant>, | |
139 | or if <citerefentry><refentrytitle>glRenderMode</refentrytitle></citerefentry> is called with argument <constant>GL_SELECT</constant> before | |
140 | <function>glSelectBuffer</function> is called at least once. | |
141 | </para> | |
142 | <para> | |
143 | <constant>GL_INVALID_OPERATION</constant> is generated if <function>glSelectBuffer</function> | |
144 | is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> | |
145 | and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>. | |
146 | </para> | |
147 | </refsect1> | |
148 | <refsect1 id="associatedgets"><title>Associated Gets</title> | |
149 | <para> | |
150 | <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_NAME_STACK_DEPTH</constant> | |
151 | </para> | |
152 | <para> | |
153 | <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_SELECTION_BUFFER_SIZE</constant> | |
154 | </para> | |
155 | <para> | |
156 | <citerefentry><refentrytitle>glGetPointerv</refentrytitle></citerefentry> with argument <constant>GL_SELECTION_BUFFER_POINTER</constant> | |
157 | </para> | |
158 | </refsect1> | |
159 | <refsect1 id="seealso"><title>See Also</title> | |
160 | <para> | |
161 | <citerefentry><refentrytitle>glFeedbackBuffer</refentrytitle></citerefentry>, | |
162 | <citerefentry><refentrytitle>glInitNames</refentrytitle></citerefentry>, | |
163 | <citerefentry><refentrytitle>glLoadName</refentrytitle></citerefentry>, | |
164 | <citerefentry><refentrytitle>glPushName</refentrytitle></citerefentry>, | |
165 | <citerefentry><refentrytitle>glRenderMode</refentrytitle></citerefentry> | |
166 | </para> | |
167 | </refsect1> | |
168 | <refsect1 id="Copyright"><title>Copyright</title> | |
169 | <para> | |
170 | Copyright <trademark class="copyright"></trademark> 1991-2006 | |
171 | Silicon Graphics, Inc. This document is licensed under the SGI | |
172 | Free Software B License. For details, see | |
173 | <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>. | |
174 | </para> | |
175 | </refsect1> | |
176 | </refentry> |