10. Function for Directly Specifying Command Lists

CTR-SDK 4.2 added a function that can directly specify command lists without binding them. Applications must manage objects and buffers. However, you can build a framework with a greater degree of freedom because applications do not have to depend on the library's internal status.

The function that directly specifies the command list is called as a gx Raw() function and the original function is called as a gx() function.

Except for some functions, the suffix "Raw" is appended to the corresponding gx() function, and a pointer specification is added to the nngxCommandList structure to specify an argument. Basically, there is no difference from the operation and errors generated with the function.

Note the following when using gx Raw() functions.

  • gl() functions and GD library functions, which depend on the current command list, cannot be used with gx Raw() functions.
  • The nngxCommandList structure cannot be copied and used.
  • The operation is not guaranteed when a gx() function that uses the command list and a gx Raw() function are used together.
  • There are no corresponding gx() functions when using gx Raw() functions for saving, reusing, copying, importing, and exporting command lists, in addition to adding jump and subroutine commands. These functions must all be implemented in the application.
Table 10-1. gx Raw Functions Corresponding to the gx Function Used for the Command List
gx API gx Raw API
nngxGenCmdlists No corresponding function
nngxBindCmdlist No corresponding function
nngxCmdlistStorage

nngxCmdlistStorageRaw

nngxGetCommandRequestSizeRaw

nngxDeleteCmdlists No corresponding function
nngxSplitDrawCmdlist nngxSplitDrawCmdlistRaw
nngxFlush3DCommand No corresponding function
nngxFlush3DCommandNoCacheFlush nngxFlush3DCommandNoCacheFlushRaw
nngxFlush3DCommandPartially nngxFlush3DCommandPartiallyRaw
nngxAdd3DCommand No corresponding function
nngxAdd3DCommandNoCacheFlush nngxAdd3DCommandNoCacheFlushRaw
nngxAddJumpCommand No corresponding function
nngxAddSubroutineCommand No corresponding function
nngxMoveCommandbufferPointer nngxMoveCommandbufferPointerRaw
nngxAddB2LTransferCommand nngxAddB2LTransferCommandRaw
nngxAddBlockImageCopyCommand nngxAddBlockImageCopyCommandRaw
nngxAddL2BTransferCommand nngxAddL2BTransferCommandRaw
nngxAddMemoryFillCommand nngxAddMemoryFillCommandRaw
nngxAddVramDmaCommand No corresponding function
nngxAddVramDmaCommandNoCacheFlush nngxAddVramDmaCommandNoCacheFlushRaw
nngxFilterBlockImage nngxFilterBlockImageRaw
nngxEnableCmdlistCallback nngxEnableCmdlistCallbackRaw
nngxDisableCmdlistCallback nngxDisableCmdlistCallbackRaw
nngxSetCmdlistCallback nngxSetCmdlistCallbackRaw

nngxRunCmdlist

nngxRunCmdlistById

nngxRunCmdlistRaw
nngxStopCmdlist Use the same function
nngxReserveStopCmdlist nngxReserveStopCmdlistRaw
nngxWaitCmdlistDone Use the same function
nngxSetTimeout Use the same function
nngxGetIsRunning Use the same function
nngxClearCmdlist nngxClearCmdlistRaw
nngxClearFillCmdlist nngxClearFillCmdlistRaw
nngxStartCmdlistSave No corresponding function
nngxStopCmdlistSave No corresponding function
nngxUseSavedCmdlist No corresponding function
nngxUseSavedCmdlistNoCacheFlush No corresponding function
nngxAddCmdlist No corresponding function
nngxCopyCmdlist No corresponding function
nngxExportCmdlist No corresponding function
nngxImportCmdlist No corresponding function
nngxSetGasAutoAccumulationUpdate nngxSetGasAutoAccumulationUpdateRaw
nngxSetCmdlistParameteri nngxSetGasUpdateRaw
nngxGetCmdlistParameteri

nngxGetIsRunningRaw

nngxGetUsedBufferSizeRaw

nngxGetUsedRequestCountRaw

nngxGetMaxBufferSizeRaw

nngxGetMaxRequestCountRaw

nngxGetTopBufferAddrRaw

nngxGetRunBufferSizeRaw

nngxGetRunRequestCountRaw

nngxGetTopRequestAddrRaw

nngxGetNextRequestTypeRaw

nngxGetNextBufferAddrRaw

nngxGetNextBufferSizeRaw

nngxGetHWStateRaw

nngxGetCurrentBufferAddrRaw

The following section explains functions that have different methods of use between the gx API and gx Raw API.

10.1. Allocating and Destroying Command Lists

The gx Raw API uses different methods from the gx API to allocate the save data region used in command lists and to destroy command lists.

In the gx API, the following procedure is used to allocate the command list.

  1. Generate the command list (nngxGenCmdlist() function).
  2. Bind the command list object (nngxBindCmdlist() function).
  3. Allocate the save data region (3D command buffer, command request buffer) (nngxCmdlistStorage() function).

By contrast, in the gx Raw API, the following procedure is used to allocate the command list.

  1. Get the necessary region size for the Command Request queue (nngxGetCommandRequestSizeRaw() function).
  2. Allocate the save data region (3D command buffer, command request buffer).
  3. Generate the command list object (nngxCmdlistStorageRaw() function).

The function used to allocate the command list is as follows.

Code 10-1. gx Raw API Function for Allocating Command Lists
GLsizei nngxGetCommandRequestSizeRaw(GLsizei requestcount);
void nngxCmdlistStorageRaw(nngxCommandList* cmdlist,
                           GLsizei bufsize, GLvoid* commandbuffer,
                           GLsizei requestcount, GLvoid* commandrequest); 

For the requestcount parameter, specify the number of Command Requests that can be queued in the command list.

When allocating the 3D command buffer, note that its address and size (commandbuffer and bufsize) must be 16-byte aligned. Also, the 3D command buffer must be allocated in system memory.

We recommend that the address of the nngxCommandList structure itself (cmdlist) and the command request buffer (command request) are 4-byte aligned. There are no restrictions on the memory to allocate the buffer.

Take care not to deallocate any of the buffers while using the command list.

For the gx Raw API, there is no function corresponding to nngxDeleteCmdlists that destroys the command list. The application must manage each save data region for command lists, 3D command buffers, and command request buffers.

10.2. Setting Parameters

In the nngxSetCmdlistParameteri() function, which sets parameters for the current command list, the argument pname is used to specify the type of parameter set. In the gx Raw API, a different function is called to set each type of parameter.

Table 10-2. Values Specified for pname to Set Parameter and Corresponding gx Raw Function
pname Value gx Raw API Parameter Type
NN_GX_CMDLIST_RUN_MODE No corresponding function ---
NN_GX_CMDLIST_GAS_UPDATE nngxSetGasUpdateRaw GLboolean

10.3. Getting Parameters

In the nngxGetCmdlistParameteri() function, which gets the parameters of the current command list, the argument pname is used to specify the parameter type to get and receive the parameter as an argument. In the gx Raw API, a different function is called for each type of parameter and, the parameter can be obtained as a return value.

Table 10-3. Values Specified for pname and Corresponding gx Raw API for Getting Parameters
pname Value gx Raw API Return Value Type
NN_GX_CMDLIST_RUN_MODE No corresponding function ---
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 No corresponding function ---
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*

Only the nngxGetHWStateRaw() function is without an argument. All other functions are called by passing the pointer to the nngxCommandList structure.


CONFIDENTIAL