2013-10-10 23:58:54 +00:00
<?xml version="1.0" encoding="UTF-8"?>
< !DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id= "glViewportArray" >
<refmeta >
<refmetainfo >
<copyright >
<year > 2010</year>
<holder > Khronos Group</holder>
</copyright>
</refmetainfo>
<refentrytitle > glViewportArray</refentrytitle>
<manvolnum > 3G</manvolnum>
</refmeta>
<refnamediv >
<refname > glViewportArray</refname>
<refpurpose > set multiple viewports</refpurpose>
</refnamediv>
<refsynopsisdiv > <title > C Specification</title>
<funcsynopsis >
<funcprototype >
<funcdef > void <function > glViewportArrayv</function> </funcdef>
<paramdef > GLuint <parameter > first</parameter> </paramdef>
<paramdef > GLsizei <parameter > count</parameter> </paramdef>
<paramdef > const GLfloat *<parameter > v</parameter> </paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id= "parameters" > <title > Parameters</title>
<variablelist >
<varlistentry >
<term > <parameter > first</parameter> </term>
<listitem >
<para >
Specify the first viewport to set.
</para>
</listitem>
</varlistentry>
<varlistentry >
<term > <parameter > count</parameter> </term>
<listitem >
<para >
Specify the number of viewports to set.
</para>
</listitem>
</varlistentry>
<varlistentry >
<term > <parameter > v</parameter> </term>
<listitem >
<para >
Specify the address of an array containing the viewport parameters.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id= "description" > <title > Description</title>
<para >
<function > glViewportArrayv</function> specifies the parameters for multiple viewports
simulataneously. <parameter > first</parameter> specifies the index of the first viewport
to modify and <parameter > count</parameter> specifies the number of viewports to modify.
<parameter > first</parameter> must be less than the value of <constant > GL_MAX_VIEWPORTS</constant> ,
and <parameter > first</parameter> + <parameter > count</parameter> must be less than or equal to
the value of <constant > GL_MAX_VIEWPORTS</constant> . Viewports whose indices lie outside
the range [<parameter > first</parameter> , <parameter > first</parameter> + <parameter > count</parameter> )
are not modified. <parameter > v</parameter> contains the address of an array of floating
point values specifying the
left (<inlineequation > <mml:math > <mml:mi mathvariant= "italic" > x</mml:mi> </mml:math> </inlineequation> ),
bottom (<inlineequation > <mml:math > <mml:mi mathvariant= "italic" > y</mml:mi> </mml:math> </inlineequation> ),
width (<inlineequation > <mml:math > <mml:mi mathvariant= "italic" > w</mml:mi> </mml:math> </inlineequation> ),
and height (<inlineequation > <mml:math > <mml:mi mathvariant= "italic" > h</mml:mi> </mml:math> </inlineequation> )
of each viewport, in that order. <inlineequation > <mml:math > <mml:mi mathvariant= "italic" > x</mml:mi> </mml:math> </inlineequation>
and <inlineequation > <mml:math > <mml:mi mathvariant= "italic" > y</mml:mi> </mml:math> </inlineequation> give
the location of the viewport's lower left corner, and
<inlineequation > <mml:math > <mml:mi mathvariant= "italic" > w</mml:mi> </mml:math> </inlineequation>
and <inlineequation > <mml:math > <mml:mi mathvariant= "italic" > h</mml:mi> </mml:math> </inlineequation>
give the width and height of the viewport, respectively.
The viewport specifies the affine transformation of
<inlineequation > <mml:math > <mml:mi mathvariant= "italic" > x</mml:mi> </mml:math> </inlineequation>
and
<inlineequation > <mml:math > <mml:mi mathvariant= "italic" > y</mml:mi> </mml:math> </inlineequation>
from
normalized device coordinates to window coordinates.
Let
<inlineequation > <mml:math >
<!-- eqn: (x sub nd, y sub nd): -->
<mml:mfenced open= "(" close= ")" >
<mml:msub > <mml:mi mathvariant= "italic" > x</mml:mi>
<mml:mi mathvariant= "italic" > nd</mml:mi>
</mml:msub>
<mml:msub > <mml:mi mathvariant= "italic" > y</mml:mi>
<mml:mi mathvariant= "italic" > nd</mml:mi>
</mml:msub>
</mml:mfenced>
</mml:math> </inlineequation>
be normalized device coordinates.
Then the window coordinates
<inlineequation > <mml:math >
<!-- eqn: (x sub w, y sub w): -->
<mml:mfenced open= "(" close= ")" >
<mml:msub > <mml:mi mathvariant= "italic" > x</mml:mi>
<mml:mi mathvariant= "italic" > w</mml:mi>
</mml:msub>
<mml:msub > <mml:mi mathvariant= "italic" > y</mml:mi>
<mml:mi mathvariant= "italic" > w</mml:mi>
</mml:msub>
</mml:mfenced>
</mml:math> </inlineequation>
are computed as follows:
</para>
<para >
<informalequation > <mml:math >
<!-- eqn: x sub w = ( x sub nd + 1 ) left ( width over 2 right ) + x: -->
<mml:mrow >
<mml:msub > <mml:mi mathvariant= "italic" > x</mml:mi>
<mml:mi mathvariant= "italic" > w</mml:mi>
</mml:msub>
<mml:mo > =</mml:mo>
<mml:mrow >
<mml:mfenced open= "(" close= ")" >
<mml:mrow >
<mml:msub > <mml:mi mathvariant= "italic" > x</mml:mi>
<mml:mi mathvariant= "italic" > nd</mml:mi>
</mml:msub>
<mml:mo > +</mml:mo>
<mml:mn > 1</mml:mn>
</mml:mrow>
</mml:mfenced>
<mml:mo > ⁢ </mml:mo>
<mml:mfenced open= "(" close= ")" >
<mml:mfrac >
<mml:mi mathvariant= "italic" > width</mml:mi>
<mml:mn > 2</mml:mn>
</mml:mfrac>
</mml:mfenced>
<mml:mo > +</mml:mo>
<mml:mi mathvariant= "italic" > x</mml:mi>
</mml:mrow>
</mml:mrow>
</mml:math> </informalequation>
</para>
<para >
<informalequation > <mml:math >
<!-- eqn: y sub w = ( y sub nd + 1 ) left ( height over 2 right ) + y: -->
<mml:mrow >
<mml:msub > <mml:mi mathvariant= "italic" > y</mml:mi>
<mml:mi mathvariant= "italic" > w</mml:mi>
</mml:msub>
<mml:mo > =</mml:mo>
<mml:mrow >
<mml:mfenced open= "(" close= ")" >
<mml:mrow >
<mml:msub > <mml:mi mathvariant= "italic" > y</mml:mi>
<mml:mi mathvariant= "italic" > nd</mml:mi>
</mml:msub>
<mml:mo > +</mml:mo>
<mml:mn > 1</mml:mn>
</mml:mrow>
</mml:mfenced>
<mml:mo > ⁢ </mml:mo>
<mml:mfenced open= "(" close= ")" >
<mml:mfrac >
<mml:mi mathvariant= "italic" > height</mml:mi>
<mml:mn > 2</mml:mn>
</mml:mfrac>
</mml:mfenced>
<mml:mo > +</mml:mo>
<mml:mi mathvariant= "italic" > y</mml:mi>
</mml:mrow>
</mml:mrow>
</mml:math> </informalequation>
</para>
<para >
The location of the viewport's bottom left corner, given by
(<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> )
is clamped to be within the implementaiton-dependent viewport bounds range.
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> ]
can be determined by calling <citerefentry > <refentrytitle > glGet</refentrytitle> </citerefentry> with argument
<constant > GL_VIEWPORT_BOUNDS_RANGE</constant> .
Viewport width and height are silently clamped
to a range that depends on the implementation.
To query this range, call <citerefentry > <refentrytitle > glGet</refentrytitle> </citerefentry> with argument
<constant > GL_MAX_VIEWPORT_DIMS</constant> .
</para>
<para >
The precision with which the GL interprets the floating point viewport bounds is implementation-dependent
and may be determined by querying the impementation-defined constant <constant > GL_VIEWPORT_SUBPIXEL_BITS</constant> .
</para>
</refsect1>
<refsect1 id= "errors" > <title > Errors</title>
<para >
<constant > GL_INVALID_VALUE</constant> is generated if <parameter > first</parameter> is greater than or equal to
the value of <constant > GL_MAX_VIEWPORTS</constant> .
</para>
<para >
<constant > GL_INVALID_VALUE</constant> is generated if <parameter > first</parameter> + <parameter > count</parameter>
is greater than or equal to the value of <constant > GL_MAX_VIEWPORTS</constant> .
</para>
<para >
<constant > GL_INVALID_VALUE</constant> is generated if either <parameter > width</parameter> or <parameter > height</parameter> is negative.
</para>
</refsect1>
<refsect1 id= "associatedgets" > <title > Associated Gets</title>
<para >
<citerefentry > <refentrytitle > glGet</refentrytitle> </citerefentry> with argument <constant > GL_VIEWPORT</constant>
</para>
<para >
<citerefentry > <refentrytitle > glGet</refentrytitle> </citerefentry> with argument <constant > GL_MAX_VIEWPORT_DIMS</constant>
</para>
<para >
<citerefentry > <refentrytitle > glGet</refentrytitle> </citerefentry> with argument <constant > GL_VIEWPORT_BOUNDS_RANGE</constant>
</para>
<para >
<citerefentry > <refentrytitle > glGet</refentrytitle> </citerefentry> with argument <constant > GL_VIEWPORT_SUBPIXEL_BITS</constant>
</para>
</refsect1>
<refsect1 id= "seealso" > <title > See Also</title>
<para >
<citerefentry > <refentrytitle > glDepthRange</refentrytitle> </citerefentry> ,
<citerefentry > <refentrytitle > glViewport</refentrytitle> </citerefentry> ,
<citerefentry > <refentrytitle > glViewportIndexed</refentrytitle> </citerefentry>
</para>
</refsect1>
<refsect1 id= "Copyright" > <title > Copyright</title>
<para >
Copyright <trademark class= "copyright" > </trademark> 2010 Khronos Group.
This material may be distributed subject to the terms and conditions set forth in
the Open Publication License, v 1.0, 8 June 1999.
<ulink url= "http://opencontent.org/openpub/" > http://opencontent.org/openpub/</ulink> .
</para>
</refsect1>
</refentry>
