upstream-man-pages/man3/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 indicated. <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_DEPTH_CLAMP</constant></term>
 183                 <listitem>
 184                 <para>
 185                 </para>
 186                     <para>
 187                         If enabled,
 188                         the
 189                         <!-- - wc <= zc <= wc -->
 190                         <inlineequation><mml:math>
 191                             <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>
 192                         </mml:math></inlineequation>
 193                         plane equation is ignored by view volume clipping (effectively, there is no near or
 194                         far plane clipping).
 195                         See <citerefentry><refentrytitle>glDepthRange</refentrytitle></citerefentry>.
 196                     </para>
 197                 </listitem>
 198             </varlistentry>
 199             <varlistentry>
 200                 <term><constant>GL_DEPTH_TEST</constant></term>
 201                 <listitem>
 202                 <para>
 203                 </para>
 204                     <para>
 205                         If enabled,
 206                         do depth comparisons and update the depth buffer. Note that even if
 207                         the depth buffer exists and the depth mask is non-zero, the
 208                         depth buffer is not updated if the depth test is disabled. See
 209                         <citerefentry><refentrytitle>glDepthFunc</refentrytitle></citerefentry> and
 210                         <citerefentry><refentrytitle>glDepthRange</refentrytitle></citerefentry>.
 211                     </para>
 212                 </listitem>
 213             </varlistentry>
 214             <varlistentry>
 215                 <term><constant>GL_DITHER</constant>    </term>
 216                 <listitem>
 217                 <para>
 218                 </para>
 219                     <para>
 220                         If enabled,
 221                         dither color components or indices before they are written to the
 222                         color buffer.
 223                     </para>
 224                 </listitem>
 225             </varlistentry>
 226             <varlistentry>
 227                 <term><constant>GL_FRAMEBUFFER_SRGB</constant>    </term>
 228                 <listitem>
 229                 <para>
 230                 </para>
 231                     <para>
 232                         If enabled
 233                         and the value of <constant>GL_FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING</constant> for the
 234                         framebuffer attachment corresponding to the destination buffer is <constant>GL_SRGB</constant>,
 235                         the R, G, and B destination color values (after conversion from fixed-point to floating-point)
 236                         are considered to be encoded for the sRGB color space and hence are linearized prior to
 237                         their use in blending.
 238                     </para>
 239                 </listitem>
 240             </varlistentry>
 241             <varlistentry>
 242                 <term><constant>GL_LINE_SMOOTH</constant></term>
 243                 <listitem>
 244                 <para>
 245                 </para>
 246                     <para>
 247                         If enabled,
 248                         draw lines with correct filtering.
 249                         Otherwise,
 250                         draw aliased lines.
 251                         See <citerefentry><refentrytitle>glLineWidth</refentrytitle></citerefentry>.
 252                     </para>
 253                 </listitem>
 254             </varlistentry>
 255             <varlistentry>
 256                 <term><constant>GL_MULTISAMPLE</constant></term>
 257                 <listitem>
 258                 <para>
 259                 </para>
 260                     <para>
 261                         If enabled,
 262                         use multiple fragment samples in computing the final color of a pixel.
 263                         See <citerefentry><refentrytitle>glSampleCoverage</refentrytitle></citerefentry>.
 264                     </para>
 265                 </listitem>
 266             </varlistentry>
 267             <varlistentry>
 268                 <term><constant>GL_POLYGON_OFFSET_FILL</constant></term>
 269                 <listitem>
 270                 <para>
 271                 </para>
 272                     <para>
 273                         If enabled, and if the polygon is rendered in
 274                         <constant>GL_FILL</constant> mode, an offset is added to depth values of a polygon's
 275                         fragments before the depth comparison is performed.
 276                         See <citerefentry><refentrytitle>glPolygonOffset</refentrytitle></citerefentry>.
 277                     </para>
 278                 </listitem>
 279             </varlistentry>
 280             <varlistentry>
 281                 <term><constant>GL_POLYGON_OFFSET_LINE</constant></term>
 282                 <listitem>
 283                 <para>
 284                 </para>
 285                     <para>
 286                         If enabled, and if the polygon is rendered in
 287                         <constant>GL_LINE</constant> mode, an offset is added to depth values of a polygon's
 288                         fragments before the depth comparison is performed.
 289                         See <citerefentry><refentrytitle>glPolygonOffset</refentrytitle></citerefentry>.
 290                     </para>
 291                 </listitem>
 292             </varlistentry>
 293             <varlistentry>
 294                 <term><constant>GL_POLYGON_OFFSET_POINT</constant></term>
 295                 <listitem>
 296                 <para>
 297                 </para>
 298                     <para>
 299                         If enabled, an offset is added to depth values of a polygon's fragments
 300                         before the depth comparison is performed, if the polygon is rendered in
 301                         <constant>GL_POINT</constant> mode. See <citerefentry><refentrytitle>glPolygonOffset</refentrytitle></citerefentry>.
 302                     </para>
 303                 </listitem>
 304             </varlistentry>
 305             <varlistentry>
 306                 <term><constant>GL_POLYGON_SMOOTH</constant></term>
 307                 <listitem>
 308                 <para>
 309                 </para>
 310                     <para>
 311                         If enabled, draw polygons with proper filtering.
 312                         Otherwise, draw aliased polygons. For correct antialiased polygons,
 313                         an alpha buffer is needed and the polygons must be sorted front to
 314                         back.
 315                     </para>
 316                 </listitem>
 317             </varlistentry>
 318             <varlistentry>
 319                 <term><constant>GL_PRIMITIVE_RESTART</constant></term>
 320                 <listitem>
 321                 <para>
 322                 </para>
 323                     <para>
 324                         Enables primitive restarting.  If enabled, any one of the draw commands
 325                         which transfers a set of generic attribute array elements to the GL will restart
 326                         the primitive when the index of the vertex is equal to the primitive restart index.
 327                         See <citerefentry><refentrytitle>glPrimitiveRestartIndex</refentrytitle></citerefentry>.
 328                     </para>
 329                 </listitem>
 330             </varlistentry>
 331             <varlistentry>
 332                 <term><constant>GL_SAMPLE_ALPHA_TO_COVERAGE</constant></term>
 333                 <listitem>
 334                 <para>
 335                 </para>
 336                     <para>
 337                         If enabled,
 338                         compute a temporary coverage value where each bit is determined by the
 339                         alpha value at the corresponding sample location.  The temporary coverage
 340                         value is then ANDed with the fragment coverage value.
 341                     </para>
 342                 </listitem>
 343             </varlistentry>
 344             <varlistentry>
 345                 <term><constant>GL_SAMPLE_ALPHA_TO_ONE</constant></term>
 346                 <listitem>
 347                 <para>
 348                 </para>
 349                     <para>
 350                         If enabled,
 351                         each sample alpha value is replaced by the maximum representable alpha value.
 352                     </para>
 353                 </listitem>
 354             </varlistentry>
 355             <varlistentry>
 356                 <term><constant>GL_SAMPLE_COVERAGE</constant></term>
 357                 <listitem>
 358                 <para>
 359                 </para>
 360                     <para>
 361                         If enabled,
 362                         the fragment's coverage is ANDed with the temporary coverage value.  If
 363                         <constant>GL_SAMPLE_COVERAGE_INVERT</constant> is set to <constant>GL_TRUE</constant>, invert the coverage
 364                         value.
 365                         See <citerefentry><refentrytitle>glSampleCoverage</refentrytitle></citerefentry>.
 366                     </para>
 367                 </listitem>
 368             </varlistentry>
 369             <varlistentry>
 370                 <term><constant>GL_SCISSOR_TEST</constant></term>
 371                 <listitem>
 372                 <para>
 373                 </para>
 374                     <para>
 375                         If enabled,
 376                         discard fragments that are outside the scissor rectangle.
 377                         See <citerefentry><refentrytitle>glScissor</refentrytitle></citerefentry>.
 378                     </para>
 379                 </listitem>
 380             </varlistentry>
 381             <varlistentry>
 382                 <term><constant>GL_STENCIL_TEST</constant></term>
 383                 <listitem>
 384                 <para>
 385                 </para>
 386                     <para>
 387                         If enabled,
 388                         do stencil testing and update the stencil buffer.
 389                         See <citerefentry><refentrytitle>glStencilFunc</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glStencilOp</refentrytitle></citerefentry>.
 390                     </para>
 391                 </listitem>
 392             </varlistentry>
 393             <varlistentry>
 394                 <term><constant>GL_TEXTURE_CUBE_MAP_SEAMLESS</constant></term>
 395                 <listitem>
 396                 <para>
 397                 </para>
 398                     <para>
 399                         If enabled, modifies the way sampling is performed on cube map textures.  See the spec for more information.
 400                     </para>
 401                 </listitem>
 402             </varlistentry>
 403             <varlistentry>
 404                 <term><constant>GL_PROGRAM_POINT_SIZE</constant></term>
 405                 <listitem>
 406                 <para>
 407                 </para>
 408                     <para>
 409                         If enabled
 410                         and a vertex or geometry shader is active, then the derived point size is taken from the (potentially clipped) shader builtin
 411                         <constant>gl_PointSize</constant> and clamped to the implementation-dependent point size range.
 412                     </para>
 413                 </listitem>
 414             </varlistentry>
 415         </variablelist>
 416     </refsect1>
 417     <refsect1 id="errors"><title>Errors</title>
 418         <para>
 419             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>cap</parameter> is not one of the values
 420             listed previously.
 421         </para>
 422         <para>
 423             <constant>GL_INVALID_VALUE</constant> is generated by <function>glEnablei</function> and <function>glDisablei</function>
 424             if <parameter>index</parameter> is greater than or equal to the number of indexed capabilities for <parameter>cap</parameter>.
 425         </para>
 426     </refsect1>
 427     <refsect1 id="notes"><title>Notes</title>
 428         <para>
 429             <constant>GL_PRIMITIVE_RESTART</constant> is available only if the GL version is 3.1 or greater.
 430         </para>
 431         <para>
 432             <constant>GL_TEXTURE_CUBE_MAP_SEAMLESS</constant> is available only if the GL version is 3.2 or greater.
 433         </para>
 434         <para>
 435             Any token accepted by <function>glEnable</function> or <function>glDisable</function> is also accepted by
 436             <function>glEnablei</function> and <function>glDisablei</function>, but if the capability is not indexed,
 437             the maximum value that <parameter>index</parameter> may take is zero.
 438         </para>
 439         <para>
 440             In general, passing an indexed capability to <function>glEnable</function> or <function>glDisable</function>
 441             will enable or disable that capability for all indices, resepectively.
 442         </para>
 443     </refsect1>
 444     <refsect1 id="associatedgets"><title>Associated Gets</title>
 445         <para>
 446             <citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry>
 447         </para>
 448         <para>
 449             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
 450         </para>
 451     </refsect1>
 452     <refsect1 id="seealso"><title>See Also</title>
 453         <para>
 454             <citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>,
 455             <citerefentry><refentrytitle>glBlendFunc</refentrytitle></citerefentry>,
 456             <citerefentry><refentrytitle>glCullFace</refentrytitle></citerefentry>,
 457             <citerefentry><refentrytitle>glDepthFunc</refentrytitle></citerefentry>,
 458             <citerefentry><refentrytitle>glDepthRange</refentrytitle></citerefentry>,
 459             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>,
 460             <citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry>,
 461             <citerefentry><refentrytitle>glLineWidth</refentrytitle></citerefentry>,
 462             <citerefentry><refentrytitle>glLogicOp</refentrytitle></citerefentry>,
 463             <citerefentry><refentrytitle>glPointSize</refentrytitle></citerefentry>,
 464             <citerefentry><refentrytitle>glPolygonMode</refentrytitle></citerefentry>,
 465             <citerefentry><refentrytitle>glPolygonOffset</refentrytitle></citerefentry>,
 466             <citerefentry><refentrytitle>glSampleCoverage</refentrytitle></citerefentry>,
 467             <citerefentry><refentrytitle>glScissor</refentrytitle></citerefentry>,
 468             <citerefentry><refentrytitle>glStencilFunc</refentrytitle></citerefentry>,
 469             <citerefentry><refentrytitle>glStencilOp</refentrytitle></citerefentry>,
 470             <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
 471             <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
 472             <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>
 473         </para>
 474     </refsect1>
 475     <refsect1 id="Copyright"><title>Copyright</title>
 476         <para>
 477             Copyright <trademark class="copyright"></trademark> 1991-2006
 478             Silicon Graphics, Inc. Copyright <trademark class="copyright"></trademark> 2010 Khronos Group.
 479             This document is licensed under the SGI
 480             Free Software B License. For details, see
 481             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 482         </para>
 483     </refsect1>
 484 </refentry>