Materialx Protobuf API 1.39.4
Serialization API to convert between MaterialX and Google Protobuf formats.
Loading...
Searching...
No Matches
Brief Blurb

Google Protocol Buffers offer a compact, deterministic, and version-safe way to represent shading networks. Its .proto schemas generate strong, multi-language APIs (C++, Python, JS, etc.) while supporting forward/backward compatibility via numeric field IDs, optional, oneof, and reserved fields. Deterministic binary output enables caching, network distribution, and equality checks, and messages are thread-safe for concurrent reads and parallel I/O.

Caveats: unlike USDShade, it does not handle scene composition or variants, and unlike glTF, it lacks binary packaging or runtime constraints — pipeline and runtime logic must be handled separately.

Summary Blurb

  • Structured schema:
    .proto files define a pure data schema that generates strongly typed classes across C++, Python, JS, and more — ensuring consistent APIs.
  • Version-safe evolution:
    Numeric field IDs with optional, reserved, and oneof allow forward/backward compatibility at the data model, API, and ABI levels.
  • Compact, deterministic binary:
    Smaller and faster than XML/JSON, deterministic output enables caching, network distribution, and binary equality checks.
  • Multi-language APIs:
    Single source .proto generates bindings automatically, removing manual interface code.
  • Thread-safe, parallel I/O:
    Safe for concurrent reads and parallel serialization/deserialization.
  • Restrictions:
    • No scene composition or variant logic (unlike USDShade).
    • No binary packaging or runtime constraints (unlike glTF).
    • Higher-level pipeline, runtime, and delivery logic must be handled separately.

Detailed Blurb

Protobuf offers some interesting features as a serialization format.

  • Structured data schema:
    • Protobuf defines a pure data schema (.proto) that can be compiled into strongly typed classes in different languages for API consistency.
    • Languages supported include: C++, Python, JavaScript, with extensions for languages like: Rust, Go, etc.
  • Forward and backward compatibility:
    • Schema fields have unique numeric IDs along with optional, reserved, and oneof usage rules – allowing fields to be added or deprecated without breaking older versions.
    • This ensures compatibility at the data model, API, and ABI levels across versions and to be able to evolve as needed.
  • Binary representation:
    • Protobuf encodes data compactly and deterministically
      • The footprint is smaller and faster than XML or JSON by avoiding parsing and hierarchy building.
      • Deterministic output ensures identical binary results for identical shading graphs — ideal for caching and network distribution.
      • As sequencing is preserved this allows for deterministic binary equality checks.
  • Automatic multi-language APIs:
    • The .proto file acts as the single source of truth for generating bindings, removing the need for manual interfaces (e.g., pybind11).
  • Thread-safe, parallelizable I/O:
    • Protobuf messages are thread safe for concurrent reads and can be serialized or deserialized in parallel.
  • Caveats
    • Unlike USDShade it does not provide any scene composition or variant logic as it is not a stage system.
    • Unlike glTF it does not support binary packaging nor runtime constraints.
    • Naturally things like scene composition, runtime binding, pipeline and delivery layers need to be handled at a higher level.