OpenUsd.Runtime.Imaging.osx-arm64 0.4.0-alpha

OpenUsd

A high-performance, NativeAOT-compatible .NET data and rendering stack for OpenUSD, plus an Avalonia desktop viewer.

OpenUsd keeps OpenUSD C++ types behind a versioned, project-owned C ABI. Its managed surface covers stages, layers, prims, typed values, composition, focused schema facades, ordered live authoring, and renderer-neutral state. Hydra/Storm is the primary renderer; Hydra-fed Silk.NET backends provide D3D12, Vulkan, and Metal alternatives without putting per-element P/Invoke on scene or render hot paths.

Current distribution: public source repository and published packages, version 0.4.0-alpha, with pre-1.0 APIs. Managed and runtime packages are on NuGet.org and on GitHub Packages; package identities and public APIs may still change before 1.0.

dotnet add package OpenUsd --version 0.4.0-alpha
dotnet add package OpenUsd.Runtime.Core.win-x64 --version 0.4.0-alpha

Keep every OpenUsd* package at the same version, and add the matching OpenUsd.Runtime.Imaging.<rid> package for rendering. See Packaging.

✨ Highlights

• Idiomatic data API for stage and layer lifecycle, prims, attributes, relationships, variants, metadata, composition arcs, world bounds, and bulk values.
• Focused schemas for UsdGeom, UsdShade, UsdLux, and UsdSkel.
• Owned native boundary with opaque handles, bulk buffers, explicit lifetime rules, and no exposure of OpenUSD C++ layouts.
• Ordered shared-stage access through UsdStageScheduler, change notifications, and retained render sources for live editing.
• Renderer-neutral viewer state for camera, time, selection, picking, diagnostics, and failover.
• A managed Hydra renderer over D3D12, Vulkan, and Metal covering materials, textures, UsdLux lighting, point instancing, curves, points, draw modes, clip planes, UsdSkel skinning, and time-varying values.
• Measured parity with Storm on 19 hard-gated curated scenes at exactly 1.000000 adjusted IoU, with every uncovered feature named rather than implied.
• Cross-platform packaging gates for win-x64, linux-x64, and osx-arm64.
• NativeAOT and trimming analyzers across production libraries targeting .NET 8, 9, and 10.

🚀 Start from source

The repository pins .NET SDK 10.0.301. The managed baseline does not build OpenUSD itself:

git clone https://github.com/marcschier/openusd-dotnet.git
cd openusd-dotnet
dotnet --version
dotnet build OpenUsd.slnx -c Release
./eng/run-managed-tests.ps1 -Configuration Release
dotnet build samples/OpenUsd.HelloStage/OpenUsd.HelloStage.csproj -c Release -f net10.0

dotnet --version must print 10.0.301. If it is unavailable, use ./eng/install-dotnet.ps1 on Windows or bash ./eng/install-dotnet.sh on macOS/Linux. Managed projects compile without OpenUSD; executing OpenUsd.HelloStage requires the matching Core runtime.

For the native-backed API, inspect and build the locked runtime for the current RID:

./eng/build-native.ps1 -Rid win-x64 -PlanOnly
./eng/fetch-native.ps1 -Rid win-x64
./eng/build-native.ps1 -Rid win-x64
./eng/run-native-probe.ps1 -Rid win-x64

The public API used by the native probe and package consumers starts like this:

using OpenUsd;

using UsdStage stage = UsdStage.Create("scene.usda");
UsdPrim world = stage.DefinePrim("/World", "Xform");
world.SetString("custom:greeting", "hello");
stage.SetDefaultPrim("/World");
stage.Save();

See Getting started for platform prerequisites, native staging, the viewer, and NativeAOT commands. The runnable source setup is in the HelloStage guide, and the complete API walkthrough is in Data API.

🏗️ Architecture

flowchart LR
    App[Application or sample] --> Data[OpenUsd data API]
    Viewer[Avalonia Viewer] --> Data
    Viewer --> Neutral[OpenUsd.Rendering]
    Data --> Interop[OpenUsd.Interop]
    Interop --> CABI[Project-owned C ABI]
    CABI --> USD[OpenUSD C++]
    Neutral --> Storm[Hydra / Storm]
    Neutral --> Silk[Hydra / hdSilk pages]
    Storm --> Interop
    Silk --> Interop
    Silk --> RHI[D3D12 / Vulkan / Metal]

The data facade, renderer-neutral contracts, Hydra translation, and concrete RHIs remain separate. Large scene and render payloads cross owned bulk boundaries rather than one native call per element. See Architecture and Rendering.

📦 Package matrix

All package IDs below are published to NuGet.org and GitHub Packages, and are buildable from this repository.

Runtime projects use net8.0 as their NuGet asset-carrier TFM; the managed libraries they accompany target .NET 8, 9, and 10. Package layout and clean-consumer gates are documented in Packaging.

🎯 Target frameworks

🖥️ RID and viewer matrix

The package prefix in the runtime columns is OpenUsd.Runtime..

