upstream-doc/man2/gluPickMatrix.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="gluPickMatrix">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>gluPickMatrix</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>gluPickMatrix</refname>
  17         <refpurpose>define a picking region</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>gluPickMatrix</function></funcdef>
  23                 <paramdef>GLdouble <parameter>x</parameter></paramdef>
  24                 <paramdef>GLdouble <parameter>y</parameter></paramdef>
  25                 <paramdef>GLdouble <parameter>delX</parameter></paramdef>
  26                 <paramdef>GLdouble <parameter>delY</parameter></paramdef>
  27                 <paramdef>GLint * <parameter>viewport</parameter></paramdef>
  28             </funcprototype>
  29         </funcsynopsis>
  30     </refsynopsisdiv>
  31     <!-- eqn: ignoring delim $$ -->
  32     <refsect1 id="parameters"><title>Parameters</title>
  33         <variablelist>
  34         <varlistentry>
  35             <term><parameter>x</parameter></term>
  36             <term><parameter>y</parameter></term>
  37             <listitem>
  38                 <para>
  39                     Specify the center of a picking region in window coordinates.
  40                 </para>
  41             </listitem>
  42         </varlistentry>
  43         <varlistentry>
  44             <term><parameter>delX</parameter></term>
  45             <term><parameter>delY</parameter></term>
  46             <listitem>
  47                 <para>
  48                     Specify the width and height, respectively, of the picking region in window
  49                     coordinates.
  50                 </para>
  51             </listitem>
  52         </varlistentry>
  53         <varlistentry>
  54             <term><parameter>viewport</parameter></term>
  55             <listitem>
  56                 <para>
  57                     Specifies the current viewport (as from a <citerefentry><refentrytitle>glGetIntegerv</refentrytitle></citerefentry> call).
  58                 </para>
  59             </listitem>
  60         </varlistentry>
  61         </variablelist>
  62     </refsect1>
  63     <refsect1 id="description"><title>Description</title>
  64         <para>
  65             <function>gluPickMatrix</function> creates a projection matrix that can be used to restrict drawing
  66             to a small region of the viewport.
  67             This is typically useful to
  68             determine what objects are being drawn near the cursor.
  69             Use <function>gluPickMatrix</function> to
  70             restrict drawing to a small region around the cursor.
  71             Then,
  72             enter selection mode (with <citerefentry><refentrytitle>glRenderMode</refentrytitle></citerefentry>) and rerender the scene.
  73             All primitives that would have been drawn near
  74             the cursor are identified and stored in the selection buffer.
  75         </para>
  76         <para>
  77             The matrix created by <function>gluPickMatrix</function> is multiplied by the current matrix just
  78             as if <citerefentry><refentrytitle>glMultMatrix</refentrytitle></citerefentry> is called with the generated matrix.
  79             To effectively use the generated pick matrix for picking,
  80             first call <citerefentry><refentrytitle>glLoadIdentity</refentrytitle></citerefentry> to load an identity matrix onto the
  81             perspective matrix stack.
  82             Then call <function>gluPickMatrix</function>,
  83             and, finally, call a command (such as <citerefentry><refentrytitle>gluPerspective</refentrytitle></citerefentry>)
  84             to multiply the perspective matrix by the pick matrix.
  85         </para>
  86         <para>
  87             When using <function>gluPickMatrix</function> to pick NURBS, be careful to turn off the NURBS
  88             property
  89             <constant>GLU_AUTO_LOAD_MATRIX</constant>.  If <constant>GLU_AUTO_LOAD_MATRIX</constant> is not
  90             turned off, then any NURBS surface rendered is subdivided differently with
  91             the pick matrix than the way it was subdivided without the pick matrix.
  92         </para>
  93     </refsect1>
  94     <refsect1 id="example"><title>Example</title>
  95         <para>
  96             When rendering a scene as follows:
  97             <programlisting>
  98 glMatrixMode(GL_PROJECTION);
  99 glLoadIdentity();
 100 gluPerspective(...);
 101 glMatrixMode(GL_MODELVIEW);
 102 /* Draw the scene */
 103             </programlisting>
 104             a portion of the viewport can be selected as a pick region like this:
 105             <programlisting>
 106 glMatrixMode(GL_PROJECTION);
 107 glLoadIdentity();
 108 gluPickMatrix(x, y, width, height, viewport);
 109 gluPerspective(...);
 110 glMatrixMode(GL_MODELVIEW);
 111 /* Draw the scene */
 112             </programlisting>
 113         </para>
 114     </refsect1>
 115     <refsect1 id="seealso"><title>See Also</title>
 116         <para>
 117             <citerefentry><refentrytitle>gluPerspective</refentrytitle></citerefentry>,
 118             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>,
 119             <citerefentry><refentrytitle>glLoadIdentity</refentrytitle></citerefentry>,
 120             <citerefentry><refentrytitle>glMultMatrix</refentrytitle></citerefentry>,
 121             <citerefentry><refentrytitle>glRenderMode</refentrytitle></citerefentry>
 122         </para>
 123     </refsect1>
 124     <refsect1 id="Copyright"><title>Copyright</title>
 125         <para>
 126             Copyright <trademark class="copyright"></trademark> 1991-2006
 127             Silicon Graphics, Inc. This document is licensed under the SGI
 128             Free Software B License. For details, see
 129             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 130         </para>
 131     </refsect1>
 132 </refentry>