---
title: WebGL2RenderingContext.texImage3D()
slug: Web/API/WebGL2RenderingContext/texImage3D
translation_of: Web/API/WebGL2RenderingContext/texImage3D
---
<div>{{APIRef("WebGL")}} {{SeeCompatTable}}</div>

<p><a href="/en-US/docs/Web/API/WebGL_API">WebGL API</a> 的 <strong><code>WebGLRenderingContext.texImage3D()</code></strong>方法指定一个3d（three-dimensional）纹理贴图。</p>

<h2 id="语法">语法</h2>

<pre class="syntaxbox">void <var>gl</var>.texImage3D(target, level, internalformat, width, height, depth, border, format, type, GLintptr offset);

void <var>gl</var>.texImage3D(target, level, internalformat, width, height, depth, border, format, type, HTMLCanvasElement source);
void <var>gl</var>.texImage3D(target, level, internalformat, width, height, depth, border, format, type, HTMLImageElement source);
void <var>gl</var>.texImage3D(target, level, internalformat, width, height, depth, border, format, type, HTMLVideoElement source);
void <var>gl</var>.texImage3D(target, level, internalformat, width, height, depth, border, format, type, ImageBitmap source);
void <var>gl</var>.texImage3D(target, level, internalformat, width, height, depth, border, format, type, ImageData source);
void <var>gl</var>.texImage3D(target, level, internalformat, width, height, depth, border, format, type, ArrayBufferView? srcData);
void <var>gl</var>.texImage3D(target, level, internalformat, width, height, depth, border, format, type, ArrayBufferView srcData, srcOffset);
</pre>

<h3 id="参数">参数</h3>

<dl>
 <dt><code>target</code></dt>
 <dd> {{domxref("GLenum")}}指定绑定纹理图像类型。可能值：
 <ul>
  <li><code>gl.TEXTURE_3D</code>: 一个3D贴图</li>
  <li><code>gl.TEXTURE_2D_ARRAY</code>: 一个2D数组贴图</li>
 </ul>
 </dd>
 <dt><code>level</code></dt>
 <dd>{{domxref("GLint")}}指定细节等级。level0是基础图片等级， n是第n个mipmap纹理衰减等级。（译者注：原文中衰减应该指像素，并且注意，webgl的Mipmapping技术要求顶层图像的行和列的维数均为2的幂）</dd>
 <dt><code>internalformat</code></dt>
 <dd>{{domxref("GLint")}}指定贴图的颜色组成，可能值为：
 <ul>
  <li><code>gl.ALPHA</code>: 忽略红色，绿色，蓝色分量值只读取alpha信息。</li>
  <li><code>gl.RGB</code>: 忽略alpha信息，读取红绿蓝分量</li>
  <li><code>gl.RGBA</code>: 从颜色缓冲（colorBuffer）读取红色，绿色，蓝色和alpha分量</li>
  <li><code>gl.LUMINANCE</code>:每个颜色组件都是亮度组件，alpha值为1.0.</li>
  <li><code>gl.LUMINANCE_ALPHA</code>:每个组件都是亮度/alpha 组件（component） .</li>
  <li><code>gl.R8</code></li>
  <li><code>gl.R16F</code></li>
  <li><code>gl.</code>R32F</li>
  <li><code>gl.R8UI</code></li>
  <li><code>gl.RG8</code></li>
  <li><code>gl.RG16F</code></li>
  <li><code>gl.RG32F</code></li>
  <li><code>gl.RGUI</code></li>
  <li><code>gl.RGB8</code></li>
  <li><code>gl.SRGB8</code></li>
  <li><code>gl.RGB565</code></li>
  <li><code>gl.R11F_G11F_B10F</code></li>
  <li><code>gl.RGB9_E5</code></li>
  <li><code>gl.RGB16F</code></li>
  <li><code>gl.RGB32F</code></li>
  <li><code>gl.RGB8UI</code></li>
  <li><code>gl.RGBA8</code></li>
  <li><code>gl.SRGB_APLHA8</code></li>
  <li><code>gl.RGB5_A1</code></li>
  <li><code>gl.RGBA4444</code></li>
  <li><code>gl.RGBA16F</code></li>
  <li><code>gl.RGBA32F</code></li>
  <li><code>gl.RGBA8UI</code></li>
 </ul>
 </dd>
 <dt><code>width</code></dt>
 <dd> {{domxref("GLsizei")}}指定纹理的宽度</dd>
 <dt><code>height</code></dt>
 <dd>{{domxref("GLsizei")}} 指定纹理的高度</dd>
 <dt><code>depth</code></dt>
 <dd>{{domxref("GLsizei")}} 指定纹理的深度信息</dd>
 <dt><code>border</code></dt>
 <dd>{{domxref("GLint")}}指定边框宽度，必须为0</dd>
 <dt><code>format</code></dt>
 <dd>{{domxref("GLenum")}}制定纹素的版本。正确的 <code>内部格式</code> 组合被列举在 <a href="https://www.khronos.org/registry/webgl/specs/latest/2.0/#TEXTURE_TYPES_FORMATS_FROM_DOM_ELEMENTS_TABLE">这个列表</a>。</dd>
 <dt><code>type</code></dt>
 <dd>A {{domxref("GLenum")}}指定纹素的数据类型，可能值：
 <ul>
  <li><code>gl.UNSIGNED_BYTE</code>: 每个<code>gl.RGBA</code>对应8个字节</li>
  <li><code>gl.UNSIGNED_SHORT_5_6_5</code>: 红色占五个字节，绿色占六个字节，蓝色占五个字节</li>
  <li><code>gl.UNSIGNED_SHORT_4_4_4_4</code>: 红色占四个字节，绿色占 四 个字节，蓝色占 四 个字节</li>
  <li><code>gl.UNSIGNED_SHORT_5_5_5_1</code>:红色占五个字节，绿色占五个字节，蓝色占五个字节，alpha占一个字节</li>
  <li><code>gl.BYTE </code>（这些属性的信息原文中均未提到，但是在webgl1中出现过，可以适当参考webgl1文献）</li>
  <li><code>gl.UNSIGNED_SHORT</code></li>
  <li><code>gl.SHORT</code></li>
  <li><code>gl.UNSIGNED_INT</code></li>
  <li><code>gl.INT</code></li>
  <li><code>gl.HALF_FLOAT</code></li>
  <li><code>gl.FLOAT</code></li>
  <li><code>gl.UNSIGNED_INT_2_10_10_10_REV</code></li>
  <li><code>gl.UNSIGNED_INT_10F_11F_11F_REV</code></li>
  <li><code>gl.UNSIGNED_INT_5_9_9_9_REV</code></li>
  <li><code>gl.UNSIGNED_INT_24_8</code></li>
  <li><code>gl.FLOAT_32_UNSIGNED_INT_24_8_REV</code> (pixels must be {{jsxref("null")}})</li>
 </ul>
 </dd>
 <dt><code>source</code></dt>
 <dd>其中一个对象可以用作纹理对象的源：</dd>
 <dd>
 <ul>
  <li>{{domxref("ArrayBufferView")}},</li>
  <li>{{domxref("ImageBitmap")}},</li>
  <li>{{domxref("ImageData")}},</li>
  <li>{{domxref("HTMLImageElement")}},</li>
  <li>{{domxref("HTMLCanvasElement")}},</li>
  <li>{{domxref("HTMLVideoElement")}}.</li>
 </ul>
 </dd>
 <dt>offset</dt>
 <dd>一个针对于{{domxref("WebGLBuffer")}}所储存数据的{{domxref("GLintptr")}}字节的偏移量。用来重新加载已经用<code>WebGLBuffer</code>绑定到<code>PIXEL_UNPACK_BUFFER</code>的{{domxref("WebGLTexture")}} 。</dd>
 <dd>
 <ul>
 </ul>
 </dd>
