upstream-man-pages/man2/glGetTexLevelParameter.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="glGetTexLevelParameter">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glGetTexLevelParameter</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glGetTexLevelParameter</refname>
  17         <refpurpose>return texture parameter values for a specific level of detail</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glGetTexLevelParameterfv</function></funcdef>
  23                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  24                 <paramdef>GLint <parameter>level</parameter></paramdef>
  25                 <paramdef>GLenum <parameter>pname</parameter></paramdef>
  26                 <paramdef>GLfloat * <parameter>params</parameter></paramdef>
  27             </funcprototype>
  28         </funcsynopsis>
  29         <funcsynopsis>
  30             <funcprototype>
  31                 <funcdef>void <function>glGetTexLevelParameteriv</function></funcdef>
  32                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  33                 <paramdef>GLint <parameter>level</parameter></paramdef>
  34                 <paramdef>GLenum <parameter>pname</parameter></paramdef>
  35                 <paramdef>GLint * <parameter>params</parameter></paramdef>
  36             </funcprototype>
  37         </funcsynopsis>
  38     </refsynopsisdiv>
  39     <!-- eqn: ignoring delim $$ -->
  40     <refsect1 id="parameters"><title>Parameters</title>
  41         <variablelist>
  42         <varlistentry>
  43             <term><parameter>target</parameter></term>
  44             <listitem>
  45                 <para>
  46                     Specifies the symbolic name of the target texture,
  47                     either <constant>GL_TEXTURE_1D</constant>, <constant>GL_TEXTURE_2D</constant>, <constant>GL_TEXTURE_3D</constant>,
  48                     <constant>GL_PROXY_TEXTURE_1D</constant>, <constant>GL_PROXY_TEXTURE_2D</constant>,
  49                     <constant>GL_PROXY_TEXTURE_3D</constant>,
  50                     <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>,
  51                     <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>,
  52                     <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>,
  53                     <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>,
  54                     <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>,
  55                     <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>, or
  56                     <constant>GL_PROXY_TEXTURE_CUBE_MAP</constant>.
  57                 </para>
  58             </listitem>
  59         </varlistentry>
  60         <varlistentry>
  61             <term><parameter>level</parameter></term>
  62             <listitem>
  63                 <para>
  64                     Specifies the level-of-detail number of the desired image.
  65                     Level 0 is the base image level.
  66                     Level
  67                     <inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>
  68                     is the
  69                     <inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>th
  70                     mipmap reduction image.
  71                 </para>
  72             </listitem>
  73         </varlistentry>
  74         <varlistentry>
  75             <term><parameter>pname</parameter></term>
  76             <listitem>
  77                 <para>
  78                     Specifies the symbolic name of a texture parameter.
  79                     <constant>GL_TEXTURE_WIDTH</constant>,
  80                     <constant>GL_TEXTURE_HEIGHT</constant>,
  81                     <constant>GL_TEXTURE_DEPTH</constant>,
  82                     <constant>GL_TEXTURE_INTERNAL_FORMAT</constant>,
  83                     <constant>GL_TEXTURE_BORDER</constant>,
  84                     <constant>GL_TEXTURE_RED_SIZE</constant>,
  85                     <constant>GL_TEXTURE_GREEN_SIZE</constant>,
  86                     <constant>GL_TEXTURE_BLUE_SIZE</constant>,
  87                     <constant>GL_TEXTURE_ALPHA_SIZE</constant>,
  88                     <constant>GL_TEXTURE_LUMINANCE_SIZE</constant>,
  89                     <constant>GL_TEXTURE_INTENSITY_SIZE</constant>,
  90                     <constant>GL_TEXTURE_DEPTH_SIZE</constant>,
  91                     <constant>GL_TEXTURE_COMPRESSED</constant>, and
  92                     <constant>GL_TEXTURE_COMPRESSED_IMAGE_SIZE</constant>
  93                      are accepted.
  94                 </para>
  95             </listitem>
  96         </varlistentry>
  97         <varlistentry>
  98             <term><parameter>params</parameter></term>
  99             <listitem>
 100                 <para>
 101                     Returns the requested data.
 102                 </para>
 103             </listitem>
 104         </varlistentry>
 105         </variablelist>
 106     </refsect1>
 107     <refsect1 id="description"><title>Description</title>
 108         <para>
 109             <function>glGetTexLevelParameter</function> returns in <parameter>params</parameter> texture parameter values for a specific
 110             level-of-detail value,
 111             specified as <parameter>level</parameter>.
 112             <parameter>target</parameter> defines the target texture,
 113             either <constant>GL_TEXTURE_1D</constant>, <constant>GL_TEXTURE_2D</constant>, <constant>GL_TEXTURE_3D</constant>,
 114             <constant>GL_PROXY_TEXTURE_1D</constant>,
 115             <constant>GL_PROXY_TEXTURE_2D</constant>,
 116             <constant>GL_PROXY_TEXTURE_3D</constant>,
 117             <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>,
 118             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>,
 119             <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>,
 120             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>,
 121             <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>,
 122             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>, or
 123             <constant>GL_PROXY_TEXTURE_CUBE_MAP</constant>.
 124         </para>
 125         <para>
 126             <constant>GL_MAX_TEXTURE_SIZE</constant>, and <constant>GL_MAX_3D_TEXTURE_SIZE</constant> are not really
 127             descriptive enough.
 128             It has to report the largest square texture image that can be
 129             accommodated with mipmaps and borders,
 130             but a long skinny texture, or a texture without mipmaps and borders, may
 131             easily fit in texture memory.
 132             The proxy targets allow the user to more accurately query
 133             whether the GL can accommodate a texture of a given configuration.
 134             If the texture cannot be accommodated, the texture state variables, which
 135             may be queried with <function>glGetTexLevelParameter</function>, are set to 0.  If the texture can be accommodated,
 136             the texture state values will be set as they would be set for a
 137             non-proxy target.
 138         </para>
 139         <para>
 140             <parameter>pname</parameter> specifies the texture parameter whose value or values
 141             will be returned.
 142         </para>
 143         <para>
 144             The accepted parameter names are as follows:
 145         </para>
 146         <variablelist>
 147             <varlistentry>
 148                 <term><constant>GL_TEXTURE_WIDTH</constant></term>
 149                 <listitem>
 150                     <para>
 151                     </para>
 152                     <para>
 153                         <parameter>params</parameter> returns a single value,
 154                         the width of the texture image.
 155                         This value includes the border of the texture image. The initial value is
 156                         0.
 157                     </para>
 158                 </listitem>
 159             </varlistentry>
 160             <varlistentry>
 161                 <term><constant>GL_TEXTURE_HEIGHT</constant></term>
 162                 <listitem>
 163                     <para>
 164                     </para>
 165                     <para>
 166                         <parameter>params</parameter> returns a single value,
 167                         the height of the texture image.
 168                         This value includes the border of the texture image. The initial value is
 169                         0.
 170                     </para>
 171                 </listitem>
 172             </varlistentry>
 173             <varlistentry>
 174                 <term><constant>GL_TEXTURE_DEPTH</constant></term>
 175                 <listitem>
 176                     <para>
 177                     </para>
 178                     <para>
 179                         <parameter>params</parameter> returns a single value,
 180                         the depth of the texture image.
 181                         This value includes the border of the texture image. The initial value is
 182                         0.
 183                     </para>
 184                 </listitem>
 185             </varlistentry>
 186             <varlistentry>
 187                 <term><constant>GL_TEXTURE_INTERNAL_FORMAT</constant></term>
 188                 <listitem>
 189                     <para>
 190                     </para>
 191                     <para>
 192                         <parameter>params</parameter> returns a single value,
 193                         the internal format of the texture image.
 194                     </para>
 195                 </listitem>
 196             </varlistentry>
 197             <varlistentry>
 198                 <term><constant>GL_TEXTURE_BORDER</constant></term>
 199                 <listitem>
 200                     <para>
 201                     </para>
 202                     <para>
 203                         <parameter>params</parameter> returns a single value,
 204                         the width in pixels of the border of the texture image. The initial value
 205                         is 0.
 206                     </para>
 207                 </listitem>
 208             </varlistentry>
 209             <varlistentry>
 210                 <term><constant>GL_TEXTURE_RED_SIZE</constant>,</term>
 211                 <listitem>
 212                 </listitem>
 213             </varlistentry>
 214             <varlistentry>
 215                 <term><constant>GL_TEXTURE_GREEN_SIZE</constant>,</term>
 216                 <listitem>
 217                 </listitem>
 218             </varlistentry>
 219             <varlistentry>
 220                 <term><constant>GL_TEXTURE_BLUE_SIZE</constant>,</term>
 221                 <listitem>
 222                 </listitem>
 223             </varlistentry>
 224             <varlistentry>
 225                 <term><constant>GL_TEXTURE_ALPHA_SIZE</constant>,</term>
 226                 <listitem>
 227                 </listitem>
 228             </varlistentry>
 229             <varlistentry>
 230                 <term><constant>GL_TEXTURE_LUMINANCE_SIZE</constant>,</term>
 231                 <listitem>
 232                 </listitem>
 233             </varlistentry>
 234             <varlistentry>
 235                 <term><constant>GL_TEXTURE_INTENSITY_SIZE</constant>,</term>
 236                 <listitem>
 237                 </listitem>
 238             </varlistentry>
 239             <varlistentry>
 240                 <term><constant>GL_TEXTURE_DEPTH_SIZE</constant></term>
 241                 <listitem>
 242                     <para>
 243                     </para>
 244                     <para>
 245                         The internal storage resolution of an individual component.
 246                         The resolution chosen by the GL will be a close match for the resolution
 247                         requested by the user with the component argument of <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
 248                         <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>, and
 249                         <citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>. The initial value is 0.
 250                     </para>
 251                 </listitem>
 252             </varlistentry>
 253             <varlistentry>
 254                 <term><constant>GL_TEXTURE_COMPRESSED</constant></term>
 255                 <listitem>
 256                     <para>
 257                     </para>
 258                     <para>
 259                         <parameter>params</parameter> returns a single boolean value indicating if the texture image is
 260                         stored in a compressed internal format.  The initiali value is <constant>GL_FALSE</constant>.
 261                     </para>
 262                 </listitem>
 263             </varlistentry>
 264             <varlistentry>
 265                 <term><constant>GL_TEXTURE_COMPRESSED_IMAGE_SIZE</constant></term>
 266                 <listitem>
 267                     <para>
 268                     </para>
 269                     <para>
 270                         <parameter>params</parameter> returns a single integer value, the number of unsigned bytes of the
 271                         compressed texture image that would be returned from
 272                         <citerefentry><refentrytitle>glGetCompressedTexImage</refentrytitle></citerefentry>.
 273                     </para>
 274                 </listitem>
 275             </varlistentry>
 276         </variablelist>
 277     </refsect1>
 278     <refsect1 id="notes"><title>Notes</title>
 279         <para>
 280             If an error is generated,
 281             no change is made to the contents of <parameter>params</parameter>.
 282         </para>
 283         <para>
 284             <constant>GL_TEXTURE_INTERNAL_FORMAT</constant> is available only if the GL version is
 285             1.1 or greater. In version 1.0, use <constant>GL_TEXTURE_COMPONENTS</constant>
 286             instead.
 287         </para>
 288         <para>
 289             <constant>GL_PROXY_TEXTURE_1D</constant> and <constant>GL_PROXY_TEXTURE_2D</constant> are
 290             available only if the GL version is 1.1 or greater.
 291         </para>
 292         <para>
 293             <constant>GL_TEXTURE_3D</constant>, <constant>GL_PROXY_TEXTURE_3D</constant>, and <constant>GL_TEXTURE_DEPTH</constant>
 294             are available only if the GL version is 1.2 or greater.
 295         </para>
 296         <para>
 297             <constant>GL_TEXTURE_COMPRESSED</constant>,
 298             <constant>GL_TEXTURE_COMPRESSED_IMAGE_SIZE</constant>,
 299             <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>,
 300             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>,
 301             <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>,
 302             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>,
 303             <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>,
 304             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>, and
 305             <constant>GL_PROXY_TEXTURE_CUBE_MAP</constant> are available only if the GL version is 1.3
 306             or greater.
 307         </para>
 308         <para>
 309             For OpenGL versions 1.3 and greater, or when the <code>ARB_multitexture</code> extension is supported, <function>glGetTexLevelParameter</function> returns
 310             the texture level parameters for the active texture unit.
 311         </para>
 312     </refsect1>
 313     <refsect1 id="errors"><title>Errors</title>
 314         <para>
 315             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> or <parameter>pname</parameter> is not an
 316             accepted value.
 317         </para>
 318         <para>
 319             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>level</parameter> is less than 0.
 320         </para>
 321         <para>
 322             <constant>GL_INVALID_VALUE</constant> may be generated if <parameter>level</parameter> is greater
 323             than
 324             <inlineequation><mml:math>
 325                 <!-- eqn: log sub 2:-->
 326                 <mml:msub><mml:mi mathvariant="italic">log</mml:mi>
 327                 <mml:mn>2</mml:mn>
 328                 </mml:msub>
 329             </mml:math></inlineequation>
 330             <emphasis>max</emphasis>,
 331             where <emphasis>max</emphasis> is the returned value of <constant>GL_MAX_TEXTURE_SIZE</constant>.
 332         </para>
 333         <para>
 334             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glGetTexLevelParameter</function>
 335             is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
 336             and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 337         </para>
 338         <para>
 339             <constant>GL_INVALID_OPERATION</constant> is generated if
 340             <constant>GL_TEXTURE_COMPRESSED_IMAGE_SIZE</constant> is queried on texture images with an
 341             uncompressed internal format or on proxy targets.
 342         </para>
 343     </refsect1>
 344     <refsect1 id="seealso"><title>See Also</title>
 345         <para>
 346             <citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>,
 347             <citerefentry><refentrytitle>glGetTexParameter</refentrytitle></citerefentry>,
 348             <citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
 349             <citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>,
 350             <citerefentry><refentrytitle>glCopyTexSubImage1D</refentrytitle></citerefentry>,
 351             <citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>,
 352             <citerefentry><refentrytitle>glCopyTexSubImage3D</refentrytitle></citerefentry>,
 353             <citerefentry><refentrytitle>glTexEnv</refentrytitle></citerefentry>,
 354             <citerefentry><refentrytitle>glTexGen</refentrytitle></citerefentry>,
 355             <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
 356             <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
 357             <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
 358             <citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
 359             <citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
 360             <citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>,
 361             <citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>
 362         </para>
 363     </refsect1>
 364     <refsect1 id="Copyright"><title>Copyright</title>
 365         <para>
 366             Copyright <trademark class="copyright"></trademark> 1991-2006
 367             Silicon Graphics, Inc. This document is licensed under the SGI
 368             Free Software B License. For details, see
 369             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 370         </para>
 371     </refsect1>
 372 </refentry>