[clinton/guile-figl.git] / upstream-doc / man2 / gluPerspective.xml

<?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="gluPerspective">
    <refmeta>
        <refmetainfo>
            <copyright>
                <year>1991-2006</year>
                <holder>Silicon Graphics, Inc.</holder>
            </copyright>
        </refmetainfo>
        <refentrytitle>gluPerspective</refentrytitle>
        <manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
        <refname>gluPerspective</refname>
        <refpurpose>set up a perspective projection matrix</refpurpose>
    </refnamediv>
    <refsynopsisdiv><title>C Specification</title>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>gluPerspective</function></funcdef>
                <paramdef>GLdouble <parameter>fovy</parameter></paramdef>
                <paramdef>GLdouble <parameter>aspect</parameter></paramdef>
                <paramdef>GLdouble <parameter>zNear</parameter></paramdef>
                <paramdef>GLdouble <parameter>zFar</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <!-- eqn: ignoring delim $$ -->
    <refsect1 id="parameters"><title>Parameters</title>
        <variablelist>
        <varlistentry>
            <term><parameter>fovy</parameter></term>
            <listitem>
                <para>
                    Specifies the field of view angle, in degrees, in the <emphasis>y</emphasis> direction.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>aspect</parameter></term>
            <listitem>
                <para>
                    Specifies the aspect ratio that determines
                    the field of view in the <emphasis>x</emphasis> direction.
                    The aspect ratio is the ratio of <emphasis>x</emphasis> (width) to <emphasis>y</emphasis> (height).
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>zNear</parameter></term>
            <listitem>
                <para>
                    Specifies the distance from the viewer to the near clipping plane
                    (always positive).
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>zFar</parameter></term>
            <listitem>
                <para>
                    Specifies the distance from the viewer to the far clipping plane
                    (always positive).
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsect1>
    <refsect1 id="description"><title>Description</title>
        <para>
            <function>gluPerspective</function> specifies a viewing frustum into the world coordinate system.
            In general, the aspect ratio in <function>gluPerspective</function> should match the aspect ratio
            of the associated viewport. For example, 
            <inlineequation><mml:math>
                <!-- eqn: aspect  =  2.0:-->
                <mml:mrow>
                    <mml:mi mathvariant="italic">aspect</mml:mi>
                    <mml:mo>=</mml:mo>
                    <mml:mn>2.0</mml:mn>
                </mml:mrow>
            </mml:math></inlineequation>
            means 
            the viewer's
            angle of view is twice as wide in <emphasis>x</emphasis> as it is in <emphasis>y</emphasis>.
            If the viewport is
            twice as wide as it is tall, it displays the image without distortion.
        </para>
        <para>
            The matrix generated by <function>gluPerspective</function> is multipled by the current matrix,
            just as if <citerefentry><refentrytitle>glMultMatrix</refentrytitle></citerefentry> were called with the generated matrix.
            To load the perspective matrix onto the current matrix stack instead,
            precede the call to <function>gluPerspective</function> with a call to <citerefentry><refentrytitle>glLoadIdentity</refentrytitle></citerefentry>.
        </para>
        <para>
            Given <emphasis>f</emphasis> defined as follows:
        </para>
        <para>
            <informalequation><mml:math>
                <!-- eqn: f   =  cotangent(fovy over 2):-->
                <mml:mrow>
                    <mml:mi mathvariant="italic">f</mml:mi>
                    <mml:mo>=</mml:mo>
                    <mml:mrow>
                        <mml:mi mathvariant="italic">cotangent</mml:mi>
                        <mml:mo>&af;</mml:mo>
                        <mml:mfenced open="(" close=")">
                            <mml:mfrac>
                                <mml:mi mathvariant="italic">fovy</mml:mi>
                                <mml:mn>2</mml:mn>
                            </mml:mfrac>
                        </mml:mfenced>
                    </mml:mrow>
                </mml:mrow>
            </mml:math></informalequation>
            The generated matrix is
        </para>
        <para>
            <informalequation><mml:math>
                <!-- eqn: left (    matrix {    ccol { f over aspect above 0 above 0 above 0 }    ccol { 0 above f above 0 above 0 }    ccol { 0 above 0 above {zFar + zNear} over {zNear - zFar} above -1 }    ccol { 0 above 0 above {2 * zFar * zNear} over {zNear - zFar} above 0} }      right ):-->
                <mml:mfenced open="(" close=")">
                    <mml:mtable>
                        <mml:mtr>
                            <mml:mtd>
                                <mml:mfrac>
                                    <mml:mi mathvariant="italic">f</mml:mi>
                                    <mml:mi mathvariant="italic">aspect</mml:mi>
                                </mml:mfrac>
                            </mml:mtd>
                            <mml:mtd>
                                <mml:mn>0</mml:mn>
                            </mml:mtd>
                            <mml:mtd>
                                <mml:mn>0</mml:mn>
                            </mml:mtd>
                            <mml:mtd>
                                <mml:mn>0</mml:mn>
                            </mml:mtd>
                        </mml:mtr>
                        <mml:mtr>
                            <mml:mtd>
                                <mml:mn>0</mml:mn>
                            </mml:mtd>
                            <mml:mtd>
                                <mml:mi mathvariant="italic">f</mml:mi>
                            </mml:mtd>
                            <mml:mtd>
                                <mml:mn>0</mml:mn>
                            </mml:mtd>
                            <mml:mtd>
                                <mml:mn>0</mml:mn>
                            </mml:mtd>
                        </mml:mtr>
                        <mml:mtr>
                            <mml:mtd>
                                <mml:mn>0</mml:mn>
                            </mml:mtd>
                            <mml:mtd>
                                <mml:mn>0</mml:mn>
                            </mml:mtd>
                            <mml:mtd>
                                <mml:mfrac>
                                    <mml:mfenced open="" close="">
                                        <mml:mrow>
                                            <mml:mi mathvariant="italic">zFar</mml:mi>
                                            <mml:mo>+</mml:mo>
                                            <mml:mi mathvariant="italic">zNear</mml:mi>
                                        </mml:mrow>
                                    </mml:mfenced>
                                    <mml:mfenced open="" close="">
                                        <mml:mrow>
                                            <mml:mi mathvariant="italic">zNear</mml:mi>
                                            <mml:mo>-</mml:mo>
                                            <mml:mi mathvariant="italic">zFar</mml:mi>
                                        </mml:mrow>
                                    </mml:mfenced>
                                </mml:mfrac>
                            </mml:mtd>
                            <mml:mtd>
                                <mml:mfrac>
                                    <mml:mfenced open="" close="">
                                        <mml:mrow>
                                            <mml:mn>2</mml:mn>
                                            <mml:mo>&times;</mml:mo>
                                            <mml:mi mathvariant="italic">zFar</mml:mi>
                                            <mml:mo>&times;</mml:mo>
                                            <mml:mi mathvariant="italic">zNear</mml:mi>
                                        </mml:mrow>
                                    </mml:mfenced>
                                    <mml:mfenced open="" close="">
                                        <mml:mrow>
                                            <mml:mi mathvariant="italic">zNear</mml:mi>
                                            <mml:mo>-</mml:mo>
                                            <mml:mi mathvariant="italic">zFar</mml:mi>
                                        </mml:mrow>
                                    </mml:mfenced>
                                </mml:mfrac>
                            </mml:mtd>
                        </mml:mtr>
                        <mml:mtr>
                            <mml:mtd>
                                <mml:mn>0</mml:mn>
                            </mml:mtd>
                            <mml:mtd>
                                <mml:mn>0</mml:mn>
                            </mml:mtd>
                            <mml:mtd>
                                <mml:mn>-1</mml:mn>
                            </mml:mtd>
                            <mml:mtd>
                                <mml:mn>0</mml:mn>
                            </mml:mtd>
                        </mml:mtr>
                    </mml:mtable>
                </mml:mfenced>
            </mml:math></informalequation>
        </para>
    </refsect1>
    <refsect1 id="notes"><title>Notes</title>
        <para>
            Depth buffer precision is affected by the values specified for
            <parameter>zNear</parameter> and <parameter>zFar</parameter>.
            The greater the ratio of <parameter>zFar</parameter> to <parameter>zNear</parameter> is,
            the less effective the depth buffer will be at distinguishing between
            surfaces that are near each other.
            If 
        </para>
        <para>
            <inlineequation><mml:math>
                <!-- eqn: r  =  zFar over zNear:-->
                <mml:mrow>
                    <mml:mi mathvariant="italic">r</mml:mi>
                    <mml:mo>=</mml:mo>
                    <mml:mfrac>
                        <mml:mi mathvariant="italic">zFar</mml:mi>
                        <mml:mi mathvariant="italic">zNear</mml:mi>
                    </mml:mfrac>
                </mml:mrow>
            </mml:math></inlineequation>
        </para>
        <para>
        </para>
        <para>
            roughly 
            <inlineequation><mml:math>
                <!-- eqn: log sub 2 (r):-->
                <mml:mrow>
                    <mml:msub><mml:mi mathvariant="italic">log</mml:mi>
                    <mml:mn>2</mml:mn>
                    </mml:msub>
                    <mml:mo>&af;</mml:mo>
                    <mml:mfenced open="(" close=")">
                        <mml:mi mathvariant="italic">r</mml:mi>
                    </mml:mfenced>
                </mml:mrow>
            </mml:math></inlineequation>
            bits of depth buffer precision are lost.
            Because 
            <inlineequation><mml:math><mml:mi mathvariant="italic">r</mml:mi></mml:math></inlineequation>
            approaches infinity as <parameter>zNear</parameter> approaches 0,
            <parameter>zNear</parameter> must never be set to 0.
        </para>
    </refsect1>
    <refsect1 id="seealso"><title>See Also</title>
        <para>
            <citerefentry><refentrytitle>gluOrtho2D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glFrustum</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glLoadIdentity</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glMultMatrix</refentrytitle></citerefentry>
        </para>
    </refsect1>
    <refsect1 id="Copyright"><title>Copyright</title>
        <para>
            Copyright <trademark class="copyright"></trademark> 1991-2006
            Silicon Graphics, Inc. This document is licensed under the SGI
            Free Software B License. For details, see
            <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
        </para>
    </refsect1>
