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