a6046b1bd1bd2521cda3cbd7705259a2ae1f97b8
[clinton/guile-figl.git] / upstream-man-pages / man4 / glEnable.xml
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="glEnable">
5 <refmeta>
6 <refmetainfo>
7 <copyright>
8 <year>1991-2006</year>
9 <holder>Silicon Graphics, Inc.</holder>
10 </copyright>
11 </refmetainfo>
12 <refentrytitle>glEnable</refentrytitle>
13 <manvolnum>3G</manvolnum>
14 </refmeta>
15 <refnamediv>
16 <refname>glEnable</refname>
17 <refpurpose>enable or disable server-side GL capabilities</refpurpose>
18 </refnamediv>
19 <refsynopsisdiv><title>C Specification</title>
20 <funcsynopsis>
21 <funcprototype>
22 <funcdef>void <function>glEnable</function></funcdef>
23 <paramdef>GLenum <parameter>cap</parameter></paramdef>
24 </funcprototype>
25 </funcsynopsis>
26 </refsynopsisdiv>
27 <refsect1 id="parameters"><title>Parameters</title>
28 <variablelist>
29 <varlistentry>
30 <term><parameter>cap</parameter></term>
31 <listitem>
32 <para>
33 Specifies a symbolic constant indicating a GL capability.
34 </para>
35 </listitem>
36 </varlistentry>
37 </variablelist>
38 </refsect1>
39 <refsynopsisdiv><title>C Specification</title>
40 <funcsynopsis>
41 <funcprototype>
42 <funcdef>void <function>glDisable</function></funcdef>
43 <paramdef>GLenum <parameter>cap</parameter></paramdef>
44 </funcprototype>
45 </funcsynopsis>
46 </refsynopsisdiv>
47 <refsect1 id="parameters2"><title>Parameters</title>
48 <variablelist>
49 <varlistentry>
50 <term><parameter>cap</parameter></term>
51 <listitem>
52 <para>
53 Specifies a symbolic constant indicating a GL capability.
54 </para>
55 </listitem>
56 </varlistentry>
57 </variablelist>
58 </refsect1>
59 <refsynopsisdiv><title>C Specification</title>
60 <funcsynopsis>
61 <funcprototype>
62 <funcdef>void <function>glEnablei</function></funcdef>
63 <paramdef>GLenum <parameter>cap</parameter></paramdef>
64 <paramdef>GLuint <parameter>index</parameter></paramdef>
65 </funcprototype>
66 </funcsynopsis>
67 </refsynopsisdiv>
68 <refsect1 id="parameters3"><title>Parameters</title>
69 <variablelist>
70 <varlistentry>
71 <term><parameter>cap</parameter></term>
72 <listitem>
73 <para>
74 Specifies a symbolic constant indicating a GL capability.
75 </para>
76 </listitem>
77 </varlistentry>
78 <varlistentry>
79 <term><parameter>index</parameter></term>
80 <listitem>
81 <para>
82 Specifies the index of the swtich to enable.
83 </para>
84 </listitem>
85 </varlistentry>
86 </variablelist>
87 </refsect1>
88 <refsynopsisdiv><title>C Specification</title>
89 <funcsynopsis>
90 <funcprototype>
91 <funcdef>void <function>glDisablei</function></funcdef>
92 <paramdef>GLenum <parameter>cap</parameter></paramdef>
93 <paramdef>GLuint <parameter>index</parameter></paramdef>
94 </funcprototype>
95 </funcsynopsis>
96 </refsynopsisdiv>
97 <refsect1 id="parameters4"><title>Parameters</title>
98 <variablelist>
99 <varlistentry>
100 <term><parameter>cap</parameter></term>
101 <listitem>
102 <para>
103 Specifies a symbolic constant indicating a GL capability.
104 </para>
105 </listitem>
106 </varlistentry>
107 <varlistentry>
108 <term><parameter>index</parameter></term>
109 <listitem>
110 <para>
111 Specifies the index of the swtich to disable.
112 </para>
113 </listitem>
114 </varlistentry>
115 </variablelist>
116 </refsect1>
117 <refsect1 id="description"><title>Description</title>
118 <para>
119 <function>glEnable</function> and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> enable and disable various capabilities.
120 Use <citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> or <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> to determine the current setting
121 of any capability. The initial value for each capability with the
122 exception of <constant>GL_DITHER</constant> and <constant>GL_MULTISAMPLE</constant> is
123 <constant>GL_FALSE</constant>. The initial value for
124 <constant>GL_DITHER</constant> and <constant>GL_MULTISAMPLE</constant> is <constant>GL_TRUE</constant>.
125 </para>
126 <para>
127 Both <function>glEnable</function> and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> take a single argument, <parameter>cap</parameter>,
128 which can assume one of the following values:
129 </para>
130 <para>
131 Some of the GL's capabilities are indexed. <function>glEnablei</function> and <function>glDisablei</function> enable and disable
132 indexed capabilities.
133 </para>
134 <variablelist>
135 <varlistentry>
136 <term><constant>GL_BLEND</constant></term>
137 <listitem>
138 <para>
139 </para>
140 <para>
141 If enabled,
142 blend the computed fragment color values with the values in the color
143 buffers. See <citerefentry><refentrytitle>glBlendFunc</refentrytitle></citerefentry>.
144 </para>
145 </listitem>
146 </varlistentry>
147 <varlistentry>
148 <term><constant>GL_CLIP_DISTANCE</constant><emphasis>i</emphasis></term>
149 <listitem>
150 <para>
151 </para>
152 <para>
153 If enabled, clip geometry against user-defined half space <emphasis>i</emphasis>.
154 </para>
155 </listitem>
156 </varlistentry>
157 <varlistentry>
158 <term><constant>GL_COLOR_LOGIC_OP</constant></term>
159 <listitem>
160 <para>
161 </para>
162 <para>
163 If enabled,
164 apply the currently selected logical operation to the computed fragment
165 color and color buffer values. See <citerefentry><refentrytitle>glLogicOp</refentrytitle></citerefentry>.
166 </para>
167 </listitem>
168 </varlistentry>
169 <varlistentry>
170 <term><constant>GL_CULL_FACE</constant></term>
171 <listitem>
172 <para>
173 </para>
174 <para>
175 If enabled,
176 cull polygons based on their winding in window coordinates.
177 See <citerefentry><refentrytitle>glCullFace</refentrytitle></citerefentry>.
178 </para>
179 </listitem>
180 </varlistentry>
181 <varlistentry>
182 <term><constant>GL_DEBUG_OUTPUT</constant></term>
183 <listitem>
184 <para>
185 </para>
186 <para>
187 If enabled, debug messages are produced by a debug context. When disabled,
188 the debug message log is silenced. Note that in a non-debug context, very
189 few, if any messages might be produced, even when <constant>GL_DEBUG_OUTPUT</constant>
190 is enabled.
191 </para>
192 </listitem>
193 </varlistentry>
194 <varlistentry>
195 <term><constant>GL_DEBUG_OUTPUT_SYNCHRONOUS</constant></term>
196 <listitem>
197 <para>
198 </para>
199 <para>
200 If enabled, debug messages are produced synchronously by a debug context. If disabled,
201 debug messages may be produced asynchronously. In particular, they may be delayed relative
202 to the execution of GL commands, and the debug callback function may be called from
203 a thread other than that in which the commands are executed.
204 See <citerefentry><refentrytitle>glDebugMessageCallback</refentrytitle></citerefentry>.
205 </para>
206 </listitem>
207 </varlistentry>
208 <varlistentry>
209 <term><constant>GL_DEPTH_CLAMP</constant></term>
210 <listitem>
211 <para>
212 </para>
213 <para>
214 If enabled,
215 the
216 <!-- - wc <= zc <= wc -->
217 <inlineequation><mml:math>
218 <mml:mo>-</mml:mo><mml:msub><mml:mi>w</mml:mi><mml:mi>c</mml:mi></mml:msub><mml:mo>&le;</mml:mo><mml:msub><mml:mi>z</mml:mi><mml:mi>c</mml:mi></mml:msub><mml:mo>&le;</mml:mo><mml:msub><mml:mi>w</mml:mi><mml:mi>c</mml:mi></mml:msub>
219 </mml:math></inlineequation>
220 plane equation is ignored by view volume clipping (effectively, there is no near or
221 far plane clipping).
222 See <citerefentry><refentrytitle>glDepthRange</refentrytitle></citerefentry>.
223 </para>
224 </listitem>
225 </varlistentry>
226 <varlistentry>
227 <term><constant>GL_DEPTH_TEST</constant></term>
228 <listitem>
229 <para>
230 </para>
231 <para>
232 If enabled,
233 do depth comparisons and update the depth buffer. Note that even if
234 the depth buffer exists and the depth mask is non-zero, the
235 depth buffer is not updated if the depth test is disabled. See
236 <citerefentry><refentrytitle>glDepthFunc</refentrytitle></citerefentry> and
237 <citerefentry><refentrytitle>glDepthRange</refentrytitle></citerefentry>.
238 </para>
239 </listitem>
240 </varlistentry>
241 <varlistentry>
242 <term><constant>GL_DITHER</constant> </term>
243 <listitem>
244 <para>
245 </para>
246 <para>
247 If enabled,
248 dither color components or indices before they are written to the
249 color buffer.
250 </para>
251 </listitem>
252 </varlistentry>
253 <varlistentry>
254 <term><constant>GL_FRAMEBUFFER_SRGB</constant> </term>
255 <listitem>
256 <para>
257 </para>
258 <para>
259 If enabled
260 and the value of <constant>GL_FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING</constant> for the
261 framebuffer attachment corresponding to the destination buffer is <constant>GL_SRGB</constant>,
262 the R, G, and B destination color values (after conversion from fixed-point to floating-point)
263 are considered to be encoded for the sRGB color space and hence are linearized prior to
264 their use in blending.
265 </para>
266 </listitem>
267 </varlistentry>
268 <varlistentry>
269 <term><constant>GL_LINE_SMOOTH</constant></term>
270 <listitem>
271 <para>
272 </para>
273 <para>
274 If enabled,
275 draw lines with correct filtering.
276 Otherwise,
277 draw aliased lines.
278 See <citerefentry><refentrytitle>glLineWidth</refentrytitle></citerefentry>.
279 </para>
280 </listitem>
281 </varlistentry>
282 <varlistentry>
283 <term><constant>GL_MULTISAMPLE</constant></term>
284 <listitem>
285 <para>
286 </para>
287 <para>
288 If enabled,
289 use multiple fragment samples in computing the final color of a pixel.
290 See <citerefentry><refentrytitle>glSampleCoverage</refentrytitle></citerefentry>.
291 </para>
292 </listitem>
293 </varlistentry>
294 <varlistentry>
295 <term><constant>GL_POLYGON_OFFSET_FILL</constant></term>
296 <listitem>
297 <para>
298 </para>
299 <para>
300 If enabled, and if the polygon is rendered in
301 <constant>GL_FILL</constant> mode, an offset is added to depth values of a polygon's
302 fragments before the depth comparison is performed.
303 See <citerefentry><refentrytitle>glPolygonOffset</refentrytitle></citerefentry>.
304 </para>
305 </listitem>
306 </varlistentry>
307 <varlistentry>
308 <term><constant>GL_POLYGON_OFFSET_LINE</constant></term>
309 <listitem>
310 <para>
311 </para>
312 <para>
313 If enabled, and if the polygon is rendered in
314 <constant>GL_LINE</constant> mode, an offset is added to depth values of a polygon's
315 fragments before the depth comparison is performed.
316 See <citerefentry><refentrytitle>glPolygonOffset</refentrytitle></citerefentry>.
317 </para>
318 </listitem>
319 </varlistentry>
320 <varlistentry>
321 <term><constant>GL_POLYGON_OFFSET_POINT</constant></term>
322 <listitem>
323 <para>
324 </para>
325 <para>
326 If enabled, an offset is added to depth values of a polygon's fragments
327 before the depth comparison is performed, if the polygon is rendered in
328 <constant>GL_POINT</constant> mode. See <citerefentry><refentrytitle>glPolygonOffset</refentrytitle></citerefentry>.
329 </para>
330 </listitem>
331 </varlistentry>
332 <varlistentry>
333 <term><constant>GL_POLYGON_SMOOTH</constant></term>
334 <listitem>
335 <para>
336 </para>
337 <para>
338 If enabled, draw polygons with proper filtering.
339 Otherwise, draw aliased polygons. For correct antialiased polygons,
340 an alpha buffer is needed and the polygons must be sorted front to
341 back.
342 </para>
343 </listitem>
344 </varlistentry>
345 <varlistentry>
346 <term><constant>GL_PRIMITIVE_RESTART</constant></term>
347 <listitem>
348 <para>
349 </para>
350 <para>
351 Enables primitive restarting. If enabled, any one of the draw commands
352 which transfers a set of generic attribute array elements to the GL will restart
353 the primitive when the index of the vertex is equal to the primitive restart index.
354 See <citerefentry><refentrytitle>glPrimitiveRestartIndex</refentrytitle></citerefentry>.
355 </para>
356 </listitem>
357 </varlistentry>
358 <varlistentry>
359 <term><constant>GL_PRIMITIVE_RESTART_FIXED_INDEX</constant></term>
360 <listitem>
361 <para>
362 </para>
363 <para>
364 Enables primitive restarting with a fixed index. If enabled, any one of the
365 draw commands which transfers a set of generic attribute array elements to the GL will
366 restart the primitive when the index of the vertex is equal to the fixed primitive
367 index for the specified index type. The fixed index is equal to
368 <inlineequation><mml:math><mml:msup><mml:mn>2</mml:mn><mml:mi>n</mml:mi></mml:msup><mml:mo>&minus;</mml:mo><mml:mn>1</mml:mn></mml:math></inlineequation>
369 where <emphasis>n</emphasis> is equal to 8 for <constant>GL_UNSIGNED_BYTE</constant>,
370 16 for <constant>GL_UNSIGNED_SHORT</constant> and 32 for <constant>GL_UNSIGNED_INT</constant>.
371 </para>
372 </listitem>
373 </varlistentry>
374 <varlistentry>
375 <term><constant>GL_SAMPLE_ALPHA_TO_COVERAGE</constant></term>
376 <listitem>
377 <para>
378 </para>
379 <para>
380 If enabled,
381 compute a temporary coverage value where each bit is determined by the
382 alpha value at the corresponding sample location. The temporary coverage
383 value is then ANDed with the fragment coverage value.
384 </para>
385 </listitem>
386 </varlistentry>
387 <varlistentry>
388 <term><constant>GL_SAMPLE_ALPHA_TO_ONE</constant></term>
389 <listitem>
390 <para>
391 </para>
392 <para>
393 If enabled,
394 each sample alpha value is replaced by the maximum representable alpha value.
395 </para>
396 </listitem>
397 </varlistentry>
398 <varlistentry>
399 <term><constant>GL_SAMPLE_COVERAGE</constant></term>
400 <listitem>
401 <para>
402 </para>
403 <para>
404 If enabled,
405 the fragment's coverage is ANDed with the temporary coverage value. If
406 <constant>GL_SAMPLE_COVERAGE_INVERT</constant> is set to <constant>GL_TRUE</constant>, invert the coverage
407 value.
408 See <citerefentry><refentrytitle>glSampleCoverage</refentrytitle></citerefentry>.
409 </para>
410 </listitem>
411 </varlistentry>
412 <varlistentry>
413 <term><constant>GL_SAMPLE_SHADING</constant></term>
414 <listitem>
415 <para>
416 </para>
417 <para>
418 If enabled, the active fragment shader is run once for each covered sample, or at
419 fraction of this rate as determined by the current value of <constant>GL_MIN_SAMPLE_SHADING_VALUE</constant>.
420 See <citerefentry><refentrytitle>glMinSampleShading</refentrytitle></citerefentry>.
421 </para>
422 </listitem>
423 </varlistentry>
424 <varlistentry>
425 <term><constant>GL_SAMPLE_MASK</constant></term>
426 <listitem>
427 <para>
428 </para>
429 <para>
430 If enabled, the sample coverage mask generated for a fragment during rasterization
431 will be ANDed with the value of <constant>GL_SAMPLE_MASK_VALUE</constant> before
432 shading occurs.
433 See <citerefentry><refentrytitle>glSampleMaski</refentrytitle></citerefentry>.
434 </para>
435 </listitem>
436 </varlistentry>
437 <varlistentry>
438 <term><constant>GL_SCISSOR_TEST</constant></term>
439 <listitem>
440 <para>
441 </para>
442 <para>
443 If enabled,
444 discard fragments that are outside the scissor rectangle.
445 See <citerefentry><refentrytitle>glScissor</refentrytitle></citerefentry>.
446 </para>
447 </listitem>
448 </varlistentry>
449 <varlistentry>
450 <term><constant>GL_STENCIL_TEST</constant></term>
451 <listitem>
452 <para>
453 </para>
454 <para>
455 If enabled,
456 do stencil testing and update the stencil buffer.
457 See <citerefentry><refentrytitle>glStencilFunc</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glStencilOp</refentrytitle></citerefentry>.
458 </para>
459 </listitem>
460 </varlistentry>
461 <varlistentry>
462 <term><constant>GL_TEXTURE_CUBE_MAP_SEAMLESS</constant></term>
463 <listitem>
464 <para>
465 </para>
466 <para>
467 If enabled, cubemap textures are sampled such that when linearly sampling from the border
468 between two adjacent faces, texels from both faces are used to generate the final sample
469 value. When disabled, texels from only a single face are used to construct the final
470 sample value.
471 </para>
472 </listitem>
473 </varlistentry>
474 <varlistentry>
475 <term><constant>GL_PROGRAM_POINT_SIZE</constant></term>
476 <listitem>
477 <para>
478 </para>
479 <para>
480 If enabled
481 and a vertex or geometry shader is active, then the derived point size is taken from the (potentially clipped) shader builtin
482 <constant>gl_PointSize</constant> and clamped to the implementation-dependent point size range.
483 </para>
484 </listitem>
485 </varlistentry>
486 </variablelist>
487 </refsect1>
488 <refsect1 id="errors"><title>Errors</title>
489 <para>
490 <constant>GL_INVALID_ENUM</constant> is generated if <parameter>cap</parameter> is not one of the values
491 listed previously.
492 </para>
493 <para>
494 <constant>GL_INVALID_VALUE</constant> is generated by <function>glEnablei</function> and <function>glDisablei</function>
495 if <parameter>index</parameter> is greater than or equal to the number of indexed capabilities for <parameter>cap</parameter>.
496 </para>
497 </refsect1>
498 <refsect1 id="notes"><title>Notes</title>
499 <para>
500 <constant>GL_PRIMITIVE_RESTART</constant> is available only if the GL version is 3.1 or greater.
501 </para>
502 <para>
503 <constant>GL_TEXTURE_CUBE_MAP_SEAMLESS</constant> is available only if the GL version is 3.2 or greater.
504 </para>
505 <para>
506 <constant>GL_PRIMITIVE_RESTART_FIXED_INDEX</constant> is available only if the GL version is 4.3 or greater.
507 </para>
508 <para>
509 <constant>GL_DEBUG_OUTPUT</constant> and <constant>GL_DEBUG_OUTPUT_SYNCHRONOUS</constant> are available only if the GL version is 4.3 or greater.
510 </para>
511 <para>
512 Any token accepted by <function>glEnable</function> or <function>glDisable</function> is also accepted by
513 <function>glEnablei</function> and <function>glDisablei</function>, but if the capability is not indexed,
514 the maximum value that <parameter>index</parameter> may take is zero.
515 </para>
516 <para>
517 In general, passing an indexed capability to <function>glEnable</function> or <function>glDisable</function>
518 will enable or disable that capability for all indices, resepectively.
519 </para>
520 </refsect1>
521 <refsect1 id="associatedgets"><title>Associated Gets</title>
522 <para>
523 <citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry>
524 </para>
525 <para>
526 <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
527 </para>
528 </refsect1>
529 <refsect1 id="seealso"><title>See Also</title>
530 <para>
531 <citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>,
532 <citerefentry><refentrytitle>glBlendFunc</refentrytitle></citerefentry>,
533 <citerefentry><refentrytitle>glCullFace</refentrytitle></citerefentry>,
534 <citerefentry><refentrytitle>glDepthFunc</refentrytitle></citerefentry>,
535 <citerefentry><refentrytitle>glDepthRange</refentrytitle></citerefentry>,
536 <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>,
537 <citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry>,
538 <citerefentry><refentrytitle>glLineWidth</refentrytitle></citerefentry>,
539 <citerefentry><refentrytitle>glLogicOp</refentrytitle></citerefentry>,
540 <citerefentry><refentrytitle>glPointSize</refentrytitle></citerefentry>,
541 <citerefentry><refentrytitle>glPolygonMode</refentrytitle></citerefentry>,
542 <citerefentry><refentrytitle>glPolygonOffset</refentrytitle></citerefentry>,
543 <citerefentry><refentrytitle>glSampleCoverage</refentrytitle></citerefentry>,
544 <citerefentry><refentrytitle>glScissor</refentrytitle></citerefentry>,
545 <citerefentry><refentrytitle>glStencilFunc</refentrytitle></citerefentry>,
546 <citerefentry><refentrytitle>glStencilOp</refentrytitle></citerefentry>,
547 <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
548 <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
549 <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>
550 </para>
551 </refsect1>
552 <refsect1 id="Copyright"><title>Copyright</title>
553 <para>
554 Copyright <trademark class="copyright"></trademark> 1991-2006
555 Silicon Graphics, Inc. Copyright <trademark class="copyright"></trademark> 2010-2011 Khronos Group.
556 This document is licensed under the SGI
557 Free Software B License. For details, see
558 <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
559 </para>
560 </refsect1>
561 </refentry>