</refentry>
Commit	Line	Data
7faf1d71 AW	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="gluPerspective">
	5	<refmeta>
	6	<refmetainfo>
	7	<copyright>
	8	<year>1991-2006</year>
	9	<holder>Silicon Graphics, Inc.</holder>
	10	</copyright>
	11	</refmetainfo>
	12	<refentrytitle>gluPerspective</refentrytitle>
	13	<manvolnum>3G</manvolnum>
	14	</refmeta>
	15	<refnamediv>
	16	<refname>gluPerspective</refname>
	17	<refpurpose>set up a perspective projection matrix</refpurpose>
	18	</refnamediv>
	19	<refsynopsisdiv><title>C Specification</title>
	20	<funcsynopsis>
	21	<funcprototype>
	22	<funcdef>void <function>gluPerspective</function></funcdef>
	23	<paramdef>GLdouble <parameter>fovy</parameter></paramdef>
	24	<paramdef>GLdouble <parameter>aspect</parameter></paramdef>
	25	<paramdef>GLdouble <parameter>zNear</parameter></paramdef>
	26	<paramdef>GLdouble <parameter>zFar</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>fovy</parameter></term>
	35	<listitem>
	36	<para>
	37	Specifies the field of view angle, in degrees, in the <emphasis>y</emphasis> direction.
	38	</para>
	39	</listitem>
	40	</varlistentry>
	41	<varlistentry>
	42	<term><parameter>aspect</parameter></term>
	43	<listitem>
	44	<para>
	45	Specifies the aspect ratio that determines
	46	the field of view in the <emphasis>x</emphasis> direction.
	47	The aspect ratio is the ratio of <emphasis>x</emphasis> (width) to <emphasis>y</emphasis> (height).
	48	</para>
	49	</listitem>
	50	</varlistentry>
	51	<varlistentry>
	52	<term><parameter>zNear</parameter></term>
	53	<listitem>
	54	<para>
	55	Specifies the distance from the viewer to the near clipping plane
	56	(always positive).
	57	</para>
	58	</listitem>
	59	</varlistentry>
	60	<varlistentry>
	61	<term><parameter>zFar</parameter></term>
	62	<listitem>
	63	<para>
	64	Specifies the distance from the viewer to the far clipping plane
