OpenUsd.Rendering.Silk.Vulkan 0.7.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 22 published 0.7.0-alpha packages, with pre-1.0 APIs. This set adds the five Cesium package IDs enumerated below, which were buildable from the tree but withheld from NuGet.org at 0.5.0-alpha. Package identities and public APIs may still change before 1.0.

dotnet add package OpenUsd --version 0.7.0-alpha
dotnet add package OpenUsd.Runtime.Core --version 0.7.0-alpha

OpenUsd.Runtime.Core is the RID-agnostic metapackage for win-x64, linux-x64, and osx-arm64. Rendering consumers add the managed backend and OpenUsd.Runtime.Imaging; the RID-specific package IDs remain available when a project wants explicit asset selection. RID-less builds and publishes copy the current host's assets only on win-x64, linux-x64, and osx-arm64; cross-publishing, CI matrix jobs, and unsupported hosts should set RuntimeIdentifier explicitly. See Packaging.

Release evidence now includes a checked CycloneDX SBOM, nuget.org symbol-package promotion wiring, and render gates that run before releases. The details and caveats live in Packaging, Packaging symbols, and Testing.

✨ 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 22 hard-gated curated scenes whose structured gate requires 1.000000 adjusted IoU for D3D12 WARP and Vulkan SwiftShader; the render workflow also attempts the same curated capture on macOS CGL/Metal and records an explicit capability skip when hosted CGL cannot create the required pixel format.
• 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, Cesium importer, 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 22 package IDs below are buildable from this repository and published to NuGet.org at 0.7.0-alpha. The five Cesium IDs were withheld at 0.5.0-alpha and ship for the first time in this release.

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 lacks the Win32 external-memory and external-semaphore extensions needed to export a Vulkan image to a D3D11 shared handle. Hosted Linux reaches lavapipe, but the compositor reports no supported image handles, so no external Vulkan image can be imported.

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:

• 25 curated scenes are registered; 22 are hard gates with a structured required adjusted IoU of exactly 1.000000 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 wired into the curated set but hosted Storm/Metal parity is not yet observed. The macOS render job runs the same capture only when CGL is available; hosted arm64 currently records a CGL capability skip instead of counting that path as passing.
• 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 still has no usable Vulkan ICD, which is the render-unblock-vulkan limitation described in Testing and needs a GPU-equipped self-hosted runner for Vulkan composition. Hosted WGL and hosted Linux are automated render gates.

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 Python-hosting usdview clone, full DCC, or general-purpose game engine. The Viewer can still pursue usdview-style inspection parity over the C++ USD and Hydra APIs.
• Runtime packages for RIDs outside win-x64, linux-x64, and osx-arm64 today.
• Bundling Python, usdview, tutorials, examples, Embree, or RenderMan in the locked native profile. OpenVDB, Alembic, Draco, and Ptex are now included in that 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.7.0-alpha baseline with 22 packages published to NuGet.org, but it is 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.

The standalone Viewer bundle smoke is now proven on win-x64 and linux-x64. Run 31290108012 records viewer distribution linux-x64 as successful and reports a rendered Storm/OpenGL frame under Xvfb after the Linux X11 error-trap self-deadlock was fixed in 278b1f6. The osx-arm64 result is also established, but still red: the same run reaches GPU composition: ready (808 × 513), falls back from Storm to Metal after the headless CGL pixel-format limit, initializes hdSilk/Metal, and then never reports frame rendered within 120 seconds. The published packages are unaffected — they are gated separately — but the macOS standalone Viewer bundle remains a known failing smoke.