CTR-SDK 4.2 added a function that can directly specify command lists without binding them. Applications need to 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 withgx 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 agx Raw
function are used together. - There are no corresponding
gx
functions when usinggx Raw
functions for saving, reusing, copying, importing and exporting command lists, in addition to adding jump and subroutine commands. These functions all must be implemented in the application.
gx API | gx Raw API |
---|---|
nngxGenCmdlists
|
No corresponding function |
nngxBindCmdlist
|
No corresponding function |
nngxCmdlistStorage
|
|
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
|
|
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
|
|
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.
- Generate the command list (
nngxGenCmdlist
function). - Bind the command list object (
nngxBindCmdlist
function). - 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.
- Get the necessary region size for the Command Request queue (
nngxGetCommandRequestSizeRaw
function). - Allocate the save data region (3D command buffer, command request buffer).
- Generate the command list object (
nngxCmdlistStorageRaw
function).
The function used to allocate the command list is as follows.
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.
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.
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
|
|
|
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.