B.48. OpenGLバッファとの同期

B.48.1. clCreateFromGLBuffer

表B.130 表:clCreateFromGLBuffer

関数
cl_mem
clCreateFromGLBuffer(
    cl_context context,
    cl_mem_flags flags,
    GLuint bufobj,
    cl_int *errcode_ret
)
OpenCLバッファオブジェクトを
OpenGLバッファオブジェクトから生成。
 引数
context
OpenGLコンテキス
トから生成した有効な
OpenCLコンテキストを指定。
flags
メモリ使用情報を指
定するたのビットフィー
ルドです。

以下の3つのいずれ
かのみサポートされ
ています。

CL_MEM_READ_ONLY
CL_MEM_WRITE_ONLY
CL_MEM_READ_WRITE
bufobj
GLバッファオブジェク
トの名称。GLバッファ
オブジェクトのデータ記
憶(ストア)は
glBufferDataの呼び出し
で事前に生成されたものと
なる。データ記憶サイズは
CLバッファオブジェクトの
サイズを決定するのに
用いる。
errcode_ret
適切なエラーコー
ドを戻す。
 成功した場合
の戻り値
 CL_SUCCESS
 失敗した場合
の戻り値
CL_INVALID_
CONTEXT
有効なコンテキス
トでない場合。

GLコンテキストか
ら生成されてない
場合。
CL_INVALID_
VALUE
flagsに指定し
た値が無効な場合。
CL_INVALID_
GL_OBJECT
bufobjがGLバッファ
オブジェクトでない場合。

GLバッファオブジェク
トだが、データ記憶域
を持たない場合。
バッファサイズが0の
場合。
CL_OUT_
OF_RESOURCES
デバイス上のOpenCL実
装が必要とするリソース
確保に失敗した場合。
CL_OUT_OF_
HOST_MEMORY
ホスト上のOpenCL実装
が必要とするリソース
確保に失敗したとき。

B.48.2. clCreateFromGLTexture

表B.131 表:clCreateFromGLTexture

関数
cl_mem
clCreateFromGLTexture (
    cl_context context,
    cl_mem_flags flags,
    GLenum texture_target,
    GLint miplevel,
    GLuint texture,
    cl_int *errcode_ret
)
以下のオブジェクトを生成します。

OpenGL-2Dテキスチャオブジェク
トまたはOpenGLキューブマップオ
ブジェクトテキスチャの一面から
OpenCL-2Dイメージオブジェクト

OpenGL-2Dテキスチャ配列オブジ
ェクトからOpenCL-2Dイメージ配
列オブジェクト

OpenGL-1Dテキスチャオブジェク
トからOpenCL-1Dイメージオブ
ジェクト

OpenGL-1Dテキスチャ配列オブジ
ェクトからOpenCL-1Dイメージ
配列オブジェクト

OpenGL-3Dテキスチャオブジェク
トからOpenCL-3Dイメージオブ
ジェクト
 引数
context
OpenGLコンテキス
トから生成した有効な
OpenCLコンテキスト
を指定。
flags
メモリ使用情報を
指定するたのビット
フィールドです。

以下の3つのいずれ
かのみサポートされ
ています。

CL_MEM_READ_ONLY
CL_MEM_WRITE_ONLY
CL_MEM_READ_WRITE
texture_
target
以下のうち一つ
の値をとります。

GL_TEXTURE_1D,

GL_TEXTURE_1D_
ARRAY,

GL_TEXTURE_BUFFER,

GL_TEXTURE_2D,

GL_TEXTURE_2D_
ARRAY,

GL_TEXTURE_3D,

GL_TEXTURE_CUBE_
MAP_POSITIVE_X,

GL_TEXTURE_CUBE_
MAP_POSITIVE_Y,

GL_TEXTURE_CUBE_
MAP_POSITIVE_Z,

GL_TEXTURE_CUBE_
MAP_NEGATIVE_X,

GL_TEXTURE_CUBE_
MAP_NEGATIVE_Y,

GL_TEXTURE_CUBE_
MAP_NEGATIVE_Z,

GL_TEXTURE_
RECTANGLE

