10. コマンドリストを直接指定する関数

コマンドリストをバインドせずに直接指定する関数も用意されています。オブジェクトやバッファの管理などをアプリケーションで行わなければなりませんが、ライブラリの内部状態に依存しないため、より自由度の高いフレームワークを構築することができます。

ここでは、コマンドリストを直接指定する関数を「gx Raw API」、従来の関数を「gx API」と表記します。

一部の関数を除いて、対応する gx API の末尾に「Raw」が付加され、引数の指定に nngxCommandList 構造体へのポインタ指定が追加されます。基本的に、関数の動作や生成されるエラーに違いはありません。

gx Raw API を使用する場合は、以下の点に注意してください。

  • カレントのコマンドリストに依存する、gl 関数や GD ライブラリの関数とは併用できません。
  • nngxCommandList 構造体をコピーして使用することはできません。
  • コマンドリストを使用する gx API と gx Raw API を混成使用した場合の動作は保証されません。
  • コマンドリストの保存、再使用、コピー、ジャンプコマンドの追加、サブルーチンコマンドの追加、エクスポート、インポートには対応する関数が用意されていないため、アプリケーションで実装する必要があります。
表 10-1. コマンドリストを使用する gx API に対応する gx Raw API
gx API gx Raw API
nngxGenCmdlists() 対応する関数はありません
nngxBindCmdlist() 対応する関数はありません
nngxCmdlistStorage()

nngxCmdlistStorageRaw()

nngxGetCommandRequestSizeRaw()

nngxDeleteCmdlists() 対応する関数はありません
nngxSplitDrawCmdlist() nngxSplitDrawCmdlistRaw()
nngxFlush3DCommand() 対応する関数はありません
nngxFlush3DCommandNoCacheFlush() nngxFlush3DCommandNoCacheFlushRaw()
nngxFlush3DCommandPartially() nngxFlush3DCommandPartiallyRaw()
nngxAdd3DCommand() 対応する関数はありません
nngxAdd3DCommandNoCacheFlush() nngxAdd3DCommandNoCacheFlushRaw()
nngxAddJumpCommand() 対応する関数はありません
nngxAddSubroutineCommand() 対応する関数はありません
nngxMoveCommandbufferPointer() nngxMoveCommandbufferPointerRaw()
nngxAddB2LTransferCommand() nngxAddB2LTransferCommandRaw()
nngxAddBlockImageCopyCommand() nngxAddBlockImageCopyCommandRaw()
nngxAddL2BTransferCommand() nngxAddL2BTransferCommandRaw()
nngxAddMemoryFillCommand() nngxAddMemoryFillCommandRaw()
nngxAddVramDmaCommand() 対応する関数はありません
nngxAddVramDmaCommandNoCacheFlush() nngxAddVramDmaCommandNoCacheFlushRaw()
nngxFilterBlockImage() nngxFilterBlockImageRaw()
nngxEnableCmdlistCallback() nngxEnableCmdlistCallbackRaw()
nngxDisableCmdlistCallback() nngxDisableCmdlistCallbackRaw()
nngxSetCmdlistCallback() nngxSetCmdlistCallbackRaw()

nngxRunCmdlist()

nngxRunCmdlistById()

nngxRunCmdlistRaw()
nngxStopCmdlist() 同じ関数を使用します
nngxReserveStopCmdlist() nngxReserveStopCmdlistRaw()
nngxWaitCmdlistDone() 同じ関数を使用します
nngxSetTimeout() 同じ関数を使用します
nngxGetIsRunning() 同じ関数を使用します
nngxClearCmdlist() nngxClearCmdlistRaw()
nngxClearFillCmdlist() nngxClearFillCmdlistRaw()
nngxStartCmdlistSave() 対応する関数はありません
nngxStopCmdlistSave() 対応する関数はありません
nngxUseSavedCmdlist() 対応する関数はありません
nngxUseSavedCmdlistNoCacheFlush() 対応する関数はありません
nngxAddCmdlist() 対応する関数はありません
nngxCopyCmdlist() 対応する関数はありません
nngxExportCmdlist() 対応する関数はありません
nngxImportCmdlist() 対応する関数はありません
nngxSetGasAutoAccumulationUpdate() nngxSetGasAutoAccumulationUpdateRaw()
nngxSetCmdlistParameteri() nngxSetGasUpdateRaw()
nngxGetCmdlistParameteri()

nngxGetIsRunningRaw()

nngxGetUsedBufferSizeRaw()

nngxGetUsedRequestCountRaw()

nngxGetMaxBufferSizeRaw()

nngxGetMaxRequestCountRaw()

nngxGetTopBufferAddrRaw()

nngxGetRunBufferSizeRaw()

nngxGetRunRequestCountRaw()

nngxGetTopRequestAddrRaw()

nngxGetNextRequestTypeRaw()

nngxGetNextBufferAddrRaw()

nngxGetNextBufferSizeRaw()

nngxGetHWStateRaw()

nngxGetCurrentBufferAddrRaw()

gx API と gx Raw API とで使用方法が異なる関数については、以降の節で説明します。

10.1. コマンドリストの確保と破棄

