upstream-man-pages/man2/glMapGrid.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="glMapGrid">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glMapGrid</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glMapGrid</refname>
  17         <refpurpose>define a one- or two-dimensional mesh</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glMapGrid1d</function></funcdef>
  23                 <paramdef>GLint <parameter>un</parameter></paramdef>
  24                 <paramdef>GLdouble <parameter>u1</parameter></paramdef>
  25                 <paramdef>GLdouble <parameter>u2</parameter></paramdef>
  26             </funcprototype>
  27         </funcsynopsis>
  28         <funcsynopsis>
  29             <funcprototype>
  30                 <funcdef>void <function>glMapGrid1f</function></funcdef>
  31                 <paramdef>GLint <parameter>un</parameter></paramdef>
  32                 <paramdef>GLfloat <parameter>u1</parameter></paramdef>
  33                 <paramdef>GLfloat <parameter>u2</parameter></paramdef>
  34             </funcprototype>
  35         </funcsynopsis>
  36         <funcsynopsis>
  37             <funcprototype>
  38                 <funcdef>void <function>glMapGrid2d</function></funcdef>
  39                 <paramdef>GLint <parameter>un</parameter></paramdef>
  40                 <paramdef>GLdouble <parameter>u1</parameter></paramdef>
  41                 <paramdef>GLdouble <parameter>u2</parameter></paramdef>
  42                 <paramdef>GLint <parameter>vn</parameter></paramdef>
  43                 <paramdef>GLdouble <parameter>v1</parameter></paramdef>
  44                 <paramdef>GLdouble <parameter>v2</parameter></paramdef>
  45             </funcprototype>
  46         </funcsynopsis>
  47         <funcsynopsis>
  48             <funcprototype>
  49                 <funcdef>void <function>glMapGrid2f</function></funcdef>
  50                 <paramdef>GLint <parameter>un</parameter></paramdef>
  51                 <paramdef>GLfloat <parameter>u1</parameter></paramdef>
  52                 <paramdef>GLfloat <parameter>u2</parameter></paramdef>
  53                 <paramdef>GLint <parameter>vn</parameter></paramdef>
  54                 <paramdef>GLfloat <parameter>v1</parameter></paramdef>
  55                 <paramdef>GLfloat <parameter>v2</parameter></paramdef>
  56             </funcprototype>
  57         </funcsynopsis>
  58     </refsynopsisdiv>
  59     <!-- eqn: ignoring delim $$ -->
  60     <refsect1 id="parameters"><title>Parameters</title>
  61         <variablelist>
  62         <varlistentry>
  63             <term><parameter>un</parameter></term>
  64             <listitem>
  65                 <para>
  66                     Specifies the number of partitions in the grid range interval
  67                     [<parameter>u1</parameter>, <parameter>u2</parameter>].
  68                     Must be positive.
  69                 </para>
  70             </listitem>
  71         </varlistentry>
  72         <varlistentry>
  73             <term><parameter>u1</parameter></term>
  74             <term><parameter>u2</parameter></term>
  75             <listitem>
  76                 <para>
  77                     Specify the mappings for integer grid domain values
  78                     <inlineequation><mml:math>
  79                         <!-- eqn: i = 0:-->
  80                         <mml:mrow>
  81                             <mml:mi mathvariant="italic">i</mml:mi>
  82                             <mml:mo>=</mml:mo>
  83                             <mml:mn>0</mml:mn>
  84                         </mml:mrow>
  85                     </mml:math></inlineequation>
  86                     and
  87                     <inlineequation><mml:math>
  88                         <!-- eqn: i = un:-->
  89                         <mml:mrow>
  90                             <mml:mi mathvariant="italic">i</mml:mi>
  91                             <mml:mo>=</mml:mo>
  92                             <mml:mi mathvariant="italic">un</mml:mi>
  93                         </mml:mrow>
  94                     </mml:math></inlineequation>.
  95                 </para>
  96             </listitem>
  97         </varlistentry>
  98         <varlistentry>
  99             <term><parameter>vn</parameter></term>
 100             <listitem>
 101                 <para>
 102                     Specifies the number of partitions in the grid range interval
 103                     [<parameter>v1</parameter>, <parameter>v2</parameter>]
 104                     (<function>glMapGrid2</function> only).
 105                 </para>
 106             </listitem>
 107         </varlistentry>
 108         <varlistentry>
 109             <term><parameter>v1</parameter></term>
 110             <term><parameter>v2</parameter></term>
 111             <listitem>
 112                 <para>
 113                     Specify the mappings for integer grid domain values
 114                     <inlineequation><mml:math>
 115                         <!-- eqn: j = 0:-->
 116                         <mml:mrow>
 117                             <mml:mi mathvariant="italic">j</mml:mi>
 118                             <mml:mo>=</mml:mo>
 119                             <mml:mn>0</mml:mn>
 120                         </mml:mrow>
 121                     </mml:math></inlineequation>
 122                     and
 123                     <inlineequation><mml:math>
 124                         <!-- eqn: j = vn:-->
 125                         <mml:mrow>
 126                             <mml:mi mathvariant="italic">j</mml:mi>
 127                             <mml:mo>=</mml:mo>
 128                             <mml:mi mathvariant="italic">vn</mml:mi>
 129                         </mml:mrow>
 130                     </mml:math></inlineequation>
 131                     (<function>glMapGrid2</function> only).
 132                 </para>
 133             </listitem>
 134         </varlistentry>
 135         </variablelist>
 136     </refsect1>
 137     <refsect1 id="description"><title>Description</title>
 138         <para>
 139             <function>glMapGrid</function> and <citerefentry><refentrytitle>glEvalMesh</refentrytitle></citerefentry> are used together to efficiently
 140             generate and evaluate a series of evenly-spaced map domain values.
 141             <citerefentry><refentrytitle>glEvalMesh</refentrytitle></citerefentry> steps through the integer domain
 142             of a one- or two-dimensional grid,
 143             whose range is the domain of the evaluation maps specified by
 144             <citerefentry><refentrytitle>glMap1</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glMap2</refentrytitle></citerefentry>.
 145         </para>
 146         <para>
 147             <function>glMapGrid1</function> and <function>glMapGrid2</function> specify the linear grid mappings
 148             between the
 149             <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>
 150             (or
 151             <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>
 152             and
 153             <inlineequation><mml:math><mml:mi mathvariant="italic">j</mml:mi></mml:math></inlineequation>)
 154             integer grid coordinates,
 155             to the
 156             <inlineequation><mml:math><mml:mi mathvariant="italic">u</mml:mi></mml:math></inlineequation>
 157             (or
 158             <inlineequation><mml:math><mml:mi mathvariant="italic">u</mml:mi></mml:math></inlineequation>
 159             and
 160             <inlineequation><mml:math><mml:mi mathvariant="italic">v</mml:mi></mml:math></inlineequation>)
 161             floating-point evaluation map coordinates.
 162             See <citerefentry><refentrytitle>glMap1</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glMap2</refentrytitle></citerefentry> for details of how
 163             <inlineequation><mml:math><mml:mi mathvariant="italic">u</mml:mi></mml:math></inlineequation>
 164             and
 165             <inlineequation><mml:math><mml:mi mathvariant="italic">v</mml:mi></mml:math></inlineequation>
 166             coordinates
 167             are evaluated.
 168         </para>
 169         <para>
 170             <function>glMapGrid1</function> specifies a single linear mapping
 171             such that integer grid coordinate 0 maps exactly to <parameter>u1</parameter>,
 172             and integer grid coordinate <parameter>un</parameter> maps exactly to <parameter>u2</parameter>.
 173             All other integer grid coordinates
 174             <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>
 175             are mapped so that
 176         </para>
 177         <para>
 178             <informalequation><mml:math>
 179                 <!-- eqn: u  =  i (u2 - u1) / un  +  u1:-->
 180                 <mml:mrow>
 181                     <mml:mi mathvariant="italic">u</mml:mi>
 182                     <mml:mo>=</mml:mo>
 183                     <mml:mrow>
 184                         <mml:mfrac>
 185                             <mml:mrow>
 186                                 <mml:mi mathvariant="italic">i</mml:mi>
 187                                 <mml:mo>&af;</mml:mo>
 188                                 <mml:mfenced open="(" close=")">
 189                                     <mml:mrow>
 190                                         <mml:mi mathvariant="italic">u2</mml:mi>
 191                                         <mml:mo>-</mml:mo>
 192                                         <mml:mi mathvariant="italic">u1</mml:mi>
 193                                     </mml:mrow>
 194                                 </mml:mfenced>
 195                             </mml:mrow>
 196                             <mml:mi mathvariant="italic">un</mml:mi>
 197                         </mml:mfrac>
 198                         <mml:mo>+</mml:mo>
 199                         <mml:mi mathvariant="italic">u1</mml:mi>
 200                     </mml:mrow>
 201                 </mml:mrow>
 202             </mml:math></informalequation>
 203         </para>
 204         <para>
 205             <function>glMapGrid2</function> specifies two such linear mappings.
 206             One maps integer grid coordinate
 207             <inlineequation><mml:math>
 208                 <!-- eqn: i = 0:-->
 209                 <mml:mrow>
 210                     <mml:mi mathvariant="italic">i</mml:mi>
 211                     <mml:mo>=</mml:mo>
 212                     <mml:mn>0</mml:mn>
 213                 </mml:mrow>
 214             </mml:math></inlineequation>
 215             exactly to <parameter>u1</parameter>,
 216             and integer grid coordinate
 217             <inlineequation><mml:math>
 218                 <!-- eqn: i = un:-->
 219                 <mml:mrow>
 220                     <mml:mi mathvariant="italic">i</mml:mi>
 221                     <mml:mo>=</mml:mo>
 222                     <mml:mi mathvariant="italic">un</mml:mi>
 223                 </mml:mrow>
 224             </mml:math></inlineequation>
 225             exactly to <parameter>u2</parameter>.
 226             The other maps integer grid coordinate
 227             <inlineequation><mml:math>
 228                 <!-- eqn: j = 0:-->
 229                 <mml:mrow>
 230                     <mml:mi mathvariant="italic">j</mml:mi>
 231                     <mml:mo>=</mml:mo>
 232                     <mml:mn>0</mml:mn>
 233                 </mml:mrow>
 234             </mml:math></inlineequation>
 235             exactly to <parameter>v1</parameter>,
 236             and integer grid coordinate
 237             <inlineequation><mml:math>
 238                 <!-- eqn: j = vn:-->
 239                 <mml:mrow>
 240                     <mml:mi mathvariant="italic">j</mml:mi>
 241                     <mml:mo>=</mml:mo>
 242                     <mml:mi mathvariant="italic">vn</mml:mi>
 243                 </mml:mrow>
 244             </mml:math></inlineequation>
 245             exactly to <parameter>v2</parameter>.
 246             Other integer grid coordinates
 247             <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>
 248             and
 249             <inlineequation><mml:math><mml:mi mathvariant="italic">j</mml:mi></mml:math></inlineequation>
 250             are mapped such that
 251         </para>
 252         <para>
 253             <informalequation><mml:math>
 254                 <!-- eqn: u  =  i (u2 - u1) / un  +  u1:-->
 255                 <mml:mrow>
 256                     <mml:mi mathvariant="italic">u</mml:mi>
 257                     <mml:mo>=</mml:mo>
 258                     <mml:mrow>
 259                         <mml:mfrac>
 260                             <mml:mrow>
 261                                 <mml:mi mathvariant="italic">i</mml:mi>
 262                                 <mml:mo>&af;</mml:mo>
 263                                 <mml:mfenced open="(" close=")">
 264                                     <mml:mrow>
 265                                         <mml:mi mathvariant="italic">u2</mml:mi>
 266                                         <mml:mo>-</mml:mo>
 267                                         <mml:mi mathvariant="italic">u1</mml:mi>
 268                                     </mml:mrow>
 269                                 </mml:mfenced>
 270                             </mml:mrow>
 271                             <mml:mi mathvariant="italic">un</mml:mi>
 272                         </mml:mfrac>
 273                         <mml:mo>+</mml:mo>
 274                         <mml:mi mathvariant="italic">u1</mml:mi>
 275                     </mml:mrow>
 276                 </mml:mrow>
 277             </mml:math></informalequation>
 278         </para>
 279         <para>
 280             <informalequation><mml:math>
 281                 <!-- eqn: v  =  j (v2 - v1) / vn  +  v1:-->
 282                 <mml:mrow>
 283                     <mml:mi mathvariant="italic">v</mml:mi>
 284                     <mml:mo>=</mml:mo>
 285                     <mml:mrow>
 286                         <mml:mfrac>
 287                             <mml:mrow>
 288                                 <mml:mi mathvariant="italic">j</mml:mi>
 289                                 <mml:mo>&af;</mml:mo>
 290                                 <mml:mfenced open="(" close=")">
 291                                     <mml:mrow>
 292                                         <mml:mi mathvariant="italic">v2</mml:mi>
 293                                         <mml:mo>-</mml:mo>
 294                                         <mml:mi mathvariant="italic">v1</mml:mi>
 295                                     </mml:mrow>
 296                                 </mml:mfenced>
 297                             </mml:mrow>
 298                             <mml:mi mathvariant="italic">vn</mml:mi>
 299                         </mml:mfrac>
 300                         <mml:mo>+</mml:mo>
 301                         <mml:mi mathvariant="italic">v1</mml:mi>
 302                     </mml:mrow>
 303                 </mml:mrow>
 304             </mml:math></informalequation>
 305         </para>
 306         <para>
 307             The mappings specified by <function>glMapGrid</function> are used identically by
 308             <citerefentry><refentrytitle>glEvalMesh</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glEvalPoint</refentrytitle></citerefentry>.
 309         </para>
 310     </refsect1>
 311     <refsect1 id="errors"><title>Errors</title>
 312         <para>
 313             <constant>GL_INVALID_VALUE</constant> is generated if either <parameter>un</parameter> or <parameter>vn</parameter> is not
 314             positive.
 315         </para>
 316         <para>
 317             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glMapGrid</function>
 318             is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
 319             and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 320         </para>
 321     </refsect1>
 322     <refsect1 id="associatedgets"><title>Associated Gets</title>
 323         <para>
 324             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MAP1_GRID_DOMAIN</constant>
 325         </para>
 326         <para>
 327             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MAP2_GRID_DOMAIN</constant>
 328         </para>
 329         <para>
 330             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MAP1_GRID_SEGMENTS</constant>
 331         </para>
 332         <para>
 333             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MAP2_GRID_SEGMENTS</constant>
 334         </para>
 335     </refsect1>
 336     <refsect1 id="seealso"><title>See Also</title>
 337         <para>
 338             <citerefentry><refentrytitle>glEvalCoord</refentrytitle></citerefentry>,
 339             <citerefentry><refentrytitle>glEvalMesh</refentrytitle></citerefentry>,
 340             <citerefentry><refentrytitle>glEvalPoint</refentrytitle></citerefentry>,
 341             <citerefentry><refentrytitle>glMap1</refentrytitle></citerefentry>,
 342             <citerefentry><refentrytitle>glMap2</refentrytitle></citerefentry>
 343         </para>
 344     </refsect1>
 345     <refsect1 id="Copyright"><title>Copyright</title>
 346         <para>
 347             Copyright <trademark class="copyright"></trademark> 1991-2006
 348             Silicon Graphics, Inc. This document is licensed under the SGI
 349             Free Software B License. For details, see
 350             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 351         </para>
 352     </refsect1>
 353 </refentry>