upstream-man-pages/man2/glHint.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="glHint">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glHint</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glHint</refname>
  17         <refpurpose>specify implementation-specific hints</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glHint</function></funcdef>
  23                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  24                 <paramdef>GLenum <parameter>mode</parameter></paramdef>
  25             </funcprototype>
  26         </funcsynopsis>
  27     </refsynopsisdiv>
  28     <refsect1 id="parameters"><title>Parameters</title>
  29         <variablelist>
  30         <varlistentry>
  31             <term><parameter>target</parameter></term>
  32             <listitem>
  33                 <para>
  34                     Specifies a symbolic constant indicating the behavior to be controlled.
  35                     <constant>GL_FOG_HINT</constant>,
  36                     <constant>GL_GENERATE_MIPMAP_HINT</constant>,
  37                     <constant>GL_LINE_SMOOTH_HINT</constant>,
  38                     <constant>GL_PERSPECTIVE_CORRECTION_HINT</constant>,
  39                     <constant>GL_POINT_SMOOTH_HINT</constant>,
  40                     <constant>GL_POLYGON_SMOOTH_HINT</constant>,
  41                     <constant>GL_TEXTURE_COMPRESSION_HINT</constant>, and
  42                     <constant>GL_FRAGMENT_SHADER_DERIVATIVE_HINT</constant>
  43                     are accepted.
  44                 </para>
  45             </listitem>
  46         </varlistentry>
  47         <varlistentry>
  48             <term><parameter>mode</parameter></term>
  49             <listitem>
  50                 <para>
  51                     Specifies a symbolic constant indicating the desired behavior.
  52                     <constant>GL_FASTEST</constant>,
  53                     <constant>GL_NICEST</constant>, and
  54                     <constant>GL_DONT_CARE</constant> are accepted.
  55                 </para>
  56             </listitem>
  57         </varlistentry>
  58         </variablelist>
  59     </refsect1>
  60     <refsect1 id="description"><title>Description</title>
  61         <para>
  62             Certain aspects of GL behavior,
  63             when there is room for interpretation,
  64             can be controlled with hints.
  65             A hint is specified with two arguments.
  66             <parameter>target</parameter> is a symbolic
  67             constant indicating the behavior to be controlled,
  68             and <parameter>mode</parameter> is another symbolic constant indicating the desired
  69             behavior. The initial value for each <parameter>target</parameter> is <constant>GL_DONT_CARE</constant>.
  70             <parameter>mode</parameter> can be one of the following:
  71         </para>
  72         <variablelist>
  73             <varlistentry>
  74                 <term><constant>GL_FASTEST</constant></term>
  75                 <listitem>
  76                     <para>
  77                     </para>
  78                     <para>
  79                         The most efficient option should be chosen.
  80                     </para>
  81                 </listitem>
  82             </varlistentry>
  83             <varlistentry>
  84                 <term><constant>GL_NICEST</constant></term>
  85                 <listitem>
  86                     <para>
  87                     </para>
  88                     <para>
  89                         The most correct,
  90                         or highest quality,
  91                         option should be chosen.
  92                     </para>
  93                 </listitem>
  94             </varlistentry>
  95             <varlistentry>
  96                 <term><constant>GL_DONT_CARE</constant></term>
  97                 <listitem>
  98                     <para>
  99                     </para>
 100                     <para>
 101                         No preference.
 102                     </para>
 103                 </listitem>
 104             </varlistentry>
 105         </variablelist>
 106         <para>
 107             Though the implementation aspects that can be hinted are well defined,
 108             the interpretation of the hints depends on the implementation.
 109             The hint aspects that can be specified with <parameter>target</parameter>,
 110             along with suggested semantics,
 111             are as follows:
 112         </para>
 113         <variablelist>
 114             <varlistentry>
 115                 <term><constant>GL_FOG_HINT</constant></term>
 116                 <listitem>
 117                     <para>
 118                     </para>
 119                     <para>
 120                         Indicates the accuracy of fog calculation.
 121                         If per-pixel fog calculation is not efficiently supported
 122                         by the GL implementation,
 123                         hinting <constant>GL_DONT_CARE</constant> or <constant>GL_FASTEST</constant> can result in per-vertex
 124                         calculation of fog effects.
 125                     </para>
 126                 </listitem>
 127             </varlistentry>
 128             <varlistentry>
 129                 <term><constant>GL_FRAGMENT_SHADER_DERIVATIVE_HINT</constant></term>
 130                 <listitem>
 131                     <para>
 132                     </para>
 133                     <para>
 134                         Indicates the accuracy of the derivative calculation for the GL shading language fragment processing built-in functions:
 135                         <constant>dFdx</constant>, <constant>dFdy</constant>, and <constant>fwidth</constant>.
 136                     </para>
 137                 </listitem>
 138             </varlistentry>
 139             <varlistentry>
 140                 <term><constant>GL_GENERATE_MIPMAP_HINT</constant></term>
 141                 <listitem>
 142                     <para>
 143                     </para>
 144                     <para>
 145                         Indicates the quality of filtering when generating mipmap images.
 146                     </para>
 147                 </listitem>
 148             </varlistentry>
 149             <varlistentry>
 150                 <term><constant>GL_LINE_SMOOTH_HINT</constant></term>
 151                 <listitem>
 152                     <para>
 153                     </para>
 154                     <para>
 155                         Indicates the sampling quality of antialiased lines.
 156                         If a larger filter function is applied, hinting <constant>GL_NICEST</constant> can
 157                         result in more pixel fragments being generated during rasterization.
 158                     </para>
 159                 </listitem>
 160             </varlistentry>
 161             <varlistentry>
 162                 <term><constant>GL_PERSPECTIVE_CORRECTION_HINT</constant></term>
 163                 <listitem>
 164                     <para>
 165                     </para>
 166                     <para>
 167                         Indicates the quality of color, texture coordinate, and fog coordinate
 168                         interpolation.  If perspective-corrected parameter interpolation is not
 169                         efficiently supported by the GL implementation, hinting <constant>GL_DONT_CARE</constant>
 170                         or <constant>GL_FASTEST</constant> can result in simple linear interpolation of colors
 171                         and/or texture coordinates.
 172                     </para>
 173                 </listitem>
 174             </varlistentry>
 175             <varlistentry>
 176                 <term><constant>GL_POINT_SMOOTH_HINT</constant></term>
 177                 <listitem>
 178                     <para>
 179                     </para>
 180                     <para>
 181                         Indicates the sampling quality of antialiased points.
 182                         If a larger filter function is applied, hinting <constant>GL_NICEST</constant> can
 183                         result in more pixel fragments being generated during rasterization.
 184                     </para>
 185                 </listitem>
 186             </varlistentry>
 187             <varlistentry>
 188                 <term><constant>GL_POLYGON_SMOOTH_HINT</constant></term>
 189                 <listitem>
 190                     <para>
 191                     </para>
 192                     <para>
 193                         Indicates the sampling quality of antialiased polygons.
 194                         Hinting <constant>GL_NICEST</constant> can result in more pixel fragments being generated
 195                         during rasterization,
 196                         if a larger filter function is applied.
 197                     </para>
 198                 </listitem>
 199             </varlistentry>
 200             <varlistentry>
 201                 <term><constant>GL_TEXTURE_COMPRESSION_HINT</constant></term>
 202                 <listitem>
 203                     <para>
 204                     </para>
 205                     <para>
 206                         Indicates the quality and performance of the compressing texture images.
 207                         Hinting <constant>GL_FASTEST</constant> indicates that texture images should be compressed
 208                         as quickly as possible, while <constant>GL_NICEST</constant> indicates that texture images
 209                         should be compressed with as little image quality loss as possible.
 210                         <constant>GL_NICEST</constant> should be selected if the texture is to be retrieved by
 211                         <citerefentry><refentrytitle>glGetCompressedTexImage</refentrytitle></citerefentry> for reuse.
 212                     </para>
 213                 </listitem>
 214             </varlistentry>
 215         </variablelist>
 216     </refsect1>
 217     <refsect1 id="notes"><title>Notes</title>
 218         <para>
 219             The interpretation of hints depends on the implementation.
 220             Some implementations ignore <function>glHint</function> settings.
 221         </para>
 222         <para>
 223             <constant>GL_TEXTURE_COMPRESSION_HINT</constant> is available only if the GL version is 1.3
 224             or greater.
 225         </para>
 226         <para>
 227             <constant>GL_GENERATE_MIPMAP_HINT</constant> is available only if the GL version is 1.4
 228             or greater.
 229         </para>
 230         <para>
 231             <constant>GL_FRAGMENT_SHADER_DERIVATIVE_HINT</constant> is available only if the GL version is 2.0
 232             or greater.
 233         </para>
 234     </refsect1>
 235     <refsect1 id="errors"><title>Errors</title>
 236         <para>
 237             <constant>GL_INVALID_ENUM</constant> is generated if either <parameter>target</parameter> or <parameter>mode</parameter> is not
 238             an accepted value.
 239         </para>
 240         <para>
 241             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glHint</function>
 242             is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
 243             and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 244         </para>
 245     </refsect1>
 246     <refsect1 id="Copyright"><title>Copyright</title>
 247         <para>
 248             Copyright <trademark class="copyright"></trademark> 1991-2006
 249             Silicon Graphics, Inc. This document is licensed under the SGI
 250             Free Software B License. For details, see
 251             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 252         </para>
 253     </refsect1>
 254 </refentry>