upstream-doc/man4/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>2013</year>
   9                 <holder>Khronos Group</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                     one of
  48                     <constant>GL_TEXTURE_1D</constant>,
  49                     <constant>GL_TEXTURE_2D</constant>,
  50                     <constant>GL_TEXTURE_3D</constant>,
  51                     <constant>GL_TEXTURE_1D_ARRAY</constant>,
  52                     <constant>GL_TEXTURE_2D_ARRAY</constant>,
  53                     <constant>GL_TEXTURE_RECTANGLE</constant>,
  54                     <constant>GL_TEXTURE_2D_MULTISAMPLE</constant>,
  55                     <constant>GL_TEXTURE_2D_MULTISAMPLE_ARRAY</constant>,
  56                     <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>,
  57                     <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>,
  58                     <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>,
  59                     <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>,
  60                     <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>,
  61                     <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>,
  62                     <constant>GL_PROXY_TEXTURE_1D</constant>,
  63                     <constant>GL_PROXY_TEXTURE_2D</constant>,
  64                     <constant>GL_PROXY_TEXTURE_3D</constant>,
  65                     <constant>GL_PROXY_TEXTURE_1D_ARRAY</constant>,
  66                     <constant>GL_PROXY_TEXTURE_2D_ARRAY</constant>,
  67                     <constant>GL_PROXY_TEXTURE_RECTANGLE</constant>,
  68                     <constant>GL_PROXY_TEXTURE_2D_MULTISAMPLE</constant>,
  69                     <constant>GL_PROXY_TEXTURE_2D_MULTISAMPLE_ARRAY</constant>,
  70                     <constant>GL_PROXY_TEXTURE_CUBE_MAP</constant>, or
  71                     <constant>GL_TEXTURE_BUFFER</constant>.
  72                 </para>
  73             </listitem>
  74         </varlistentry>
  75         <varlistentry>
  76             <term><parameter>level</parameter></term>
  77             <listitem>
  78                 <para>
  79                     Specifies the level-of-detail number of the desired image.
  80                     Level 0 is the base image level.
  81                     Level
  82                     <inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>
  83                     is the
  84                     <inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>th
  85                     mipmap reduction image.
  86                 </para>
  87             </listitem>
  88         </varlistentry>
  89         <varlistentry>
  90             <term><parameter>pname</parameter></term>
  91             <listitem>
  92                 <para>
  93                     Specifies the symbolic name of a texture parameter.
  94                     <constant>GL_TEXTURE_WIDTH</constant>,
  95                     <constant>GL_TEXTURE_HEIGHT</constant>,
  96                     <constant>GL_TEXTURE_DEPTH</constant>,
  97                     <constant>GL_TEXTURE_INTERNAL_FORMAT</constant>,
  98                     <constant>GL_TEXTURE_RED_SIZE</constant>,
  99                     <constant>GL_TEXTURE_GREEN_SIZE</constant>,
 100                     <constant>GL_TEXTURE_BLUE_SIZE</constant>,
 101                     <constant>GL_TEXTURE_ALPHA_SIZE</constant>,
 102                     <constant>GL_TEXTURE_DEPTH_SIZE</constant>,
 103                     <constant>GL_TEXTURE_COMPRESSED</constant>,
 104                     <constant>GL_TEXTURE_COMPRESSED_IMAGE_SIZE</constant>, and
 105                     <constant>GL_TEXTURE_BUFFER_OFFSET</constant>
 106                      are accepted.
 107                 </para>
 108             </listitem>
 109         </varlistentry>
 110         <varlistentry>
 111             <term><parameter>params</parameter></term>
 112             <listitem>
 113                 <para>
 114                     Returns the requested data.
 115                 </para>
 116             </listitem>
 117         </varlistentry>
 118         </variablelist>
 119     </refsect1>
 120     <refsect1 id="description"><title>Description</title>
 121         <para>
 122             <function>glGetTexLevelParameter</function> returns in <parameter>params</parameter> texture parameter values for a specific
 123             level-of-detail value,
 124             specified as <parameter>level</parameter>.
 125             <parameter>target</parameter> defines the target texture,
 126             either <constant>GL_TEXTURE_1D</constant>, <constant>GL_TEXTURE_2D</constant>, <constant>GL_TEXTURE_3D</constant>,
 127             <constant>GL_PROXY_TEXTURE_1D</constant>,
 128             <constant>GL_PROXY_TEXTURE_2D</constant>,
 129             <constant>GL_PROXY_TEXTURE_3D</constant>,
 130             <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>,
 131             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>,
 132             <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>,
 133             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>,
 134             <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>,
 135             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>, or
 136             <constant>GL_PROXY_TEXTURE_CUBE_MAP</constant>.
 137         </para>
 138         <para>
 139             <constant>GL_MAX_TEXTURE_SIZE</constant>, and <constant>GL_MAX_3D_TEXTURE_SIZE</constant> are not really
 140             descriptive enough.
 141             It has to report the largest square texture image that can be
 142             accommodated with mipmaps
 143             but a long skinny texture, or a texture without mipmaps may
 144             easily fit in texture memory.
 145             The proxy targets allow the user to more accurately query
 146             whether the GL can accommodate a texture of a given configuration.
 147             If the texture cannot be accommodated, the texture state variables, which
 148             may be queried with <function>glGetTexLevelParameter</function>, are set to 0.  If the texture can be accommodated,
 149             the texture state values will be set as they would be set for a
 150             non-proxy target.
 151         </para>
 152         <para>
 153             <parameter>pname</parameter> specifies the texture parameter whose value or values
 154             will be returned.
 155         </para>
 156         <para>
 157             The accepted parameter names are as follows:
 158         </para>
 159         <variablelist>
 160             <varlistentry>
 161                 <term><constant>GL_TEXTURE_WIDTH</constant></term>
 162                 <listitem>
 163                     <para>
 164                     </para>
 165                     <para>
 166                         <parameter>params</parameter> returns a single value,
 167                         the width of the texture image.
 168                         The initial value is 0.
 169                     </para>
 170                 </listitem>
 171             </varlistentry>
 172             <varlistentry>
 173                 <term><constant>GL_TEXTURE_HEIGHT</constant></term>
 174                 <listitem>
 175                     <para>
 176                     </para>
 177                     <para>
 178                         <parameter>params</parameter> returns a single value,
 179                         the height of the texture image.
 180                         The initial value is 0.
 181                     </para>
 182                 </listitem>
 183             </varlistentry>
 184             <varlistentry>
 185                 <term><constant>GL_TEXTURE_DEPTH</constant></term>
 186                 <listitem>
 187                     <para>
 188                     </para>
 189                     <para>
 190                         <parameter>params</parameter> returns a single value,
 191                         the depth of the texture image.
 192                         The initial value is 0.
 193                     </para>
 194                 </listitem>
 195             </varlistentry>
 196             <varlistentry>
 197                 <term><constant>GL_TEXTURE_INTERNAL_FORMAT</constant></term>
 198                 <listitem>
 199                     <para>
 200                     </para>
 201                     <para>
 202                         <parameter>params</parameter> returns a single value,
 203                         the internal format of the texture image.
 204                     </para>
 205                 </listitem>
 206             </varlistentry>
 207             <varlistentry>
 208                 <term><constant>GL_TEXTURE_RED_TYPE</constant>,</term>
 209                 <listitem>
 210                 </listitem>
 211             </varlistentry>
 212             <varlistentry>
 213                 <term><constant>GL_TEXTURE_GREEN_TYPE</constant>,</term>
 214                 <listitem>
 215                 </listitem>
 216             </varlistentry>
 217             <varlistentry>
 218                 <term><constant>GL_TEXTURE_BLUE_TYPE</constant>,</term>
 219                 <listitem>
 220                 </listitem>
 221             </varlistentry>
 222             <varlistentry>
 223                 <term><constant>GL_TEXTURE_ALPHA_TYPE</constant>,</term>
 224                 <listitem>
 225                 </listitem>
 226             </varlistentry>
 227             <varlistentry>
 228                 <term><constant>GL_TEXTURE_DEPTH_TYPE</constant></term>
 229                 <listitem>
 230                     <para>
 231                     </para>
 232                     <para>
 233                         The data type used to store the component.
 234                         The types <constant>GL_NONE</constant>, <constant>GL_SIGNED_NORMALIZED</constant>,
 235                         <constant>GL_UNSIGNED_NORMALIZED</constant>, <constant>GL_FLOAT</constant>,
 236                         <constant>GL_INT</constant>, and <constant>GL_UNSIGNED_INT</constant> may be returned
 237                         to indicate signed normalized fixed-point, unsigned normalized fixed-point, floating-point, integer unnormalized, and
 238                         unsigned integer unnormalized components, respectively.
 239                     </para>
 240                 </listitem>
 241             </varlistentry>
 242             <varlistentry>
 243                 <term><constant>GL_TEXTURE_RED_SIZE</constant>,</term>
 244                 <listitem>
 245                 </listitem>
 246             </varlistentry>
 247             <varlistentry>
 248                 <term><constant>GL_TEXTURE_GREEN_SIZE</constant>,</term>
 249                 <listitem>
 250                 </listitem>
 251             </varlistentry>
 252             <varlistentry>
 253                 <term><constant>GL_TEXTURE_BLUE_SIZE</constant>,</term>
 254                 <listitem>
 255                 </listitem>
 256             </varlistentry>
 257             <varlistentry>
 258                 <term><constant>GL_TEXTURE_ALPHA_SIZE</constant>,</term>
 259                 <listitem>
 260                 </listitem>
 261             </varlistentry>
 262             <varlistentry>
 263                 <term><constant>GL_TEXTURE_DEPTH_SIZE</constant></term>
 264                 <listitem>
 265                     <para>
 266                     </para>
 267                     <para>
 268                         The internal storage resolution of an individual component.
 269                         The resolution chosen by the GL will be a close match for the resolution
 270                         requested by the user with the component argument of <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
 271                         <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>, and
 272                         <citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>. The initial value is 0.
 273                     </para>
 274                 </listitem>
 275             </varlistentry>
 276             <varlistentry>
 277                 <term><constant>GL_TEXTURE_COMPRESSED</constant></term>
 278                 <listitem>
 279                     <para>
 280                     </para>
 281                     <para>
 282                         <parameter>params</parameter> returns a single boolean value indicating if the texture image is
 283                         stored in a compressed internal format.  The initiali value is <constant>GL_FALSE</constant>.
 284                     </para>
 285                 </listitem>
 286             </varlistentry>
 287             <varlistentry>
 288                 <term><constant>GL_TEXTURE_COMPRESSED_IMAGE_SIZE</constant></term>
 289                 <listitem>
 290                     <para>
 291                     </para>
 292                     <para>
 293                         <parameter>params</parameter> returns a single integer value, the number of unsigned bytes of the
 294                         compressed texture image that would be returned from
 295                         <citerefentry><refentrytitle>glGetCompressedTexImage</refentrytitle></citerefentry>.
 296                     </para>
 297                 </listitem>
 298             </varlistentry>
 299             <varlistentry>
 300                 <term><constant>GL_TEXTURE_BUFFER_OFFSET</constant></term>
 301                 <listitem>
 302                     <para>
 303                     </para>
 304                     <para>
 305                         <parameter>params</parameter> returns a single integer value, the offset into the
 306                         data store of the buffer bound to a buffer texture.
 307                         <citerefentry><refentrytitle>glTexBufferRange</refentrytitle></citerefentry>.
 308                     </para>
 309                 </listitem>
 310             </varlistentry>
 311             <varlistentry>
 312                 <term><constant>GL_TEXTURE_BUFFER_SIZE</constant></term>
 313                 <listitem>
 314                     <para>
 315                     </para>
 316                     <para>
 317                         <parameter>params</parameter> returns a single integer value, the size of the range of a
 318                         data store of the buffer bound to a buffer texture.
 319                         <citerefentry><refentrytitle>glTexBufferRange</refentrytitle></citerefentry>.
 320                     </para>
 321                 </listitem>
 322             </varlistentry>
 323         </variablelist>
 324     </refsect1>
 325     <refsect1 id="notes"><title>Notes</title>
 326         <para>
 327             If an error is generated,
 328             no change is made to the contents of <parameter>params</parameter>.
 329         </para>
 330         <para>
 331             <function>glGetTexLevelParameter</function> returns the texture level parameters for the active texture unit.
 332         </para>
 333         <para>
 334             <constant>GL_TEXTURE_BUFFER_OFFSET</constant> and <constant>GL_TEXTURE_BUFFER_SIZE</constant> are available only
 335             if the GL version is 4.3 or greater.
 336         </para>
 337     </refsect1>
 338     <refsect1 id="errors"><title>Errors</title>
 339         <para>
 340             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> or <parameter>pname</parameter> is not an
 341             accepted value.
 342         </para>
 343         <para>
 344             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>level</parameter> is less than 0.
 345         </para>
 346         <para>
 347             <constant>GL_INVALID_VALUE</constant> may be generated if <parameter>level</parameter> is greater
 348             than
 349             <inlineequation><mml:math>
 350                 <!-- eqn: log sub 2: -->
 351                 <mml:msub><mml:mi mathvariant="italic">log</mml:mi>
 352                 <mml:mn>2</mml:mn>
 353                 </mml:msub>
 354             </mml:math></inlineequation>
 355             <emphasis>max</emphasis>,
 356             where <emphasis>max</emphasis> is the returned value of <constant>GL_MAX_TEXTURE_SIZE</constant>.
 357         </para>
 358         <para>
 359             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>target</parameter> is <constant>GL_TEXTURE_BUFFER</constant>
 360             and <parameter>level</parameter> is not zero.
 361         </para>
 362         <para>
 363             <constant>GL_INVALID_OPERATION</constant> is generated if
 364             <constant>GL_TEXTURE_COMPRESSED_IMAGE_SIZE</constant> is queried on texture images with an
 365             uncompressed internal format or on proxy targets.
 366         </para>
 367     </refsect1>
 368     <refsect1 id="seealso"><title>See Also</title>
 369         <para>
 370             <citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>,
 371             <citerefentry><refentrytitle>glGetTexParameter</refentrytitle></citerefentry>,
 372             <citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
 373             <citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>,
 374             <citerefentry><refentrytitle>glCopyTexSubImage1D</refentrytitle></citerefentry>,
 375             <citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>,
 376             <citerefentry><refentrytitle>glCopyTexSubImage3D</refentrytitle></citerefentry>,
 377             <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
 378             <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
 379             <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
 380             <citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
 381             <citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
 382             <citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>,
 383             <citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>
 384         </para>
 385     </refsect1>
 386     <refsect1 id="Copyright"><title>Copyright</title>
 387         <para>
 388             Copyright <trademark class="copyright"></trademark> 1991-2006
 389             Silicon Graphics, Inc. Copyright <trademark class="copyright"></trademark> 2010-2013
 390             Khronos Group. This document is licensed under the SGI
 391             Free Software B License. For details, see
 392             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 393         </para>
 394     </refsect1>
 395 </refentry>