Monday, March 24, 2014

VoglEditor Adds Trimming Support and Persistent Settings

After receiving a few bug reports about users not being able to load large trace files, it became very clear that VoglEditor needed support for trimming large trace files.

VoglReplay Trim Support

The functionality was already available to users via command line options to voglreplay, but getting there after making a trace file is not an obvious second step.

VoglEditor Trim Support

The command line above can now be executed interactively from within VoglEditor when a trace file is loaded. VoglEditor detects whether the trace contains "too many" frames, and will display the following prompt. Selecting 'No' will continue to load the selected trace; 'Yes' will bring up the Trim Trace dialog.

The dialog will ensure that valid frames are entered for 'trim_frame' and 'trim_len' - validating that the user selects a frame that actually exists in the loaded trace file, and that "too many" frames are not included in the trim file (as this would cause the same dialog to appear when loading the trimmed trace). A new trim filename and path can be directly typed into the dialog, or click the '...' button to open a typical FileSaveDialog.

Clicking 'OK' will confirm the file does not exist and prompt you to overwrite if it does (or cancel to return to the dialog and select a new file name). The trace file will be trimmed in another process, saved to disk, and then the user is prompted to open the newly trimmed trace.

As expected, 'Yes' will load the new trimmed file into VoglEditor; 'No' will cause the originally selected trace file to be loaded.

This same trimming functionality is also now made available on-demand using the new 'Trim Trace' toolbar button.

NOTE: Currently, the 'Trim Trace' behavior is slightly different than the 'Play Trace', in that its input is the original trace file, whereas 'Play Trace' operates on the trace data that is in memory in the editor. This means that any edits made in VoglEditor will be reflected by 'Play Trace', but NOT reflected in 'Trim Trace'.

So... what constitutes as "too many" frames? You decide! (continue below)

VoglEditor Settings File

When implementing the automatic detection of "large traces" to prompt for trimming, it became clear that different users will have different definitions of "large" - in house we often look at multi-gigabyte trace files with hundreds of frames, and other systems may only be able to support a few hundred frames, or perhaps for debugging a particular issue only a handful of frames will be needed. In order to configure the definition of "large traces", a settings file was added.

To keep it easily readable, editable, and consistent with other vogl features, the settings file is stored in JSON. To stick with Linux standards, it is stored in one of the following paths:
In addition to the number of frames at which to consider a trace "large", the initial implementation of the settings file also supports storing the window position and size.

Here are the contents of the default settings file, which will be automatically created when you first open vogleditor, and automatically resaved when the editor is closed.
  "metadata" : {
      "vogleditor_settings_file_format_version" : "0x1"
   "settings" : {
      "trim_large_trace_prompt_size" : 200,
      "window_position_left" : 0,
      "window_position_top" : 0,
      "window_size_width" : 1024,
      "window_size_height" : 768
Manually editing this file should be done while VoglEditor is closed, as any manual changes will be overwritten when the editor is closed.

Thursday, March 20, 2014

VoglEditor Feature List

The past few months have been spent plugging away with Valve on a user interface for a new OpenGL debugging tool called VOGL, which we've recently open sourced on github -

We are developing entirely in Linux, but are also assisting several members of the community who are working on ports to other platforms.

Since I've primarily been working on the user interface, called "VoglEditor", here's an initial feature set as of the time VOGL went public. New features are being added almost daily, so keep an eye out for updates, and feel free to get involved in the project!

Current VoglEditor features:
  • Loading multi-frame trace files
  • Obtaining a GL state snapshot at any API call that is not within a glBegin/glEnd block
  • Save / Load debug sessions
    • Saves a JSON file which links together the base trace file and all collected state snapshots
    • Saves all collected state snapshots to disk
  • Traces can be replayed from within vogleditor
  • CPU-based timeline 
    • Shows API call execution and cost
    • Most expensive call is shown in red and all other calls are scaled between Red -> Green based on relative execution time
  • API call hierarchy
    • Shows frames and API calls hierarchically
    • Clicking on an API call will launch the replayer and collect a state snapshot after that call executes
    • Icons indicate which API calls have a snapshot
    • Supports searching entrypoints and parameters for a supplied string, and navigating to prev / next search match
    • Supports jumping to prev / next draw call
    • Supports jumping to prev / next snapshot   
  • State snapshot panel 
    • Viewing all GL state within a snapshot
    • Automatic diff'ing of state between two snapshots
    • GL object explorers will default to displaying currently bound / active objects
    • Visualization of all existing framebuffers, renderbuffers, and textures
      • All visualizations can be scrolled and zoomed
      • Ability to view RGBA (with customizable alpha blend color), RGB, individual color components, 1-component, and 1/component
      • Support for viewing individual samples
      • Support for Y-flipping the images
    • Viewing of all created shader objects 
    • Viewing of all created program objects and their linked / attached shaders
      • Linked shaders can be edited and saved back into the snapshot so that the changes affect the trace replay