You are here:

Save a Capture with Source Code Generation

Sometimes starting up an application and getting to a specific spot can take a very long time. Instead, you can save the capture to disk, and reload it later for a much faster startup. Using this method, the capture can also be shared among the development team, to point out any potential errors or performance issues.

Saving the current captured frame for later debugging or profiling:

Begin debugging your app and launch the Frame Debugger.
Click the Serialize Capture to C/C++ button on the HUD toolbar.
Select the folder where you wish to save the capture.
Choose a directory that has no spaces as the NDK cannot compile from directories with spaces.
The source code will be generated from the capture and when you see the message indicating completion, the captured frame will be saved on disk.

If your application uses binary programs, the resulting serialized capture is only compatible with the same target device and OS version. The driver can embed information into the binary that locks it to the current system. To work around this, delete any shader cache before running the tool if you want to serialize the capture.

Using a saved capture

To use the saved capture, open the generated project from the directory you chose using Visual Studio. Saving a capture will generate the source code, as well as project and solution files for all supported Visual Studio versions.

Versioned Visual Studio projects may be opened with Visual Studio versions that do not match the project version, but note that you may be asked to upgrade your project when opening it for the first time.

Generated source files:

.sln and .vcxproj files — These are Microsoft Visual Studio solution and project files for building the resulting executable.
Main.cpp — This is where all of the initialization code is called, resources are created, and each frame portion is called in a message loop.
ResourcesNN.cpp and Resources.h — Depending on the number of resources to be created, there will be multiple ResourcesNN.cpp files, each with a CreateResourcesNN call in them, that will construct all of the resources (contexts, textures, shaders, etc.) that are used in the scene. These are called in Main.cpp before replaying the frame in the message loop.
FrameSetupMM.cpp — These files contain all of the state setting calls to set the API state to the proper values for the beginning of the frame, including what buffers are bound, which shaders are enabled, etc.
FrameResetMM.cpp or ThreadNNFrameResetMM.cpp — These files contain the code required to reset API state back to its capture begin values after the frame has been run. In multi-threaded serializations each thread receives its own file.
PerfMarkersSetup.cpp and PerfMarkersReset.cpp — These files contain the code to setup perf markers active before the capture and terminate those still active at the end of the frame.
WinResourcesSetup.cpp and WinResourcesReset.cpp — These files contain the code to setup and reset any resources used by the windowing system.

FrameNPartMM.cpp — In single-threaded OpenGL captures, these files contain the frame replay functions, each named RunFrameNPartMM(), to replay the frame. It is split into multiple files so generated code is easier to work with. These functions are called sequentially in the message loop in Main.cpp.

In this scenario, both N and MM are placeholders for numbers in the multiple files generated. FrameN will typically be Frame0 since only a single frame is captured, and PartMM will typically be in the 00-05 range, depending on how many API calls are in the frame.

ThreadLLFrameNPartMM.cpp — In multi-threaded OpenGL captures, these files contain the frame replay functions, each named ThreadLLRunFrameNPartMM(), to replay the frame. The functions correspond to the work done by each thread during the frame. These functions are called by their respective threads and synchronized to replay the saved events in the same order as captured.
ReadOnlyDatabase.cpp and ReadOnlyDatabase.h — This is a helper class to access resource data that is stored in the data.bin file. It is accessed throughout the code via the GetResource() call.
Helpers.cpp and Helpers.h — These functions are used throughout the replayer for various conversions and access to the ReadOnlyDatabase.
Threading.cpp and Threading.h — These files contain helper functions and classes to manage threads used in the project.
ReplayProcedures.cpp and ReplayProcedures.h — These files contain the implementations of the methods used by Main.cpp to create and setup resources and run the captured frame.

Build and run the project.

Changing a Resource

If you want to change a resource (for example, to swap in a different texture), you can change the parameters for the construction by looking within the ResourcesNN.cpp files for the texture in question. Textures can be matched by size and/or format. Once you find the variable for the texture, look for that name in the FrameSetup.cpp file. This will contain source lines to lock the texture, call GetResource() to retrieve the data from the ReadOnlyDatabase, and then call memcpy(…) to load the data into the texture. You can substitute the call to the ReadOnlyDatabase with a call to read from a file of choice to load the alternate texture.

Changing a Draw Call

If you want to change the state for a given draw call, you can locate the draw call by replaying the capture within Tegra Graphics Debugger and scrubbing to find the call you want to examine. Search in the FrameNPartMM.cpp files for Draw NN, where NN is the 0-based draw call index that Tegra Graphics Debugger displayed on the scrubber. Doing this will bring you to the source line for that draw call, and from here, you can add any state changes before that call. Alternatively, you can also disable that specific call by commenting out the source call containing the draw call.

Parameters

repeatCount — Variable set at the top of Main.cpp, under the heading Replay Data. The value of this variable indicates the number of times to repeat the entire capture; the default setting is -1, which keeps the capture running on an infinite loop.
noReset — Variable set at the top of Main.cpp, under the heading Replay Data. This setting controls whether context state and all resources are reset to their beginning of frame value. When this variable is set to true, all frame restoration operations will be skipped, avoiding the performance cost associated with them. Note that this may introduce rendering errors if the rendered frame has a data dependency on the results of a previous frame.