GLUBUILD2DMIPMAPS(3G)

名前
gluBuild2DMipmaps - 2 次元のミップマップを作る

書式
GLint gluBuild2DMipmaps( GLenum target,
	GLint internalFormat,
	GLsizei width,
	GLsizei height,
	GLenum format,
	GLenum type,
	const void *data )

引き数

target
    対象のテクスチャを指定する。 GL_TEXTURE_2D でなければならない。

internalFormat
    テクスチャイメージの内部格納領域を要求する。 SGI による最新バージョンの GLU の実装では、GLU から呼び出される OpenGL の実装にこの値を渡す前に値の正しさのチェックは行われない。 OpenGL の実装が受け付けない値は、OpenGL のエラーとなる。 GLU のレベルで値のチェックをしないことの利点は、GLU の実装のリビジョン を取得しなくても OpenGL の機能拡張としてテクスチャの新しい 内部フォーマットを追加できることである。 古い GLU の実装はこの値をチェックし、値が 1, 2, 3, 4 または以下に示す シンボル定数でない場合にエラーとなる: GL_ALPHA, GL_ALPHA4, GL_ALPHA8, GL_ALPHA12, GL_ALPHA16, GL_LUMINANCE, GL_LUMINANCE4, GL_LUMINANCE8, GL_LUMINANCE12, GL_LUMINANCE16, GL_LUMINANCE_ALPHA, GL_LUMINANCE4_ALPHA4, GL_LUMINANCE6_ALPHA2, GL_LUMINANCE8_ALPHA8, GL_LUMINANCE12_ALPHA4, GL_LUMINANCE12_ALPHA12, GL_LUMINANCE16_ALPHA16, GL_INTENSITY, GL_INTENSITY4, GL_INTENSITY8, GL_INTENSITY12, GL_INTENSITY16, GL_RGB, GL_R3_G3_B2, GL_RGB4, GL_RGB5, GL_RGB8, GL_RGB10, GL_RGB12, GL_RGB16, GL_RGBA, GL_RGBA2, GL_RGBA4, GL_RGB5_A1, GL_RGBA8, GL_RGB10_A2, GL_RGBA12, GL_RGBA16。

width, height
    テクスチャイメージの幅と高さをピクセル単位で指定する。

format
    ピクセルデータのフォーマットを指定する。 フォーマットは以下のいずれかでなければならない: GL_COLOR_INDEX, GL_DEPTH_COMPONENT, GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_RGBA, GL_BGR, GL_BGRA, GL_LUMINANCE, GL_LUMINANCE_ALPHA。

type
    data のデータ型を指定する。 以下のいずれかでなければならない: データ型は以下のいずれかでなければならない: GL_UNSIGNED_BYTE, GL_BYTE, GL_BITMAP, GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT, GL_FLOAT, GL_UNSIGNED_BYTE_3_3_2, GL_UNSIGNED_BYTE_2_3_3_REV, GL_UNSIGNED_SHORT_5_6_5, GL_UNSIGNED_SHORT_5_6_5_REV, GL_UNSIGNED_SHORT_4_4_4_4, GL_UNSIGNED_SHORT_4_4_4_4_REV, GL_UNSIGNED_SHORT_5_5_5_1, GL_UNSIGNED_SHORT_1_5_5_5_REV, GL_UNSIGNED_INT_8_8_8_8, GL_UNSIGNED_INT_8_8_8_8_REV, GL_UNSIGNED_INT_10_10_10_2, GL_UNSIGNED_INT_2_10_10_10_REV。

data
    メモリ上のイメージデータを指すポインタを指定する。

説明
gluBuild2DMipmaps はミップマップと呼ばれる、フィルタ処理された 2 次元のテクスチャマップを解像度を下げながら並べたものを作る。 ミップマップはテクスチャマッピング処理をしたプリミティブの アンチエイリアス処理に使われる。

返り値は 0 ならば成功を表す。 それ以外の返り値は GLU のエラーコードである(gluErrorString を 参照)。

まず、データ(data)の幅(width)と高さ(height)が 2 の べき乗であるかどうかがチェックされる。 べき乗でない場合は、data のコピー(data そのものではない)が 拡大または縮小され、幅と高さが最も近い 2 のべき乗になるように調整される。 このコピーが後述のミップマップ操作で使われる。 (width や height がふたつのべき乗値のちょうど中間だった場合は、 data のコピーは拡大される。) 例えば width が 57, height が 23 ならば、data のコピーは ミップマップ処理の前に幅 64, 高さ 16 に拡大される。

次にプロキシテクスチャ(glTexImage2D を参照)を使って、 要求されたテクスチャを OpenGL の実装が当てはめられるかどうかが調べられる。 当てはめられなければ、当てはめられるようになるまで、幅と高さを半分に する処理が繰り返される。 (OpenGL のバージョンが ≤ 1.0 ならば、テクスチャの幅・高さの最大値は 関数 glGetIntegerv に引き数 GL_MAX_TEXTURE_SIZE を指定 した時の返り値に固定されている。)

