6. Packet Recording

Using the packet recording feature, you can record a group of command packets and then replay them later. This feature is useful when the majority of an image requires repeated rendering (excluding camera, light, and other settings). This is the same as rendering a scene twice stereoscopically.

The following functions control the packet recording feature.

Code 6-1. Functions Used to Control the Packet Recording Feature
nn::gd::System::StartRecordingPackets(
        u32* forceDirtyModuleFlag,
        nn::gd::RecordingPacketUsage usage = RECORD_COMMAND_LIST_COPY);
nn::gd::System::StopRecordingPackets(nn::gd::RecordedPacketId** packetId);
nn::gd::System::ReplayPackets(nn::gd::RecordedPacketId* packetId,
        u32* forceDirtyModuleFlag);
nn::gd::System::ReleasePackets(nn::gd::RecordedPacketId* packetId); 

You can record both 3D commands output to the 3D command buffer and command requests (see 7.1. Internal Use of nngx Functions) output to the request buffer.

You can use the nn::gd::System::ReleasePackets() function to release command packets that you no longer need.

Effects of the Internal State on Outputting 3D Commands

Depending on the internal state of the GD library, functions do not necessarily output 3D commands. This may cause behavior to deviate from what was expected when the command packets were recorded. Similarly, the state of the GPU may be inconsistent with the internal state of the GD library when the command packets are replayed. To work around this problem, the nn::gd::System::StartRecordingPackets() and nn::gd::System::ReplayRecordingPackets() functions each accept flags as arguments, allowing you to indicate which modules to mark as dirty before the function is executed.

The safest course of action is to specify the MODULE_ALL flag and mark all modules as dirty. This causes all 3D commands to be output and definitely prevents erroneous states. When you use this feature, if you know which module's state will be recorded and replayed and whether that particular state will cause a conflict, you can improve performance by specifying only the minimum number of necessary modules as dirty.

Editing Command Packets

You can edit recorded command packets before you replay them. To calculate the 3D command buffer position to update, combine two values: The first value is the offset for output into the 3D command buffer that is returned by the nn::gd::System::GetCommandBufferOffset() function while packets are being recorded (between calls to the nn::gd::System::StartRecordingPackets and nn::gd::System::StopRecordingPackets() functions). The second value is the base address of the 3D command buffer that is returned by the nn::gd::System::GetCommandBufferBaseAddress() function after you have finished recording packets. However, to overwrite 3D commands, you can only use immediate functions, which output 3D commands to the 3D command buffer.

Using the usage Parameter to Issue an Instruction to Copy the 3D Command Buffer

To create a copy of the 3D command buffer, specify Record_Command_List_Copy in usage under the nn::gd::System::StartRecordingPackets() function as was done before adding the argument. The 3D command in the command packet that was recorded can be overwritten for this purpose.

On the other hand, specifying Record_Command_List_No_Copy in usage means that a 3D command buffer copy will not be created. This shortens processing time, but the 3D command cannot be overwritten. In addition, clearing the 3D command buffer acting as the source of the copy renders the command packet unexecutable.

When packet recording is started with RECORD_3D_COMMAND_BUFFER_FOR_JUMP specified in usage, the nn::gd::System::ReplyPackets() function creates a copy of the 3D command buffer, and it is executed with a jump by inserting a jump command using the nngxAddSubroutineCommand() function.


CONFIDENTIAL