Curated parity runs on Windows against D3D12 WARP and Vulkan SwiftShader. Two Vulkan composition proofs are narrowed on hosted runners and need GPU-equipped self-hosted hardware: hosted Windows has no system Vulkan ICD and SwiftShader cannot export to a D3D11 shared handle, and the hosted Linux compositor reports no supported image handles.

See Support matrix for the distinction between implemented source, workflow-defined gates, and hosted execution evidence.

🎨 Renderer and backend matrix

The renderer-neutral capability declarations are:

An em dash means the capability is not advertised by the current renderer-neutral descriptor, not that the underlying graphics API can never provide it. The Shadows row states that the Storm descriptor advertises the capability; it does not mean shadows are rendered in every configuration, and the offscreen parity harness is measured not to produce them at all.

🧩 Feature matrix

hdSilk rendering features

These are the managed renderer's Hydra-fed features. "Parity-gated" means a curated scene is compared against Storm and must match exactly; see the section below for what that does and does not claim.

🔬 What "parity with Storm" means here

Storm is the reference renderer. A parity harness renders the same USD stage through Storm and through hdSilk and compares coverage and colour, and the claim this project makes is deliberately narrow:

• 22 curated scenes are registered; 19 are hard gates at exactly 1.000000 adjusted IoU against D3D12 WARP and Vulkan SwiftShader. A gate is only accepted with a perturbation margin of at least 0.18, so a scene that would score well by symmetry alone cannot qualify.
• Metal is not covered by the curated set. It is validated by a single macOS native pipeline probe. Do not read three-backend scene parity into the backend table above.
• Three scenes are measured and deliberately left ungated, because Storm in the offscreen harness renders the subdivision control cage, renders MaterialX black, and does not cast shadows at all. Those are recorded limits, not hidden failures.
• Several shipped features are reachable but not proven by a gate — non-diffuse texture slots, most UsdPreviewSurface inputs, metallic shading, and animated materials among them.

Where it runs matters as much as the number. The parity harness is driven by the render workflow, not by ordinary CI, so a green ci badge does not mean parity ran. Today:

Hosted Windows has no usable Vulkan ICD, which is the render-unblock-vulkan limitation described in Testing and needs a GPU-equipped self-hosted runner. Until then the full Windows matrix is reproduced on a developer machine, and hosted Linux is the automated gate.

Support matrix carries the full feature-to-scene table naming every uncovered feature, and Testing records every rejected hypothesis and measured divergence.

🗺️ Repository map

🧪 Samples

See the samples overview for prerequisites, expected output, and package versus source consumption.

📚 Documentation

🛠️ Build, test, and NativeAOT

dotnet restore OpenUsd.slnx
dotnet build OpenUsd.slnx -c Release --no-restore
./eng/run-managed-tests.ps1 -Configuration Release
dotnet format OpenUsd.slnx --verify-no-changes --no-restore
./eng/check-line-length.ps1
./eng/test-documentation.ps1
./eng/run-performance.ps1

Managed tests use TUnit on Microsoft.Testing.Platform. Use eng/run-managed-tests.ps1, not a bare dotnet test, for the repository's verified execution path. Targeted commands are in Testing.

The same NativeAOT compile smoke used by CI can be reproduced with the platform AOT toolchain. On Windows, run it from an x64 Visual Studio developer shell:

dotnet publish samples/OpenUsd.HelloStage/OpenUsd.HelloStage.csproj -c Release -f net10.0 -r win-x64 -p:PublishAot=true

Native-backed execution additionally requires the matching locked runtime and shim. Use eng/run-native-probe.ps1 after the native build rather than manually assembling loader paths.

🚧 Non-goals

• A stable public package or API compatibility promise before 1.0.
• Direct bindings to the OpenUSD C++ ABI or exposure of C++ object layouts.
• Per-prim, per-vertex, or per-element P/Invoke on scene and render hot paths.
• Complete generated coverage of every OpenUSD schema and optional component.
• A replacement for usdview, a full DCC, or a general-purpose game engine.
• Runtime packages for RIDs outside win-x64, linux-x64, and osx-arm64 today.
• Bundling Python, usdview, tutorials, examples, Embree, Alembic, Draco, OpenVDB, or RenderMan in the locked native profile.

🔒 Security

Treat USD files, asset paths, plugin metadata, and native package contents as untrusted input. Report vulnerabilities privately through GitHub Security Advisories; do not open a public issue. See Security.

🤝 Contributing

Keep changes focused, analyzer-clean, deterministic, and separated across data, renderer-neutral, Hydra translation, and concrete backend layers. Native or public API changes require corresponding tests and documentation. See Contributing.

📄 License

MIT. OpenUSD and bundled third-party native dependencies retain their own licenses; see NOTICE.

Status

OpenUsd is a substantial public 0.4.0-alpha baseline, published to NuGet.org, but not a stable release. Data, rendering, Viewer, package, NativeAOT, shader, parity, and performance gates exist, and this README states what they do and do not prove. Public API and package identities may change before 1.0. Workflow badges above are the authoritative status for the default branch.

Before 1.0 the remaining work is code signing and notarization credentials for signed Viewer distributions, GPU-equipped self-hosted runners for the two Vulkan composition gates, and closing the measured divergences recorded in Testing.