</dl>

<h3 id="返回值">返回值</h3>

<p>没有</p>

<h2 id="例子">例子</h2>

<pre class="brush: js">gl.texImage3D(gl.TEXTURE_3D,
              0,                                          // level
              gl.RGBA,                                    // internalFormat
              1,                                          // width
              1,                                          // height
              1,                                          // depth
              0,                                          // border
              gl.RGBA,                                    // format
              gl.UNSIGNED_BYTE,                           // type
              new Uint8Array([0xff, 0x00, 0x00, 0x00]));  // data
</pre>

<h2 id="说明">说明</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">说明（Specification ）</th>
   <th scope="col">状态（Status）</th>
   <th scope="col">意见（Comment）</th>
  </tr>
  <tr>
   <td>{{SpecName('WebGL2', "#3.7.6", "texImage3D")}}</td>
   <td>{{Spec2('WebGL2')}}</td>
   <td>Updated definition for WebGL.</td>
  </tr>
  <tr>
   <td>{{SpecName('OpenGL ES 3.0', "glTexImage3D.xhtml", "glTexImage3D")}}</td>
   <td>{{Spec2('OpenGL ES 3.0')}}</td>
   <td>Man page of the (similar) OpenGL ES 3.0 API.</td>
  </tr>
 </tbody>
</table>

<h2 id="浏览器兼容性">浏览器兼容性</h2>

<p>{{Compat("api.WebGL2RenderingContext.texImage3D")}}</p>

<h2 id="另见">另见</h2>

<ul>
 <li>{{domxref("WebGLRenderingContext.createTexture()")}}</li>
 <li>{{domxref("WebGLRenderingContext.bindTexture()")}}</li>
 <li>{{domxref("WebGLRenderingContext.texSubImage2D()")}}</li>
 <li>{{domxref("WebGLRenderingContext.compressedTexImage2D()")}}</li>
 <li>{{domxref("WebGLRenderingContext.copyTexImage2D()")}}</li>
 <li>{{domxref("WebGLRenderingContext.getTexParameter()")}}</li>
</ul>