テキスチャのイメージ
型を定義するために
使われる。
miplevel
使用されるmipmap
レベルを指定。GL_
TEXTURE_BUFFERの場
合、miplevelは0とな
る必要がある。
texture
GL 1D, 2D, 3D,
1D配列、2D配列、
cubemap、矩形、バッ
ファテキスチャオブジ
ェクトの名称です。
errcode_ret
適切なエラーコ
ードを戻します。
 成功した場合
の戻り値
 CL_SUCCESS
 失敗した場合
の戻り値
CL_INVALID_
CONTEXT
コンテキストが有
効でない場合。

GLコンテキストから
生成されていない
場合。
CL_INVALID_
VALUE
flagsに指定され
た値が有効でない
場合。

texture_target
に指定された値が
有効でない場合。
CL_INVALID_
MIP_LEVEL
miplevelがレベ
ルベース(OpenGL
実装)の値より小さ
い場合か、0の場合
(OpenGL ES実装)。
CL_INVALID_
MIP_LEVEL
miplevelが0より
大きく、OpenGL実装
が非ゼロmipmapレ
ベルの生成をサポート
しない場合。
CL_INVALID_
GL_OBJECT
テキスチャがtexture_
targetに適合するGLテ
キスチャオブジェクト
でない場合。

指定されたテキスチャ
のmiplevelが定義さ
れていない場合。
CL_INVALID_
IMAGE_FORMAT_
DESCRIPTOR
OpenGL内部テキス
チャ型式が、OpenCLが
サポートするイメージ
型式にマップしない
場合。
CL_INVALID_
OPERATION
テキスチャが、ボーダ
ーの太さが0以上の値
で生成されたGLテキス
チャオブジェクトの場
合。
CL_OUT_
OF_RESOURCES
デバイス上のOpenCL
実装が必要とするリ
ソース確保に失敗し
た場合。
CL_OUT_
OF_HOST_
MEMORY
ホスト上のOpenCL
実装が必要とするリ
ソース確保に失敗し
たとき。

B.48.3. clGetGLObjectInfo

表B.132 表:clGetGLObjectInfo

関数
cl_int
clGetGLObjectInfo (
    cl_mem memobj,
    cl_gl_object_type *gl_object_type,
    GLuint *gl_object_name
)
gl_object_typeはmemobjにアタッ
チされたGLオブジェクトを戻し、以下
のいずれかの値をとります。

CL_GL_OBJECT_
BUFFER

CL_GL_OBJECT_
TEXTURE2D

CL_GL_OBJECT_
TEXTURE3D

CL_GL_OBJECT_
TEXTURE2D_ARRAY

CL_GL_OBJECT_
TEXTURE1D

CL_GL_OBJECT_
TEXTURE1D_ARRAY

CL_GL_OBJECT_
TEXTURE_BUFFER

CL_GL_OBJECT_
RENDERBUFFER

NULLの場合は無視。
 引数
gl_object_name
memobjを生成する
のに用いるGLオブジ
ェクト名を戻す。
NULLの場合は無視。
 成功した場合
の戻り値
 CL_SUCCESS
 失敗した場合
の戻り値
CL_INVALID_
MEM_OBJECT
memobjが有効な
OpenCLメモリオブ
ジェクトでない場合。
CL_INVALID_
GL_OBJECT
memObjに関連づけ
られたGLオブジェ
クトが存在しない
場合。
CL_OUT_
OF_RESOURCES
デバイス上のOpenCL
実装が必要とするリ
ソース確保に失敗し
た場合。
CL_OUT_OF_
HOST_MEMORY
ホスト上のOpenCL実
装が必要とするリソー
ス確保に失敗したとき。

B.48.4. clGetGLTextureInfo

表B.133 表:clGetGLTextureInfo

関数
cl_int
clGetGLTextureInfo (
    cl_mem memobj,
    cl_gl_texture_info param_name,
    size_t param_value_size,
    void *param_value,
    size_t *param_value_size_ret
)
memObjに関連付けられたGLテキスチャオ
ブジェクトについての追加情報を戻します。
 引数
param_name
クエリするmemobjに
関連付けられたGLテ
キスチャオブジェクト
についての追加情報を
指定。
param_value
クエリした結果が戻
るメモリ空間を指すポ
インタを指定。
param_value_
size
param_valueが指
すメモリ空間のバイ
トサイズを指定。サ
イズは>=戻り値の型
となります。
param_value_
size_ret
param_valueに複製
されるデータの実際の
バイトサイズを戻す。
NULLの場合は無視。
 成功した場合
