upstream-doc/man2/glRotate.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="glRotate">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glRotate</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glRotate</refname>
  17         <refpurpose>multiply the current matrix by a rotation matrix</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glRotated</function></funcdef>
  23                 <paramdef>GLdouble <parameter>angle</parameter></paramdef>
  24                 <paramdef>GLdouble <parameter>x</parameter></paramdef>
  25                 <paramdef>GLdouble <parameter>y</parameter></paramdef>
  26                 <paramdef>GLdouble <parameter>z</parameter></paramdef>
  27             </funcprototype>
  28         </funcsynopsis>
  29         <funcsynopsis>
  30             <funcprototype>
  31                 <funcdef>void <function>glRotatef</function></funcdef>
  32                 <paramdef>GLfloat <parameter>angle</parameter></paramdef>
  33                 <paramdef>GLfloat <parameter>x</parameter></paramdef>
  34                 <paramdef>GLfloat <parameter>y</parameter></paramdef>
  35                 <paramdef>GLfloat <parameter>z</parameter></paramdef>
  36             </funcprototype>
  37         </funcsynopsis>
  38     </refsynopsisdiv>
  39     <!-- eqn: ignoring delim $$ -->
  40     <refsect1 id="parameters"><title>Parameters</title>
  41         <variablelist>
  42         <varlistentry>
  43             <term><parameter>angle</parameter></term>
  44             <listitem>
  45                 <para>
  46                     Specifies the angle of rotation, in degrees.
  47                 </para>
  48             </listitem>
  49         </varlistentry>
  50         <varlistentry>
  51             <term><parameter>x</parameter></term>
  52             <term><parameter>y</parameter></term>
  53             <term><parameter>z</parameter></term>
  54             <listitem>
  55                 <para>
  56                     Specify the <emphasis>x</emphasis>, <emphasis>y</emphasis>, and <emphasis>z</emphasis> coordinates of a vector, respectively.
  57                 </para>
  58             </listitem>
  59         </varlistentry>
  60         </variablelist>
  61     </refsect1>
  62     <refsect1 id="description"><title>Description</title>
  63         <para>
  64             <function>glRotate</function> produces a rotation of <parameter>angle</parameter> degrees around
  65             the vector
  66             <inlineequation><mml:math>
  67                 <!-- eqn: (x, y, z):-->
  68                 <mml:mfenced open="(" close=")">
  69                     <mml:mi mathvariant="italic">x</mml:mi>
  70                     <mml:mi mathvariant="italic">y</mml:mi>
  71                     <mml:mi mathvariant="italic">z</mml:mi>
  72                 </mml:mfenced>
  73             </mml:math></inlineequation>.
  74             The current matrix (see <citerefentry><refentrytitle>glMatrixMode</refentrytitle></citerefentry>) is multiplied by a rotation
  75             matrix with the product
  76             replacing the current matrix, as if <citerefentry><refentrytitle>glMultMatrix</refentrytitle></citerefentry> were called
  77             with the following matrix as its argument:
  78         </para>
  79         <para>
  80             <informalequation><mml:math>
  81                 <!-- eqn: left (   matrix {  ccol {    x sup 2 (1  -  c) +  c above    y x (1  -  c) +  z s above    x z (1  -  c) - y s above     0  }  ccol {       x y (1  -  c) - z s above       y sup 2 (1  -  c) +  c above       y z (1  -  c) +  x s above        0  }  ccol {       x z (1  -  c) +  y s above       y z (1  -  c) -  x s above       z sup 2 (1  -  c)  +   c above        0  }  ccol {  0 above  0 above  0 above  1} }    right ):-->
  82                 <mml:mfenced open="(" close=")">
  83                     <mml:mtable>
  84                         <mml:mtr>
  85                             <mml:mtd>
  86                                 <mml:mrow>
  87                                     <mml:mrow>
  88                                         <mml:msup><mml:mi mathvariant="italic">x</mml:mi>
  89                                         <mml:mn>2</mml:mn>
  90                                         </mml:msup>
  91                                         <mml:mo>&af;</mml:mo>
  92                                         <mml:mfenced open="(" close=")">
  93                                             <mml:mrow>
  94                                                 <mml:mn>1</mml:mn>
  95                                                 <mml:mo>-</mml:mo>
  96                                                 <mml:mi mathvariant="italic">c</mml:mi>
  97                                             </mml:mrow>
  98                                         </mml:mfenced>
  99                                     </mml:mrow>
 100                                     <mml:mo>+</mml:mo>
 101                                     <mml:mi mathvariant="italic">c</mml:mi>
 102                                 </mml:mrow>
 103                             </mml:mtd>
 104                             <mml:mtd>
 105                                 <mml:mrow>
 106                                     <mml:mi mathvariant="italic">x</mml:mi>
 107                                     <mml:mo>&it;</mml:mo>
 108                                     <mml:mrow>
 109                                         <mml:mi mathvariant="italic">y</mml:mi>
 110                                         <mml:mo>&af;</mml:mo>
 111                                         <mml:mfenced open="(" close=")">
 112                                             <mml:mrow>
 113                                                 <mml:mn>1</mml:mn>
 114                                                 <mml:mo>-</mml:mo>
 115                                                 <mml:mi mathvariant="italic">c</mml:mi>
 116                                             </mml:mrow>
 117                                         </mml:mfenced>
 118                                     </mml:mrow>
 119                                     <mml:mo>-</mml:mo>
 120                                     <mml:mi mathvariant="italic">z</mml:mi>
 121                                     <mml:mo>&it;</mml:mo>
 122                                     <mml:mi mathvariant="italic">s</mml:mi>
 123                                 </mml:mrow>
 124                             </mml:mtd>
 125                             <mml:mtd>
 126                                 <mml:mrow>
 127                                     <mml:mi mathvariant="italic">x</mml:mi>
 128                                     <mml:mo>&it;</mml:mo>
 129                                     <mml:mrow>
 130                                         <mml:mi mathvariant="italic">z</mml:mi>
 131                                         <mml:mo>&af;</mml:mo>
 132                                         <mml:mfenced open="(" close=")">
 133                                             <mml:mrow>
 134                                                 <mml:mn>1</mml:mn>
 135                                                 <mml:mo>-</mml:mo>
 136                                                 <mml:mi mathvariant="italic">c</mml:mi>
 137                                             </mml:mrow>
 138                                         </mml:mfenced>
 139                                     </mml:mrow>
 140                                     <mml:mo>+</mml:mo>
 141                                     <mml:mi mathvariant="italic">y</mml:mi>
 142                                     <mml:mo>&it;</mml:mo>
 143                                     <mml:mi mathvariant="italic">s</mml:mi>
 144                                 </mml:mrow>
 145                             </mml:mtd>
 146                             <mml:mtd>
 147                                 <mml:mn>0</mml:mn>
 148                             </mml:mtd>
 149                         </mml:mtr>
 150                         <mml:mtr>
 151                             <mml:mtd>
 152                                 <mml:mrow>
 153                                     <mml:mi mathvariant="italic">y</mml:mi>
 154                                     <mml:mo>&it;</mml:mo>
 155                                     <mml:mrow>
 156                                         <mml:mi mathvariant="italic">x</mml:mi>
 157                                         <mml:mo>&af;</mml:mo>
 158                                         <mml:mfenced open="(" close=")">
 159                                             <mml:mrow>
 160                                                 <mml:mn>1</mml:mn>
 161                                                 <mml:mo>-</mml:mo>
 162                                                 <mml:mi mathvariant="italic">c</mml:mi>
 163                                             </mml:mrow>
 164                                         </mml:mfenced>
 165                                     </mml:mrow>
 166                                     <mml:mo>+</mml:mo>
 167                                     <mml:mi mathvariant="italic">z</mml:mi>
 168                                     <mml:mo>&it;</mml:mo>
 169                                     <mml:mi mathvariant="italic">s</mml:mi>
 170                                 </mml:mrow>
 171                             </mml:mtd>
 172                             <mml:mtd>
 173                                 <mml:mrow>
 174                                     <mml:mrow>
 175                                         <mml:msup><mml:mi mathvariant="italic">y</mml:mi>
 176                                         <mml:mn>2</mml:mn>
 177                                         </mml:msup>
 178                                         <mml:mo>&af;</mml:mo>
 179                                         <mml:mfenced open="(" close=")">
 180                                             <mml:mrow>
 181                                                 <mml:mn>1</mml:mn>
 182                                                 <mml:mo>-</mml:mo>
 183                                                 <mml:mi mathvariant="italic">c</mml:mi>
 184                                             </mml:mrow>
 185                                         </mml:mfenced>
 186                                     </mml:mrow>
 187                                     <mml:mo>+</mml:mo>
 188                                     <mml:mi mathvariant="italic">c</mml:mi>
 189                                 </mml:mrow>
 190                             </mml:mtd>
 191                             <mml:mtd>
 192                                 <mml:mrow>
 193                                     <mml:mi mathvariant="italic">y</mml:mi>
 194                                     <mml:mo>&it;</mml:mo>
 195                                     <mml:mrow>
 196                                         <mml:mi mathvariant="italic">z</mml:mi>
 197                                         <mml:mo>&af;</mml:mo>
 198                                         <mml:mfenced open="(" close=")">
 199                                             <mml:mrow>
 200                                                 <mml:mn>1</mml:mn>
 201                                                 <mml:mo>-</mml:mo>
 202                                                 <mml:mi mathvariant="italic">c</mml:mi>
 203                                             </mml:mrow>
 204                                         </mml:mfenced>
 205                                     </mml:mrow>
 206                                     <mml:mo>-</mml:mo>
 207                                     <mml:mi mathvariant="italic">x</mml:mi>
 208                                     <mml:mo>&it;</mml:mo>
 209                                     <mml:mi mathvariant="italic">s</mml:mi>
 210                                 </mml:mrow>
 211                             </mml:mtd>
 212                             <mml:mtd>
 213                                 <mml:mn>0</mml:mn>
 214                             </mml:mtd>
 215                         </mml:mtr>
 216                         <mml:mtr>
 217                             <mml:mtd>
 218                                 <mml:mrow>
 219                                     <mml:mi mathvariant="italic">x</mml:mi>
 220                                     <mml:mo>&it;</mml:mo>
 221                                     <mml:mrow>
 222                                         <mml:mi mathvariant="italic">z</mml:mi>
 223                                         <mml:mo>&af;</mml:mo>
 224                                         <mml:mfenced open="(" close=")">
 225                                             <mml:mrow>
 226                                                 <mml:mn>1</mml:mn>
 227                                                 <mml:mo>-</mml:mo>
 228                                                 <mml:mi mathvariant="italic">c</mml:mi>
 229                                             </mml:mrow>
 230                                         </mml:mfenced>
 231                                     </mml:mrow>
 232                                     <mml:mo>-</mml:mo>
 233                                     <mml:mi mathvariant="italic">y</mml:mi>
 234                                     <mml:mo>&it;</mml:mo>
 235                                     <mml:mi mathvariant="italic">s</mml:mi>
 236                                 </mml:mrow>
 237                             </mml:mtd>
 238                             <mml:mtd>
 239                                 <mml:mrow>
 240                                     <mml:mi mathvariant="italic">y</mml:mi>
 241                                     <mml:mo>&it;</mml:mo>
 242                                     <mml:mrow>
 243                                         <mml:mi mathvariant="italic">z</mml:mi>
 244                                         <mml:mo>&af;</mml:mo>
 245                                         <mml:mfenced open="(" close=")">
 246                                             <mml:mrow>
 247                                                 <mml:mn>1</mml:mn>
 248                                                 <mml:mo>-</mml:mo>
 249                                                 <mml:mi mathvariant="italic">c</mml:mi>
 250                                             </mml:mrow>
 251                                         </mml:mfenced>
 252                                     </mml:mrow>
 253                                     <mml:mo>+</mml:mo>
 254                                     <mml:mi mathvariant="italic">x</mml:mi>
 255                                     <mml:mo>&it;</mml:mo>
 256                                     <mml:mi mathvariant="italic">s</mml:mi>
 257                                 </mml:mrow>
 258                             </mml:mtd>
 259                             <mml:mtd>
 260                                 <mml:mrow>
 261                                     <mml:mrow>
 262                                         <mml:msup><mml:mi mathvariant="italic">z</mml:mi>
 263                                         <mml:mn>2</mml:mn>
 264                                         </mml:msup>
 265                                         <mml:mo>&af;</mml:mo>
 266                                         <mml:mfenced open="(" close=")">
 267                                             <mml:mrow>
 268                                                 <mml:mn>1</mml:mn>
 269                                                 <mml:mo>-</mml:mo>
 270                                                 <mml:mi mathvariant="italic">c</mml:mi>
 271                                             </mml:mrow>
 272                                         </mml:mfenced>
 273                                     </mml:mrow>
 274                                     <mml:mo>+</mml:mo>
 275                                     <mml:mi mathvariant="italic">c</mml:mi>
 276                                 </mml:mrow>
 277                             </mml:mtd>
 278                             <mml:mtd>
 279                                 <mml:mn>0</mml:mn>
 280                             </mml:mtd>
 281                         </mml:mtr>
 282                         <mml:mtr>
 283                             <mml:mtd>
 284                                 <mml:mn>0</mml:mn>
 285                             </mml:mtd>
 286                             <mml:mtd>
 287                                 <mml:mn>0</mml:mn>
 288                             </mml:mtd>
 289                             <mml:mtd>
 290                                 <mml:mn>0</mml:mn>
 291                             </mml:mtd>
 292                             <mml:mtd>
 293                                 <mml:mn>1</mml:mn>
 294                             </mml:mtd>
 295                         </mml:mtr>
 296                     </mml:mtable>
 297                 </mml:mfenced>
 298             </mml:math></informalequation>
 299         </para>
 300         <para>
 301         </para>
 302         <para>
 303             Where
 304             <inlineequation><mml:math>
 305                 <!-- eqn: c  =  cos (angle):-->
 306                 <mml:mrow>
 307                     <mml:mi mathvariant="italic">c</mml:mi>
 308                     <mml:mo>=</mml:mo>
 309                     <mml:mrow>
 310                         <mml:mi mathvariant="italic">cos</mml:mi>
 311                         <mml:mo>&af;</mml:mo>
 312                         <mml:mfenced open="(" close=")">
 313                             <mml:mi mathvariant="italic">angle</mml:mi>
 314                         </mml:mfenced>
 315                     </mml:mrow>
 316                 </mml:mrow>
 317             </mml:math></inlineequation>,
 318             <inlineequation><mml:math>
 319                 <!-- eqn: s  =  sin (angle):-->
 320                 <mml:mrow>
 321                     <mml:mi mathvariant="italic">s</mml:mi>
 322                     <mml:mo>=</mml:mo>
 323                     <mml:mrow>
 324                         <mml:mi mathvariant="italic">sin</mml:mi>
 325                         <mml:mo>&af;</mml:mo>
 326                         <mml:mfenced open="(" close=")">
 327                             <mml:mi mathvariant="italic">angle</mml:mi>
 328                         </mml:mfenced>
 329                     </mml:mrow>
 330                 </mml:mrow>
 331             </mml:math></inlineequation>,
 332             and
 333             <inlineequation><mml:math>
 334                 <!-- eqn: ||( x, y, z )||  =  1:-->
 335                 <mml:mrow>
 336                     <mml:mfenced open="&DoubleVerticalBar;" close="&DoubleVerticalBar;">
 337                         <mml:mfenced open="(" close=")">
 338                             <mml:mi mathvariant="italic">x</mml:mi>
 339                             <mml:mi mathvariant="italic">y</mml:mi>
 340                             <mml:mi mathvariant="italic">z</mml:mi>
 341                         </mml:mfenced>
 342                     </mml:mfenced>
 343                     <mml:mo>=</mml:mo>
 344                     <mml:mn>1</mml:mn>
 345                 </mml:mrow>
 346             </mml:math></inlineequation>
 347             (if not, the GL
 348             will normalize this vector).
 349         </para>
 350         <para>
 351         </para>
 352         <para>
 353         </para>
 354         <para>
 355             If the matrix mode is either <constant>GL_MODELVIEW</constant> or <constant>GL_PROJECTION</constant>,
 356             all objects drawn after <function>glRotate</function> is called are rotated.
 357             Use <citerefentry><refentrytitle>glPushMatrix</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glPopMatrix</refentrytitle></citerefentry> to save and restore
 358             the unrotated coordinate system.
 359         </para>
 360     </refsect1>
 361     <refsect1 id="notes"><title>Notes</title>
 362         <para>
 363             This rotation follows the right-hand rule, so
 364             if the vector
 365             <inlineequation><mml:math>
 366                 <!-- eqn: (x, y, z):-->
 367                 <mml:mfenced open="(" close=")">
 368                     <mml:mi mathvariant="italic">x</mml:mi>
 369                     <mml:mi mathvariant="italic">y</mml:mi>
 370                     <mml:mi mathvariant="italic">z</mml:mi>
 371                 </mml:mfenced>
 372             </mml:math></inlineequation>
 373             points toward the
 374             user, the rotation will be counterclockwise.
 375         </para>
 376     </refsect1>
 377     <refsect1 id="errors"><title>Errors</title>
 378         <para>
 379             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glRotate</function>
 380             is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
 381             and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 382         </para>
 383     </refsect1>
 384     <refsect1 id="associatedgets"><title>Associated Gets</title>
 385         <para>
 386             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MATRIX_MODE</constant>
 387         </para>
 388         <para>
 389             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_COLOR_MATRIX</constant>
 390         </para>
 391         <para>
 392             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MODELVIEW_MATRIX</constant>
 393         </para>
 394         <para>
 395             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PROJECTION_MATRIX</constant>
 396         </para>
 397         <para>
 398             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_MATRIX</constant>
 399         </para>
 400     </refsect1>
 401     <refsect1 id="seealso"><title>See Also</title>
 402         <para>
 403             <citerefentry><refentrytitle>glMatrixMode</refentrytitle></citerefentry>,
 404             <citerefentry><refentrytitle>glMultMatrix</refentrytitle></citerefentry>,
 405             <citerefentry><refentrytitle>glPushMatrix</refentrytitle></citerefentry>,
 406             <citerefentry><refentrytitle>glScale</refentrytitle></citerefentry>,
 407             <citerefentry><refentrytitle>glTranslate</refentrytitle></citerefentry>
 408         </para>
 409     </refsect1>
 410     <refsect1 id="Copyright"><title>Copyright</title>
 411         <para>
 412             Copyright <trademark class="copyright"></trademark> 1991-2006
 413             Silicon Graphics, Inc. This document is licensed under the SGI
 414             Free Software B License. For details, see
 415             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 416         </para>
 417     </refsect1>
 418 </refentry>