texImage2D

概要

指定したデータをGPUにテクスチャ画像として転送することを指示します。表示する3Dポリゴンへ画像を貼り付ける際に必要となる関数です。
一部の関数バリエーションを除き、引数に具体的な画像ビットマップデータを指定して呼び出します。

事前準備

この関数を呼び出す前に、事前に作成済みのTextureオブジェクトのバインド操作が必要になります。
GLのAPI作法は、テクスチャ関数など一部の設定関数について、バインドした対象のオブジェクトに対してのみ効果が及ぶ仕組みになっています。

また関連して、バインド後に各種テクスチャパラメータ設定も必要です。

// Textureオブジェクトの生成 const tex = gl.createTexture(); // Textureオブジェクトをバインド gl.bindTexture(gl.TEXTURE_2D, tex); // テクスチャ画像の転送指示 gl.texImage2D(target, level, internalformat, width, height, border, format, type, GLintptr offset); // テクスチャフィルタリングの設定 gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR); // gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR_MIPMAP_NEAREST); gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE); // S(テクスチャUV座標系における横方向)座標のラッピング (繰り返し) を禁止 gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE); // T(テクスチャUV座標系における横方向)座標のラッピング (繰り返し) を禁止 // gl.LINEAR_MIPMAP_NEARESTなどのMipmap系のフィルタリング指定を行う場合には、このgenerateMipmap関数の呼び出し、 // または手動のミップマップテクスチャ転送を行う必要があります。 gl.generateMipmap(gl.TEXTURE_2D); // Textureオブジェクトのバインドを解除 gl.bindTexture(gl.TEXTURE_2D, null);

構文

WebGL1とWebGL2で引数リストの仕様が異なります。

それぞれの関数バリエーションの細部仕様については、MDNを参照してください 

WebGL1

WebGL1では、ArrayBufferViewを引数にするもの以外の全てのバリエーションで、widthとheightの引数がありません。
WebGLが指定された画像オブジェクトから、適切にwidthとheightを取得するためです。

void gl.texImage2D(target, level, internalformat, format, type, ImageData? pixels); void gl.texImage2D(target, level, internalformat, format, type, HTMLImageElement? pixels); void gl.texImage2D(target, level, internalformat, format, type, HTMLCanvasElement? pixels); void gl.texImage2D(target, level, internalformat, format, type, HTMLVideoElement? pixels); void gl.texImage2D(target, level, internalformat, format, type, ImageBitmap? pixels); void gl.texImage2D(target, level, internalformat, width, height, border, format, type, ArrayBufferView? pixels);

WebGL2

WebGL2では全ての関数バリエーションで、第8引数(type)までは引数のリストが同一です。
各バリエーションで第9引数から差異があります。ArrayBufferViewが引数の場合は、さらにsrcOffset引数が第10引数として存在します。

void gl.texImage2D(target, level, internalformat, width, height, border, format, type, GLintptr offset); void gl.texImage2D(target, level, internalformat, width, height, border, format, type, HTMLCanvasElement source); void gl.texImage2D(target, level, internalformat, width, height, border, format, type, HTMLImageElement source); void gl.texImage2D(target, level, internalformat, width, height, border, format, type, HTMLVideoElement source); void gl.texImage2D(target, level, internalformat, width, height, border, format, type, ImageBitmap source); void gl.texImage2D(target, level, internalformat, width, height, border, format, type, ImageData source); void gl.texImage2D(target, level, internalformat, width, height, border, format, type, ArrayBufferView srcData, srcOffset);

引数

【target】

アクティブテクスチャのバインドを指定します。

【level】

レベルを指定します。0はベース画像になり、レベルnはn番目のミップマップ縮小レベルになります。

【internalformat】

テクスチャの色を指定します。

【width】

テクスチャの幅を指定します。

【height】

テクスチャの高さを指定します。

【border】

境界線の幅を指定します。ここは0でなければいけません。

【format】

テクセル(texture pixel)のフォーマットデータを指定します。
WebGL1では、internalformatと同じである必要があります。
WebGL2の組み合わせは、こちらの表 を参照してください。

【type】

テクセルのデータ型を指定します。

【pixels】

下記のオブジェクトのいずれかを、テクスチャのピクセルソースとして使用できます。

  • ArrayBufferView、
  • ImageData
  • HTMLImageElement
  • HTMLCanvasElement
  • HTMLVideoElement
  • ImageBitmap

戻り値

無し。

gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, image);

サポート及びバージョン

  • WebGL1
  • WebGL2
  • OpenGL ES 1.0 ~
  • OpenGL 1.1 ~

OpenGL ES, OpenGLでは引数として渡す画像データのサポートフォーマットはWebGLと異なります。

備考

WebGL1では、テクスチャ画像サイズの横(width)と縦(height)がそれぞれ2の累乗サイズ(256や512など)でない場合、有効なテクスチャパラメータ設定に強い制約がかかります。
詳細はMDNを御覧ください 

Links

MDN: WebGLRenderingContext.texImage2D() 

khronos: glTexImage2D