v26.8.3 | OpenUSD v26.08

[furbytm]

_{SwiftUSD v26.8.3}

^{OpenUSD v26.08, apple/SwiftUsd v8.0.0, HydraKit viewport picking with selection outline overlays on Metal + hotkeys}

Changelog

---

🎧 now playing
listen to heard me right by amtrac.

---

Changes

• HydraKit: adds viewport picking with selection outline overlays on Metal, along with hotkeys for framing (F), select-all (A), deselect-all (Alt+A), panning (Shift+MMB), etc.
  • The color and pixel width of the selection outline overlays can be configured with the following Swift code:

    import HydraKit
    
    // create or open a stage.
    let stage = UsdStage.createInMemory()
    
    // specify a color and pixel width for the selection outline overlay.
    let orange = Pixar.GfVec4f(1.0, 0.6, 0.0, 1.0)
    let pixelWidth = 4
    
    // configure the selection outline overlays when constructing a new render engine instance. 
    let engine = Hydra.RenderEngine(stage: stage, selectionColor: orange, selectionOutlineWidth: pixelWidth)
    
    // selection outline overlays can also be modified at any point during runtime, after render engine construction.
    engine.selectionOutlineColor = orange
    engine.selectionOutlineWidth = pixelWidth

  • For viewport picking with selection outline overlays on Metal, the environment variable SWIFTUSD_BUILD_FROM_SOURCE=1 is required until some changes are upstreamed into apple/SwiftUsd to support it, namely, exposing UsdImagingGL.Engine.GetAovRenderBuffer(_:) to Swift (apple/SwiftUsd issue#40), and patching the HgiMetal graphics pipeline (like this) in a PR to OpenUSD so that it doesn't fail pipeline validation by gating against enabling blending for integer render target formats (e.g. primId/instanceId id AOVs) which are not blendable in Metal.
• apple/SwiftUsd: brings v8.0.0 for OpenUSD v26.08.

Rolling changes since v26.8.2

• Hotfix Patch: temporarily removes the HioOpenVDB plugin since Xcode and Swift toolchains differ in their strictness on imports within namespaces, once OpenVDB imports are removed from within namespaces in MetaverseKit, we can add it back in.
• Adds HdGp.
• HydraKit
  • Adds two new async methods to Hydra.RenderEngine:
    • waitUntilSceneReady() - Populates the stage off the main thread if this hasn't already started, then returns once population is complete. Safe to call from multiple places - population only actually runs once, backed by a single memoized task. (This is useful for knowing when to present the Hydra.Viewport with ex. ProgressView("Loading Stage") subbing in until scene population is complete).
    • poll(every:onChange) - Polls PollForAsynchronousUpdates() at a fixed interval, calling onChange on the main actor whenever the engine reports the scene changed. Requires allowAsynchronousSceneProcessing: true to have been passed at engine construction - otherwise this always returns false and onChange is never called, with no error to indicate why. Cancel the enclosing Task to stop polling.
  • Adds UsdImagingGLEngine constructor params to Hydra.RenderEngine, so users can override the previously hardcoded defaults:

    // class Hydra.RenderEngine
    public required init(
      stage: UsdStage,
      colorCorrectionMode: Tf.Token = .sRGB,
      rendererPluginId: Tf.Token = Tf.Token(),
      excludedPaths: Sdf.PathVector = Sdf.PathVector(),
      invisedPaths: Sdf.PathVector = Sdf.PathVector(),
      sceneDelegateId: Sdf.Path = Sdf.Path.absoluteRootPath(),
      allowAsynchronousSceneProcessing: Bool = false,
      enableUsdDrawModes: Bool = true,
      displayUnloadedPrimsWithBounds: Bool = false,
      gpuEnabled: Bool = true
    )

Rolling changes since v26.8.1

• HydraKit improvements:
  • Moves the full stage population (first render() call) off of the main thread, so that application UI's that compose with Hydra.Viewport do not freeze during full stage population, which was especially noticeable when populating large production USD scenes.
  • Adds an optional colorCorrectionMode parameter which defaults to .sRGB for Hydra.RenderEngine(stage:colorCorrectionMode:) to support color management features such as .openColorIO configurations, this is usually used in tandem with the following Swift code:

    import OpenUSDKit
    import HydraKit
    import OCIOBundle // for OCIOConfigProfileType
    
    // retrieves a specified ocio config from OCIOBundle's resources bundle, and
    // sets the 'OCIO' environment variable to the specified config's '.ocio' file.
    func setupColorManagement(config ocio: OCIOConfigProfileType) {
      guard let ocioConfig = ocio.config
      else { return print("Could not find OCIO config.") }
      
      // setup ocio color config.
      setenv("OCIO", ocioConfig, 1)
    }
    
    func setupRenderEngine(for stage: UsdStage) -> Hydra.RenderEngine {
      setupColorManagement(config: .agx) // or .aces
    
      // create render engine with opencolorio color management.
      let hydra = Hydra.RenderEngine(stage: stage, colorCorrectionMode: .openColorIO)
    
      // setup color correction matching agx ocio config.
      // these particular settings would be used on an
      // apple display for the agx ocio config.
      hydra.getEngine().SetColorCorrectionSettings(
        .openColorIO,
        Tf.Token("Display P3"),
        Tf.Token("AgX"),
        Tf.Token("Linear BT.709"),
        Tf.Token()
      )
    
      return hydra
    }

• Brings OpenUSD source current with the dev branch, as of commit c32a446.
• Adds all Hio imaging plugins, enabling texture and volume workflows against production HDRI and VDB assets:
  • HioAVIF
  • HioImageIO
  • HioOIIO
  • HioOpenEXR
  • HioOpenVDB

Commits

• [HydraKit] fix main-thread stall on first stage population
• [HydraKit] Expose colorCorrectionMode param for RenderEngine
• Add all Hio plugins: [AVIF, ImageIO, OIIO, OpenEXR, OpenVDB], fix Arch bloat
• Align TBB linkage and config with OpenUSD

Rolling changes since v26.5.2

• Introducing OpenUSDKit, a unified cross-platform Swift API for OpenUSD. It is a direct replacement for the PixarUSD target.
• Introducing HydraKit, a composable Hydra viewport with SwiftCrossUI:

  import Foundation
  import OpenUSDKit
  import HydraKit
  import SwiftCrossUI
  
  @main
  struct MyApp: App {
    typealias Backend = PlatformBackend
  
    let stage: UsdStage
    let engine: Hydra.RenderEngine
  
    init() {
      Pixar.Bundler.shared.setup(.resources)
  
      stage = UsdStage.createInMemory()
      engine = Hydra.RenderEngine(stage: stage)
    }
    
    var body: some Scene {
      WindowGroup("MyApp") {
        Hydra.Viewport(engine: engine)
      }
    }
  }

  import SwiftCrossUI
    
  // Platform backend selection is explicit for now, this will eventually just end up
  // in HydraKit to handle this by default, but figured it was worth showing what is
  // going on under the hood, if developers wish to make extensible backends for
  // their own apps.
  #if os(Android)
    import AndroidBackend
    public typealias PlatformBackend = AndroidBackend
  #elseif os(Linux)
    import GtkBackend
    public typealias PlatformBackend = GtkBackend
  #elseif os(Windows)
    import WinUIBackend
    public typealias PlatformBackend = WinUIBackend
  #elseif os(macOS)
    import AppKitBackend
    public typealias PlatformBackend = AppKitBackend
  #else
    import UIKitBackend
    public typealias PlatformBackend = UIKitBackend
  #endif

• Integrates apple/SwiftUsd within OpenUSDKit and brings precompiled binaries for Darwin platforms by default, use the environment variable SWIFTUSD_BUILD_FROM_SOURCE=1 if you prefer to build from source and match the behavior on all other platforms (Android, Linux, and Microsoft Windows).
• Adds the availability of zero-copy VtArray reads, and single-copy VtArray writes from a contiguous buffer in Swift.
• Adds the availability of some OpenExec types to Swift:

  import OpenUSDKit
  
  let stage = UsdStage.createInMemory()
  let system = ExecUsdSystem.create(stage: stage)
  
  UsdGeom.Xform.define(stage, path: "/hello")
  let prim = UsdGeom.Sphere.define(stage, path: "/hello/world")
  
  let key = Pixar.ExecUsdValueKey(prim, .init("computeLocalToWorldTransform"))
  let request = system.BuildRequest(consuming: [key])
  let view = system.Compute(request)
  
  var val = view.Get(0)
  if val.IsHolding(T: pxr.GfMatrix4d.self) {
    let matrix: pxr.GfMatrix4d = val.UncheckedGet()
  }

Thank you

• @maddyadams
• @drwave
• @meshula
• @dgovil
• @brechtvl
• @stackotter
• @gracien-app
• @scott-wilson
• @obvgab
• @felfoldy
• Pixar's OpenUSD contributors

---

Usage

To use this release of USD in your swift project, add the following to the dependencies section in your Package.swift file:

// swift-tools-version: 6.1

dependencies: [
  .package(url: "https://github.com/wabiverse/swift-usd.git", from: "26.8.3")
]

Linux

For Linux, these are the only dependencies required, as MetaverseKit provides everything else.

Tip

If you are on a distro like Ubuntu there is a good chance you already have most of these installed.

Dependency	CentOS	Ubuntu
BZ2	bzip2-devel	libbz2-dev
ZLib	zlib-devel	zlib1g-dev
FreeGLUT	freeglut-devel	freeglut3-dev
DEFLATE	libdeflate-devel	libdeflate-dev
Expat	libexpat-devel	libexpat1-dev
Xcursor	libXcursor-devel	libxcursor-dev
Xt	libXt-devel	libxt-dev
Xi	libXi-devel	libxi-dev
Xinerama	libXinerama-devel	libxinerama-dev
Xrandr	libXrandr-devel	libxrandr-dev