upstream-man-pages/man2/glScale.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="glScale">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glScale</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glScale</refname>
  17         <refpurpose>multiply the current matrix by a general scaling matrix</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glScaled</function></funcdef>
  23                 <paramdef>GLdouble <parameter>x</parameter></paramdef>
  24                 <paramdef>GLdouble <parameter>y</parameter></paramdef>
  25                 <paramdef>GLdouble <parameter>z</parameter></paramdef>
  26             </funcprototype>
  27         </funcsynopsis>
  28         <funcsynopsis>
  29             <funcprototype>
  30                 <funcdef>void <function>glScalef</function></funcdef>
  31                 <paramdef>GLfloat <parameter>x</parameter></paramdef>
  32                 <paramdef>GLfloat <parameter>y</parameter></paramdef>
  33                 <paramdef>GLfloat <parameter>z</parameter></paramdef>
  34             </funcprototype>
  35         </funcsynopsis>
  36     </refsynopsisdiv>
  37     <!-- eqn: ignoring delim $$ -->
  38     <refsect1 id="parameters"><title>Parameters</title>
  39         <variablelist>
  40         <varlistentry>
  41             <term><parameter>x</parameter></term>
  42             <term><parameter>y</parameter></term>
  43             <term><parameter>z</parameter></term>
  44             <listitem>
  45                 <para>
  46                     Specify scale factors along the <emphasis>x</emphasis>, <emphasis>y</emphasis>, and <emphasis>z</emphasis> axes, respectively.
  47                 </para>
  48             </listitem>
  49         </varlistentry>
  50         </variablelist>
  51     </refsect1>
  52     <refsect1 id="description"><title>Description</title>
  53         <para>
  54             <function>glScale</function> produces a nonuniform scaling along the <emphasis>x</emphasis>, <emphasis>y</emphasis>, and
  55             <emphasis>z</emphasis> axes.
  56             The three parameters indicate the desired scale factor along
  57             each of the three axes.
  58         </para>
  59         <para>
  60             The current matrix
  61             (see <citerefentry><refentrytitle>glMatrixMode</refentrytitle></citerefentry>)
  62             is multiplied by this scale matrix,
  63             and the product replaces the current matrix
  64             as if <citerefentry><refentrytitle>glMultMatrix</refentrytitle></citerefentry> were called with the following matrix
  65             as its argument:
  66         </para>
  67         <para>
  68             <informalequation><mml:math>
  69                 <!-- eqn: left (   matrix {    ccol {  x above  0 above  0 above  0 }    ccol {  0 above  y above  0 above  0 }    ccol {  0 above  0 above  z above  0 }    ccol {  0 above  0 above  0 above  1} }    right ):-->
  70                 <mml:mfenced open="(" close=")">
  71                     <mml:mtable>
  72                         <mml:mtr>
  73                             <mml:mtd>
  74                                 <mml:mi mathvariant="italic">x</mml:mi>
  75                             </mml:mtd>
  76                             <mml:mtd>
  77                                 <mml:mn>0</mml:mn>
  78                             </mml:mtd>
  79                             <mml:mtd>
  80                                 <mml:mn>0</mml:mn>
  81                             </mml:mtd>
  82                             <mml:mtd>
  83                                 <mml:mn>0</mml:mn>
  84                             </mml:mtd>
  85                         </mml:mtr>
  86                         <mml:mtr>
  87                             <mml:mtd>
  88                                 <mml:mn>0</mml:mn>
  89                             </mml:mtd>
  90                             <mml:mtd>
  91                                 <mml:mi mathvariant="italic">y</mml:mi>
  92                             </mml:mtd>
  93                             <mml:mtd>
  94                                 <mml:mn>0</mml:mn>
  95                             </mml:mtd>
  96                             <mml:mtd>
  97                                 <mml:mn>0</mml:mn>
  98                             </mml:mtd>
  99                         </mml:mtr>
 100                         <mml:mtr>
 101                             <mml:mtd>
 102                                 <mml:mn>0</mml:mn>
 103                             </mml:mtd>
 104                             <mml:mtd>
 105                                 <mml:mn>0</mml:mn>
 106                             </mml:mtd>
 107                             <mml:mtd>
 108                                 <mml:mi mathvariant="italic">z</mml:mi>
 109                             </mml:mtd>
 110                             <mml:mtd>
 111                                 <mml:mn>0</mml:mn>
 112                             </mml:mtd>
 113                         </mml:mtr>
 114                         <mml:mtr>
 115                             <mml:mtd>
 116                                 <mml:mn>0</mml:mn>
 117                             </mml:mtd>
 118                             <mml:mtd>
 119                                 <mml:mn>0</mml:mn>
 120                             </mml:mtd>
 121                             <mml:mtd>
 122                                 <mml:mn>0</mml:mn>
 123                             </mml:mtd>
 124                             <mml:mtd>
 125                                 <mml:mn>1</mml:mn>
 126                             </mml:mtd>
 127                         </mml:mtr>
 128                     </mml:mtable>
 129                 </mml:mfenced>
 130             </mml:math></informalequation>
 131         </para>
 132         <para>
 133             If the matrix mode is either <constant>GL_MODELVIEW</constant> or <constant>GL_PROJECTION</constant>,
 134             all objects drawn after <function>glScale</function> is called are scaled.
 135         </para>
 136         <para>
 137             Use <citerefentry><refentrytitle>glPushMatrix</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glPopMatrix</refentrytitle></citerefentry> to save and restore
 138             the unscaled coordinate
 139             system.
 140         </para>
 141     </refsect1>
 142     <refsect1 id="notes"><title>Notes</title>
 143         <para>
 144             If scale factors other than 1 are applied to the modelview matrix
 145             and lighting is enabled, lighting often appears wrong.
 146             In that case, enable automatic normalization of normals by
 147             calling <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> with the argument <constant>GL_NORMALIZE</constant>.
 148         </para>
 149     </refsect1>
 150     <refsect1 id="errors"><title>Errors</title>
 151         <para>
 152             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glScale</function>
 153             is executed between the execution of
 154             <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
 155             and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 156         </para>
 157     </refsect1>
 158     <refsect1 id="associatedgets"><title>Associated Gets</title>
 159         <para>
 160             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MATRIX_MODE</constant>
 161         </para>
 162         <para>
 163             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_COLOR_MATRIX</constant>
 164         </para>
 165         <para>
 166             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MODELVIEW_MATRIX</constant>
 167         </para>
 168         <para>
 169             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PROJECTION_MATRIX</constant>
 170         </para>
 171         <para>
 172             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_MATRIX</constant>
 173         </para>
 174     </refsect1>
 175     <refsect1 id="seealso"><title>See Also</title>
 176         <para>
 177             <citerefentry><refentrytitle>glMatrixMode</refentrytitle></citerefentry>,
 178             <citerefentry><refentrytitle>glMultMatrix</refentrytitle></citerefentry>,
 179             <citerefentry><refentrytitle>glPushMatrix</refentrytitle></citerefentry>,
 180             <citerefentry><refentrytitle>glRotate</refentrytitle></citerefentry>,
 181             <citerefentry><refentrytitle>glTranslate</refentrytitle></citerefentry>
 182         </para>
 183     </refsect1>
 184     <refsect1 id="Copyright"><title>Copyright</title>
 185         <para>
 186             Copyright <trademark class="copyright"></trademark> 1991-2006
 187             Silicon Graphics, Inc. This document is licensed under the SGI
 188             Free Software B License. For details, see
 189             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 190         </para>
 191     </refsect1>
 192 </refentry>