gx Raw

This is the directly specified command list version of the DMPGL system API.

The gx Raw API is a group of functions that enable the command list-related controls of the gx API to be processed in the form of directly specified command list objects.

With the existing gx API, command list processing adheres to OpenGL style rules: you specify the IDs for objects allocated in the library and use them in a bound form. The code for the use of command lists looks something like this:

// For saving the command list ID
GLuint s_MyCmdListId;

{
    // Prepare a new command list.
    nngxGenCmdlists(1, &s_MyCmdListId);
    
    nngxBindCmdlist(s_MyCmdListId);
    nngxCmdlistStorage(MY_CMDLIST_BUFFER_SIZE, MY_CMDLIST_NUM_REQUESTS);
    nngxClearCmdlist();
}

{
    // Run the command list.
    nngxBindCmdlist(s_MyCmdListId);
    nngxRunCmdlist();
}

{
    // Destroy the command list.
    nngxDeleteCmdlists(1, &s_MyCmdListId);
}
            

In contrast, with this gx Raw function group, the definition of the nngxCommandList structure that maintains command list management information is provided, and the various functions are called with a pointer to an object of this type given as the first argument. In this case, the code for performing this same kind of process looks something like this:

// Allocate command list object.
nngxCommandList s_MyCmdListObj;

{
    // Prepare a new command list.
    GLsizei reqSize;
    GLvoid* pCmdBuffer;
    GLvoid* pReqBuffer;
    
    // The application allocates the required buffer region.
    reqSize = nngxGetCommandRequestSizeRaw(MY_CMDLIST_NUM_REQUESTS);
    pCmdBuffer = MyAlloc(MY_CMDLIST_BUFFER_SIZE);
    pReqBuffer = MyAlloc(reqSize);
    
    nngxCmdlistStorageRaw(&s_MyCmdListObj, pCmdBuffer, MY_CMDLIST_BUFFER_SIZE, pReqBuffer, reqSize);
    nngxClearCmdlistRaw(&s_MyCmdListObj);
}

{
    // Run the command list.
    nngxRunCmdlistRaw(&s_MyCmdListObj);
}

// No need to explicitly destroy the command list.
            

Although this requires that the application take complete responsibility for managing the allocating and deallocating of objects and buffer regions, it gives you more freedom to build a framework that is not dependent on the state inside the library.

The provided APIs are named like the existing functions but with "Raw" appended to the end of the name, and with the added parameter of the pointer to nngxCommandList. As long as there are no special descriptions, you can read details about operations and errors by reading the references for the existing functions. (Wherever the reference says "the current command list," replace it with "the command list specified by nngxCommandList."))

Note:

• Because the gl and gd APIs operate on the presumption that the command list is bound inside the library, you cannot use those functions in combination with the gx Raw API. It is assumed the gx Raw API will be used mainly in combination with the gr API.
• For the sake of internal implementation, you cannot use copies of nngxCommandList objects.
• Behavior is not guaranteed if you use normal gx command list processing functions in combination with gx Raw functions. However, the following functions are exceptions in that they can be used at the same time as the gx Raw functions.
• nngxWaitCmdlistDone
• nngxSetTimeout
• nngxGetIsRunning

2012/06/14

Added a list of the gx command list processing functions that can be used at the same time as the gx Raw functions.

2012/05/09

Initial version.