nngxFlush3DCommandPartially Function
NNGX_APICALL void NNGX_APIENTRY nngxFlush3DCommandPartially(
GLsizei buffersize
);
| Name | Description | |
|---|---|---|
| in | buffersize |
Size (in bytes) of the command buffer to execute |
Issues a render command request and flushes the accumulated 3D command buffer. However, 3D commands are only executed for the specified size.
A command to complete the loading of 3D commands is added to the 3D command buffer of the bound command list object, and a render command request is queued to the command requests.
This function is an extended version of the nngxFlush3DCommand function. It provides nearly the same functionality, but differs on the following points.
Use this function when you want the application to freely create command-buffer execution register commands (such as using the GR library), without using the nngxAddJumpCommand or nngxAddSubroutineCommand functions.There is no need to use this function if you implement command-buffer jumps using the nngx API.
The standard nngxFlush3DCommand function attempts to execute the entire contents of the 3D command buffer at the time it is called. However, if the accumulated commands include a command-buffer execution register kick command, then it must kick the GPU using the buffer up to the kick command (the first one stored in the command buffer) as the size, rather than executing all accumulated commands.
If you have added a kick command using the nngxAddJumpCommand or nngxAddSubroutineCommand function, then the driver will adjust the execution size to that of the buffer up to the first kick command. However, if you use the nngxAdd3DCommand function to add data provided by the application as a command, then the driver will not be able to tell whether there is a kick command among these commands. That is why there is a need for the functionality provided by this function to specify the execution size and flush the command buffer.
Set buffersize to the size of the command buffer to execute in bytes. Must be a multiple of 16.
If you accumulate a kick command in the command buffer without using the nngxAddJumpCommand or nngxAddSubroutineCommand functions, for buffersize specify the address of the last command flush until the first kick command (inclusive).
You must set buffersize correctly to the size from the address after the last command flush until the first kick command (inclusive). Setting this to an incorrect value could cause such behavior as commands executing out of their intended sequence, or 3D executions being unable to terminate correctly.
Contents in the 3D command buffer accumulated after the last command flush until this function call are not flushed from the cache. The application is responsible for flushing the cache for the command buffer. Ensure that the application does so. Wait until after calling this function before flushing the entire cache, because this function also generates several commands itself, including commands that raise interrupts. (There is a restriction against calling this function on executing command lists. This is to prevent execution before a cache flush, because the cache must be flushed after calling this function.)
The nngxTransferRenderImage, glClear, glCopyTexImage2D and other functions also flush the command cache. These commands flush the cache using the same method as the nngxFlush3DCommand function. Always use this function to flush the cache.
If you have added a kick command using the nngxAddSubroutineCommand function, then the driver will adjust the execution size to that of the buffer up to the first kick command. For this reason, there is no need for the application to specify the command execution size or to even use this function if the nngxAddSubroutineCommand function has been used. If this function is used to flush a command buffer to which a kick command has been added using the nngxAddSubroutineCommand function, the execution size specified by this function is used rather than the size calculated by the driver.
This function generates the following errors.
GL_ERROR_80A9_DMP | 0 is bound to the current command list. |
|---|---|
GL_ERROR_80AA_DMP | The number of accumulated command requests has reached the maximum number of command requests. |
GL_ERROR_80AB_DMP | The accumulated 3D command buffer exceeds its maximum size when the command to complete the loading of 3D commands is added to the buffer. |
GL_ERROR_80AC_DMP | buffersize is 0 or less, or is not a multiple of 16. |
GL_ERROR_80AD_DMP | The current command list is running. |
CONFIDENTIAL