upstream-doc/man3/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_LINE_SMOOTH_HINT</constant>,
  36                     <constant>GL_POLYGON_SMOOTH_HINT</constant>,
  37                     <constant>GL_TEXTURE_COMPRESSION_HINT</constant>, and
  38                     <constant>GL_FRAGMENT_SHADER_DERIVATIVE_HINT</constant>
  39                     are accepted.
  40                 </para>
  41             </listitem>
  42         </varlistentry>
  43         <varlistentry>
  44             <term><parameter>mode</parameter></term>
  45             <listitem>
  46                 <para>
  47                     Specifies a symbolic constant indicating the desired behavior.
  48                     <constant>GL_FASTEST</constant>,
  49                     <constant>GL_NICEST</constant>, and
  50                     <constant>GL_DONT_CARE</constant> are accepted.
  51                 </para>
  52             </listitem>
  53         </varlistentry>
  54         </variablelist>
  55     </refsect1>
  56     <refsect1 id="description"><title>Description</title>
  57         <para>
  58             Certain aspects of GL behavior,
  59             when there is room for interpretation,
  60             can be controlled with hints.
  61             A hint is specified with two arguments.
  62             <parameter>target</parameter> is a symbolic
  63             constant indicating the behavior to be controlled,
  64             and <parameter>mode</parameter> is another symbolic constant indicating the desired
  65             behavior. The initial value for each <parameter>target</parameter> is <constant>GL_DONT_CARE</constant>.
  66             <parameter>mode</parameter> can be one of the following:
  67         </para>
  68         <variablelist>
  69             <varlistentry>
  70                 <term><constant>GL_FASTEST</constant></term>
  71                 <listitem>
  72                     <para>
  73                     </para>
  74                     <para>
  75                         The most efficient option should be chosen.
  76                     </para>
  77                 </listitem>
  78             </varlistentry>
  79             <varlistentry>
  80                 <term><constant>GL_NICEST</constant></term>
  81                 <listitem>
  82                     <para>
  83                     </para>
  84                     <para>
  85                         The most correct,
  86                         or highest quality,
  87                         option should be chosen.
  88                     </para>
  89                 </listitem>
  90             </varlistentry>
  91             <varlistentry>
  92                 <term><constant>GL_DONT_CARE</constant></term>
  93                 <listitem>
  94                     <para>
  95                     </para>
  96                     <para>
  97                         No preference.
  98                     </para>
  99                 </listitem>
 100             </varlistentry>
 101         </variablelist>
 102         <para>
 103             Though the implementation aspects that can be hinted are well defined,
 104             the interpretation of the hints depends on the implementation.
 105             The hint aspects that can be specified with <parameter>target</parameter>,
 106             along with suggested semantics,
 107             are as follows:
 108         </para>
 109         <variablelist>
 110             <varlistentry>
 111                 <term><constant>GL_FRAGMENT_SHADER_DERIVATIVE_HINT</constant></term>
 112                 <listitem>
 113                     <para>
 114                     </para>
 115                     <para>
 116                         Indicates the accuracy of the derivative calculation for the GL shading language fragment processing built-in functions:
 117                         <constant>dFdx</constant>, <constant>dFdy</constant>, and <constant>fwidth</constant>.
 118                     </para>
 119                 </listitem>
 120             </varlistentry>
 121             <varlistentry>
 122                 <term><constant>GL_LINE_SMOOTH_HINT</constant></term>
 123                 <listitem>
 124                     <para>
 125                     </para>
 126                     <para>
 127                         Indicates the sampling quality of antialiased lines.
 128                         If a larger filter function is applied, hinting <constant>GL_NICEST</constant> can
 129                         result in more pixel fragments being generated during rasterization.
 130                     </para>
 131                 </listitem>
 132             </varlistentry>
 133             <varlistentry>
 134                 <term><constant>GL_POLYGON_SMOOTH_HINT</constant></term>
 135                 <listitem>
 136                     <para>
 137                     </para>
 138                     <para>
 139                         Indicates the sampling quality of antialiased polygons.
 140                         Hinting <constant>GL_NICEST</constant> can result in more pixel fragments being generated
 141                         during rasterization,
 142                         if a larger filter function is applied.
 143                     </para>
 144                 </listitem>
 145             </varlistentry>
 146             <varlistentry>
 147                 <term><constant>GL_TEXTURE_COMPRESSION_HINT</constant></term>
 148                 <listitem>
 149                     <para>
 150                     </para>
 151                     <para>
 152                         Indicates the quality and performance of the compressing texture images.
 153                         Hinting <constant>GL_FASTEST</constant> indicates that texture images should be compressed
 154                         as quickly as possible, while <constant>GL_NICEST</constant> indicates that texture images
 155                         should be compressed with as little image quality loss as possible.
 156                         <constant>GL_NICEST</constant> should be selected if the texture is to be retrieved by
 157                         <citerefentry><refentrytitle>glGetCompressedTexImage</refentrytitle></citerefentry> for reuse.
 158                     </para>
 159                 </listitem>
 160             </varlistentry>
 161         </variablelist>
 162     </refsect1>
 163     <refsect1 id="notes"><title>Notes</title>
 164         <para>
 165             The interpretation of hints depends on the implementation.
 166             Some implementations ignore <function>glHint</function> settings.
 167         </para>
 168     </refsect1>
 169     <refsect1 id="errors"><title>Errors</title>
 170         <para>
 171             <constant>GL_INVALID_ENUM</constant> is generated if either <parameter>target</parameter> or <parameter>mode</parameter> is not
 172             an accepted value.
 173         </para>
 174     </refsect1>
 175     <refsect1 id="Copyright"><title>Copyright</title>
 176         <para>
 177             Copyright <trademark class="copyright"></trademark> 1991-2006
 178             Silicon Graphics, Inc. This document is licensed under the SGI
 179             Free Software B License. For details, see
 180             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 181         </para>
 182     </refsect1>
 183 </refentry>