の戻り値
 CL_SUCCESS
 失敗した場合
の戻り値
CL_INVALID_
MEM_OBJECT
memobjが有効な
OpenCLメモリオブ
ジェクトでない場合。
CL_INVALID_
GL_OBJECT
memobjに関連付け
られたGLテキスチャ
オブジェクトが存在
しない場合。
CL_INVALID_
VALUE
param_nameが有
効でない場合。

param_value_size
のバイトサイズが戻り
値の型より小さく、
param_valueがNULL
でない場合。

param_valueと
param_value_
size_retがNULL
の場合。
CL_OUT_
OF_RESOURCES
デバイス上のOpenCL
実装が必要とするリ
ソース確保に失敗し
た場合。
CL_OUT_OF_
HOST_MEMORY
ホスト上のOpenCL
実装が必要とするリ
ソース確保に失敗し
たとき。

B.48.5. clEnqueueAcquireGLObjects

表B.134 表:clEnqueueAcquireGLObjects

関数
cl_int
clEnqueueAcquireGLObjects (
    cl_command_queue command_queue,
    cl_uint num_objects,
    const cl_mem *mem_objects,
    cl_uint num_events_in_wait_list,
    const cl_event *event_wait_list,
    cl_event *event)
OpenGLオブジェクトから生成されたOpenCL
メモリオブジェクトを取得するために用いま
す。コマンドキューに挿入されたコマンドが
使用される前に、これらのオブジェクトは取
得される必要があります。OpenGLオブジェク
トは、コマンドキューに関連付けられた
OpenCLコンテキストにより取得され、
OpenCLコンテキスト関連づけられた全ての
コマンドキューで使うことができます。
 引数
command_queue
有効なコマンドキュー。
コマンドキューに関連づ
けられたOpenCLコンテ
キストを生成するのに
用いた全てのデバイスは
CL/GL共有オブジェクト
の取得をサポートしてな
くてはならない。この制
約はコンテキスト生成時
に適用される。
num_objects
mem_objectsで取得
されるメモリオブジェ
クトの数を指定。
mem_objects
GLオブジェクトに対応
するCLメモりオブジェ
クトのリストを指すポ
インタです。
num_events_
in_wait_list
event_wait_list
で指定したイベントオ
ブジェクトの数を指定
します。
event_wait_
list
このコマンドが実行さ
れる前に完了していなけ
ればならないイベントを
指定。

event_wait_listが
NULLの場合、このコマ
ンドはどのイベントの
完了待機もしない。

event_wait_listが
NULLの場合、num_
events_in_wait_list
は0となる必要がある。

event_wait_listが
NULLでない場合、
event_wait_listが
指す各イベントは有効
となる必要があり、
またnum_events_in_
wait_listは0より大き
な値となる必要がある。

event_wait_listに指
定したイベントは同期点
としてふるまう。

event_wait_list内の
イベントと関連付けられ
たOpenCLコンテキスト
と command_queueと
関連付けられたOpenCL
コンテキストは同じとな
る必要がある。

event_wait_listと
関連付けられたメモリ
は、関数が完了の後に、
再利用または解放できる。
event
このコマンドを識別
するイベントオブジ
ェクトが戻され、コ
マンド完了の確認や
コマンド完了待機をす
る。eventがNULLの
場合、アプリケーシ
ョンはコマンドの状
況確認やコマンド完
了待ちを行えない。

event_wait_list
とevent引数がNULL
でない場合、event
引数はevent_wait_
list配列の要素を参
照すべきでない。
 成功した場合
の戻り値
 CL_SUCCESS
 失敗した場合
の戻り値
CL_INVALID_
VALUE
num_objectsが0で、
mem_objectsがNULL
でない場合。

`num_objects > 0`
で、mem_objectsが
NULLの場合。
CL_INVALID_
MEM_OBJECT
mem_objects内の
メモリオブジェクト
が有効でない場合。
CL_INVALID_
COMMAND_QUEUE
command_queue
が有効でない場合
CL_INVALID_
CONTEXT
command_queue
に関連付けられた
コンテキストが
OpenGLコンテキスト
から生成されてい
ない場合。
CL_INVALID_
GL_OBJECT
mem_objects内の
メモリオブジェクトが
OpenGLオブジェクト
から生成されていな
い場合。
CL_INVALID_
EVENT_WAIT_LIST
event_wait_list
がNULLでnum_events_
in_wait_listが0よ
り大きい場合。

