GLREADPIXELS
Section: Misc. Reference Manual Pages (3G)
索引
xjman
名前
glReadPixels
- フレームバッファからピクセルのブロックを読み取る
書式
void glReadPixels(
GLint x,
GLint y,
GLsizei width,
GLsizei height,
GLenum format,
GLenum type,
GLvoid *pixels )
delim $$
引き数
- x, y
-
フレームバッファから読み取る最初のピクセルのウィンドウ座標を指定する。
この位置は、ピクセルの矩形ブロックの左下隅の座標である。
- width, height
-
ピクセル矩形領域の寸法を指定する。
width および height が 1 の時はピクセル 1 つを指定した
ことになる。
- format
-
ピクセルデータのフォーマットを指定する。
次のシンボル値を指定できる:
GL_COLOR_INDEX,
GL_STENCIL_INDEX,
GL_DEPTH_COMPONENT,
GL_RED,
GL_GREEN,
GL_BLUE,
GL_ALPHA,
GL_RGB,
GL_BGR,
GL_RGBA,
GL_BGRA,
GL_LUMINANCE,
GL_LUMINANCE_ALPHA。
- type
-
ピクセルデータのデータ型を指定する。
次のいずれかでなければならない:
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。
- pixels
-
ピクセルデータが返される。
説明
glReadPixels はフレームバッファから読み取ったピクセルデータを返す。
読み取りは、左下隅が (x, y) の位置にあるピクセルから始め、
pixels の位置から始まるクライアントメモリ領域にデータが
格納される。
いくつかのパラメータにより、ピクセルデータがクライアントメモリ領域に
格納される前の処理が制御される。
これらのパラメータは 3 つのコマンドを使って設定する:
glPixelStore,
glPixelTransfer, and
glPixelMap。
これらのコマンドのマニュアルページには、glReadPixels に
与える影響の大部分が説明されているが、全てのパラメータが
これら 3 つのコマンドによって指定されるわけではない。
実装が GL_ARB_imaging 機能拡張に対応している場合は、
ピクセルデータには他の操作を加えることができる。
この処理には色テーブル参照、色行列変換、畳み込み、ヒストグラム、
ピクセル値の最小値や最大値の計算などがある。
glReadPixels は、左下隅が (x + $i$, y + $j$) の
位置にある各ピクセルの値を返す。
ここで 0 < $i$ < width, 0 < $j$ < height である。
このピクセルは $j$ 番目の列の $i$ 番目のピクセルと呼ばれる。
返されるピクセルの並び順は、列としては下から上へ、ある列の中では
左から右への順である。
format は返されるピクセル値のフォーマットを指定する。
指定できる値は次のとおりである:
- GL_COLOR_INDEX
-
glReadBuffer によって指定された色バッファから
色インデックスが読み取られる。
各インデックスはまず固定小数点値に変換され、
次に GL_INDEX_SHIFT の符号と値に基づいて右か左にシフト操作され、
最後に GL_INDEX_OFFSET が加えられる。
GL_MAP_COLOR が GL_TRUE ならば、
インデックスは GL_PIXEL_MAP_I_TO_I テーブル内のマッピングに
基づいて置き換えられる。
- GL_STENCIL_INDEX
-
ステンシルバッファからステンシル値が読み取られる。
各インデックスはまず固定小数点値に変換され、
次に GL_INDEX_SHIFT の符号と値に基づいて右か左にシフト操作され、
最後に GL_INDEX_OFFSET が加えられる。
GL_MAP_STENCIL が GL_TRUE ならば、
インデックスは GL_PIXEL_MAP_S_TO_S テーブル内のマッピングに
基づいて置き換えられる。
- GL_DEPTH_COMPONENT
-
深さバッファから深さ値が読み取られる。
各要素は、最も小さい深さ値が 0 となり、最も大きい深さ値が 1 となるように
浮動小数点値に変換される。
次に各要素に GL_DEPTH_SCALE が掛けられ、それから
GL_DEPTH_BIAS が加えられ、最後に [0,1] への制限が
行われる。
- GL_RED
-
- GL_GREEN
-
- GL_BLUE
-
- GL_ALPHA
-
- GL_RGB
-
- GL_BGR
-
- GL_RGBA
-
- GL_BGRA
-
- GL_LUMINANCE
-
- GL_LUMINANCE_ALPHA
-
色インデックスや RGBA 色要素を格納している色バッファによって処理が異なる。
色インデックスが格納されている場合は、
glReadBuffer によって選ばれた色バッファから
色インデックスが読み取られる。
各インデックスはまず固定小数点値に変換され、
次に GL_INDEX_SHIFT の符号と値に基づいて右か左にシフト操作され、
最後に GL_INDEX_OFFSET が加えられる。
次に、テーブル
GL_PIXEL_MAP_I_TO_R,
GL_PIXEL_MAP_I_TO_G,
GL_PIXEL_MAP_I_TO_B,
GL_PIXEL_MAP_I_TO_A
のインデックスを使って、R, G, B, A の値が求められる。
それぞれのテーブルの大きさは $2 sup n$ でなければならないが、$n$ は
テーブルごとに異なってもかまわない。
インデックスを使って、大きさが $2 sup n$ のテーブルを参照する前には、
インデックスには $2 sup n - 1$ でマスクをかけなければならない。
-
色バッファに RGBA 色要素が格納されている場合には、
これらの値は glReadBuffer によって選択された色バッファから読み取られる。
それぞれの色要素は固定小数点値に変換される。
この変換は、強度 0 が 0.0 に、最大強度が 1.0 に対応するように行われる。
次に各要素には GL_c_SCALE が掛けられてから GL_c_BIAS が
加えられる。
ここで c は RED, GREEN, BLUE, ALPHA のいずれかである。
最後に、GL_MAP_COLOR が GL_TRUE の場合には、
各要素は [0, 1] の範囲に収まるように調整され、
対応する色テーブルの大きさに合わせて大きさが変更され、
GL_PIXEL_MAP_c_TO_c テーブル内のマッピングによって値を
置き換えられる。
ここで c は R, G, B, A のいずれかである。
-
それから不必要なデータが破棄される。
例えば、GL_RED は緑、青、アルファ要素を破棄するし、
一方で GL_RGB はアルファ要素だけを破棄する。
GL_LUMINANCE は、赤、緑、青要素の合計として、
要素をひとつだけ持つ値を計算する。
GL_LUMINANCE_ALPHA は同じ計算をするが、アルファ値を
2 番目の値として持ち続ける。
最終的に得られた値は [0, 1] の範囲に制限される。
今までの説明で触れられたシフト操作、スケール操作、バイアス操作、
係数参照はすべて glPixelTransfer によって指定される。
参照テーブルの内容そのものは glPixelMap によって指定される。
最後に、インデックスおよび要素は type が指定する型に
適切に変換される。
format が GL_COLOR_INDEX または GL_STENCIL_INDEX
であり、かつ type が GL_FLOAT でない場合には、
次の表で示されるマスク値がインデックスに対してかけられる。
type が GL_FLOAT ならば、
整数値を持つ各インデックスは単精度の浮動小数点値に変換される。
format が
GL_RED,
GL_GREEN,
GL_BLUE,
GL_ALPHA,
GL_RGB,
GL_BGR,
GL_RGBA,
GL_BGRA,
GL_LUMINANCE,
であり、かつ type が GL_FLOAT でない場合には、
以下の表に示す値がそれぞれの要素に掛けられる。
type が GL_FLOAT の場合には、それぞれの要素はそのまま
通過する(GL とクライアントで浮動小数点値の精度が異なる場合には、
クライアントの単精度の浮動小数点値に変換される)。
|
| type | インデックスのマスク値 | 要素変換
|
|
| GL_UNSIGNED_BYTE | $2"^"8 - 1$ | $(2"^"8 - 1) c$
|
| GL_BYTE | $2"^"7 - 1$ | $[(2"^"8 - 1) c - 1] / 2$
|
| GL_BITMAP | $1$ | $1$
|
| GL_UNSIGNED_SHORT | $2"^"16 - 1$ | $(2"^"16 - 1) c$
|
| GL_SHORT | $2"^"15 - 1$ | $[(2"^"16 - 1) c - 1] / 2$
|
| GL_UNSIGNED_INT | $2"^"32 - 1$ | $(2"^"32 - 1) c$
|
| GL_INT | $2"^"31 - 1$ | $[(2"^"32 - 1) c - 1] / 2$
|
| GL_FLOAT | none | $c$
|
|
返される値は次に示すようにメモリに格納される。
format が
GL_COLOR_INDEX,
GL_STENCIL_INDEX,
GL_DEPTH_COMPONENT,
GL_RED,
GL_GREEN,
GL_BLUE,
GL_ALPHA,
GL_LUMINANCE,
のいずれかの場合には、ひとつの値が返され、$j$ 番目の列の $i$ 番目の
ピクセルについてのデータが $(j)~"width"~+~i$ の位置に格納される。
GL_RGB と GL_BGR は 3 個の値を返し、
GL_RGBA と GL_BGRA は 4 個の値を返す。
GL_LUMINANCE_ALPHA は各ピクセルについてふたつの値を返す。
いずれの場合も、ひとつのピクセルに対応する値は、pixels 内で
連続する領域を占める。
glPixelStore によって設定する格納パラメータは
(GL_PACK_LSB_FIRST, GL_PACK_SWAP_BYTES)、
データのメモリへの書き込みかたに影響を与える。
説明については glPixelStore を参照すること。
注意
現在の GL コンテクストが接続されているウィンドウの外側にある
ピクセルについての値は未定義である。
エラーが起きた場合、pixels の内容はまったく変化しない。
エラー
GL_INVALID_ENUM:
format または type の値が不正な場合に起こる。
GL_INVALID_ENUM:
type が GL_BITMAP であり、かつ format が
GL_COLOR_INDEX と GL_STENCIL_INDEX のいずれでもない場合に起こる。
GL_INVALID_VALUE:
width または height の値が負の場合に起こる。
GL_INVALID_OPERATION:
format が GL_COLOR_INDEX であり、かつ色バッファが RGBA 色要素を
格納している場合に起こる。
GL_INVALID_OPERATION:
format が GL_STENCIL_INDEX であり、かつステンシルバッファが
ない場合に起こる。
GL_INVALID_OPERATION:
format が GL_DEPTH_COMPONENT であり、かつ深さバッファがない
場合に起こる。
GL_INVALID_OPERATION:
glBegin と、その対になる glEnd の間で
glReadPixels が実行されると起こる。
GL_INVALID_OPERATION:
type が
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
のいずれかであり、かつ
format が GL_RGB でない場合に起こる。
GL_INVALID_OPERATION:
type が
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
のいずれかであり、かつ
format が GL_RGBA と GL_BGRA のいずれでもない場合に起こる。
フォーマット 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
はバージョン 1.2 以降の GL でなければ利用できない。
関連する取得値
引き数 GL_INDEX_MODE を指定した glGet
関連項目
glCopyPixels(3G),
glDrawPixels(3G),
glPixelMap(3G),
glPixelStore(3G),
glPixelTransfer(3G),
glReadBuffer(3G)
Index
- 名前
-
- 書式
-
- 引き数
-
- 説明
-
- 注意
-
- エラー
-
- 関連する取得値
-
- 関連項目
-
Time: 07:01:10 GMT, January 12, 2009