From 4bf7b90ea6f94aeb78a30d913700230ceb056cbd Mon Sep 17 00:00:00 2001 From: Jakub Svoboda <132791205+rolledhand@users.noreply.github.com> Date: Mon, 31 Aug 2026 15:37:24 +0200 Subject: [PATCH] Document Houdini 22 macOS alignment Signed-off-by: Jakub Svoboda <132791205+rolledhand@users.noreply.github.com> --- building/macOS/Houdini22_build_notes.md | 248 ++++++++++++++++++++++++ building/macOS/macOS_build.md | 4 +- 2 files changed, 251 insertions(+), 1 deletion(-) create mode 100644 building/macOS/Houdini22_build_notes.md diff --git a/building/macOS/Houdini22_build_notes.md b/building/macOS/Houdini22_build_notes.md new file mode 100644 index 0000000..9930555 --- /dev/null +++ b/building/macOS/Houdini22_build_notes.md @@ -0,0 +1,248 @@ +# Houdini 22 macOS alignment notes + +This document records the changes and validation performed on the +`test/houdini22-clean-build` branch. The work started from +`OpenMoonRay/openmoonray` `main` at `b9b0ac2` and targets Houdini 22.0.408 on +Apple Silicon. + +This is a validation branch, not a statement of upstream support for every +Houdini 22 production workflow. + +## Validated platform + +- Houdini 22.0.408 +- Houdini USD 26.05 +- Houdini Python 3.13.10 +- AppleClang arm64 with C++20 +- macOS Tahoe on Apple Silicon +- Qt applications disabled +- MaterialX shader DSOs and Houdini nodes enabled +- Houdini's USD, Python, Vulkan headers, and Vulkan library used by the build +- MoonRay Embree generation retained at Embree 4 +- Metal accelerator compatibility retained, while `MOONRAY_USE_METAL` remains + disabled in the validation preset + +## Dependency alignment + +The macOS dependency build was refreshed without building a second USD copy. +The Houdini build uses `NO_USD=1` and links against Houdini's USD 26.05. + +| Dependency | Version | +| --- | --- | +| Boost | 1.88.0 | +| OpenSubdiv | 3.7.0 | +| Imath | 3.2.2 | +| OpenEXR | 3.4.3 | +| oneTBB | 2022.1.0 | +| OpenVDB | 13.0.0 | +| OpenColorIO | 2.5.0 | +| OpenImageIO | 2.5.18.0 | +| MaterialX | 1.39.5 | +| OpenImageDenoise | 2.3.3 | +| Embree | 4.2.0 | + +The dependency work also: + +- builds standalone Imath before OpenEXR 3; +- uses oneTBB's CMake build and install flow; +- removes OIDN's bundled TBB libraries so the dependency tree uses one TBB; +- disables Boost.NumPy, which is not required and did not build against the + Houdini Python configuration; +- uses Houdini Python 3.13 for Boost.Python and OpenImageIO; +- installs MaterialX independently instead of relying on Houdini's private copy; +- disables Qt and GUI applications for this build; +- isolates dependency discovery from Homebrew to avoid accidental ABI mixing; +- supplies CMake 4 policy compatibility to older dependency projects. + +## Houdini USD 26.05 integration + +The local PXR imported-target shim was regenerated for Houdini 22. The target +set follows the libraries shipped by Houdini 22.0.408, including `hdsi`, +`usdRi`, and `usdviewq`. Obsolete targets not shipped by this USD build, such as +`ndr` and `usdRiImaging`, are not synthesized. `usdRiPxrImaging` is also not +invented when Houdini does not ship that library. + +The shim uses Houdini's Python 3.13 framework and +`libhboost_python313-mt-a64.dylib`. A small Boost.Asio compatibility header is +provided for USD code that still includes the removed `io_service.hpp` path. + +The root preset now uses: + +- `CMAKE_CXX_STANDARD=20`; +- Houdini's Python executable and Python 3.13 module paths; +- Houdini's Vulkan include directory and library; +- Unix Makefiles for the Houdini configuration; +- `BUILD_MATERIALX_SHADERS=ON`; +- `BUILD_QT_APPS=OFF`; +- `BUILD_MOONRAY_SDR_PLUGINS=OFF` for the legacy SDR plugin path. + +## Submodule alignment and compatibility work + +The branch intentionally pins coordinated submodule revisions. The effective +changes are summarized below. + +### hdMoonray + +- starts from Rob's Hydra 2.0 `hdm_10` work; +- adapts renderer plugin entry points for USD 26; +- adds C++20 and Houdini 22 integer-value compatibility; +- retains the Apple Silicon half-float AOV allocation fix; +- keeps the internal `HdMoonray_Light` class name—this is a C++ implementation + name, not a Hydra prim token; +- recognizes Houdini 22's `houdini:viewport` setting as an interactive client; +- keeps an active Render Settings prim on the interactive Solaris render-pass + path instead of switching IPR to the one-shot disk-product path; +- invalidates completed offline product renders when their Render Settings or + scene changes. + +Houdini's generic Light LOP is expected to produce a Hydra `SphereLight` with +`moonray:class=PointLight`. Its default position is the origin; if the test +sphere is also at the origin, the point light is inside the sphere and the +outside initially appears black. + +### MoonRay, scene_rdl2, and Moonshine + +- replaces the Metal GPU accelerator map's legacy `tbb::atomic` use with + `std::atomic`; +- adds the remaining USD 26 and oneTBB source compatibility needed by the + H22 build; +- fixes ARM half conversion in MoonRay render-output writing and scene_rdl2 + tile packing; +- adjusts macOS compiler, Python framework loading, and signing compatibility; +- fixes a C++20 attribute lookup in Moonshine's DwaBase material path. + +### MaterialX and Houdini DCC plugins + +- builds MaterialX shaders against the standalone MaterialX 1.39.5 package; +- updates MaterialX source compatibility for Houdini 22/C++20; +- uses Nick's updated DCC plugin work as the plugin base; +- supports MaterialX HDA generation with USD 26; +- installs the Houdini startup hook in the Python 3.13 location; +- installs renderer `.ds` files and HDAs beneath the OpenMoonRay Houdini plugin + directory. + +### Artist-facing Solaris tools + +The H22 DCC payload includes an editable **MoonRay Material Builder** shelf +tool. Create it inside a Solaris Material Library; it creates a native +`DwaBaseMaterial` and `NormalDisplacement` network and publishes `surface` and +`displacement` through Houdini 22's `suboutput` node. The builder is a plain +editable subnet, so additional MoonRay VOPs can be inserted without editing a +locked asset. + +The Light Filter Library includes the MoonRay filter HDAs supplied by the DCC +plugin (`IntensityLightFilter`, `DecayLightFilter`, `CookieLightFilter`, +`BarnDoorLightFilter`, `ColorRampLightFilter`, `CombineLightFilter`, +`RodLightFilter`, and `VdbLightFilter`). These are intended to be created +inside a Solaris Light Filter Library rather than a regular material network. + +Render Geometry already exposes MoonRay mesh tessellation controls in +`HdMoonrayRendererPlugin_Geometry.ds`. Set the control mode to **Set or Create** +before editing **Mesh Resolution** or **Adaptive Error**; their default +**Do Nothing** mode intentionally leaves existing scene-authored primvars +untouched. + +### Arras and IPR lifecycle + +The apparent scene-update starvation had two independent causes. + +First, Athena UDP telemetry was called inline from Arras message delivery. A +blocking `sendto()` to an unavailable local syslog target could stop the client +before scene updates were delivered. The socket is now non-blocking and logging +is best-effort. + +Second, hdm10 treated every active Render Settings prim as an offline product +render. In Solaris this latched `mProductRenderComplete` after one execution and +prevented later IPR changes. Houdini 22 viewport detection and render-pass +routing now keep that path interactive. + +Temporary full-scene reload, renderer pausing, client-message serialization, +and deferred-MCRT queue workarounds were tested and reverted after transport +and render-pass tracing identified the actual causes. Investigation-only frame +and queue logging was also removed from the final state. + +## Clean build procedure + +The paths below match the checked-in validation preset. Change the Houdini +installation path in `CMakeMacOSPresets.json`, `building/macOS/CMakeLists.txt`, +and `building/macOS/user-config.jam` when testing another Houdini build. + +From a clean checkout with recursively initialized submodules: + +```bash +mkdir -p /Applications/MoonRay/{build,build-deps,installs} + +cmake \ + -S /Applications/MoonRay/source/openmoonray/building/macOS \ + -B /Applications/MoonRay/build-deps \ + -DNO_USD=1 \ + -DNO_QT=1 +cmake --build /Applications/MoonRay/build-deps --parallel + +cmake \ + --preset macos-houdini-release \ + -S /Applications/MoonRay/source/openmoonray +cmake --build --preset macos-houdini-release --parallel +``` + +The install prefix is `/Applications/MoonRay/installs/openmoonray`. + +## Houdini plugin and HDA refresh + +The normal root install copies the plugin. To regenerate HDAs after changing +RDL2 proxy definitions: + +```bash +cd /Applications/Houdini/Houdini22.0.408/Frameworks/Houdini.framework/Versions/Current/Resources +source ./houdini_setup +source /Applications/MoonRay/installs/openmoonray/scripts/macOS/setupHoudini.sh + +cd /Applications/MoonRay/source/openmoonray/moonray/moonray_dcc_plugins +hython scripts/update_hdas.py --output-dir ./houdini +cmake --install /Applications/MoonRay/build +``` + +This flow generated standard nodes such as `VdbVolume` and `DwaBaseMaterial` +and MaterialX `ND_*` nodes from the fresh proxy libraries. + +## Launch command + +Start Houdini from a terminal so its USD and Python environment is established +before the OpenMoonRay setup is applied: + +```bash +cd /Applications/Houdini/Houdini22.0.408/Frameworks/Houdini.framework/Versions/Current/Resources +source ./houdini_setup +source /Applications/MoonRay/installs/openmoonray/scripts/macOS/setupHoudini.sh +houdini +``` + +## Validation performed + +The final installed Release and Debug delegates were loaded in a fresh Houdini +22.0.408 process. Validation covered: + +- MoonRay renderer discovery in the Solaris viewport; +- a sphere rendered with the generic Houdini Light LOP resolved as + `SphereLight` plus `moonray:class=PointLight`; +- repeated PointLight intensity edits with distinct completed framebuffers; +- an active `/Render/rendersettings` prim; +- live `pixel_samples` changes with new Arras synchronization IDs and distinct + completed framebuffers; +- MaterialX shader DSO and `ND_*` node generation; +- ARM half-float framebuffer/AOV paths; +- successful compilation and installation of `hd_moonray`, + `hd_moonray_debug`, and `computation_progmcrt`. + +The install step may print duplicate `LC_RPATH` warnings when reinstalling over +an existing tree. They did not prevent the rebuilt binaries from being +installed or loaded during this validation. + +## Remaining scope + +- The preset is intentionally pinned to Houdini 22.0.408 paths. +- Qt applications and the MoonRay GUI were not part of this validation. +- Metal rendering is disabled in the preset; only the source compatibility fix + is included. +- The branch contains coordinated submodule revisions and should be reviewed as + an integration branch rather than as one isolated library update. diff --git a/building/macOS/macOS_build.md b/building/macOS/macOS_build.md index 3b93c94..8127efa 100644 --- a/building/macOS/macOS_build.md +++ b/building/macOS/macOS_build.md @@ -48,7 +48,9 @@ Note: If building for Houdini, you'll potentially need to make the following cha * Edit source/openmoonray/scripts/macOS/setupHoudini.sh to update HOUDINI_PATH * Edit source/openmoonray/building/macOS/pxr-houdini/pxrTargets.cmake to update HPYTHONLIB and HPYTHONINC if needed -Houdini 20 is officially supported. +Houdini 20 is officially supported. The experimental Houdini 22 alignment and +its exact dependency, submodule, build, and validation details are documented +in [Houdini22_build_notes.md](Houdini22_build_notes.md). --- ### Step 4. Build the dependencies