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 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 must all 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.