次に、data のコピーを半分の大きさに簡略化する処理を サイズが $1 ~times~ 1$ になるまで繰り返すことにより、 ミップマップレベルの列が作られる。 それぞれのレベルでは、半分になったミップマップレベルに含まれる 各テクセル値は、大きいミップマップレベル内でこれに対応する 4 つの テクセル値の平均値となる。 (長方形イメージの場合は、簡略化によりサイズは最終的に $N ~times~ 1$ または $1 ~times~ N$ になる。 この場合は、4 つのテクセルの平均値の代わりに、ふたつのテクセルの平均値 が使われる。)

glTexImage2D はこれらのミップマップレベルを個別にロードするため に使われる。 レベル 0 は data のコピーである。 もっとも大きなレベルは ${log sub 2} ( max ("width","height"))$ である。 例えば、width が 64, height が 16 であり、OpenGL の実装が このサイズのテクスチャを格納できる場合には、次のミップマップレベルが 作られる: $64 ~times~ 16$, $32 ~times~ 8$, $16 ~times~ 4$, $8 ~times~ 2$, $4 ~times~ 1$, $2 ~times~ 1$, $1 ~times~ 1$ これらは順にレベル 0 から 6 に対応する。

type 引き数に指定できる値の説明については、glTexImage1D の 項目を参照すること。 data 引き数に指定できる値の説明については、glDrawPixels の 項目を参照すること。

注意
最大レベルを直接問い合わせる手段はない点に注意すること。 最大レベルは glGetTexLevelParameter を使って間接的に求められる。 最初にレベル 0 で実際に使われている幅を求める。 (この幅と高さは width と height でないことがある。 プロキシテクスチャは OpenGL の実装に合うように拡大・縮小されるかもしれ ないからである。) すると最大レベルは公式 ${log sub 2}( max (width,height))$ で計算できる。

注意
フォーマット GL_BGR および GL_BGRA、 型 GL_UNSIGNED_BYTE_3_3_2, GL_UNSIGNED_BYTE_2_3_3_REV, GL_UNSIGNED_SHORT_5_6_5, GL_UNSIGNED_SHORT_5_6_5_REV, GL_UNSIGNED_SHORT_4_4_4_4, GL_UNSIGNED_SHORT_4_4_4_4_REV, GL_UNSIGNED_SHORT_5_5_5_1, GL_UNSIGNED_SHORT_1_5_5_5_REV, GL_UNSIGNED_INT_8_8_8_8, GL_UNSIGNED_INT_8_8_8_8_REV, GL_UNSIGNED_INT_10_10_10_2, GL_UNSIGNED_INT_2_10_10_10_REV が使えるのは GL のバージョン 1.2 以降および GLU のバージョン 1.3 以降 だけである。

エラー
width または height が 1 未満ならば GLU_INVALID_VALUE が返される。

internalFormat または format, type が不正な場合には GLU_INVALID_ENUM が返される。

type が GL_UNSIGNED_BYTE_3_3_2 または GL_UNSIGNED_BYTE_2_3_3_REV であり、かつ format が GL_RGB でない場合には GLU_INVALID_OPERATION が返される。

type が GL_UNSIGNED_SHORT_5_6_5 または GL_UNSIGNED_SHORT_5_6_5_REV であり、かつ format が GL_RGB でない場合には GLU_INVALID_OPERATION が返される。

type が GL_UNSIGNED_SHORT_4_4_4_4 または GL_UNSIGNED_SHORT_4_4_4_4_REV であり、かつ format が GL_RGBA と GL_BGRA のいずれでもない 場合には GLU_INVALID_OPERATION が返される。

type が GL_UNSIGNED_SHORT_5_5_5_1 または GL_UNSIGNED_SHORT_1_5_5_5_REV であり、かつ format が GL_RGBA と GL_BGRA のいずれでもない 場合には GLU_INVALID_OPERATION が返される。

type が GL_UNSIGNED_INT_8_8_8_8 または GL_UNSIGNED_INT_8_8_8_8_REV であり、かつ format が GL_RGBA と GL_BGRA のいずれでもない 場合は GLU_INVALID_OPERATION が返される。

type が GL_UNSIGNED_INT_10_10_10_2 または GL_UNSIGNED_INT_2_10_10_10_REV であり、かつ format が GL_RGBA と GL_BGRA のいずれでもない 場合には GLU_INVALID_OPERATION が返される。

関連項目
glDrawPixels, glTexImage1D, glTexImage2D, glTexImage3D, gluBuild1DMipmaps, gluBuild3DMipmaps, gluErrorString, glGetTexImage, glGetTexLevelParameter, gluBuild1DMipmapLevels, gluBuild2DMipmapLevels, gluBuild3DMipmapLevels