Blender addon

BLENDER_INTEGRATION.md

@@ -0,0 +1,65 @@
+# MoonRay Blender Integration (macOS)
+
+This branch adds a Blender integration to the MoonRay render engine, plus
+the system-compatibility fixes needed to build MoonRay on current macOS
+(macOS 27 / Apple Silicon / AppleClang 21).
+
+## What's here
+
+| Path | Content |
+|------|---------|
+| `blender_addon/` | The Blender add-on (render engine integration) |
+| `COMPATIBILITY.md` | All macOS compatibility fixes applied (10 items) |
+| `patches/` | The openmoonray superbuild/preset changes used for the build |
+| `install_addon.sh` | Symlinks the add-on into Blender |
+| `build_moonray.sh` | Configures + builds MoonRay itself (`macos-release-ninja` preset) |
+| `verify_moonray.sh` | Renders the official sphere test scene with the built binary |
+| `finish_build_and_test.sh` | One-shot: wait for deps → build → verify → Blender E2E |
+| `moonray_env.sh` | Terminal environment for running moonray/denoise directly |
+
+## Build (macOS, Apple Silicon)
+
+The engine repo itself uses DreamWorks' internal build system; the public
+build lives in the [`OpenMoonRay/openmoonray`](https://github.com/OpenMoonRay/openmoonray)
+superproject (this repo is its `moonray/moonray` submodule). Steps:
+
+```bash
+# 1. clone the superproject next to this checkout
+git clone --recurse-submodules https://github.com/OpenMoonRay/openmoonray.git
+
+# 2. build dependencies (patches/CMakeUserPresets.json + the superbuild
+#    changes in patches/openmoonray-building-macOS.patch are applied to it)
+mkdir -p installs/{bin,lib,include} build-deps
+cmake -DSKIP_QT=ON ../openmoonray/building/macOS   # in build-deps/
+cmake --build .                                     # ~2-4 h, serial chain
+
+# 3. build MoonRay
+#    (copy patches/CMakeUserPresets.json into openmoonray/ first)
+cd openmoonray && cmake --preset macos-release-ninja
+cmake --build --preset macos-release-ninja
+```
+
+See `COMPATIBILITY.md` for the reasoning behind each patch.
+
+## Blender add-on
+
+- Registers **MoonRay** as a render engine (F12 / Render Image button /
+  animation rendering).
+- Compiles Blender shader-node graphs to MoonRay Dwa materials (Principled,
+  Diffuse, Glossy, Glass, Transparent, Emission, Mix/Add Shader, image
+  textures, normal maps, procedural noise, static baking of color/scalar
+  subgraphs, texture Mapping nodes).
+- Exports meshes (UVs/normals), instancing, lights, camera (DOF, shift),
+  world (constant or HDRI), optional motion blur, optional OIDN denoise.
+- The intermediate `.rdla` scene is temporary by default and kept only when
+  **Save RDLA Scene** is enabled.
+
+Install and test:
+
+```bash
+./install_addon.sh
+/Applications/Blender.app/Contents/MacOS/Blender --background --factory-startup \
+    --python blender_addon/tests/test_render.py -- /tmp/render.png
+```
+
+Full test instructions in `blender_addon/README.md`.

COMPATIBILITY.md

@@ -0,0 +1,127 @@
+# System compatibility fixes (macOS 27 / Apple Silicon / clang 21 / CMake 4.4)
+
+The user's machine is an **M5 MacBook Air, macOS 27, Xcode 26.6 (CLT active),
+AppleClang 21, CMake 4.4.3, Blender 5.2 Alpha**. MoonRay officially supports
+macOS 14/15 with Xcode 15/16, so several adjustments were needed.
+
+## Repository layout
+
+- `OpenMoonRay/moonray` (the repo the user asked to clone) is the **render
+  engine component** and uses DreamWorks' internal rez/SCons build system
+  (`package.py`, `SDKScript`) that only works inside the studio infrastructure.
+  It is checked out at the workspace root.
+- `OpenMoonRay/openmoonray` is the **official superproject** that references
+  this engine repo as the `moonray/moonray` Git submodule and carries the
+  public CMake build + macOS support. It is checked out at `openmoonray/`
+  and is what we build.
+
+## Fixes applied
+
+### 1. Generator mismatch in the dependency superbuild
+`building/macOS/CMakeLists.txt` hardcodes `make ${JOBS_ARG}` as the build
+command for several ExternalProjects. Configuring the superbuild with Ninja
+(which we wanted) made the inner builds generate `build.ninja` while `make`
+ran → "No targets specified and no makefile found" on Blosc.
+**Fix:** configure the superbuild with the default Unix Makefiles generator
+(the documented path; the superbuild itself only orchestrates stamps).
+
+### 2. Qt 5.12.12 cannot build with modern toolchains (and is unneeded)
+Qt 5.12 predates clang 15+ and fails on current macOS SDKs. The Blender
+integration only needs the `moonray` CLI, not `moonray_gui`.
+**Fix:** added `option(SKIP_QT)` to `building/macOS/CMakeLists.txt` and guard
+the `qt5` ExternalProject; build with `-DSKIP_QT=ON`. The main build is
+configured with `-DBUILD_QT_APPS=NO`.
+
+### 3. Memory-bounded parallelism
+24 GB RAM is not enough for `-j10` on the biggest deps (Boost/USD).
+**Fix:** added `MAX_BUILD_JOBS` (default 6) cap in the superbuild.
+
+### 4. Xcode generator unusable (CLT-only developer dir)
+The official `macos-release` preset uses the Xcode generator, which requires
+`xcodebuild`, but this machine's active developer directory is the Command
+Line Tools. Switching to full Xcode needs sudo, which is unavailable.
+**Fix:** `CMakeUserPresets.json` adds `macos-release-ninja` (inherits the
+official preset, overrides the generator to Ninja). AppleClang from CLT is
+used for the whole build.
+
+### 5. Blender 5.x API removals in the add-on
+Blender 5.2 removed `Mesh.loops`, `Mesh.calc_normals_split()` and
+`MeshUVLoopLayer.data` (renamed to `corners`/`uv`).
+**Fix:** `blender_addon/exporter.py` uses the new API with fallbacks for
+Blender 4.x.
+
+### 6. `installs/{bin,lib,include}` must exist before the superbuild runs
+The Lua dependency's install step copies `lua`/`luac` into
+`${InstallRoot}/bin` without creating the directory ("cp: .../bin: Not a
+directory" failure). The official docs Step 1 pre-creates these folders.
+**Fix:** `mkdir -p installs/{bin,lib,include}` before building deps.
+
+### 7. Skip the unit tests in the main build
+`moonray/CMakeLists.txt` gates `add_subdirectory(tests)` on
+`CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME AND BUILD_TESTING`, which is true
+for the top-level superproject build (and `include(CTest)` defaults
+`BUILD_TESTING` to ON). Building the test suite would multiply compile time
+and requires CppUnit to behave under clang 21.
+**Fix:** `-DBUILD_TESTING=OFF` in `CMakeUserPresets.json`.
+
+### 8. Unreliable GitHub clones on this network
+Full clones repeatedly died with "fetch-pack: invalid index-pack output" /
+"RPC failed; curl 56", and ExternalProject hung on the dead clone.
+**Fix:** `GIT_SHALLOW TRUE` + `GIT_PROGRESS TRUE` on every git-based
+dependency in the superbuild, plus global git hardening
+(`http.postBuffer`, `http.version HTTP/1.1`, low-speed timeout).
+Note: changing ExternalProject arguments invalidates its stamps, so already
+built deps were re-run once (object caches made this cheap).
+
+### 9. Blender 5.2 alpha RenderEngine API regressions
+- Any *instance attribute* access on the engine raises `ReferenceError:
+  StructRNA ... has been removed` (only built-in methods like `report`/
+  `update_stats`/`test_break`/`begin_result` work through `self`).
+- A bare `def __init__(self, *args): pass` swallows Blender's struct-creation
+  call, leaving the engine unbound — every subsequent method call (even
+  `update_stats`) raises `ReferenceError` and the render silently produces
+  black. The class must NOT define `__init__` at all.
+- After the render, Blender calls `render()` a second time on the
+  already-released engine struct.
+**Fix:** the engine stores NO instance state and keeps ALL helper logic in
+module-level functions receiving the engine instance explicitly (custom
+methods are also unreachable through `self`); it defines NO `__init__`;
+`render()` catches `ReferenceError` from the phantom second invocation.
+
+### 12. MoonRay beauty channels vs Blender's "Combined" pass
+MoonRay writes its beauty EXR with channels `R/G/B/A`, but Blender's
+`RenderLayer.load_from_file()` only maps `Combined.R/G/B/A` into the
+render result; any other channel names make the final composite silently
+black (`Reading render result: expected channel "Combined.R" ... not found`).
+**Fix:** the engine renames the channels to `Combined.*` with `oiiotool`
+(from the dependency install) before loading, and passes `-out` to the
+moonray CLI so the output path is explicit (the mock renderer test relies
+on the same contract).
+
+### 10. libc++ "selected platform no longer supported" warning
+embree (and possibly other old deps) request a very old macOS deployment
+target; the macOS 27 libc++ warns about it during compilation. It is a
+warning only (`-W#warnings`) and does not fail the build.
+
+### 11. Anaconda environment pollution breaks OpenColorIO
+With Anaconda's `bin` on `PATH`, CMake's find_* commands derive search
+prefixes from PATH entries and pick up Anaconda packages. OpenColorIO then
+linked against Anaconda's yaml-cpp 0.8 headers (via the expat imported
+target's interface include dirs) while linking its own yaml-cpp 0.6.3 →
+undefined symbols (`YAML::FpToString`, `YAML::Emitter::Write(char const*,
+unsigned long)`).
+**Fix:** build with Anaconda removed from `PATH` and `CONDA_*` env vars
+unset (also `PYTHONPATH`, `CMAKE_PREFIX_PATH`), after deleting the
+OpenColorIO build/stamp directories so its configure re-runs cleanly.
+
+## Status
+
+- Dependency superbuild: complete (all deps installed to `installs/`).
+- Main build: complete, installed to `installs/openmoonray/`; `moonray` CLI
+  renders the reference `sphere.rdla` correctly (verified by
+  `verify_moonray.sh`).
+- Add-on: complete and tested — export, full scene (18/18), materials
+  (11/11), motion blur, robustness, renderer, registration, animation mock,
+  engine mock end-to-end, and real end-to-end render (Blender → moonray →
+  `Combined.*` EXR → non-black PNG, mean ≈ 0.25) all pass.
+  Installed into Blender via `install_addon.sh`.

INSTALL.md

@@ -0,0 +1,146 @@
+# Installing MoonRay (macOS / Apple Silicon)
+
+Build-from-source instructions for this fork. The fork adds a Blender add-on
+and a handful of macOS build patches on top of
+[OpenMoonRay/openmoonray](https://github.com/OpenMoonRay/openmoonray); the
+render engine itself is upstream.
+
+The paths below use `<WORKSPACE>` as a placeholder. The machine this fork was
+developed on uses:
+
+```
+<WORKSPACE> = /Users/faputa/Documents/wave-tracer
+```
+
+## Layout
+
+```
+<WORKSPACE>/
+  moonray/                  # this fork (blender_addon/, patches/, scripts)
+    openmoonray/            # OpenMoonRay superproject (nested checkout)
+  installs/                 # dependencies + final moonray install
+  build/                    # main build tree
+  build-deps/               # dependency superbuild tree
+```
+
+## Requirements
+
+- Apple M-series Mac, macOS (tested on macOS 27 / Tahoe, Xcode 26.6 CLT).
+- Xcode Command Line Tools (`xcode-select --install`).
+  - Full-Xcode-only Metal toolchain is NOT needed — this fork builds with
+    `MOONRAY_USE_METAL=OFF`.
+- CMake 4.x (Ninja generator).
+- Git (Git LFS for upstream test assets is optional).
+- Blender 4.0+ (tested 5.2 alpha) for the add-on.
+- ~17 GB disk, 24 GB RAM recommended.
+
+## Step 1 — Check out
+
+```bash
+mkdir -p <WORKSPACE>/installs/{bin,lib,include}
+cd <WORKSPACE>
+git clone --recurse-submodules https://github.com/OpenMoonRay/openmoonray.git \
+    moonray/openmoonray
+# replace the engine submodule with this fork (branch blender-addon)
+git clone https://github.com/SakuraEntropia/moonray.git moonray
+```
+
+If `openmoonray` was cloned first, point its `moonray/moonray` submodule at
+this fork's `blender-addon` branch, or simply keep the two checkouts side by
+side as shown above and let the superproject reference the fork.
+
+## Step 2 — Apply the patches
+
+This fork fixes several macOS/clang-21/CMake-4 build issues. Copy the presets
+and apply every patch in `moonray/patches/`:
+
+```bash
+cd moonray/openmoonray
+cp ../patches/CMakeUserPresets.json CMakeUserPresets.json
+for p in ../patches/*.patch; do
+  git apply "$p"
+done
+```
+
+What they do (details in [`COMPATIBILITY.md`](COMPATIBILITY.md)):
+
+- `openmoonray-building-macOS.patch` — `SKIP_QT` option (Qt 5.12 is
+  unbuildable on clang 21 and unused), memory-bounded parallelism.
+- `openmoonray-moonray-CMakeLists.patch` — skip unit-test subdirectory.
+- `*-ispc-ninja.patch` — custom ISPC command path for the Ninja generator
+  (MoonRay's built-in ISPC language support does not emit the required stub
+  headers).
+- `openmoonray-ninja-duplicate-output.patch` — drop a duplicate BYPRODUCTS
+  line in MoonrayDso.cmake.
+- `openmoonray-codesign-ninja.patch` — codesign the `rdl2_ispc_util` target by
+  its real path instead of a broken glob.
+- `CMakeUserPresets.json` — adds `macos-release-ninja` (Ninja, no Qt,
+  `BUILD_TESTING=OFF`, `MOONRAY_USE_METAL=OFF`, `DEPS_ROOT`/`TBB_ROOT`
+  pointing at `<WORKSPACE>/installs`). Edit `DEPS_ROOT`/`BUILD_DIR` if your
+  workspace differs.
+
+## Step 3 — Build dependencies
+
+```bash
+mkdir -p <WORKSPACE>/build-deps
+cd <WORKSPACE>/build-deps
+cmake ../moonray/openmoonray/building/macOS -DSKIP_QT=ON
+cmake --build .
+```
+
+This compiles Boost, USD, OpenEXR, TBB, OpenSubdiv, OpenVDB, OIIO and friends
+into `<WORKSPACE>/installs`. Takes a long while (hours). Keep Anaconda/conda
+off `PATH` and `CMAKE_PREFIX_PATH` — see the OpenColorIO note in
+[`COMPATIBILITY.md`](COMPATIBILITY.md).
+
+## Step 4 — Build MoonRay
+
+```bash
+cd <WORKSPACE>/moonray
+./build_moonray.sh
+```
+
+This configures `macos-release-ninja` and builds/installs `moonray` into
+`<WORKSPACE>/installs/openmoonray`.
+
+## Step 5 — Verify
+
+```bash
+cd <WORKSPACE>/moonray
+./verify_moonray.sh
+```
+
+Renders the official `sphere.rdla` test scene. "Wrote …/sphere.exr" and
+exit 0 means the install is good.
+
+## Step 6 — Run from the shell (optional)
+
+```bash
+source <WORKSPACE>/moonray/moonray_env.sh
+moonray -in <scene>.rdla -out <out>.exr
+```
+
+`moonray_env.sh` sets `PATH`, `RDL2_DSO_PATH`, `PYTHONPATH` and
+`DYLD_LIBRARY_PATH`.
+
+## Step 7 — Install the Blender add-on
+
+```bash
+cd <WORKSPACE>/moonray
+./install_addon.sh
+```
+
+Then in Blender: *Edit → Preferences → Add-ons → Render → MoonRay Render*,
+enable it, and set **MoonRay Installation** to
+`<WORKSPACE>/installs/openmoonray` and **Dependencies Install Root** to
+`<WORKSPACE>/installs`. See
+[`blender_addon/README.md`](blender_addon/README.md) for usage.
+
+Alternatively install the prebuilt add-on zip
+`moonray_blender-v0.2.0.zip` via *Edit → Preferences → Add-ons → Install…*.
+
+## Known issues
+
+All build fixes and gotchas are documented in
+[`COMPATIBILITY.md`](COMPATIBILITY.md): generator mismatch, Qt, Anaconda PATH
+pollution, TBB discovery, Metal toolchain, ISPC stubs, libc++ warnings.

README.md

@@ -1,7 +1,45 @@
-# moonray - part of the [MoonRay](https://github.com/OpenMoonRay/openmoonray) project
-Policies concerning [Governance](https://github.com/OpenMoonRay/openmoonray/blob/main/GOVERNANCE.md), [Code of Conduct](https://github.com/OpenMoonRay/openmoonray/blob/main/CODE_OF_CONDUCT.md), and [Contribution](https://github.com/OpenMoonRay/openmoonray/blob/main/CONTRIBUTING.md) are available in the overarching MoonRay project, defined in the [`OpenMoonRay/openmoonray` GitHub repository superproject](https://github.com/OpenMoonRay/openmoonray).
+# MoonRay fork — Blender integration
 
-This repository implements the MoonRay render engine and the moonray command-line renderer.
-The code is comprised of roughly 20 libraries. moonray also contains a set of basic scene object (shader) plugins.
+This is a fork of [OpenMoonRay/moonray](https://github.com/OpenMoonRay/moonray)
+(the DreamWorks / Academy Software Foundation production path tracer) adding a
+**Blender add-on** that renders Blender scenes directly with the `moonray` CLI.
 
+The engine code is unchanged from upstream; all additions live in
+[`blender_addon/`](blender_addon/) on the `blender-addon` branch.
 
+## The add-on
+
+Registers **MoonRay** as a Blender render engine:
+
+1. exports the Blender scene to MoonRay's RDLA format (meshes, UVs, normals,
+   instancing, Cycles shader nodes, lights, camera, world),
+2. runs `moonray`,
+3. loads the EXR back into Blender's Render Result (F12 + animation),
+4. optional OIDN denoise.
+
+Feature highlights:
+
+- Cycles-native node parity: Principled BSDF (IOR, clearcoat, sheen,
+  subsurface, transmission, anisotropic, emission), Diffuse/Glossy/Glass/
+  Refraction/Translucent/Anisotropic/Velvet/Toon/Subsurface Scattering,
+  Blackbody, image + noise textures, normal maps.
+- Lights: Point / Sun / Spot / Area (square/rect/disk/ellipse, spread,
+  blackbody temperature).
+- Emissive meshes become MoonRay MeshLights (real area lights).
+- Progressive preview via MoonRay progress checkpoints.
+- Multi-material meshes split per material slot.
+
+Install: [`install_addon.sh`](blender_addon/) symlinks the add-on into
+Blender's add-ons folder. Full docs in
+[`blender_addon/README.md`](blender_addon/README.md).
+
+## Building & installing MoonRay
+
+Full build-from-source instructions: [`INSTALL.md`](INSTALL.md).
+macOS build notes and patches: [`COMPATIBILITY.md`](COMPATIBILITY.md).
+
+## Upstream
+
+Governance, Code of Conduct, and Contribution policies live in the upstream
+[OpenMoonRay/openmoonray](https://github.com/OpenMoonRay/openmoonray)
+superproject.