Crate zenfg_snapshot

Expand description

§zenfg-snapshot

zenfg-snapshot provides portable, wgpu-independent Snapshot 1.2 wire types, JSON codec, validation, and legacy migration. It is the Rust counterpart of the normative @zenfg/snapshot package and depends only on Serde, serde_json, and thiserror.

Snapshot documents contain graph structure and diagnostics, not GPU commands or resource contents, and cannot replay a frame. Wire-format versioning is independent from this crate’s beta API version.

Snapshot 1.1 inputs are validated before migration to 1.2; their CPU timing is marked not-collected. Writers and standalone validators accept canonical 1.2 only. Existing Legacy provenance and extensions are preserved.

§Installation

cargo add zenfg-snapshot@=0.1.0

§Quick start

Use a Cargo application and add serde_json for the JSON value conversions in this example. Put the code in fn main() -> Result<(), Box<dyn std::error::Error>> and finish with Ok(()). Run cargo run; all assertions pass without a GPU. Lines prefixed with # are rustdoc test scaffolding, not lines to paste.

Parse untrusted JSON text to validate and normalize a canonical Snapshot:

use zenfg_snapshot::{
    decode_frame_graph_snapshot, parse_frame_graph_snapshot, to_json_pretty,
    validate_frame_graph_snapshot, validate_typed_frame_graph_snapshot,
};

let json_text = r#"{
  "format": "zenfg.frame-graph-snapshot",
  "version": { "major": 1, "minor": 1 },
  "producer": { "name": "example" },
  "capture": { "frameIndex": 0 },
  "graph": {
    "groups": [], "nodes": [], "resources": [], "textureViews": [],
    "accesses": [], "dependencies": [], "roots": [], "segments": []
  },
  "memory": {
    "allocationReport": { "status": "available", "allocations": [] },
    "poolReport": { "status": "unavailable", "reason": "not captured" }
  },
  "timings": {
    "gpu": { "status": "unavailable", "reason": "not captured" }
  },
  "diagnostics": [],
  "extensions": {}
}"#;

let decoded = parse_frame_graph_snapshot(json_text)?;
let value = serde_json::to_value(&decoded.snapshot)?;
assert!(validate_frame_graph_snapshot(&value).is_empty());

let decoded_from_value = decode_frame_graph_snapshot(value)?;
assert_eq!(decoded_from_value.snapshot, decoded.snapshot);
assert!(validate_typed_frame_graph_snapshot(&decoded.snapshot).is_ok());

let canonical_json = to_json_pretty(&decoded.snapshot)?;
assert!(canonical_json.contains("zenfg.frame-graph-snapshot"));

Successful decoding returns a canonical Snapshot 1.2 value and explicit migration provenance when historical input was upgraded. Unknown formats and versions are rejected.

§Common tasks

Task	Public API
Parse untrusted JSON text	`parse_frame_graph_snapshot()`
Decode an already-parsed `serde_json::Value`	`decode_frame_graph_snapshot()`
Validate canonical JSON-shaped data	`validate_frame_graph_snapshot()`
Validate a typed in-memory Snapshot	`validate_typed_frame_graph_snapshot()`
Serialize validated typed data	`to_json()`, `to_json_pretty()`
Handle decode failures	`SnapshotDecodeError`
Inspect structured issues	`SnapshotIssue`, `SnapshotIssueSeverity`
Read format, version, and depth limits	`FRAME_GRAPH_SNAPSHOT_FORMAT`, `FRAME_GRAPH_SNAPSHOT_VERSION`, `FRAME_GRAPH_SNAPSHOT_MAX_EXTENSION_DEPTH`

The crate exports FrameGraphSnapshotV1 and all wire types with Serialize and Deserialize. Exact fields and error variants are documented on docs.rs.

§Consumer and producer boundaries

Use parse or decode for untrusted input. Canonical Snapshot 1.2, Legacy V0, and Legacy Candidate V1 are accepted; supported historical data is migrated explicitly.
Use validate_typed_frame_graph_snapshot() before returning a typed producer value. to_json() and to_json_pretty() perform the same checks before writing wire output.
Validation returns structured issues with stable codes, JSON Pointer paths, and messages.
Unknown versions are rejected until an explicit migration is implemented and tested. Missing legacy facts remain absent rather than being invented.
The crate has no wgpu dependency. Runtime-to-Snapshot projection belongs to zenfg behind its snapshot feature.

The normative Schema, specification, fixtures, and conformance manifest are published by @zenfg/snapshot. See the Snapshot 1.2 specification for the complete structural and cross-field contract.

§Common mistakes

Symptom	Fix
Legacy input fails typed or canonical validation	Decode it first so the explicit migration runs.
Serialization rejects a typed value	Validate it and inspect the structured issue before writing JSON.
An unknown version looks structurally similar	Reject it until a reader implements a tested migration.
A producer expects validation to add missing facts	Populate required facts explicitly; validators do not invent diagnostics.
A Snapshot is expected to replay GPU work	Use an application-owned command/resource capture mechanism instead.

§Complete example

The crate ships a compile-checked examples/basic.rs workflow. Cross-language fixtures and producer projections live in the normative @zenfg/snapshot conformance corpus.

§Further reading

§Documentation and versions

This README describes zenfg-snapshot 0.1.0. Registry badges show the current published channel, not your installed version.

Exact installed APIs: read the included src/, or run cargo doc --open in your consuming project.
Online guide (development branch). The site may describe changes newer than this package.
Rust API for this version.
Source and documentation for this release.
Shared concepts for this release and compatibility.
Plain Markdown documentation index (development branch).
Complete Cargo recipes are included in examples/.

