apitrace-rs

This is a library and binary crate for working with apitrace files in Rust.

Garbage collection

The apitrace-rs gc command can perform garbage collection of D3D8/D3D9 buffer, textute, and some state updates after frame trimming (removing draw calls and swaps before some frame of interest) has been done. The intent is to extend GC support to other APIs, as well.

Design goals of GC:

• Absolute correctness
  • No optimistic removing of calls that are probably dead.
• Non-disruptive by default
  • Rendering paths through the driver should be the same after GC as before.
  • No removing state changes, other than what we should need to do to make texture/buffer contents go away.

lib.rs:

Apitrace binary trace file reader/writer

This module implements parsing for apitrace trace files according to the FORMAT.markdown specification from the apitrace project.

File Format Overview (per FORMAT.markdown)

Compression

Trace files use custom compression (Snappy by default):

• Snappy: 'a' 't' header + chunks (compressed_length:uint32 + compressed_data)
• Also supports gzip and Brotli

Structure (after decompression)

trace = header event*
header = version_no semantic_version_no properties  // version >= 6
       | version_no                                 // version < 6
event = enter_call | leave_call

Version History

• Version 0: Initial implementation
• Version 1: OpenGL user arrays as blobs
• Version 2: malloc/free memory calls
• Version 3: Enum signatures with full name/value pairs
• Version 4: Call enter events include thread number
• Version 5: Call backtrace support
• Version 6: Unicode strings, semantic version, properties, fake flag

Key Concepts

• Variable-length unsigned integers (uint) for space efficiency
• Signature-based type system: First occurrence includes definition, later uses reference by ID
• Applies to: call signatures, enum signatures, bitmask signatures, struct signatures, frame signatures

Current Implementation Status

• ✓ Basic parsing of version 5-6 traces
• ✓ Call signatures and interleaved enter/leave events
• ✓ Call details with proper terminator handling
• ✓ Backtrace frame parsing with detail terminators
• ✓ Enum signature parsing (sint values, both version >= 3 and < 3)
• ✓ Wide string parsing (uint* not bytes)
• ✓ Bitmask signature parsing (uint values)
• ✓ Struct signature parsing
• ✓ Value skipping for extracting call names

Key Implementation Details

• Enum, bitmask, and struct signatures share the same ID space in the file format, but must be tracked in separate namespaces to avoid signature type collisions
• Backtrace frame signatures are cached to avoid re-reading frame details

Known Limitations

• Version < 5 header support (version 5+ traces work fully)
• File offset tracking for signature reuse (affects seeking/rewinding scenarios)
• Some complex edge cases in deeply nested structures