upstream-doc/man2/glNormal.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="glNormal">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glNormal</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glNormal</refname>
  17         <refpurpose>set the current normal vector</refpurpose>
  18     </refnamediv>
  19     <!-- eqn: ignoring delim $$ -->
  20     <refsynopsisdiv><title>C Specification</title>
  21         <funcsynopsis>
  22             <funcprototype>
  23                 <funcdef>void <function>glNormal3b</function></funcdef>
  24                 <paramdef>GLbyte <parameter>nx</parameter></paramdef>
  25                 <paramdef>GLbyte <parameter>ny</parameter></paramdef>
  26                 <paramdef>GLbyte <parameter>nz</parameter></paramdef>
  27             </funcprototype>
  28         </funcsynopsis>
  29         <funcsynopsis>
  30             <funcprototype>
  31                 <funcdef>void <function>glNormal3d</function></funcdef>
  32                 <paramdef>GLdouble <parameter>nx</parameter></paramdef>
  33                 <paramdef>GLdouble <parameter>ny</parameter></paramdef>
  34                 <paramdef>GLdouble <parameter>nz</parameter></paramdef>
  35             </funcprototype>
  36         </funcsynopsis>
  37         <funcsynopsis>
  38             <funcprototype>
  39                 <funcdef>void <function>glNormal3f</function></funcdef>
  40                 <paramdef>GLfloat <parameter>nx</parameter></paramdef>
  41                 <paramdef>GLfloat <parameter>ny</parameter></paramdef>
  42                 <paramdef>GLfloat <parameter>nz</parameter></paramdef>
  43             </funcprototype>
  44         </funcsynopsis>
  45         <funcsynopsis>
  46             <funcprototype>
  47                 <funcdef>void <function>glNormal3i</function></funcdef>
  48                 <paramdef>GLint <parameter>nx</parameter></paramdef>
  49                 <paramdef>GLint <parameter>ny</parameter></paramdef>
  50                 <paramdef>GLint <parameter>nz</parameter></paramdef>
  51             </funcprototype>
  52         </funcsynopsis>
  53         <funcsynopsis>
  54             <funcprototype>
  55                 <funcdef>void <function>glNormal3s</function></funcdef>
  56                 <paramdef>GLshort <parameter>nx</parameter></paramdef>
  57                 <paramdef>GLshort <parameter>ny</parameter></paramdef>
  58                 <paramdef>GLshort <parameter>nz</parameter></paramdef>
  59             </funcprototype>
  60         </funcsynopsis>
  61     </refsynopsisdiv>
  62     <refsect1 id="parameters"><title>Parameters</title>
  63         <variablelist>
  64         <varlistentry>
  65             <term><parameter>nx</parameter></term>
  66             <term><parameter>ny</parameter></term>
  67             <term><parameter>nz</parameter></term>
  68             <listitem>
  69                 <para>
  70                     Specify the
  71                     <inlineequation><mml:math><mml:mi mathvariant="italic">x</mml:mi></mml:math></inlineequation>,
  72                     <inlineequation><mml:math><mml:mi mathvariant="italic">y</mml:mi></mml:math></inlineequation>,
  73                     and
  74                     <inlineequation><mml:math><mml:mi mathvariant="italic">z</mml:mi></mml:math></inlineequation>
  75                     coordinates of the new current normal.
  76                     The initial value of the current normal is the unit vector, (0, 0, 1).
  77                 </para>
  78                 <para>
  79                 </para>
  80             </listitem>
  81         </varlistentry>
  82         </variablelist>
  83     </refsect1>
  84     <refsynopsisdiv><title>C Specification</title>
  85         <funcsynopsis>
  86             <funcprototype>
  87                 <funcdef>void <function>glNormal3bv</function></funcdef>
  88                 <paramdef>const GLbyte * <parameter>v</parameter></paramdef>
  89             </funcprototype>
  90         </funcsynopsis>
  91         <funcsynopsis>
  92             <funcprototype>
  93                 <funcdef>void <function>glNormal3dv</function></funcdef>
  94                 <paramdef>const GLdouble * <parameter>v</parameter></paramdef>
  95             </funcprototype>
  96         </funcsynopsis>
  97         <funcsynopsis>
  98             <funcprototype>
  99                 <funcdef>void <function>glNormal3fv</function></funcdef>
 100                 <paramdef>const GLfloat * <parameter>v</parameter></paramdef>
 101             </funcprototype>
 102         </funcsynopsis>
 103         <funcsynopsis>
 104             <funcprototype>
 105                 <funcdef>void <function>glNormal3iv</function></funcdef>
 106                 <paramdef>const GLint * <parameter>v</parameter></paramdef>
 107             </funcprototype>
 108         </funcsynopsis>
 109         <funcsynopsis>
 110             <funcprototype>
 111                 <funcdef>void <function>glNormal3sv</function></funcdef>
 112                 <paramdef>const GLshort * <parameter>v</parameter></paramdef>
 113             </funcprototype>
 114         </funcsynopsis>
 115     </refsynopsisdiv>
 116     <refsect1 id="parameters2"><title>Parameters</title>
 117         <variablelist>
 118         <varlistentry>
 119             <term><parameter>v</parameter></term>
 120             <listitem>
 121                 <para>
 122                     Specifies a pointer to an array of three elements:
 123                     the
 124                     <inlineequation><mml:math><mml:mi mathvariant="italic">x</mml:mi></mml:math></inlineequation>,
 125                     <inlineequation><mml:math><mml:mi mathvariant="italic">y</mml:mi></mml:math></inlineequation>,
 126                     and
 127                     <inlineequation><mml:math><mml:mi mathvariant="italic">z</mml:mi></mml:math></inlineequation>
 128                     coordinates of the new current normal.
 129                 </para>
 130                 <para>
 131                 </para>
 132             </listitem>
 133         </varlistentry>
 134         </variablelist>
 135     </refsect1>
 136     <refsect1 id="description"><title>Description</title>
 137         <para>
 138             The current normal is set to the given coordinates
 139             whenever <function>glNormal</function> is issued.
 140             Byte, short, or integer arguments are converted to floating-point
 141             format with a linear mapping that maps the most positive representable integer
 142             value to 1.0
 143             and the most negative representable integer value to
 144             <inlineequation><mml:math>
 145                 <!-- eqn: -1.0:-->
 146                 <mml:mn>-1.0</mml:mn>
 147             </mml:math></inlineequation>.
 148         </para>
 149         <para>
 150             Normals specified with <function>glNormal</function> need not have unit length.
 151             If <constant>GL_NORMALIZE</constant> is enabled,
 152             then normals of any length specified with <function>glNormal</function> are normalized after transformation.
 153             If <constant>GL_RESCALE_NORMAL</constant> is enabled, normals are scaled by a scaling factor
 154             derived from the modelview matrix.  <constant>GL_RESCALE_NORMAL</constant> requires that the
 155             originally specified normals were of unit length, and that the modelview
 156             matrix contain only uniform scales for proper results.
 157             To enable and disable normalization, call <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry>
 158             with either <constant>GL_NORMALIZE</constant> or <constant>GL_RESCALE_NORMAL</constant>.
 159             Normalization is initially disabled.
 160         </para>
 161     </refsect1>
 162     <refsect1 id="notes"><title>Notes</title>
 163         <para>
 164             The current normal can be updated at any time.
 165             In particular, <function>glNormal</function> can be called between a call to <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and
 166             the corresponding call to <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 167         </para>
 168     </refsect1>
 169     <refsect1 id="associatedgets"><title>Associated Gets</title>
 170         <para>
 171             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_NORMAL</constant>
 172         </para>
 173         <para>
 174             <citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_NORMALIZE</constant>
 175         </para>
 176         <para>
 177             <citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_RESCALE_NORMAL</constant>
 178         </para>
 179     </refsect1>
 180     <refsect1 id="seealso"><title>See Also</title>
 181         <para>
 182             <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>,
 183             <citerefentry><refentrytitle>glColor</refentrytitle></citerefentry>,
 184             <citerefentry><refentrytitle>glIndex</refentrytitle></citerefentry>,
 185             <citerefentry><refentrytitle>glMultiTexCoord</refentrytitle></citerefentry>,
 186             <citerefentry><refentrytitle>glNormalPointer</refentrytitle></citerefentry>,
 187             <citerefentry><refentrytitle>glTexCoord</refentrytitle></citerefentry>,
 188             <citerefentry><refentrytitle>glVertex</refentrytitle></citerefentry>
 189         </para>
 190     </refsect1>
 191     <refsect1 id="Copyright"><title>Copyright</title>
 192         <para>
 193             Copyright <trademark class="copyright"></trademark> 1991-2006
 194             Silicon Graphics, Inc. This document is licensed under the SGI
 195             Free Software B License. For details, see
 196             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 197         </para>
 198     </refsect1>
 199 </refentry>