Structs§

FrameGraphSnapshotV1: Canonical, strongly typed ZenFG FrameGraph Snapshot 1.2 document.
SnapshotAccess: One declared node-to-resource access and its normalized affected region.
SnapshotAllocation: One physical allocation compatibility class and estimated size.
SnapshotBufferRange: Byte range for a captured buffer access; absent size means the remaining buffer.
SnapshotCapture: Frame identity, capture time, and optional migration provenance.
SnapshotCpuNodeTiming: CPU duration in microseconds associated with one retained node of any kind.
SnapshotDecodeError: Failure to parse, recognize, migrate, validate, or deserialize a Snapshot.
SnapshotDecodeResult: Canonical snapshot plus provenance and non-fatal migration diagnostics.
SnapshotDependency: One value-carrying or ordering edge between captured graph nodes.
SnapshotDiagnostic: Structured producer diagnostic with optional graph entity references.
SnapshotGpuNodeTiming: GPU duration, in microseconds, associated with one retained node.
SnapshotGraph: Relational graph tables that make up the portable captured frame.
SnapshotGroup: One recording debug group and its optional parent relationship.
SnapshotIssue: One structured Snapshot validation or migration diagnostic.
SnapshotLifetime: Inclusive retained execution-order interval for one logical resource.
SnapshotMemory: Allocation-plan and cross-frame resource-pool facts for the capture.
SnapshotMigration: Provenance and unavailable facts recorded when converting a historical format.
SnapshotNode: One recorded graph node with its original metadata and compile outcome.
SnapshotProducer: Identity and optional runtime metadata of the library that produced a capture.
SnapshotResource: One logical resource with descriptor, usage, lifetime, and allocation facts.
SnapshotResourceRoot: A final resource selection. Missing facts require Legacy provenance.
SnapshotRootResolution: Compiler-provided final content sources.
SnapshotRuntime: Optional graphics implementation, API, and native backend facts.
SnapshotSegment: One ordered frame-graph or external-submission execution segment.
SnapshotTextureRegion: Normalized mip, layer/depth-slice, and aspect region for a texture access.
SnapshotTextureSize: Three-dimensional texture extent using JSON-safe integer fields.
SnapshotTextureView: Fully normalized texture-view descriptor referenced by captured accesses.
SnapshotTimings: Optional timing families captured alongside the graph.
SnapshotVersion: Major/minor version carried by every Snapshot document.

Enums§

SnapshotAccessKind: Portable pipeline or copy role of one resource access.
SnapshotAccessMode: Whether a captured access reads or writes its resource.
SnapshotAllocationReport: Available physical allocation table or an explicit unavailability reason.
SnapshotCpuTimings: CPU synchronous elapsed timings, independent of GPU completion.
SnapshotDecodeSource: Input wire shape recognized by a successful decode.
SnapshotDependencyKind: Whether a dependency carries a logical value or only constrains ordering.
SnapshotDiagnosticSeverity: Portable severity of a captured producer diagnostic.
SnapshotGpuTimings: Available GPU pass timings or an explicit unavailability reason.
SnapshotInitialContents: Whether a resource range is readable at the start of the captured frame.
SnapshotIssueSeverity: Severity assigned to a validation or migration issue.
SnapshotJsonError: Failure to validate or serialize an in-memory Snapshot.
SnapshotMigrationSourceFormat: Historical wire format from which a canonical V1 document was migrated.
SnapshotNodeCompileState: Whether a recorded node was retained, and its order or culling reason.
SnapshotNodeKind: Portable kind of work represented by a captured graph node.
SnapshotPoolReport: Available resource-pool counters or an explicit unavailability reason.
SnapshotResourceDescriptor: Portable physical descriptor for a captured texture or buffer.
SnapshotResourceKind: Portable texture-or-buffer discriminator.
SnapshotResourceOrigin: Ownership and allocation origin of a captured logical resource.
SnapshotResourceRange: Resolved non-empty logical output range.
SnapshotRoot: One observable resource/node root and its retention reason.
SnapshotRootReason: Portable reason that a node or resource remains observable after compilation.
SnapshotSegmentKind: Ownership of command submission for one execution segment.
SnapshotUnavailableFact: Canonical graph fact that a historical source format could not represent.
SnapshotUsageFlag: One normalized WebGPU usage flag in protocol-defined ordering.
SnapshotWriteContents: Whether a write overwrites or preserves the prior logical value.

Constants§

FRAME_GRAPH_SNAPSHOT_FORMAT: Canonical format discriminator for ZenFG Snapshot 1.2 documents.
FRAME_GRAPH_SNAPSHOT_MAX_EXTENSION_DEPTH: Maximum number of nested JSON container levels allowed in one extension value.
FRAME_GRAPH_SNAPSHOT_VERSION: Snapshot wire version emitted by this crate.
LEGACY_CANDIDATE_FRAME_GRAPH_SNAPSHOT_FORMAT: Historical pre-release format discriminator accepted for migration.

Functions§

decode_frame_graph_snapshot: Migrates when necessary, validates, and deserializes an arbitrary JSON value.
parse_frame_graph_snapshot: Parses, migrates when necessary, and validates a Snapshot JSON document.
to_json: Validates and serializes a canonical Snapshot as compact JSON.
to_json_pretty: Validates and serializes a canonical Snapshot as human-readable JSON.
validate_frame_graph_snapshot: Validates an arbitrary JSON value against Snapshot 1.2.
validate_typed_frame_graph_snapshot: Validates a typed Snapshot without producing JSON text.