65	(always positive).
66	</para>
67	</listitem>
68	</varlistentry>
69	</variablelist>
70	</refsect1>
71	<refsect1 id="description"><title>Description</title>
72	<para>
73	<function>gluPerspective</function> specifies a viewing frustum into the world coordinate system.
74	In general, the aspect ratio in <function>gluPerspective</function> should match the aspect ratio
75	of the associated viewport. For example,
76	<inlineequation><mml:math>
77	<!-- eqn: aspect = 2.0:-->
78	<mml:mrow>
79	<mml:mi mathvariant="italic">aspect</mml:mi>
80	<mml:mo>=</mml:mo>
81	<mml:mn>2.0</mml:mn>
82	</mml:mrow>
83	</mml:math></inlineequation>
84	means
85	the viewer's
86	angle of view is twice as wide in <emphasis>x</emphasis> as it is in <emphasis>y</emphasis>.
87	If the viewport is
88	twice as wide as it is tall, it displays the image without distortion.
89	</para>
90	<para>
91	The matrix generated by <function>gluPerspective</function> is multipled by the current matrix,
92	just as if <citerefentry><refentrytitle>glMultMatrix</refentrytitle></citerefentry> were called with the generated matrix.
93	To load the perspective matrix onto the current matrix stack instead,
94	precede the call to <function>gluPerspective</function> with a call to <citerefentry><refentrytitle>glLoadIdentity</refentrytitle></citerefentry>.
95	</para>
96	<para>
97	Given <emphasis>f</emphasis> defined as follows:
98	</para>
99	<para>
100	<informalequation><mml:math>
101	<!-- eqn: f = cotangent(fovy over 2):-->
102	<mml:mrow>
103	<mml:mi mathvariant="italic">f</mml:mi>
104	<mml:mo>=</mml:mo>
105	<mml:mrow>
106	<mml:mi mathvariant="italic">cotangent</mml:mi>
107	<mml:mo>⁡</mml:mo>
108	<mml:mfenced open="(" close=")">
109	<mml:mfrac>
110	<mml:mi mathvariant="italic">fovy</mml:mi>
111	<mml:mn>2</mml:mn>
112	</mml:mfrac>
113	</mml:mfenced>
114	</mml:mrow>
115	</mml:mrow>
116	</mml:math></informalequation>
117	The generated matrix is
118	</para>
119	<para>
120	<informalequation><mml:math>
121	<!-- eqn: left ( matrix { ccol { f over aspect above 0 above 0 above 0 } ccol { 0 above f above 0 above 0 } ccol { 0 above 0 above {zFar + zNear} over {zNear - zFar} above -1 } ccol { 0 above 0 above {2 * zFar * zNear} over {zNear - zFar} above 0} } right ):-->
122	<mml:mfenced open="(" close=")">
123	<mml:mtable>
124	<mml:mtr>
125	<mml:mtd>
126	<mml:mfrac>
127	<mml:mi mathvariant="italic">f</mml:mi>
128	<mml:mi mathvariant="italic">aspect</mml:mi>
129	</mml:mfrac>
130	</mml:mtd>
131	<mml:mtd>
132	<mml:mn>0</mml:mn>
133	</mml:mtd>
134	<mml:mtd>
135	<mml:mn>0</mml:mn>
136	</mml:mtd>
137	<mml:mtd>
138	<mml:mn>0</mml:mn>
139	</mml:mtd>
140	</mml:mtr>
141	<mml:mtr>
142	<mml:mtd>
143	<mml:mn>0</mml:mn>
144	</mml:mtd>
145	<mml:mtd>
146	<mml:mi mathvariant="italic">f</mml:mi>
147	</mml:mtd>
148	<mml:mtd>
149	<mml:mn>0</mml:mn>
150	</mml:mtd>
151	<mml:mtd>
152	<mml:mn>0</mml:mn>
153	</mml:mtd>
154	</mml:mtr>
155	<mml:mtr>
156	<mml:mtd>
157	<mml:mn>0</mml:mn>
158	</mml:mtd>
159	<mml:mtd>
160	<mml:mn>0</mml:mn>
161	</mml:mtd>
162	<mml:mtd>
163	<mml:mfrac>
164	<mml:mfenced open="" close="">
165	<mml:mrow>
166	<mml:mi mathvariant="italic">zFar</mml:mi>
167	<mml:mo>+</mml:mo>
168	<mml:mi mathvariant="italic">zNear</mml:mi>
169	</mml:mrow>
170	</mml:mfenced>
171	<mml:mfenced open="" close="">
172	<mml:mrow>
173	<mml:mi mathvariant="italic">zNear</mml:mi>
174	<mml:mo>-</mml:mo>
175	<mml:mi mathvariant="italic">zFar</mml:mi>
176	</mml:mrow>
177	</mml:mfenced>
178	</mml:mfrac>
179	</mml:mtd>
180	<mml:mtd>
181	<mml:mfrac>
182	<mml:mfenced open="" close="">
183	<mml:mrow>
184	<mml:mn>2</mml:mn>
185	<mml:mo>×</mml:mo>
186	<mml:mi mathvariant="italic">zFar</mml:mi>
187	<mml:mo>×</mml:mo>
188	<mml:mi mathvariant="italic">zNear</mml:mi>
189	</mml:mrow>
190	</mml:mfenced>
191	<mml:mfenced open="" close="">
192	<mml:mrow>
193	<mml:mi mathvariant="italic">zNear</mml:mi>
194	<mml:mo>-</mml:mo>
195	<mml:mi mathvariant="italic">zFar</mml:mi>
196	</mml:mrow>
197	</mml:mfenced>
198	</mml:mfrac>
199	</mml:mtd>
200	</mml:mtr>
201	<mml:mtr>
202	<mml:mtd>
203	<mml:mn>0</mml:mn>
204	</mml:mtd>
205	<mml:mtd>
206	<mml:mn>0</mml:mn>
207	</mml:mtd>
208	<mml:mtd>
209	<mml:mn>-1</mml:mn>
210	</mml:mtd>
211	<mml:mtd>
212	<mml:mn>0</mml:mn>
213	</mml:mtd>
214	</mml:mtr>
215	</mml:mtable>
216	</mml:mfenced>
217	</mml:math></informalequation>
218	</para>
219	</refsect1>
220	<refsect1 id="notes"><title>Notes</title>
221	<para>
222	Depth buffer precision is affected by the values specified for
223	<parameter>zNear</parameter> and <parameter>zFar</parameter>.
224	The greater the ratio of <parameter>zFar</parameter> to <parameter>zNear</parameter> is,
225	the less effective the depth buffer will be at distinguishing between
226	surfaces that are near each other.
227	If
228	</para>
229	<para>
230	<inlineequation><mml:math>
231	<!-- eqn: r = zFar over zNear:-->
232	<mml:mrow>
233	<mml:mi mathvariant="italic">r</mml:mi>
234	<mml:mo>=</mml:mo>
235	<mml:mfrac>
236	<mml:mi mathvariant="italic">zFar</mml:mi>
237	<mml:mi mathvariant="italic">zNear</mml:mi>
238	</mml:mfrac>
239	</mml:mrow>
240	</mml:math></inlineequation>
241	</para>
242	<para>
243	</para>
244	<para>
245	roughly
246	<inlineequation><mml:math>
247	<!-- eqn: log sub 2 (r):-->
248	<mml:mrow>
249	<mml:msub><mml:mi mathvariant="italic">log</mml:mi>
250	<mml:mn>2</mml:mn>
251	</mml:msub>
252	<mml:mo>⁡</mml:mo>
253	<mml:mfenced open="(" close=")">
254	<mml:mi mathvariant="italic">r</mml:mi>
255	</mml:mfenced>
256	</mml:mrow>
257	</mml:math></inlineequation>
258	bits of depth buffer precision are lost.
259	Because
260	<inlineequation><mml:math><mml:mi mathvariant="italic">r</mml:mi></mml:math></inlineequation>
261	approaches infinity as <parameter>zNear</parameter> approaches 0,
262	<parameter>zNear</parameter> must never be set to 0.
263	</para>
264	</refsect1>
265	<refsect1 id="seealso"><title>See Also</title>
266	<para>
267	<citerefentry><refentrytitle>gluOrtho2D</refentrytitle></citerefentry>,
268	<citerefentry><refentrytitle>glFrustum</refentrytitle></citerefentry>,
269	<citerefentry><refentrytitle>glLoadIdentity</refentrytitle></citerefentry>,
270	<citerefentry><refentrytitle>glMultMatrix</refentrytitle></citerefentry>
271	</para>
272	</refsect1>
273	<refsect1 id="Copyright"><title>Copyright</title>
274	<para>
275	Copyright <trademark class="copyright"></trademark> 1991-2006
276	Silicon Graphics, Inc. This document is licensed under the SGI
277	Free Software B License. For details, see
278	<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
279	</para>
280	</refsect1>
281	</refentry>