upstream-man-pages/man2/glViewport.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="glViewport">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glViewport</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glViewport</refname>
  17         <refpurpose>set the viewport</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glViewport</function></funcdef>
  23                 <paramdef>GLint <parameter>x</parameter></paramdef>
  24                 <paramdef>GLint <parameter>y</parameter></paramdef>
  25                 <paramdef>GLsizei <parameter>width</parameter></paramdef>
  26                 <paramdef>GLsizei <parameter>height</parameter></paramdef>
  27             </funcprototype>
  28         </funcsynopsis>
  29     </refsynopsisdiv>
  30     <!-- eqn: ignoring delim $$ -->
  31     <refsect1 id="parameters"><title>Parameters</title>
  32         <variablelist>
  33         <varlistentry>
  34             <term><parameter>x</parameter></term>
  35             <term><parameter>y</parameter></term>
  36             <listitem>
  37                 <para>
  38                     Specify the lower left corner of the viewport rectangle,
  39                     in pixels. The initial value is (0,0).
  40                 </para>
  41             </listitem>
  42         </varlistentry>
  43         <varlistentry>
  44             <term><parameter>width</parameter></term>
  45             <term><parameter>height</parameter></term>
  46             <listitem>
  47                 <para>
  48                     Specify the width and height
  49                     of the viewport.
  50                     When a GL context is first attached to a window,
  51                     <parameter>width</parameter> and <parameter>height</parameter> are set to the dimensions of that
  52                     window.
  53                 </para>
  54             </listitem>
  55         </varlistentry>
  56         </variablelist>
  57     </refsect1>
  58     <refsect1 id="description"><title>Description</title>
  59         <para>
  60             <function>glViewport</function> specifies the affine transformation of
  61             <inlineequation><mml:math><mml:mi mathvariant="italic">x</mml:mi></mml:math></inlineequation>
  62             and
  63             <inlineequation><mml:math><mml:mi mathvariant="italic">y</mml:mi></mml:math></inlineequation>
  64             from
  65             normalized device coordinates to window coordinates.
  66             Let
  67             <inlineequation><mml:math>
  68                 <!-- eqn: (x sub nd, y sub nd):-->
  69                 <mml:mfenced open="(" close=")">
  70                     <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
  71                     <mml:mi mathvariant="italic">nd</mml:mi>
  72                     </mml:msub>
  73                     <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
  74                     <mml:mi mathvariant="italic">nd</mml:mi>
  75                     </mml:msub>
  76                 </mml:mfenced>
  77             </mml:math></inlineequation>
  78             be normalized device coordinates.
  79             Then the window coordinates
  80             <inlineequation><mml:math>
  81                 <!-- eqn: (x sub w, y sub w):-->
  82                 <mml:mfenced open="(" close=")">
  83                     <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
  84                     <mml:mi mathvariant="italic">w</mml:mi>
  85                     </mml:msub>
  86                     <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
  87                     <mml:mi mathvariant="italic">w</mml:mi>
  88                     </mml:msub>
  89                 </mml:mfenced>
  90             </mml:math></inlineequation>
  91             are computed as follows:
  92         </para>
  93         <para>
  94             <informalequation><mml:math>
  95                 <!-- eqn: x sub w  =  ( x sub nd  +  1 ) left ( width over 2 right )  +  x:-->
  96                 <mml:mrow>
  97                     <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
  98                     <mml:mi mathvariant="italic">w</mml:mi>
  99                     </mml:msub>
 100                     <mml:mo>=</mml:mo>
 101                     <mml:mrow>
 102                         <mml:mfenced open="(" close=")">
 103                             <mml:mrow>
 104                                 <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
 105                                 <mml:mi mathvariant="italic">nd</mml:mi>
 106                                 </mml:msub>
 107                                 <mml:mo>+</mml:mo>
 108                                 <mml:mn>1</mml:mn>
 109                             </mml:mrow>
 110                         </mml:mfenced>
 111                         <mml:mo>&it;</mml:mo>
 112                         <mml:mfenced open="(" close=")">
 113                             <mml:mfrac>
 114                                 <mml:mi mathvariant="italic">width</mml:mi>
 115                                 <mml:mn>2</mml:mn>
 116                             </mml:mfrac>
 117                         </mml:mfenced>
 118                         <mml:mo>+</mml:mo>
 119                         <mml:mi mathvariant="italic">x</mml:mi>
 120                     </mml:mrow>
 121                 </mml:mrow>
 122             </mml:math></informalequation>
 123         </para>
 124         <para>
 125             <informalequation><mml:math>
 126                 <!-- eqn: y sub w  =  ( y sub nd  +  1 ) left ( height over 2 right )  +  y:-->
 127                 <mml:mrow>
 128                     <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
 129                     <mml:mi mathvariant="italic">w</mml:mi>
 130                     </mml:msub>
 131                     <mml:mo>=</mml:mo>
 132                     <mml:mrow>
 133                         <mml:mfenced open="(" close=")">
 134                             <mml:mrow>
 135                                 <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
 136                                 <mml:mi mathvariant="italic">nd</mml:mi>
 137                                 </mml:msub>
 138                                 <mml:mo>+</mml:mo>
 139                                 <mml:mn>1</mml:mn>
 140                             </mml:mrow>
 141                         </mml:mfenced>
 142                         <mml:mo>&it;</mml:mo>
 143                         <mml:mfenced open="(" close=")">
 144                             <mml:mfrac>
 145                                 <mml:mi mathvariant="italic">height</mml:mi>
 146                                 <mml:mn>2</mml:mn>
 147                             </mml:mfrac>
 148                         </mml:mfenced>
 149                         <mml:mo>+</mml:mo>
 150                         <mml:mi mathvariant="italic">y</mml:mi>
 151                     </mml:mrow>
 152                 </mml:mrow>
 153             </mml:math></informalequation>
 154         </para>
 155         <para>
 156             Viewport width and height are silently clamped
 157             to a range that depends on the implementation.
 158             To query this range, call <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument
 159             <constant>GL_MAX_VIEWPORT_DIMS</constant>.
 160         </para>
 161     </refsect1>
 162     <refsect1 id="errors"><title>Errors</title>
 163         <para>
 164             <constant>GL_INVALID_VALUE</constant> is generated if either <parameter>width</parameter> or <parameter>height</parameter> is negative.
 165         </para>
 166         <para>
 167             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glViewport</function>
 168             is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
 169             and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 170         </para>
 171     </refsect1>
 172     <refsect1 id="associatedgets"><title>Associated Gets</title>
 173         <para>
 174             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_VIEWPORT</constant>
 175         </para>
 176         <para>
 177             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MAX_VIEWPORT_DIMS</constant>
 178         </para>
 179     </refsect1>
 180     <refsect1 id="seealso"><title>See Also</title>
 181         <para>
 182             <citerefentry><refentrytitle>glDepthRange</refentrytitle></citerefentry>
 183         </para>
 184     </refsect1>
 185     <refsect1 id="Copyright"><title>Copyright</title>
 186         <para>
 187             Copyright <trademark class="copyright"></trademark> 1991-2006
 188             Silicon Graphics, Inc. This document is licensed under the SGI
 189             Free Software B License. For details, see
 190             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 191         </para>
 192     </refsect1>
 193 </refentry>