upstream-man-pages/man4/glGetTexParameter.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="glGetTexParameter">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glGetTexParameter</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glGetTexParameter</refname>
  17         <refpurpose>return texture parameter values</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glGetTexParameterfv</function></funcdef>
  23                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  24                 <paramdef>GLenum <parameter>pname</parameter></paramdef>
  25                 <paramdef>GLfloat * <parameter>params</parameter></paramdef>
  26             </funcprototype>
  27         </funcsynopsis>
  28         <funcsynopsis>
  29             <funcprototype>
  30                 <funcdef>void <function>glGetTexParameteriv</function></funcdef>
  31                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  32                 <paramdef>GLenum <parameter>pname</parameter></paramdef>
  33                 <paramdef>GLint * <parameter>params</parameter></paramdef>
  34             </funcprototype>
  35         </funcsynopsis>
  36         <funcsynopsis>
  37             <funcprototype>
  38                 <funcdef>void <function>glGetTexParameterIiv</function></funcdef>
  39                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  40                 <paramdef>GLenum <parameter>pname</parameter></paramdef>
  41                 <paramdef>GLint * <parameter>params</parameter></paramdef>
  42             </funcprototype>
  43         </funcsynopsis>
  44         <funcsynopsis>
  45             <funcprototype>
  46                 <funcdef>void <function>glGetTexParameterIuiv</function></funcdef>
  47                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  48                 <paramdef>GLenum <parameter>pname</parameter></paramdef>
  49                 <paramdef>GLuint * <parameter>params</parameter></paramdef>
  50             </funcprototype>
  51         </funcsynopsis>
  52     </refsynopsisdiv>
  53     <!-- eqn: ignoring delim $$ -->
  54     <refsect1 id="parameters"><title>Parameters</title>
  55         <variablelist>
  56         <varlistentry>
  57             <term><parameter>target</parameter></term>
  58             <listitem>
  59                 <para>
  60                     Specifies the symbolic name of the target texture.
  61                     <constant>GL_TEXTURE_1D</constant>,
  62                     <constant>GL_TEXTURE_2D</constant>,
  63                     <constant>GL_TEXTURE_1D_ARRAY</constant>,
  64                     <constant>GL_TEXTURE_2D_ARRAY</constant>,
  65                     <constant>GL_TEXTURE_3D</constant>,
  66                     <constant>GL_TEXTURE_RECTANGLE</constant>,
  67                     <constant>GL_TEXTURE_CUBE_MAP</constant>, and
  68                     <constant>GL_TEXTURE_CUBE_MAP_ARRAY</constant>
  69                     are accepted.
  70                 </para>
  71             </listitem>
  72         </varlistentry>
  73         <varlistentry>
  74             <term><parameter>pname</parameter></term>
  75             <listitem>
  76                 <para>
  77                     Specifies the symbolic name of a texture parameter.
  78                     <constant>GL_DEPTH_STENCIL_TEXTURE_MODE</constant>,
  79                     <constant>GL_TEXTURE_BASE_LEVEL</constant>,
  80                     <constant>GL_TEXTURE_BORDER_COLOR</constant>,
  81                     <constant>GL_TEXTURE_COMPARE_MODE</constant>,
  82                     <constant>GL_TEXTURE_COMPARE_FUNC</constant>,
  83                     <constant>GL_TEXTURE_IMMUTABLE_FORMAT</constant>,
  84                     <constant>GL_TEXTURE_IMMUTABLE_LEVELS</constant>,
  85                     <constant>GL_TEXTURE_LOD_BIAS</constant>,
  86                     <constant>GL_TEXTURE_MAG_FILTER</constant>,
  87                     <constant>GL_TEXTURE_MAX_LEVEL</constant>,
  88                     <constant>GL_TEXTURE_MAX_LOD</constant>,
  89                     <constant>GL_TEXTURE_MIN_FILTER</constant>,
  90                     <constant>GL_TEXTURE_MIN_LOD</constant>,
  91                     <constant>GL_TEXTURE_SWIZZLE_R</constant>,
  92                     <constant>GL_TEXTURE_SWIZZLE_G</constant>,
  93                     <constant>GL_TEXTURE_SWIZZLE_B</constant>,
  94                     <constant>GL_TEXTURE_SWIZZLE_A</constant>,
  95                     <constant>GL_TEXTURE_SWIZZLE_RGBA</constant>,
  96                     <constant>GL_TEXTURE_VIEW_MIN_LAYER</constant>,
  97                     <constant>GL_TEXTURE_VIEW_MIN_LEVEL</constant>,
  98                     <constant>GL_TEXTURE_VIEW_NUM_LAYERS</constant>,
  99                     <constant>GL_TEXTURE_VIEW_NUM_LEVELS</constant>,
 100                     <constant>GL_TEXTURE_WRAP_S</constant>,
 101                     <constant>GL_TEXTURE_WRAP_T</constant>, and
 102                     <constant>GL_TEXTURE_WRAP_R</constant>
 103                     are accepted.
 104                 </para>
 105             </listitem>
 106         </varlistentry>
 107         <varlistentry>
 108             <term><parameter>params</parameter></term>
 109             <listitem>
 110                 <para>
 111                     Returns the texture parameters.
 112                 </para>
 113             </listitem>
 114         </varlistentry>
 115         </variablelist>
 116     </refsect1>
 117     <refsect1 id="description"><title>Description</title>
 118         <para>
 119             <function>glGetTexParameter</function> returns in <parameter>params</parameter> the value or values of the texture parameter
 120             specified as <parameter>pname</parameter>.
 121             <parameter>target</parameter> defines the target texture.
 122             <constant>GL_TEXTURE_1D</constant>,
 123             <constant>GL_TEXTURE_2D</constant>,
 124             <constant>GL_TEXTURE_3D</constant>,
 125             <constant>GL_TEXTURE_1D_ARRAY</constant>,
 126             <constant>GL_TEXTURE_2D_ARRAY</constant>,
 127             <constant>GL_TEXTURE_RECTANGLE</constant>,
 128             <constant>GL_TEXTURE_CUBE_MAP</constant>,
 129             <constant>GL_TEXTURE_CUBE_MAP_ARRAY</constant>
 130             specify one-, two-, or three-dimensional, one-dimensional array, two-dimensional array, rectangle, cube-mapped or cube-mapped array texturing, respectively.
 131             <parameter>pname</parameter> accepts the same symbols as <citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>,
 132             with the same interpretations:
 133         </para>
 134         <variablelist>
 135             <varlistentry>
 136                 <term><constant>GL_DEPTH_STENCIL_TEXTURE_MODE</constant></term>
 137                 <listitem>
 138                     <para>
 139                         Returns the single-value depth stencil texture mode, a symbolic constant.
 140                         The initial value is <constant>GL_DEPTH_COMPONENT</constant>.
 141                     </para>
 142                 </listitem>
 143             </varlistentry>
 144             <varlistentry>
 145                 <term><constant>GL_TEXTURE_MAG_FILTER</constant></term>
 146                 <listitem>
 147                     <para>
 148                         Returns the single-valued texture magnification filter,
 149                         a symbolic constant. The initial value is <constant>GL_LINEAR</constant>.
 150                     </para>
 151                 </listitem>
 152             </varlistentry>
 153             <varlistentry>
 154                 <term><constant>GL_TEXTURE_MIN_FILTER</constant></term>
 155                 <listitem>
 156                     <para>
 157                         Returns the single-valued texture minification filter,
 158                         a symbolic constant. The initial value is <constant>GL_NEAREST_MIPMAP_LINEAR</constant>.
 159                     </para>
 160                 </listitem>
 161             </varlistentry>
 162             <varlistentry>
 163                 <term><constant>GL_TEXTURE_MIN_LOD</constant></term>
 164                 <listitem>
 165                     <para>
 166                         Returns the single-valued texture minimum level-of-detail value.  The
 167                         initial value is
 168                         <inlineequation><mml:math>
 169                             <!-- eqn: -1000: -->
 170                             <mml:mn>-1000</mml:mn>
 171                         </mml:math></inlineequation>.
 172                     </para>
 173                 </listitem>
 174             </varlistentry>
 175             <varlistentry>
 176                 <term><constant>GL_TEXTURE_MAX_LOD</constant></term>
 177                 <listitem>
 178                     <para>
 179                         Returns the single-valued texture maximum level-of-detail value. The
 180                         initial value is 1000.
 181                     </para>
 182                 </listitem>
 183             </varlistentry>
 184             <varlistentry>
 185                 <term><constant>GL_TEXTURE_BASE_LEVEL</constant></term>
 186                 <listitem>
 187                     <para>
 188                         Returns the single-valued base texture mipmap level.  The initial value is 0.
 189                     </para>
 190                 </listitem>
 191             </varlistentry>
 192             <varlistentry>
 193                 <term><constant>GL_TEXTURE_MAX_LEVEL</constant></term>
 194                 <listitem>
 195                     <para>
 196                         Returns the single-valued maximum texture mipmap array level.  The initial
 197                         value is 1000.
 198                     </para>
 199                 </listitem>
 200             </varlistentry>
 201             <varlistentry>
 202                 <term><constant>GL_TEXTURE_SWIZZLE_R</constant></term>
 203                 <listitem>
 204                     <para>
 205                         Returns the red component swizzle. The initial value is <constant>GL_RED</constant>.
 206                     </para>
 207                 </listitem>
 208             </varlistentry>
 209             <varlistentry>
 210                 <term><constant>GL_TEXTURE_SWIZZLE_G</constant></term>
 211                 <listitem>
 212                     <para>
 213                         Returns the green component swizzle. The initial value is <constant>GL_GREEN</constant>.
 214                     </para>
 215                 </listitem>
 216             </varlistentry>
 217             <varlistentry>
 218                 <term><constant>GL_TEXTURE_SWIZZLE_B</constant></term>
 219                 <listitem>
 220                     <para>
 221                         Returns the blue component swizzle. The initial value is <constant>GL_BLUE</constant>.
 222                     </para>
 223                 </listitem>
 224             </varlistentry>
 225             <varlistentry>
 226                 <term><constant>GL_TEXTURE_SWIZZLE_A</constant></term>
 227                 <listitem>
 228                     <para>
 229                         Returns the alpha component swizzle. The initial value is <constant>GL_ALPHA</constant>.
 230                     </para>
 231                 </listitem>
 232             </varlistentry>
 233             <varlistentry>
 234                 <term><constant>GL_TEXTURE_SWIZZLE_RGBA</constant></term>
 235                 <listitem>
 236                     <para>
 237                         Returns the component swizzle for all channels in a single query.
 238                     </para>
 239                 </listitem>
 240             </varlistentry>
 241             <varlistentry>
 242                 <term><constant>GL_TEXTURE_WRAP_S</constant></term>
 243                 <listitem>
 244                     <para>
 245                         Returns the single-valued wrapping function for texture coordinate
 246                         <inlineequation><mml:math><mml:mi mathvariant="italic">s</mml:mi></mml:math></inlineequation>,
 247                         a symbolic constant. The initial value is <constant>GL_REPEAT</constant>.
 248                     </para>
 249                 </listitem>
 250             </varlistentry>
 251             <varlistentry>
 252                 <term><constant>GL_TEXTURE_WRAP_T</constant></term>
 253                 <listitem>
 254                     <para>
 255                         Returns the single-valued wrapping function for texture coordinate
 256                         <inlineequation><mml:math><mml:mi mathvariant="italic">t</mml:mi></mml:math></inlineequation>,
 257                         a symbolic constant. The initial value is <constant>GL_REPEAT</constant>.
 258                     </para>
 259                 </listitem>
 260             </varlistentry>
 261             <varlistentry>
 262                 <term><constant>GL_TEXTURE_WRAP_R</constant></term>
 263                 <listitem>
 264                     <para>
 265                         Returns the single-valued wrapping function for texture coordinate
 266                         <inlineequation><mml:math><mml:mi mathvariant="italic">r</mml:mi></mml:math></inlineequation>,
 267                         a symbolic constant. The initial value is <constant>GL_REPEAT</constant>.
 268                     </para>
 269                 </listitem>
 270             </varlistentry>
 271             <varlistentry>
 272                 <term><constant>GL_TEXTURE_BORDER_COLOR</constant></term>
 273                 <listitem>
 274                     <para>
 275                         Returns four integer or floating-point numbers that comprise the RGBA color
 276                         of the texture border.
 277                         Floating-point values are returned in the range
 278                         <inlineequation><mml:math>
 279                             <!-- eqn: [0,1]: -->
 280                             <mml:mfenced open="[" close="]">
 281                                 <mml:mn>0</mml:mn>
 282                                 <mml:mn>1</mml:mn>
 283                             </mml:mfenced>
 284                         </mml:math></inlineequation>.
 285                         Integer values are returned as a linear mapping of the internal floating-point
 286                         representation such that 1.0 maps to the most positive representable
 287                         integer and
 288                         <inlineequation><mml:math>
 289                             <!-- eqn: -1.0: -->
 290                             <mml:mn>-1.0</mml:mn>
 291                         </mml:math></inlineequation>
 292                         maps to the most negative representable
 293                         integer. The initial value is (0, 0, 0, 0).
 294                     </para>
 295                 </listitem>
 296             </varlistentry>
 297             <varlistentry>
 298                 <term><constant>GL_TEXTURE_COMPARE_MODE</constant></term>
 299                 <listitem>
 300                     <para>
 301                         Returns a single-valued texture comparison mode, a symbolic constant.  The
 302                         initial value is <constant>GL_NONE</constant>. See <citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>.
 303                     </para>
 304                 </listitem>
 305             </varlistentry>
 306             <varlistentry>
 307                 <term><constant>GL_TEXTURE_COMPARE_FUNC</constant></term>
 308                 <listitem>
 309                     <para>
 310                         Returns a single-valued texture comparison function, a symbolic constant.  The
 311                         initial value is <constant>GL_LEQUAL</constant>. See <citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>.
 312                     </para>
 313                 </listitem>
 314             </varlistentry>
 315             <varlistentry>
 316                 <term><constant>GL_TEXTURE_VIEW_MIN_LEVEL</constant></term>
 317                 <listitem>
 318                     <para>
 319                         Returns a single-valued base level of a texture view relative to its parent.  The
 320                         initial value is 0. See <citerefentry><refentrytitle>glTextureView</refentrytitle></citerefentry>.
 321                     </para>
 322                 </listitem>
 323             </varlistentry>
 324             <varlistentry>
 325                 <term><constant>GL_TEXTURE_VIEW_NUM_LEVELS</constant></term>
 326                 <listitem>
 327                     <para>
 328                         Returns a single-valued number of levels of detail of a texture view.
 329                         See <citerefentry><refentrytitle>glTextureView</refentrytitle></citerefentry>.
 330                     </para>
 331                 </listitem>
 332             </varlistentry>
 333             <varlistentry>
 334                 <term><constant>GL_TEXTURE_VIEW_MIN_LAYER</constant></term>
 335                 <listitem>
 336                     <para>
 337                         Returns a single-valued first level of a texture array view relative to its parent.
 338                         See <citerefentry><refentrytitle>glTextureView</refentrytitle></citerefentry>.
 339                     </para>
 340                 </listitem>
 341             </varlistentry>
 342             <varlistentry>
 343                 <term><constant>GL_TEXTURE_VIEW_NUM_LAYERS</constant></term>
 344                 <listitem>
 345                     <para>
 346                         Returns a single-valued number of layers in a texture array view.
 347                         See <citerefentry><refentrytitle>glTextureView</refentrytitle></citerefentry>.
 348                     </para>
 349                 </listitem>
 350             </varlistentry>
 351             <varlistentry>
 352                 <term><constant>GL_TEXTURE_IMMUTABLE_LEVELS</constant></term>
 353                 <listitem>
 354                     <para>
 355                         Returns a single-valued number of immutable texture levels in a texture view.
 356                         See <citerefentry><refentrytitle>glTextureView</refentrytitle></citerefentry>.
 357                     </para>
 358                 </listitem>
 359             </varlistentry>
 360         </variablelist>
 361     <para>
 362         In addition to the parameters that may be set with <citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>,
 363         <function>glGetTexParameter</function> accepts the following read-only parameters:
 364     </para>
 365         <variablelist>
 366             <varlistentry>
 367                 <term><constant>GL_TEXTURE_IMMUTABLE_FORMAT</constant></term>
 368                 <listitem>
 369                     <para>
 370                         Returns non-zero if the texture has an immutable format. Textures become
 371                         immutable if their storage is specified with <citerefentry><refentrytitle>glTexStorage1D</refentrytitle></citerefentry>,
 372                         <citerefentry><refentrytitle>glTexStorage2D</refentrytitle></citerefentry> or <citerefentry><refentrytitle>glTexStorage3D</refentrytitle></citerefentry>.
 373                         The initial value is <constant>GL_FALSE</constant>.
 374                     </para>
 375                 </listitem>
 376             </varlistentry>
 377         </variablelist>
 378     </refsect1>
 379     <refsect1 id="notes"><title>Notes</title>
 380         <para>
 381             If an error is generated,
 382             no change is made to the contents of <parameter>params</parameter>.
 383         </para>
 384         <para>
 385             <constant>GL_DEPTH_STENCIL_TEXTURE_MODE</constant>, <constant>GL_TEXTURE_VIEW_MIN_LEVEL</constant>,
 386             <constant>GL_TEXTURE_VIEW_NUM_LEVELS</constant>, <constant>GL_TEXTURE_VIEW_MIN_LAYER</constant>,
 387             <constant>GL_TEXTURE_VIEW_NUM_LAYERS</constant> and <constant>GL_TEXTURE_IMMUTABLE_LEVELS</constant> are available only if the GL version is 4.3 or greater.
 388         </para>
 389     </refsect1>
 390     <refsect1 id="errors"><title>Errors</title>
 391         <para>
 392             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> or <parameter>pname</parameter> is not an
 393             accepted value.
 394         </para>
 395     </refsect1>
 396     <refsect1 id="seealso"><title>See Also</title>
 397         <para>
 398             <citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>,
 399             <citerefentry><refentrytitle>glTexStorage1D</refentrytitle></citerefentry>,
 400             <citerefentry><refentrytitle>glTexStorage2D</refentrytitle></citerefentry>,
 401             <citerefentry><refentrytitle>glTexStorage3D</refentrytitle></citerefentry>,
 402             <citerefentry><refentrytitle>glTextureView</refentrytitle></citerefentry>
 403         </para>
 404     </refsect1>
 405     <refsect1 id="Copyright"><title>Copyright</title>
 406         <para>
 407             Copyright <trademark class="copyright"></trademark> 1991-2006
 408             Silicon Graphics, Inc. Copyright <trademark class="copyright"></trademark> 2010-2012
 409             Khronos Group. This document is licensed under the SGI
 410             Free Software B License. For details, see
 411             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 412         </para>
 413     </refsect1>
 414 </refentry>