upstream-doc/man4/glViewportIndexed.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="glViewportIndexed">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>2010</year>
   9                 <holder>Khronos Group</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glViewportIndexed</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glViewportIndexed</refname>
  17         <refpurpose>set a specified viewport</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glViewportIndexedf</function></funcdef>
  23                 <paramdef>GLuint <parameter>index</parameter></paramdef>
  24                 <paramdef>GLfloat <parameter>x</parameter></paramdef>
  25                 <paramdef>GLfloat <parameter>y</parameter></paramdef>
  26                 <paramdef>GLfloat <parameter>w</parameter></paramdef>
  27                 <paramdef>GLfloat <parameter>h</parameter></paramdef>
  28             </funcprototype>
  29         </funcsynopsis>
  30         <funcsynopsis>
  31             <funcprototype>
  32                 <funcdef>void <function>glViewportIndexedfv</function></funcdef>
  33                 <paramdef>GLuint <parameter>index</parameter></paramdef>
  34                 <paramdef>const GLfloat *<parameter>v</parameter></paramdef>
  35             </funcprototype>
  36         </funcsynopsis>
  37     </refsynopsisdiv>
  38     <!-- eqn: ignoring delim $$ -->
  39     <refsect1 id="parameters"><title>Parameters</title>
  40         <variablelist>
  41         <varlistentry>
  42             <term><parameter>index</parameter></term>
  43             <listitem>
  44                 <para>
  45                    Specify the first viewport to set.
  46                 </para>
  47             </listitem>
  48         </varlistentry>
  49         <varlistentry>
  50             <term><parameter>x</parameter></term>
  51             <term><parameter>y</parameter></term>
  52             <listitem>
  53                 <para>
  54                     For <function>glViewportIndexedf</function>, specifies the lower left corner of
  55                     the viewport rectangle, in pixels. The initial value is (0,0).
  56                 </para>
  57             </listitem>
  58         </varlistentry>
  59         <varlistentry>
  60             <term><parameter>width</parameter></term>
  61             <term><parameter>height</parameter></term>
  62             <listitem>
  63                 <para>
  64                     For <function>glViewportIndexedf</function>, specifies the width and height
  65                     of the viewport.
  66                     When a GL context is first attached to a window,
  67                     <parameter>width</parameter> and <parameter>height</parameter> are set to the dimensions of that
  68                     window.
  69                 </para>
  70             </listitem>
  71         </varlistentry>
  72         <varlistentry>
  73             <term><parameter>v</parameter></term>
  74             <listitem>
  75                 <para>
  76                    For <function>glViewportIndexedfv</function>, specifies the address of an array containing the viewport parameters.
  77                 </para>
  78             </listitem>
  79         </varlistentry>
  80         </variablelist>
  81     </refsect1>
  82     <refsect1 id="description"><title>Description</title>
  83         <para>
  84             <function>glViewportIndexedf</function> and <function>glViewportIndexedfv</function>
  85             specify the parameters for a single viewport.
  86             <parameter>index</parameter> specifies the index of the viewport
  87             to modify.
  88             <parameter>index</parameter> must be less than the value of <constant>GL_MAX_VIEWPORTS</constant>.
  89             For <function>glViewportIndexedf</function>, <parameter>x</parameter>, <parameter>y</parameter>,
  90             <parameter>w</parameter>, and <parameter>h</parameter> specify the left, bottom, width and height
  91             of the viewport in pixels, respectively.
  92             For <function>glViewportIndexedfv</function>, <parameter>v</parameter> contains the address of an array of floating
  93             point values specifying the
  94             left (<inlineequation><mml:math><mml:mi mathvariant="italic">x</mml:mi></mml:math></inlineequation>),
  95             bottom (<inlineequation><mml:math><mml:mi mathvariant="italic">y</mml:mi></mml:math></inlineequation>),
  96             width (<inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>),
  97             and height (<inlineequation><mml:math><mml:mi mathvariant="italic">h</mml:mi></mml:math></inlineequation>)
  98             of each viewport, in that order. <inlineequation><mml:math><mml:mi mathvariant="italic">x</mml:mi></mml:math></inlineequation>
  99             and <inlineequation><mml:math><mml:mi mathvariant="italic">y</mml:mi></mml:math></inlineequation> give
 100             the location of the viewport's lower left corner, and
 101             <inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
 102             and <inlineequation><mml:math><mml:mi mathvariant="italic">h</mml:mi></mml:math></inlineequation>
 103             give the width and height of the viewport, respectively.
 104             The viewport specifies the affine transformation of
 105             <inlineequation><mml:math><mml:mi mathvariant="italic">x</mml:mi></mml:math></inlineequation>
 106             and
 107             <inlineequation><mml:math><mml:mi mathvariant="italic">y</mml:mi></mml:math></inlineequation>
 108             from
 109             normalized device coordinates to window coordinates.
 110             Let
 111             <inlineequation><mml:math>
 112                 <!-- eqn: (x sub nd, y sub nd): -->
 113                 <mml:mfenced open="(" close=")">
 114                     <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
 115                     <mml:mi mathvariant="italic">nd</mml:mi>
 116                     </mml:msub>
 117                     <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
 118                     <mml:mi mathvariant="italic">nd</mml:mi>
 119                     </mml:msub>
 120                 </mml:mfenced>
 121             </mml:math></inlineequation>
 122             be normalized device coordinates.
 123             Then the window coordinates
 124             <inlineequation><mml:math>
 125                 <!-- eqn: (x sub w, y sub w): -->
 126                 <mml:mfenced open="(" close=")">
 127                     <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
 128                     <mml:mi mathvariant="italic">w</mml:mi>
 129                     </mml:msub>
 130                     <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
 131                     <mml:mi mathvariant="italic">w</mml:mi>
 132                     </mml:msub>
 133                 </mml:mfenced>
 134             </mml:math></inlineequation>
 135             are computed as follows:
 136         </para>
 137         <para>
 138             <informalequation><mml:math>
 139                 <!-- eqn: x sub w  =  ( x sub nd  +  1 ) left ( width over 2 right )  +  x: -->
 140                 <mml:mrow>
 141                     <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
 142                     <mml:mi mathvariant="italic">w</mml:mi>
 143                     </mml:msub>
 144                     <mml:mo>=</mml:mo>
 145                     <mml:mrow>
 146                         <mml:mfenced open="(" close=")">
 147                             <mml:mrow>
 148                                 <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
 149                                 <mml:mi mathvariant="italic">nd</mml:mi>
 150                                 </mml:msub>
 151                                 <mml:mo>+</mml:mo>
 152                                 <mml:mn>1</mml:mn>
 153                             </mml:mrow>
 154                         </mml:mfenced>
 155                         <mml:mo>&it;</mml:mo>
 156                         <mml:mfenced open="(" close=")">
 157                             <mml:mfrac>
 158                                 <mml:mi mathvariant="italic">width</mml:mi>
 159                                 <mml:mn>2</mml:mn>
 160                             </mml:mfrac>
 161                         </mml:mfenced>
 162                         <mml:mo>+</mml:mo>
 163                         <mml:mi mathvariant="italic">x</mml:mi>
 164                     </mml:mrow>
 165                 </mml:mrow>
 166             </mml:math></informalequation>
 167         </para>
 168         <para>
 169             <informalequation><mml:math>
 170                 <!-- eqn: y sub w  =  ( y sub nd  +  1 ) left ( height over 2 right )  +  y: -->
 171                 <mml:mrow>
 172                     <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
 173                     <mml:mi mathvariant="italic">w</mml:mi>
 174                     </mml:msub>
 175                     <mml:mo>=</mml:mo>
 176                     <mml:mrow>
 177                         <mml:mfenced open="(" close=")">
 178                             <mml:mrow>
 179                                 <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
 180                                 <mml:mi mathvariant="italic">nd</mml:mi>
 181                                 </mml:msub>
 182                                 <mml:mo>+</mml:mo>
 183                                 <mml:mn>1</mml:mn>
 184                             </mml:mrow>
 185                         </mml:mfenced>
 186                         <mml:mo>&it;</mml:mo>
 187                         <mml:mfenced open="(" close=")">
 188                             <mml:mfrac>
 189                                 <mml:mi mathvariant="italic">height</mml:mi>
 190                                 <mml:mn>2</mml:mn>
 191                             </mml:mfrac>
 192                         </mml:mfenced>
 193                         <mml:mo>+</mml:mo>
 194                         <mml:mi mathvariant="italic">y</mml:mi>
 195                     </mml:mrow>
 196                 </mml:mrow>
 197             </mml:math></informalequation>
 198         </para>
 199         <para>
 200             The location of the viewport's bottom left corner, given by
 201             (<inlineequation><mml:math><mml:mi mathvariant="italic">x</mml:mi></mml:math></inlineequation>, <inlineequation><mml:math><mml:mi mathvariant="italic">y</mml:mi></mml:math></inlineequation>)
 202             is clamped to be within the implementaiton-dependent viewport bounds range.
 203             The viewport bounds range [<inlineequation><mml:math><mml:mi mathvariant="italic">min</mml:mi></mml:math></inlineequation>, <inlineequation><mml:math><mml:mi mathvariant="italic">max</mml:mi></mml:math></inlineequation>]
 204             can be determined by calling <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument
 205             <constant>GL_VIEWPORT_BOUNDS_RANGE</constant>.
 206             Viewport width and height are silently clamped
 207             to a range that depends on the implementation.
 208             To query this range, call <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument
 209             <constant>GL_MAX_VIEWPORT_DIMS</constant>.
 210         </para>
 211         <para>
 212             The precision with which the GL interprets the floating point viewport bounds is implementation-dependent
 213             and may be determined by querying the impementation-defined constant <constant>GL_VIEWPORT_SUBPIXEL_BITS</constant>.
 214         </para>
 215         <para>
 216             Calling <function>glViewportIndexedfv</function> is equivalent to calling <citerefentry><refentrytitle>glViewportArray</refentrytitle></citerefentry>
 217             with <parameter>first</parameter> set to <parameter>index</parameter>, <parameter>count</parameter> set to
 218             1 and <parameter>v</parameter> passsed directly. <function>glViewportIndexedf</function> is equivalent
 219             to:
 220         </para>
 221 <programlisting><![CDATA[    void glViewportIndexedf(GLuint index, GLfloat x, GLfloat y, GLfloat w, GLfloat h)
 222     {
 223         const float v[4]  = { x, y, w, h };
 224         glViewportArrayv(index, 1, v);
 225     }]]></programlisting>
 226     </refsect1>
 227     <refsect1 id="errors"><title>Errors</title>
 228         <para>
 229             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>index</parameter> is greater than or equal to
 230             the value of <constant>GL_MAX_VIEWPORTS</constant>.
 231         </para>
 232         <para>
 233             <constant>GL_INVALID_VALUE</constant> is generated if either <parameter>width</parameter> or <parameter>height</parameter> is negative.
 234         </para>
 235     </refsect1>
 236     <refsect1 id="associatedgets"><title>Associated Gets</title>
 237         <para>
 238             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_VIEWPORT</constant>
 239         </para>
 240         <para>
 241             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MAX_VIEWPORT_DIMS</constant>
 242         </para>
 243         <para>
 244             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_VIEWPORT_BOUNDS_RANGE</constant>
 245         </para>
 246         <para>
 247             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_VIEWPORT_SUBPIXEL_BITS</constant>
 248         </para>
 249     </refsect1>
 250     <refsect1 id="seealso"><title>See Also</title>
 251         <para>
 252             <citerefentry><refentrytitle>glDepthRange</refentrytitle></citerefentry>,
 253             <citerefentry><refentrytitle>glViewport</refentrytitle></citerefentry>,
 254             <citerefentry><refentrytitle>glViewportArray</refentrytitle></citerefentry>
 255         </para>
 256     </refsect1>
 257     <refsect1 id="Copyright"><title>Copyright</title>
 258         <para>
 259             Copyright <trademark class="copyright"></trademark> 2010 Khronos Group.
 260             This material may be distributed subject to the terms and conditions set forth in
 261             the Open Publication License, v 1.0, 8 June 1999.
 262             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 263         </para>
 264     </refsect1>
 265 </refentry>