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