event_wait_listが
NULLでなく
num_events_in_
wait_listが0の場合。

event_wait_list
内のイベントオブジ
ェクトが有効なもの
でない場合。
CL_OUT_OF_
RESOURCES
デバイス上のOpenCL
実装が必要とするリソ
ース確保に失敗した場
合。
CL_OUT_OF
_HOST_MEMORY
ホスト上のOpenCL
実装が必要とするリソ
ース確保に失敗した
とき。

B.48.6. clEnqueueReleaseGLObjects

表B.135 表:clEnqueueReleaseGLObjects

関数
cl_int
clEnqueueReleaseGLObjects (
    cl_command_queue command_queue,
    cl_uint num_objects,
    const cl_mem *mem_objects,
    cl_uint num_events_in_wait_list,
    const cl_event *event_wait_list,
    cl_event *event
)
OpenGLオブジェクトから生成されている
OpenCLメモリオブジェクトを解放するた
めに用います。これらのオブジェクトは
OpenGLに使われる前に解放する必要があ
ります。OpenGLオブジェクトはコマンド
キューに関連付けられたOpenCLコンテキ
ストによって解放されます。
 引数
num_objects
mem_objectsコレク
ション内で解放するメ
モリオブジェクトの数。
mem_objects
GLオブジェクトに対
応するCLメモリオブジ
ェクトのリストを指す
ポインタ。
num_events_
in_wait_list
event_wait_list
で指定したイベントオ
ブジェクトの数を指
定します。
event_wait_
list
このコマンドが実
行される前に完了し
ていなければならない
イベントを指定。

event_wait_list
がNULLの場合、この
コマンドはどのイベン
トの完了待機もしない。

event_wait_list
がNULLの場合、num_
events_in_wait_
listは0となる必要が
ある。

event_wait_listが
NULLでない場合、
event_wait_listが
指す各イベントは有効
となる必要があり、ま
たnum_events_in_
wait_listは0より大
きな値となる必要がある。

event_wait_listに
指定したイベントは同
期点としてふるまう。

event_wait_list内
のイベントと関連付けら
れたOpenCLコンテキ
ストと command_
queueと関連付けられ
たOpenCLコンテキスト
は同じとなる必要がある。

event_wait_listと
関連付けられたメモリ
は、関数が完了の後に、
再利用または解放できる。
event
このコマンドを識別す
るイベントオブジェク
トが戻され、コマンド
完了の確認やコマンド
完了待機をする。
eventがNULLの場合、
アプリケーションはコ
マンドの状況確認やコ
マンド完了待ちを行え
ない。

event_wait_listと
event引数がNULLで
ない場合、event引数
はevent_wait_list
配列の要素を参照すべ
きでない。
 成功した場合
の戻り値
 CL_SUCCESS
 失敗した場合
の戻り値
CL_INVALID_
VALUE
num_objectsが0
で、mem_objectsが
NULLでない場合。

`num_objects > 0`
で、mem_objectsが
NULLの場合。
CL_INVALID_
MEM_OBJECT
mem_objects内の
メモリオブジェクトが
有効でない場合。
CL_INVALID_
COMMAND_QUEUE
command_queue
が有効でない場合
CL_INVALID_
CONTEXT
command_queue
に関連付けられたコ
ンテキストがOpenGL
コンテキストから生
成されていない場合。
CL_INVALID_
GL_OBJECT
mem_objects内の
メモリオブジェクト
がOpenGLオブジェク
トから生成されてい
ない場合。
CL_INVALID_
EVENT_WAIT_LIST
event_wait_list
がNULLで
num_events_in_
wait_listが0より
大きい場合。

event_wait_list
がNULLでなくnum_
events_in_wait_
listが0の場合。

event_wait_list
内のイベントオブジ
ェクトが有効なもの
でない場合。
CL_OUT_
OF_RESOURCES
デバイス上のOpenCL
実装が必要とするリ
ソース確保に失敗
した場合。
CL_OUT_OF_
HOST_MEMORY
ホスト上のOpenCL
実装が必要とするリ
ソース確保に失敗し
たとき。

Copyright 2018-2019, by Masaki Komatsu