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>glTexImage2D</title> 8 </head> 9 <body> 10<h1><CODE>glTexImage2D</CODE> Function</h1> 11<h2>Syntax</h2> 12 <div class="section"> 13 <pre class="definition"> 14GL_APICALL void GL_APIENTRY glTexImage2D( 15 GLenum target, 16 GLint level, 17 GLenum internalformat, 18 GLsizei width, 19 GLsizei height, 20 GLint border, 21 GLenum format, 22 GLenum type, 23 const void * pixels 24); 25</pre> 26 </div> 27<h2>Parameters</h2> 28 <div class="section"> 29 <table class="arguments"> 30 <thead> 31 <tr> 32 <td width="15" /> 33<th>Name</th> 34<td>Description</td> 35 </tr> 36 </thead> 37 <tr> 38<td>in</td> 39<th>target</th> 40<td>Target texture.</td> 41 </tr> 42 <tr> 43<td>in</td> 44<th>level</th> 45<td>Mipmap level of the data to load.</td> 46 </tr> 47 <tr> 48<td>in</td> 49<th>internalformat</th> 50<td>Internal texture format (the same as <SPAN class="argument">format</SPAN>).</td> 51 </tr> 52 <tr> 53<td>in</td> 54<th>width</th> 55<td>Texture width.</td> 56 </tr> 57 <tr> 58<td>in</td> 59<th>height</th> 60<td>Texture height.</td> 61 </tr> 62 <tr> 63<td>in</td> 64<th>border</th> 65<td>Border width (<CODE>0</CODE> is the only valid value).</td> 66 </tr> 67 <tr> 68<td>in</td> 69<th>format</th> 70<td>Texture format.</td> 71 </tr> 72 <tr> 73<td>in</td> 74<th>type</th> 75<td>Texture type.</td> 76 </tr> 77 <tr> 78<td>in</td> 79<th>pixels</th> 80<td>Pointer to the texture data.</td> 81 </tr> </table> 82 </div> 83<h2>Return Values</h2> 84<div class="section">No values are returned. </div> 85<h2>Description</h2> 86 <div class="section"> 87<p>Configures 2D texture data.</p><P> 88You can set <SPAN class="argument">target</SPAN> to one of the following values. 89<TABLE><TR><TH><CODE>GL_TEXTURE_2D</CODE></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> 90To specify the region that is accessed by the GPU, set <SPAN class="argument">target</SPAN> to a bitwise OR of the aforementioned and the following values. 91<TABLE><TR><TH><CODE>NN_GX_MEM_FCRAM</CODE></TH><TD>The GPU accesses main memory.</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. By also specifying the following bitwise OR, you can specify whether to copy data to main memory.</TD></TR><TR><TH><CODE>GL_COPY_FCRAM_DMP</CODE></TH><TD>Create data copy in main memory.</TD></TR><TR><TH><CODE>GL_NO_COPY_FCRAM_DMP</CODE></TH><TD>Do not create data copy in main memory. These combinations cause data to be transferred as follows.</TD></TR><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 main memory; <SPAN class="argument">data</SPAN> is copied to main memory by the CPU; and then the GPU accesses main memory.</TD></TR><TR><TH>(<CODE>NN_GX_MEM_VRAMA</CODE> | <CODE>GL_COPY_FCRAM_DMP</CODE>)</TH><TD>A region is allocated in main memory and VRAMA; <SPAN class="argument">data</SPAN> is copied to main memory by the CPU; <SPAN class="argument">data</SPAN> is transferred via DMA from main memory to VRAMA, 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 main memory and VRAMB; <SPAN class="argument">data</SPAN> is copied to main memory by the CPU; <SPAN class="argument">data</SPAN> is transferred via DMA from main memory to VRAMB, and then the GPU accesses VRAMB.</TD></TR></TABLE></P><P> 92If a GPU access region is not specified for the <SPAN class="Argument">target</SPAN> argument and there is no specification about copying to main memory, then the processes (<CODE>NN_GX_MEM_FCRAM</CODE> | <CODE>GL_COPY_FCRAM_DMP</CODE>) are applied. However, if NULL is specified for <SPAN class="Argument">pixels</SPAN>, then the processes (<CODE>NN_GX_MEM_VRAMB</CODE> | <CODE>GL_NO_COPY_FCRAM_DMP</CODE>) are applied. 93 </P><P> 94Set <SPAN class="argument">width</SPAN> and <SPAN class="argument">height</SPAN> to the texture size. You must use powers of 2 between <CODE>8</CODE> and <CODE>1024</CODE>. You must set <SPAN class="argument">width</SPAN> and <SPAN class="argument">height</SPAN> to the same value for cube-map textures. </P><P> 95You must set <SPAN class="argument">border</SPAN> equal to <CODE>0</CODE>. 96 </P><P> 97You must set <SPAN class="argument">internalformat</SPAN> and <SPAN class="argument">format</SPAN> to the same value. You can set <SPAN class="argument">internalformat</SPAN> and <SPAN class="argument">format</SPAN> to the following values. 98<TABLE><TR><TH><CODE>GL_RGBA</CODE></TH></TR><TR><TH><CODE>GL_RGB</CODE></TH></TR><TR><TH><CODE>GL_SHADOW_DMP</CODE></TH></TR><TR><TH><CODE>GL_GAS_DMP</CODE></TH></TR><TR><TH><CODE>GL_ALPHA</CODE></TH></TR><TR><TH><CODE>GL_LUMINANCE</CODE></TH></TR><TR><TH><CODE>GL_LUMINANCE_ALPHA</CODE></TH></TR><TR><TH><CODE>GL_HILO8_DMP</CODE></TH></TR><TR><TH><CODE>GL_RGBA_NATIVE_DMP</CODE></TH></TR><TR><TH><CODE>GL_RGB_NATIVE_DMP</CODE></TH></TR><TR><TH><CODE>GL_ALPHA_NATIVE_DMP</CODE></TH></TR><TR><TH><CODE>GL_LUMINANCE_NATIVE_DMP</CODE></TH></TR><TR><TH><CODE>GL_LUMINANCE_ALPHA_NATIVE_DMP</CODE></TH></TR><TR><TH>GL_SHADOW_NATIVE_DMP</TH></TR><TR><TH>GL_GAS_NATIVE_DMP</TH></TR><TR><TH><CODE>GL_HILO8_DMP_NATIVE_DMP</CODE></TH></TR></TABLE> 99If a *_NATIVE_DMP format is specified, then the data specified for <SPAN class="Argument">pixels</SPAN> must be in the PICA native format. If the specified data is in any other format, a corrputed picture is displayed and no error is generated. 100 </P><P> 101Set <span class="argument">type</span> to one of the following values. 102<TABLE><TR><TH><CODE>GL_UNSIGNED_BYTE</CODE></TH></TR><TR><TH><CODE>GL_UNSIGNED_SHORT</CODE></TH></TR><TR><TH><CODE>GL_UNSIGNED_INT</CODE></TH></TR><TR><TH><CODE>GL_UNSIGNED_SHORT_4_4_4_4</CODE></TH></TR><TR><TH><CODE>GL_UNSIGNED_SHORT_5_5_5_1</CODE></TH></TR><TR><TH><CODE>GL_UNSIGNED_SHORT_5_6_5</CODE></TH></TR><TR><TH><CODE>GL_UNSIGNED_BYTE_4_4_DMP</CODE></TH></TR><TR><TH><CODE>GL_UNSIGNED_4BITS_DMP</CODE></TH></TR></TABLE></P><P> 103The following restrictions apply to combinations of <SPAN class="argument">type</SPAN> and <SPAN class="argument">format</SPAN>. 104<TABLE><TR><TH>type</TH><TH>format</TH></TR><TR><TD><CODE>GL_UNSIGNED_BYTE</CODE></TD><TD>Cannot specify <CODE>GL_GAS_DMP</CODE>, <CODE>GL_SHADOW_DMP</CODE></TD></TR><TR><TD><CODE>GL_UNSIGNED_SHORT</CODE></TD><TD>Limited to <CODE>GL_GAS_DMP </CODE>and <CODE>GL_GAS_NATIVE_DMP</CODE></TD></TR><TR><TD><CODE>GL_UNSIGNED_INT</CODE></TD><TD>Limited to <CODE>GL_SHADOW_DMP</CODE> and <CODE>GL_SHADOW_NATIVE_DMP</CODE></TD></TR><TR><TD><CODE>GL_UNSIGNED_SHORT_4_4_4_4</CODE> or <CODE>GL_UNSIGNED_SHORT_5_5_5_1</CODE></TD><TD>Limited to <CODE>GL_RGBA</CODE>, <CODE>GL_RGBA_NATIVE_DMP</CODE></TD></TR><TR><TD><CODE>GL_UNSIGNED_SHORT_5_6_5</CODE></TD><TD>Limited to <CODE>GL_RGB</CODE>, <CODE>GL_RGB_NATIVE_DMP</CODE></TD></TR><TR><TD><CODE>GL_UNSIGNED_BYTE_4_4_DMP</CODE></TD><TD>Limited to <CODE>GL_LUMINANCE_ALPHA</CODE>, <CODE>GL_LUMINANCE_ALPHA_NATIVE_DMP</CODE></TD></TR><TR><TD><CODE>GL_UNSIGNED_4BITS_DMP</CODE></TD><TD>Limited to <CODE>GL_ALPHA</CODE>, <CODE>GL_LUMINANCE</CODE>, <CODE>GL_ALPHA_NATIVE_DMP</CODE>, <CODE>GL_LUMINANCE_NATIVE_DMP</CODE></TD></TR></TABLE></P><P> 105The following restrictions apply to combinations of <SPAN class="argument">target</SPAN>, <SPAN class="argument">type</SPAN> and <SPAN class="argument">format</SPAN>. 106<TABLE><TR><TH>target</TH><TH>type</TH><TH>format</TH></TR><TR><TD><CODE>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</CODE>, <CODE>GL_TEXTURE_CUBE_MAP_POSITIVE_X</CODE>, <CODE>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</CODE>, <CODE>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</CODE>, <CODE>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</CODE>, <CODE>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</CODE></TD><TD><CODE>GL_RGB</CODE>, <CODE>GL_RGB_NATIVE_DMP</CODE></TD><TD>Limited to <CODE>GL_UNSIGNED_SHORT_5_6_5</CODE></TD></TR></TABLE></P><P> 107Mipmap levels are loaded all at once rather than individually. You cannot separately load data for multiple mipmap levels. Set <SPAN class="argument">level</SPAN> to the negative value of the number of mipmaps to load. (<CODE>0</CODE> and <CODE>-1</CODE> are treated the same. ) No value greater than <CODE>0</CODE> may be specified for <SPAN class="argument">level</SPAN>. 108 </P><P> 109Set <SPAN class="argument">pixels</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. If <CODE>0</CODE> has been specified for <SPAN class="Argument">pixels</SPAN>, a texture region is secured and nothing else. 110 </P><P> 111The following errors occur in this function. 112<TABLE><TR><TH><CODE>GL_INVALID_ENUM</CODE></TH><TD>The <SPAN class="argument">target</SPAN>, <SPAN class="argument">format</SPAN>, <SPAN class="argument">internalformat</SPAN>, or <SPAN class="argument">type</SPAN> argument was set to an invalid value.</TD></TR><TR><TH><CODE>GL_INVALID_VALUE</CODE></TH><TD>The <SPAN class="argument">width</SPAN>, <SPAN class="argument">height</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>An invalid combination of <SPAN class="argument">type</SPAN> and <SPAN class="argument">format</SPAN> was specified.</TD></TR><TR><TH><CODE>GL_INVALID_OPERATION</CODE></TH><TD>The <SPAN class="argument">format</SPAN> and <SPAN class="argument">internalformat</SPAN> arguments are set to different values.</TD></TR><TR><TH><CODE>GL_INVALID_OPERATION</CODE></TH><TD><CODE>GL_NO_COPY_FCRAM_DMP | NN_GX_MEM_FCRAM</CODE> was specified, and <SPAN class="argument">format</SPAN> is not a native format or <SPAN class="argument">pixels</SPAN> is 0.</TD></TR><TR><TH><CODE>GL_INVALID_OPERATION</CODE></TH><TD><CODE>GL_NO_COPY_FCRAM_DMP | NN_GX_MEM_VRAMA</CODE> (or <CODE>NN_GX_MEM_VRAMB</CODE>) was specified, <SPAN class="argument">pixels</SPAN> is nonzero, and <SPAN class="argument">format</SPAN> is not a native format.</TD></TR><TR><TH><CODE>GL_INVALID_OPERATION</CODE></TH><TD><CODE>GL_COPY_FCRAM_DMP | NN_GX_MEM_VRAMA</CODE> (or <CODE>NN_GX_MEM_VRAMB</CODE>) was specified and <SPAN class="argument">pixels</SPAN> is 0.</TD></TR><TR><TH><CODE>GL_OUT_OF_MEMORY</CODE></TH><TD>Failed to allocate texture memory.</TD></TR></TABLE></P></div> 113<h2>Revision History</h2> 114 <div class="section"> 115 <dl class="history"> 116 <dt>2011/02/18</dt> 117<dd>Fixed the omission of the <CODE>GL_SHADOW_NATIVE_DMP</CODE> and <CODE>GL_GAS_NATIVE_DMP</CODE> formats. Fixed an incorrect argument name, changing "data" to <SPAN class="Argument">pixels</SPAN>. 118 </dd> 119 <dt>2010/09/30</dt> 120<dd>Added text about specifying a GPU access region and copying to main memory when the <SPAN class="Argument">pixels</SPAN> argument is set to <CODE>NULL</CODE>.<br /> 121 </dd> 122 <dt>2010/08/20</dt> 123<dd>Matched the layout of the <I>type</I> and <I>type and format</I> tables. 124 </dd> 125 <dt>2010/08/02</dt> 126<dd>Revised layout of the Description section. Fixed accidental omission of <SPAN class="argument">type</SPAN> argument.<br /> 127 </dd> 128 <dt>2010/05/07</dt> 129<dd>Revised error conditions.<br /> 130 </dd> 131 <dt>2010/03/11</dt> 132<dd>Revised terminology. Added a description of the default value for the <SPAN class="argument">target</SPAN> argument.<br /> 133 </dd> 134 <dt>2010/01/07</dt> 135<dd>Initial version.<br /> 136 </dd> 137 </dl> 138 </div> 139 <hr><p>CONFIDENTIAL</p></body> 140</html>