upstream-man-pages/man4/glTexStorage2D.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="glTexStorage2D">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>2011</year>
   9                 <holder>Khronos Group</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glTexStorage2D</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glTexStorage2D</refname>
  17         <refpurpose>simultaneously specify storage for all levels of a two-dimensional or one-dimensional array texture</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glTexStorage2D</function></funcdef>
  23                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  24                 <paramdef>GLsizei <parameter>levels</parameter></paramdef>
  25                 <paramdef>GLenum <parameter>internalformat</parameter></paramdef>
  26                 <paramdef>GLsizei <parameter>width</parameter></paramdef>
  27                 <paramdef>GLsizei <parameter>height</parameter></paramdef>
  28             </funcprototype>
  29         </funcsynopsis>
  30     </refsynopsisdiv>
  31     <refsect1 id="parameters"><title>Parameters</title>
  32         <variablelist>
  33         <varlistentry>
  34             <term><parameter>target</parameter></term>
  35             <listitem>
  36                 <para>
  37                     Specify the target of the operation. <parameter>target</parameter> must be
  38                     one of <constant>GL_TEXTURE_2D</constant>, <constant>GL_PROXY_TEXTURE_2D</constant>,
  39                     <constant>GL_TEXTURE_1D_ARRAY</constant>, <constant>GL_PROXY_TEXTURE_1D_ARRAY</constant>,
  40                     <constant>GL_TEXTURE_RECTANGLE</constant>, <constant>GL_PROXY_TEXTURE_RECTANGLE</constant>,
  41                     or <constant>GL_PROXY_TEXTURE_CUBE_MAP</constant>.
  42                 </para>
  43             </listitem>
  44         </varlistentry>
  45         <varlistentry>
  46             <term><parameter>levels</parameter></term>
  47             <listitem>
  48                 <para>
  49                     Specify the number of texture levels.
  50                 </para>
  51             </listitem>
  52         </varlistentry>
  53         <varlistentry>
  54             <term><parameter>internalformat</parameter></term>
  55             <listitem>
  56                 <para>
  57                     Specifies the sized internal format to be used to store texture image data.
  58                 </para>
  59             </listitem>
  60         </varlistentry>
  61         <varlistentry>
  62             <term><parameter>width</parameter></term>
  63             <listitem>
  64                 <para>
  65                     Specifies the width of the texture, in texels.
  66                 </para>
  67             </listitem>
  68         </varlistentry>
  69         <varlistentry>
  70             <term><parameter>height</parameter></term>
  71             <listitem>
  72                 <para>
  73                     Specifies the height of the texture, in texels.
  74                 </para>
  75             </listitem>
  76         </varlistentry>
  77         </variablelist>
  78     </refsect1>
  79     <refsect1 id="description"><title>Description</title>
  80         <para>
  81             <function>glTexStorage2D</function> specifies the storage requirements for all levels
  82             of a two-dimensional texture or one-dimensional texture array simultaneously. Once a texture is specified with this
  83             command, the format and dimensions of all levels become immutable unless it is a proxy
  84             texture. The contents of the image may still be modified, however, its storage requirements
  85             may not change. Such a texture is referred to as an <emphasis>immutable-format</emphasis>
  86             texture.
  87         </para>
  88         <para>
  89             The behavior of <function>glTexStorage2D</function> depends on the <parameter>target</parameter> parameter.
  90             When <parameter>target</parameter> is <constant>GL_TEXTURE_2D</constant>, <constant>GL_PROXY_TEXTURE_2D</constant>,
  91             <constant>GL_TEXTURE_RECTANGLE</constant>, <constant>GL_PROXY_TEXTURE_RECTANGLE</constant> or <constant>GL_PROXY_TEXTURE_CUBE_MAP</constant>,
  92             calling <function>glTexStorage2D</function> is equivalent, assuming no errors are generated,
  93             to executing the following pseudo-code:
  94         </para>
  95 <programlisting><![CDATA[    for (i = 0; i < levels; i++)
  96     {
  97         glTexImage2D(target, i, internalformat, width, height, 0, format, type, NULL);
  98         width = max(1, (width / 2));
  99         height = max(1, (height / 2));
 100     }]]></programlisting>
 101         <para>
 102             When <parameter>target</parameter> is <constant>GL_TEXTURE_CUBE_MAP</constant>, <function>glTexStorage2D</function>
 103             is equivalent to:
 104         </para>
 105 <programlisting><![CDATA[    for (i = 0; i < levels; i++)
 106     {
 107         for (face in (+X, -X, +Y, -Y, +Z, -Z))
 108         {
 109             glTexImage2D(face, i, internalformat, width, height, 0, format, type, NULL);
 110         }
 111         width = max(1, (width / 2));
 112         height = max(1, (height / 2));
 113     }]]></programlisting>
 114         <para>
 115             When <parameter>target</parameter> is <constant>GL_TEXTURE_1D</constant> or <constant>GL_TEXTURE_1D_ARRAY</constant>,
 116             <function>glTexStorage2D</function> is equivalent to:
 117         </para>
 118 <programlisting><![CDATA[    for (i = 0; i < levels; i++)
 119     {
 120         glTexImage2D(target, i, internalformat, width, height, 0, format, type, NULL);
 121         width = max(1, (width / 2));
 122     }]]></programlisting>
 123         <para>
 124             Since no texture data is actually provided, the values used in the pseudo-code
 125             for <parameter>format</parameter> and <parameter>type</parameter> are
 126             irrelevant and may be considered to be any values that are legal for the
 127             chosen <parameter>internalformat</parameter> enumerant. <parameter>internalformat</parameter>
 128             must be one of the sized internal formats given in Table 1 below, one of the sized depth-component
 129             formats <constant>GL_DEPTH_COMPONENT32F</constant>, <constant>GL_DEPTH_COMPONENT24</constant>, or
 130             <constant>GL_DEPTH_COMPONENT16</constant>, or one of the combined depth-stencil formats,
 131             <constant>GL_DEPTH32F_STENCIL8</constant>, or <constant>GL_DEPTH24_STENCIL8</constant>. Upon success,
 132             the value of <constant>GL_TEXTURE_IMMUTABLE_FORMAT</constant> becomes
 133             <constant>GL_TRUE</constant>. The value of <constant>GL_TEXTURE_IMMUTABLE_FORMAT</constant>
 134             may be discovered by calling <citerefentry><refentrytitle>glGetTexParameter</refentrytitle></citerefentry>
 135             with <parameter>pname</parameter> set to <constant>GL_TEXTURE_IMMUTABLE_FORMAT</constant>.
 136             No further changes to the dimensions or format of the texture object may be
 137             made. Using any command that might alter the dimensions or format of the
 138             texture object (such as <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry> or
 139             another call to <function>glTexStorage2D</function>) will result in the
 140             generation of a <constant>GL_INVALID_OPERATION</constant> error, even if it
 141             would not, in fact, alter the dimensions or format of the object.
 142         </para>
 143         <para>
 144             <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="internalformattable.xml" />
 145         </para>
 146     </refsect1>
 147     <refsect1 id="errors"><title>Errors</title>
 148         <para>
 149             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>internalformat</parameter> is not a
 150             valid sized internal format.
 151         </para>
 152         <para>
 153             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not
 154             one of the accepted target enumerants.
 155         </para>
 156         <para>
 157             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>width</parameter> or <parameter>levels</parameter>
 158             are less than 1.
 159         </para>
 160         <para>
 161             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>target</parameter> is <constant>GL_TEXTURE_1D_ARRAY</constant>
 162             or <constant>GL_PROXY_TEXTURE_1D_ARRAY</constant> and <parameter>levels</parameter> is greater than <mml:math>
 163   <mml:mrow>
 164     <mml:mfenced open = '&lfloor;' close = '&rfloor;'>
 165       <mml:mrow>
 166         <mml:msub>
 167           <mml:mi>log</mml:mi>
 168           <mml:mn>2</mml:mn>
 169         </mml:msub>
 170         <mml:mfenced open = '(' close = ')'>
 171           <mml:mi>width</mml:mi>
 172         </mml:mfenced>
 173       </mml:mrow>
 174     </mml:mfenced>
 175     <mml:mo>+</mml:mo>
 176     <mml:mn>1</mml:mn>
 177   </mml:mrow>
 178 </mml:math>.
 179         </para>
 180         <para>
 181             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>target</parameter> is not <constant>GL_TEXTURE_1D_ARRAY</constant>
 182             or <constant>GL_PROXY_TEXTURE_1D_ARRAY</constant> and <parameter>levels</parameter> is greater than <mml:math>
 183   <mml:mrow>
 184     <mml:mfenced open = '&lfloor;' close = '&rfloor;'>
 185       <mml:mrow>
 186         <mml:msub>
 187           <mml:mi>log</mml:mi>
 188           <mml:mn>2</mml:mn>
 189         </mml:msub>
 190         <mml:mfenced open = '(' close = ')'>
 191           <mml:mrow>
 192             <mml:mi>max</mml:mi>
 193             <mml:mfenced open = '(' close = ')'>
 194               <mml:mrow>
 195                 <mml:mi>width</mml:mi>
 196                 <mml:mo>,</mml:mo>
 197                 <mml:mtext fontfamily='Times New Roman'>&nbsp;</mml:mtext>
 198                 <mml:mi>height</mml:mi>
 199               </mml:mrow>
 200             </mml:mfenced>
 201           </mml:mrow>
 202         </mml:mfenced>
 203       </mml:mrow>
 204     </mml:mfenced>
 205     <mml:mo>+</mml:mo>
 206     <mml:mn>1</mml:mn>
 207   </mml:mrow>
 208 </mml:math>.
 209     </para>
 210     </refsect1>
 211     <refsect1 id="seealso"><title>See Also</title>
 212         <para>
 213             <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
 214             <citerefentry><refentrytitle>glTexStorage1D</refentrytitle></citerefentry>,
 215             <citerefentry><refentrytitle>glTexStorage3D</refentrytitle></citerefentry>.
 216         </para>
 217     </refsect1>
 218     <refsect1 id="Copyright"><title>Copyright</title>
 219         <para>
 220             Copyright <trademark class="copyright"></trademark> 2011 Khronos Group.
 221             This material may be distributed subject to the terms and conditions set forth in
 222             the Open Publication License, v 1.0, 8 June 1999.
 223             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 224         </para>
 225     </refsect1>
 226 </refentry>