1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2<html xml:lang="en-US" lang="en-US" xmlns="http://www.w3.org/1999/xhtml">
3  <head>
4    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5    <meta http-equiv="Content-Style-Type" content="text/css" />
6    <link rel="stylesheet" href="../css/manpage.css" type="text/css" />
7<title>glCompressedTexImage2D</title>
8  </head>
9  <body>
10<h1><CODE>glCompressedTexImage2D</CODE> Function</h1>
11<h2>Syntax</h2>
12    <div class="section">
13      <pre class="definition">
14GL_APICALL void GL_APIENTRY glCompressedTexImage2D(
15     GLenum target,
16     GLint level,
17     GLenum internalformat,
18     GLsizei width,
19     GLsizei height,
20     GLint border,
21     GLsizei imageSize,
22     const void * data
23);
24</pre>
25    </div>
26<h2>Parameters</h2>
27    <div class="section">
28      <table class="arguments">
29        <thead>
30          <tr>
31            <td width="15" />
32<th>Name</th>
33<td>Description</td>
34          </tr>
35        </thead>
36        <tr>
37<td>in</td>
38<th>target</th>
39<td>Target texture.</td>
40        </tr>
41        <tr>
42<td>in</td>
43<th>level</th>
44<td>Mipmap level of the data to load.</td>
45        </tr>
46        <tr>
47<td>in</td>
48<th>internalformat</th>
49<td>Texture format. (<CODE>GL_ETC1_RGB8_NATIVE_DMP</CODE> or <CODE>GL_ETC1_RGB8_A4_NATIVE_DMP</CODE>.)</td>
50        </tr>
51        <tr>
52<td>in</td>
53<th>width</th>
54<td>Texture width.</td>
55        </tr>
56        <tr>
57<td>in</td>
58<th>height</th>
59<td>Texture height</td>
60        </tr>
61        <tr>
62<td>in</td>
63<th>border</th>
64<td>Border width (<CODE>0</CODE> is the only valid value).</td>
65        </tr>
66        <tr>
67<td>in</td>
68<th>imageSize</th>
69<td>Texture data size</td>
70        </tr>
71        <tr>
72<td>in</td>
73<th><CODE>data</CODE></th>
74<td>Pointer to the texture data.</td>
75        </tr> </table>
76    </div>
77<h2>Return Values</h2>
78<div class="section">No values are returned. </div>
79<h2>Description</h2>
80    <div class="section">
81<p>Loads texture data in a compressed format.</p><P>
82Set <span class="argument">target</span> to one the following values.
83<TABLE><TR><TH>GL_TEXTURE_2D</TH><TD> 2D texture.</TD></TR><TR><TH><CODE>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</CODE></TH><TD> Face of a cube-map texture in the negative x direction.</TD></TR><TR><TH><CODE>GL_TEXTURE_CUBE_MAP_POSITIVE_X</CODE></TH><TD> Face of a cube-map texture in the positive x direction.</TD></TR><TR><TH><CODE>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</CODE></TH><TD> Face of a cube-map texture in the negative y direction.</TD></TR><TR><TH><CODE>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</CODE></TH><TD> Face of a cube-map texture in the positive y direction.</TD></TR><TR><TH><CODE>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</CODE></TH><TD> Face of a cube-map texture in the negative z direction.</TD></TR><TR><TH><CODE>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</CODE></TH><TD> Face of a cube-map texture in the positive z direction. </TD></TR></TABLE></P><P>
84To specify the region that is accessed by the GPU, set <span class="argument">target</span> to a bitwise OR of the aforementioned and following values.
85<TABLE><TR><TH>NN_GX_MEM_FCRAM</TH><TD>The GPU accesses FCRAM.</TD></TR><TR><TH><CODE>NN_GX_MEM_VRAMA</CODE></TH><TD>The GPU accesses VRAMA.</TD></TR><TR><TH><CODE>NN_GX_MEM_VRAMB</CODE></TH><TD>The GPU accesses VRAMB. You can also specify whether copies of data are generated in FCRAM by including the following values in the bitwise OR.</TD></TR><TR><TH><CODE>GL_COPY_FCRAM_DMP</CODE></TH><TD>Copies of data are generated in FCRAM.</TD></TR><TR><TH>GL_NO_COPY_FCRAM_DMP</TH><TD>Copies of data are not generated in FCRAM.</TD></TR></TABLE></P><P>
86These combinations cause data to be transferred as follows.
87<TABLE><TR><TH>(<CODE>NN_GX_MEM_FCRAM</CODE> | <CODE>GL_NO_COPY_FCRAM_DMP</CODE>)</TH><TD>The GPU directly accesses the region specified by <SPAN class="argument">data</SPAN>.</TD></TR><TR><TH>(<CODE>NN_GX_MEM_VRAMA</CODE> | <CODE>GL_NO_COPY_FCRAM_DMP</CODE>)</TH><TD>A region is allocated in VRAMA; <SPAN class="argument">data</SPAN> is transferred to VRAMA via DMA; and then the GPU accesses VRAMA.</TD></TR><TR><TH>(<CODE>NN_GX_MEM_VRAMB</CODE> | <CODE>GL_NO_COPY_FCRAM_DMP</CODE>)</TH><TD>A region is allocated in VRAMB; <SPAN class="argument">data</SPAN> is transferred to VRAMB via DMA; and then the GPU accesses VRAMB.</TD></TR><TR><TH>(<CODE>NN_GX_MEM_FCRAM</CODE> | <CODE>GL_COPY_FCRAM_DMP</CODE>)</TH><TD>A region is allocated in FCRAM; <span class="argument">data</span> is copied to FCRAM via the CPU; and then the GPU accesses FCRAM.</TD></TR><TR><TH>(<CODE>NN_GX_MEM_VRAMA</CODE> | <CODE>GL_COPY_FCRAM_DMP</CODE>)</TH><TD>A region is allocated in VRAMA and FCRAM; <span class="argument">data</span> is copied to FCRAM via the CPU, then transferred from FCRAM to VRAMA via DMA; and then the GPU accesses VRAMA.</TD></TR><TR><TH>(<CODE>NN_GX_MEM_VRAMB</CODE> | <CODE>GL_COPY_FCRAM_DMP</CODE>)</TH><TD>A region is allocated in VRAMB and FCRAM; <span class="argument">data</span> is copied to FCRAM via the CPU, then transferred from FCRAM to VRAMB via DMA; and then the GPU accesses VRAMB.</TD></TR></TABLE></P><P>
88If you do not specify which region is accessed by the GPU or whether data is copied to FCRAM, <code>(NN_GX_MEM_FCRAM | GL_COPY_FCRAM_DMP)</code> is used. (These settings cannot be specified for POD.)
89            </P><P>
90Set <span class="argument">level</span> to a negative value that is equal to the number of mipmaps to load for the texture data stored in <span class="argument">data</span>. (For example, specify a value of -2 to load two mipmap levels and a value of -3 to load three mipmap levels.)
91            </P><P>
92If you set <span class="argument">level</span> to 0 or -1, it is recognized as indicating the minimum single-level mipmap.
93            </P><P>
94For <SPAN class="argument">internalformat</SPAN>, you can specify either <CODE>GL_ETC1_RGB8_NATIVE_DMP</CODE> or <CODE>GL_ETC1_ALPHA_RGB8_A4_NATIVE_DMP</CODE>.
95            </P><P>
96Set <span class="argument">width</span> and <span class="argument">height</span> to the texture size of the data to load. Specify the size of level 0 when you load multiple mipmap levels of data. With <code>GL_ETC1_RGB8_NATIVE_DMP</code>, the texture size must be a power of 2 between 16 and 1024, inclusive.
97            </P><P>
98Specify 0 for <span class="argument">border</span>.
99            </P><P>
100Set <span class="argument">imageSize</span> to the number of bytes of data specified by <span class="argument">data</span>.
101            </P><P>
102Set <span class="argument">data</span> to a pointer to the texture data to load. When data is loaded for multiple mipmap levels, it is stored in ascending level order starting with level 0. You cannot separately load the individual mipmap levels of the data. When <span class="argument">data</span> is set to NULL, this function simply allocates a region as large as the data size.
103            </P><P>
104This function generates the following errors.
105<TABLE><TR><TH><CODE>GL_INVALID_OPERATION</CODE></TH><TD>This function was called without any command-list objects bound when DMA transfers were in use.</TD></TR><TR><TH><CODE>GL_INVALID_VALUE</CODE></TH><TD>The <span class="argument">width</span>, <span class="argument">height</span>, <span class="argument">internalformat</span>, <span class="argument">border</span>, or <span class="argument">level</span> argument was set to an invalid value.</TD></TR><TR><TH><CODE>GL_INVALID_OPERATION</CODE></TH><TD>The <span class="argument">imageSize</span> argument was set to a value of 0 or less.</TD></TR><TR><TH><CODE>GL_INVALID_ENUM</CODE></TH><TD>The <span class="argument">target</span> argument was set to an invalid value.</TD></TR><TR><TH><CODE>GL_INVALID_OPERATION</CODE></TH><TD>The <span class="argument">target</span> argument was set to an invalid transfer method.</TD></TR></TABLE></P></div>
106<h2>Revision History</h2>
107    <div class="section">
108      <dl class="history">
109        <dt>2010/11/29</dt>
110<dd>Added <CODE>GL_ETC1_ALPHA_RGB8_A4_NATIVE_DMP</CODE>, which had been omitted by mistake, as one of the specifiable values for <SPAN class="argument">internalformat</SPAN>.<br />
111        </dd>
112        <dt>2010/01/07</dt>
113<dd>Initial version.<br />
114        </dd>
115      </dl>
116    </div>
117  <hr><p>CONFIDENTIAL</p></body>
118</html>