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>Arguments</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><!-- source targetにはGL_TEXTURE_2DまたはGL_TEXTURE_CUBE_MAP_NEGATIVE_X、GL_TEXTURE_CUBE_MAP_POSITIVE_X、 GL_TEXTURE_CUBE_MAP_NEGATIVE_Y、GL_TEXTURE_CUBE_MAP_POSITIVE_Y、GL_TEXTURE_CUBE_MAP_NEGATIVE_Z、GL_TEXTURE_CUBE_MAP_POSITIVE_Zが指定できます。 --></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><!-- source NN_GX_MEM_FCRAM ・・・ FCRAMにGPUがアクセスします。 NN_GX_MEM_VRAMA ・・・ VRAMAにGPUがアクセスします。 NN_GX_MEM_VRAMB ・・・ VRAMBにGPUがアクセスします。 さらに次の値を論理和で指定することで、FCRAMにデータのコピーを生成するか否かを指定することができます。 GL_COPY_FCRAM_DMP ・・・ FCRAMにデータのコピーを生成します。 GL_NO_COPY_FCRAM_DMP ・・・ FCRAMにデータのコピーを生成しません。 これらの組み合わせにより、以下のような転送処理が行われます。 (NN_GX_MEM_FCRAM | GL_NO_COPY_FCRAM_DMP) ・・・ dataに指定した領域を直接GPUがアクセスする (NN_GX_MEM_VRAMA | GL_NO_COPY_FCRAM_DMP) ・・・ VRAMAに領域を確保し、DMAでdataからVRAMAへ転送し、VRAMAをGPUがアクセスする (NN_GX_MEM_VRAMB | GL_NO_COPY_FCRAM_DMP) ・・・ VRAMBに領域を確保し、DMAでdataからVRAMBへ転送し、VRAMBをGPUがアクセスする (NN_GX_MEM_FCRAM | GL_COPY_FCRAM_DMP) ・・・ FCRAMに領域を確保し、CPUでdataからFCRAMへコピーし、FCRAMをGPUがアクセスする (NN_GX_MEM_VRAMA | GL_COPY_FCRAM_DMP) ・・・ VRAMAおよびFCRAMに領域を確保し、CPUでdataからFCRAMへコピーし、DMAでFCRAMからVRAMAへ転送し、VRAMAをGPUがアクセスする (NN_GX_MEM_VRAMB | GL_COPY_FCRAM_DMP) ・・・ VRAMBおよびFCRAMに領域を確保し、CPUでdataからFCRAMへコピーし、DMAでFCRAMからVRAMBへ転送し、VRAMBをGPUがアクセスする --></P><P> 92If not specifying any GPU access region or copying to main memory, then (<CODE>NN_GX_MEM_FCRAM</CODE> | <CODE>GL_COPY_FCRAM_DMP</CODE>) are applied. However, if <CODE>NULL</CODE> is specified for <B>format</B>, 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><CODE>GL_HILO8_DMP_NATIVE_DMP</CODE></TH></TR></TABLE><!-- GL_RGBA、GL_RGB、GL_SHADOW_DMP、GL_GAS_DMP、GL_ALPHA、 GL_LUMINANCE、GL_LUMINANCE_ALPHA、GL_HILO8_DMP、GL_RGBA_NATIVE_DMP、 GL_RGB_NATIVE_DMP、GL_ALPHA_NATIVE_DMP、GL_LUMINANCE_NATIVE_DMP、 GL_LUMINANCE_ALPHA_NATIVE_DMP、GL_HILO8_DMP_NATIVE_DMPが指定できます。--></P><P> 99Set <span class="argument">type</span> to one of the following values. 100<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><!-- GL_UNSIGNED_BYTE、GL_UNSIGNED_SHORT、GL_UNSIGNED_INT、GL_UNSIGNED_SHORT_4_4_4_4、GL_UNSIGNED_SHORT_5_5_5_1、 GL_UNSIGNED_SHORT_5_6_5が指定できます。--></P><P> 101The following restrictions apply to combinations of <SPAN class="argument">type</SPAN> and <SPAN class="argument">format</SPAN>. 102<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></TD></TR><TR><TD><CODE>GL_UNSIGNED_INT</CODE></TD><TD>Limited to <CODE>GL_SHADOW_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><!-- typeにGL_UNSIGNED_SHORT_5_5_5_1またはGL_UNSIGNED_SHORT_4_4_4_4を指定した場合、formatはGL_RGBA、GL_RGBA_NATIVE_DMPに限られます。 typeにGL_UNSIGNED_SHORT_5_6_5を指定した場合、formatはGL_RGB、GL_RGB_NATIVE_DMPに限られます。 typeにGL_UNSIGNED_SHORTを指定した場合、formatはGL_GAS_DMPに限られます。 typeにGL_UNSIGNED_INTを指定した場合、formatはGL_SHADOW_DMPに限られます。 typeにGL_UNSIGNED_BYTEを指定した場合、formatはGL_GAS_DMP、GL_SHADOW_DMPは指定できません。--></P><P> 103The following restrictions apply to combinations of <SPAN class="argument">target</SPAN>, <SPAN class="argument">type</SPAN> and <SPAN class="argument">format</SPAN>. 104<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><!-- targetにGL_TEXTURE_CUBE_MAP_NEGATIVE_X、GL_TEXTURE_CUBE_MAP_POSITIVE_X、GL_TEXTURE_CUBE_MAP_NEGATIVE_Y、GL_TEXTURE_CUBE_MAP_POSITIVE_Y、 GL_TEXTURE_CUBE_MAP_NEGATIVE_Z、GL_TEXTURE_CUBE_MAP_POSITIVE_Zが指定され、かつformatがGL_RGB、GL_RGB_NATIVE_DMPの場合、 typeはGL_UNSIGNED_SHORT_5_6_5に限られます。--></P><P> 105Mipmap 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>. Set <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 <CODE>0</CODE> at the top. 106 </P><P> 107The following errors occur in this function. 108<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><!-- source target、format、internalformat、typeに不正な値を指定した場合エラーGL_INVALID_ENUMを生成します。 typeとformatに不正な組み合わせを指定した場合エラーGL_INVALID_OPERATIONを生成します。 width、height、levelに不正な値を指定した場合エラーGL_INVALID_VALUEを生成します。 formatとinternalformatが異なる場合エラーGL_INVALID_OPERATIONを生成します。 FCRAMコピー有無の指定にGL_NO_COPY_FCRAM_DMPを指定し、かつ formatがネイティブフォーマットではない場合エラーGL_INVALID_OPERATIONを生成します。 GPUアクセス領域の指定にNN_GX_MEM_VRAMAまたはNN_GX_MEM_VRAMBを指定し、かつ pixelsに0を指定した場合エラーGL_INVALID_OPERATIONを生成します。 テクスチャ用メモリの確保に失敗した場合エラーGL_OUT_OF_MEMORYを生成します。 --></P></div> 109<h2>Revision History</h2> 110 <div class="section"> 111 <dl class="history"> 112 <dt>2010/09/30</dt> 113<dd>Added text about the GPU access region and copying to main memory when the <B>data </B>argument is set to NULL. 114 </dd> 115 <dt>2010/08/20</dt> 116<dd>Matched the layout of the <I>type</I> and <I>type and format</I> tables. 117 </dd> 118 <dt>2010/08/02</dt> 119<dd>Revised layout of the Description section. Fixed accidental omission of <SPAN class="argument">type</SPAN> argument.<br /> 120 </dd> 121 <dt>2010/05/07</dt> 122<dd>Revised error conditions.<br /> 123 </dd> 124 <dt>2010/03/11</dt> 125<dd>Revised terminology. Added a description of the default value for the <SPAN class="argument">target</SPAN> argument.<br /> 126 </dd> 127 <dt>2010/01/07</dt> 128<dd>Initial version.<br /> 129 </dd> 130 </dl> 131 </div> 132 <hr><p>CONFIDENTIAL</p></body> 133</html>