gx Raw API では、コマンドリストで使用するデータ領域を確保するまでの手順や、コマンドリストを破棄する方法が従来とは異なります。

gx API では、以下の手順でコマンドリストの確保を行っていました。

  1. コマンドリストオブジェクトを生成する(nngxGenCmdlist()
  2. コマンドリストオブジェクトをバインドする(nngxBindCmdlist()
  3. データ領域(3D コマンドバッファ、コマンドリクエストのバッファ)を確保する(nngxCmdlistStorage()

gx Raw API では、以下の手順でコマンドリストの確保を行います。

  1. コマンドリクエストのキューに必要な領域のサイズを取得する(nngxGetCommandRequestSizeRaw()
  2. データ領域(3D コマンドバッファ、コマンドリクエストのバッファ)を確保する
  3. コマンドリストオブジェクトを生成する(nngxCmdlistStorageRaw()

コマンドリストの確保に使用する関数は、以下の通りです。

コード 10-1. コマンドリストの確保に使用する関数(gx Raw API)
GLsizei nngxGetCommandRequestSizeRaw(GLsizei requestcount);
void nngxCmdlistStorageRaw(nngxCommandList* cmdlist,
                           GLsizei bufsize, GLvoid* commandbuffer,
                           GLsizei requestcount, GLvoid* commandrequest);

requestcount には、コマンドリストにキューイング可能なコマンドリクエストの数を指定します。

3D コマンドバッファを確保するときは、そのアドレスとサイズ(commandbufferbufsize)のアライメントが 16 バイトでなければならないことに注意してください。また、3D コマンドバッファはデバイスメモリ上に確保する必要があります。

nngxCommandList 構造体自身(cmdlist)とコマンドリクエストのバッファ(commandrequest)は、アドレスのアライメントが 4 バイトとなるように確保することを推奨します。バッファの確保先メモリに制約はありません。

コマンドリストを使用する間は、各バッファを解放しないように注意してください。

gx Raw API には、コマンドリストの破棄を行う nngxDeleteCmdlists() に対応する関数はありません。コマンドリストおよび 3D コマンドバッファ、コマンドリクエストのバッファの各データ領域は、アプリケーション側で管理しなければなりません。

10.2. パラメータの設定

カレントのコマンドリストのパラメータを設定する nngxSetCmdlistParameteri() では、設定するパラメータの種類を引数 pname で指定していました。gx Raw API では、パラメータの種類ごとに異なる関数を呼び出して設定します。

表 10-2. パラメータの設定で pname に指定する値と gx Raw API の対応
pname に指定する値 gx Raw API パラメータの型
NN_GX_CMDLIST_RUN_MODE 対応する関数はありません ---
NN_GX_CMDLIST_GAS_UPDATE nngxSetGasUpdateRaw() GLboolean

10.3. パラメータの取得

カレントのコマンドリストのパラメータを取得する nngxGetCmdlistParameteri() では、取得するパラメータの種類を引数 pname で指定し、パラメータを引数で受け取っていました。gx Raw API では、パラメータの種類ごとに異なる関数を呼び出し、パラメータを返り値で取得します。

表 10-3. パラメータの取得で pname に指定する値と gx Raw API の対応
pname に指定する値 gx Raw API 返り値の型
NN_GX_CMDLIST_RUN_MODE 対応する関数はありません ---
NN_GX_CMDLIST_IS_RUNNING nngxGetIsRunningRaw() GLboolean
NN_GX_CMDLIST_USED_BUFSIZE nngxGetUsedBufferSizeRaw() GLsizei
NN_GX_CMDLIST_USED_REQCOUNT nngxGetUsedRequestCountRaw() GLsizei
NN_GX_CMDLIST_MAX_BUFSIZE nngxGetMaxBufferSizeRaw() GLsizei
NN_GX_CMDLIST_MAX_REQCOUNT nngxGetMaxRequestCountRaw() GLsizei
NN_GX_CMDLIST_TOP_BUFADDR nngxGetTopBufferAddrRaw() GLvoid*
NN_GX_CMDLIST_BINDING 対応する関数はありません ---
NN_GX_CMDLIST_RUN_BUFSIZE nngxGetRunBufferSizeRaw() GLsizei
NN_GX_CMDLIST_RUN_REQCOUNT nngxGetRunRequestCountRaw() GLsizei
NN_GX_CMDLIST_TOP_REQADDR nngxGetTopRequestAddrRaw() GLvoid*
NN_GX_CMDLIST_NEXT_REQTYPE nngxGetNextRequestTypeRaw() GLenum
NN_GX_CMDLIST_NEXT_REQINFO

nngxGetNextBufferAddrRaw()

nngxGetNextBufferSizeRaw()

GLvoid*

GLsizei

NN_GX_CMDLIST_HW_STATE nngxGetHWStateRaw() GLbitfield
NN_GX_CMDLIST_CURRENT_BUFADDR nngxGetCurrentBufferAddrRaw() GLvoid*

nngxGetHWStateRaw() のみ引数なし、そのほかの関数は nngxCommandList 構造体へのポインタを渡して呼び出します。