OpenSceneGraph 0.1.2__cp313-cp313-win_amd64.whl

OpenSceneGraph/aipython/06-camera-effects.md

@@ -0,0 +1,132 @@
+# Temporary camera effects (shake, kick, scripted moves) without taking control
+
+For layering a TEMPORARY effect on top of the user's live manipulator (e.g.
+`TrackballManipulator`) without replacing it and without the user losing
+control afterward. Different from [`05-camera-manipulator.md`](05-camera-manipulator.md)'s
+fully-replacing self-driving manipulators — this is about *layering*
+something temporary on top of whatever manipulator is already there.
+
+## Why an update callback on `viewer.camera` cannot do this
+
+`osgViewer::Viewer::updateTraversal()` (`src/osgViewer/Viewer.cpp`) always
+runs, in this order, every frame:
+
+```cpp
+_scene->updateSceneGraph(*_updateVisitor);   // invokes a camera's update callback
+...
+_cameraManipulator->updateCamera(*_camera);  // ALWAYS runs after, unconditionally
+                                              // overwriting whatever the update callback wrote
+```
+
+`CameraManipulator::updateCamera()`'s C++ default is
+`camera.setViewMatrix(getInverseMatrix())`, and it runs unconditionally after
+the scene graph's own update traversal. Anything an update callback writes to
+`camera.viewMatrix` is clobbered the same frame.
+
+There is also no `cullCallback` exposed on `osg.Camera` in these bindings
+(only `updateCallback`/`preDrawCallback`/`postDrawCallback`/`DrawCallback`/
+`initialDrawCallback`/`finalDrawCallback`), and a pre/post-draw callback would
+be too late anyway — cull has already baked that frame's matrices into the
+render bins by draw time.
+
+## The mechanism: `updateCamera()` is virtual, and runs LAST on purpose
+
+`updateCamera(osg::Camera&)` is `virtual` specifically so a manipulator
+subclass can override what gets written into the camera each frame — OSG's
+own extension point for exactly this. The pattern is a **decorator
+manipulator**: wrap the user's real manipulator, forward every normal
+interaction to it untouched, and override only `updateCamera()` to compose
+something extra on top of the inner manipulator's own output.
+
+`updateCamera()` is bound on `osgGA::CameraManipulator`'s trampoline
+(`pyosg/pyosgGA.hpp`/`.cpp`) and exposed as a normal method, so a decorator
+can call `self.inner.updateCamera(camera)` directly. Uses the same
+`call_override` (not `PYBIND11_OVERRIDE`) pattern `home(ea, aa)` uses: `osg::Camera`
+derives from `osg::Referenced` and isn't copyable, and `PYBIND11_OVERRIDE`'s
+implicit copy-for-marshaling would crash the instant a Python subclass
+overrides it.
+
+## The pattern (`examples/pyosg-fire.py`'s `EffectManipulator`)
+
+```python
+class EffectManipulator(osgGA.CameraManipulator):
+	def __init__(self, inner):
+		super().__init__()
+		self.inner = inner
+		self.effects = []  # zero-arg callables -> None or an osg.Matrixd to compose
+		self._node = None
+
+	# Forward everything else untouched.
+	def setNode(self, node):
+		self._node = node
+		self.inner.node = node
+	def getNode(self): return self._node
+	def home(self, *args): self.inner.home(0.0)  # NOT self.inner.home(*args) — see below
+	def handle(self, ea, aa): return self.inner.handle(ea, aa)  # untested live, see below
+	def getMatrix(self): return self.inner.matrix
+	def getInverseMatrix(self): return self.inner.inverseMatrix
+	def setByMatrix(self, m): self.inner.matrix = m
+	def setByInverseMatrix(self, m): self.inner.inverseMatrix = m
+
+	# The one method that matters: called LAST, once per frame. Nothing runs after this.
+	def updateCamera(self, camera):
+		self.inner.updateCamera(camera)
+
+		m = camera.viewMatrix
+
+		for effect in self.effects:
+			delta = effect()
+			if delta is not None:
+				m = m * delta  # eye-space compose — see 01-core.md rule 9 for OSG's multiply order
+
+		camera.viewMatrix = m
+```
+
+Usage:
+
+```python
+trackball = osgGA.TrackballManipulator()
+effect_manip = EffectManipulator(trackball)
+viewer.cameraManipulator = effect_manip   # installed ONCE, stays for the session
+
+shake_effect, shake_trigger = make_shake_effect(viewer, duration=0.3, magnitude=0.1)
+effect_manip.effects.append(shake_effect)
+
+shake_trigger()  # fire it any time — orbiting/panning underneath keeps working
+```
+
+An "effect" is any zero-arg callable returning `None` (inactive) or a matrix
+to compose — a punch-zoom, a forced-look-at, a scripted flourish, all
+installed once and left there for the rest of the session.
+
+## The `home(ea, aa)` forwarding trap
+
+`View.setCameraManipulator(resetPosition=True)` calls `manip->home(ea, *this)`
+internally — `*this` being the live `View`/`Viewer`, passed where C++ expects
+`GUIActionAdapter&`. Python resolves that argument to a full
+`osgViewer.Viewer` object; forwarding it into `self.inner.home(ea, aa)`
+(typed `GUIActionAdapter&` too) fails, because pybind11 doesn't know
+`View`/`Viewer` "is a" `GUIActionAdapter`.
+
+**Not fixable by declaring `GUIActionAdapter` as a base of `View`**:
+`osgGA::GUIActionAdapter` is not `osg::Referenced`-derived (no `ref()`/
+`unref()`), so it can never take an `osg::ref_ptr` holder to match `View`'s —
+pybind11 requires every base in a `py::class_`'s template list to agree on
+holder type. Fails at import time (`ImportError: generic_type: type "View"
+has a non-default holder type while its base "osgGA::GUIActionAdapter" does
+not`). This is a hard wall in the binding model — don't re-attempt it.
+
+**The actual fix**: `EffectManipulator.home()` never forwards `(ea, aa)` — it
+always calls `self.inner.home(0.0)`, the overload that doesn't need a
+`GUIActionAdapter`.
+
+`handle()` (mouse drag/orbit input) has the identical exposure and no
+equivalent no-`aa` overload — `GUIEventHandler::handle()`'s real C++
+implementation resolves a real `GUIActionAdapter&` before calling the 2-arg
+`handle(ea, aa)` this binding exposes to Python, likely the same forwarding
+trap. **Not yet tested live** — verify by actually dragging the mouse through
+an installed `EffectManipulator` before trusting it. If it crashes the same
+way, the likely fix is making `EffectManipulator` *inherit* from the real
+manipulator class instead of holding it as `self.inner` and forwarding —
+inherited (non-overridden) C++ methods resolve through the trampoline via
+real virtual dispatch, no Python-argument-marshaling boundary to cross.

OpenSceneGraph/aipython/07-camera-manual.md

@@ -0,0 +1,88 @@
+# Fixed camera, no `osgGA.CameraManipulator` at all
+
+Sibling to [`05-camera-manipulator.md`](05-camera-manipulator.md): that file
+covers driving/customizing a manipulator; this one is a camera that should
+never move (an orthographic front-on layout, a locked cinematic angle),
+driven by directly assigning `viewer.camera.viewMatrix`/`projectionMatrix`
+with no manipulator attached at all.
+
+## Rule 1: `viewer.realize()` BEFORE setting view/projection, not after
+
+```python
+viewer = osgViewer.Viewer()
+viewer.sceneData = root
+viewer.realize()                              # FIRST
+
+viewer.camera.viewMatrix = osg.Matrix.lookAt(eye, center, up)
+viewer.camera.projectionMatrix = osg.Matrix.ortho(l, r, b, t, near, far)
+```
+
+Setting the projection matrix before `realize()`/the first `frame()` gets its
+horizontal extent silently zeroed on the next frame:
+`osg::Camera::ProjectionResizePolicy` (default `HORIZONTAL`) rescales the
+projection against a "reference" viewport size that is wrong (effectively
+unset) if a custom projection was assigned before the window had a real size.
+An `ortho(-3, 3, -2, 2, 0.1, 100)` matrix's `element[0]` (`0.333`) goes to
+`0.0` after one `frame()` call; vertical extent (`element[5]`) is untouched,
+matching `HORIZONTAL`'s asymmetry. Once corrupted, nothing from that camera
+renders — no diagnostic, just the clear color, indistinguishable from an
+unrelated bug.
+
+The reorder above is the real fix. No per-frame reassertion is needed once
+ordered correctly — a correctly-ordered fixed camera should never need its
+matrices touched again after setup; if a "reassert every frame" band-aid
+feels necessary, that's a signal the ordering is still wrong, not a reason to
+ship the band-aid.
+
+`viewer.realize()` alone is enough, no full `frame()` needed first.
+
+## Rule 2: disable automatic near/far unless you actually want it
+
+`osg::Camera`'s default `computeNearFarMode` is
+`COMPUTE_NEAR_FAR_USING_BOUNDING_VOLUMES` — it recomputes near/far from the
+cull-visible scene bounds every frame, independent of whether a manipulator
+is attached. This is a needless per-frame cost for a camera that never moves,
+and a sharp edge for genuinely flat (zero-depth) geometry where the
+recomputed range can be degenerate. Fix:
+
+```python
+viewer.camera.computeNearFarMode = osg.Camera.DO_NOT_COMPUTE_NEAR_FAR
+```
+
+## Rule 3: confining the camera to part of the window is not automatically viewport-aware everywhere
+
+`viewer.camera.viewport = osg.Viewport(x, y, w, h)` works exactly as expected
+for geometry — MVP-transformed vertex positions map into that sub-rectangle,
+no extra setup needed. Two things are NOT automatically viewport-aware,
+though:
+
+- **`gl_FragCoord` in a fragment shader is WINDOW-absolute, not
+  viewport-relative.** A shader that derives spatial patterns from
+  `gl_FragCoord`/a resolution uniform samples a shifted, wrong region once the
+  viewport's origin isn't `(0, 0)`. Don't patch this with a manual
+  origin-correction uniform — don't depend on `gl_FragCoord` at all: derive
+  the spatial domain from a vertex-shader `out` varying (object/world-space
+  position) instead, which is genuinely view-independent. See
+  `pyosg-noise.py`'s `VERTEX_SHADER`/`FRAGMENT_SHADER_NOISE` (`vPos`) for the
+  pattern.
+- **`osgx` needs the main camera's viewport origin subtracted from
+  window-absolute mouse coordinates.** `PickReadback::setWindowOrigin(x, y)`
+  (alongside `setWindowSize(w, h)`) is refreshed every frame by
+  `PickCameraSync` from the live viewport; both the pick1x1 sub-frustum math
+  and full-image CLICK-mode pixel mapping subtract it. Not Python-bound
+  (driven automatically). If picking/hover looks offset by a consistent pixel
+  amount after confining a camera's viewport, check whether the running osgx
+  build has this fix (see the repo's `CLAUDE.md` on `PYOSG_OSGX_SOURCE_DIR`)
+  before re-debugging from scratch. If instead picking triggers UNDER an
+  ImGui panel, or hover sticks/flickers near one, that's a different bug —
+  see [`09-picking.md`](09-picking.md).
+
+## What a manipulator gives you that a fixed camera does not
+
+Just initial framing, nothing else. `viewer.cameraManipulator = ...` after
+`sceneData` is set auto-computes a reasonable home position from the scene
+bounds (see [`05-camera-manipulator.md`](05-camera-manipulator.md)'s "There
+is no `viewer.home()`"); a fixed camera has no equivalent, the view is
+hand-computed. Rules 1–2 apply identically whether or not a manipulator is
+attached; a manipulator doesn't make viewport-offset picking correct either —
+that fix lives in `osgx` regardless of what drives the camera.

OpenSceneGraph/aipython/08-lighting.md

@@ -0,0 +1,121 @@
+# Composing osgx::gltf materials with generic osgx lighting
+
+`osgx::gltf` (formerly a separate `osgGLTF` module/repo, merged into `osgx.gltf` — there is
+no `osgGLTF` Python module) is the glTF loader plus its optional PBR/IBL adapter. The ownership
+boundary is:
+
+- `osgx.gltf.shader` defines the state populated by the loader (attribute locations, sampler
+  units, `configureProgram()`/`configureStateSet()`).
+- `osgx.gltf.pbribl` provides glTF-specific material/shading GLSL snippets and the optional
+  one-call renderer (`PBRIBLEnvironment`/`PBRIBLScene`).
+- `osgx` and `osgx` provide generic rendering and environment-processing facilities.
+- `osgx.resolveShaderLibs()` expands generic catalogs (`osgx::pbr`, `osgx::ibl`, `osgx::shadow`).
+- `osgx.gltf.pbribl.resolveShaderLibs()` registers and expands the `osgx::gltf` catalog together
+  with those generic osgx catalogs, in one call.
+
+Import `osgx` before resolving a hand-assembled glTF shader — it registers every catalog
+(`osgx.gltf.pbribl.resolveShaderLibs()` calls the PBR/IBL/shadow/gltf registration functions
+itself, so nothing else needs to be imported separately):
+
+```python
+import osgx
+
+fragment_source = """
+#version 460 core
+
+const float PI = 3.14159265359;
+
+#pragma osgx::pbr MATERIAL_STRUCT, D_GGX, G_SCHLICK, G_SMITH, F_SCHLICK, DIRECT_SPECULAR, TONEMAP_PBR_NEUTRAL
+#pragma osgx::gltf MATERIAL_INPUTS, GET_MATERIAL, SHADING_NORMAL, EMISSIVE, ALPHA_COVERAGE
+#pragma osgx::ibl HEMISPHERE_AMBIENT
+
+// application-specific lighting and main()
+"""
+
+fragment_shader = osgx.gltf.pbribl.resolveShaderLibs(fragment_source)
+```
+
+Catalog and library names are case-insensitive. Unknown entries in a registered namespace fail
+immediately; unrelated pragmas remain intact for OSG or other tooling.
+
+## Required program and StateSet setup
+
+Custom renderers should use `osgx.gltf.shader`'s public contract rather than repeat attribute
+locations or sampler units:
+
+```python
+program = osg.Program(shaders=(
+	osg.Shader(osg.Shader.VERTEX, vertex_source),
+	osg.Shader(osg.Shader.FRAGMENT, fragment_shader),
+))
+
+state_set = model.stateSet
+osgx.gltf.shader.configureProgram(program)
+osgx.gltf.shader.configureStateSet(state_set)
+state_set.setAttributeAndModes(
+	program,
+	osg.StateAttribute.ON | osg.StateAttribute.OVERRIDE,
+)
+```
+
+`configureProgram()` binds tangent and skin attributes to the locations populated by the loader.
+`configureStateSet()` maps base-color, normal, ORM, and emissive samplers to the loader's texture
+units. The loader owns the material data; the application still owns its renderer and Program.
+
+`examples/pyosg-voxelize2d.py` is a complete hand-assembled fallback example (its
+`PBR_FALLBACK_FRAGMENT_SHADER`).
+
+## GLSL dependency gotcha
+
+Some generic PBR snippets reference a caller-owned `PI`. Because pragma expansion is literal and
+ordered, declare it before the pragma:
+
+```glsl
+const float PI = 3.14159265359;
+#pragma osgx::pbr D_GGX, G_SCHLICK, G_SMITH
+```
+
+## Direct-light gotcha
+
+`osgx_DirectSpecular()` already includes its `NdotL` factor. Apply `NdotL` to the separate Lambert
+diffuse term, not to the combined diffuse-plus-specular result:
+
+```glsl
+float NdotL = max(dot(N, L), 0.0);
+vec3 diffuse = kD * mat.albedo / PI * NdotL;
+vec3 specular = osgx_DirectSpecular(N, V, L, NdotV, mat.roughness, mat.F0);
+Lo += (diffuse + specular) * lightColor[i] * attenuation;
+```
+
+## One-call PBR/IBL renderer
+
+For a pre-baked environment, load its `osgx_pbribl` manifest and use osgx's optional renderer —
+`PBRIBLEnvironment`/`PBRIBLScene` are classes with static factory methods, not free functions (see
+[`30-pbribl.md`](30-pbribl.md) for the full API, including the shadow/skinning/tonemap `hooks`
+options and the deferred G-buffer variant for many-light scenes):
+
+```python
+model = osgDB.readNodeFile("scene.gltf")
+environment = osgx.gltf.pbribl.PBRIBLEnvironment.load("papermill.gltf")
+scene = osgx.gltf.pbribl.PBRIBLScene.create(model, environment)
+
+if not environment.valid() or not scene.valid():
+	raise RuntimeError("PBR/IBL setup failed")
+
+root = osg.Group()
+
+if environment.root is not None:
+	root.children.append(environment.root)
+
+root.children.append(scene.node)
+```
+
+The environment root must participate in the rendered scene graph when the manifest uses a built-in
+LUT. For a fully dynamic setup, use `PBRIBLEnvironment.prepare("environment.hdr")`; it bakes
+specular, diffuse, and the BRDF LUT from that one source. The helper is IBL-only and does not
+invent authored/direct lights. Generic light rigs remain in `osgx` (see
+[`40-typed-lights-gizmos.md`](40-typed-lights-gizmos.md)); glTF-authored camera and
+`KHR_lights_punctual` support are separate loader work.
+
+Use `examples/pyosg-khronos-viewer.py` (`osgx.gltf.pbribl.PBRIBLScene.create()`'s thin viewer
+consumer) and `/home/cubicool/tmp/khronos/CODEX.md` for authoritative Khronos parity work.

OpenSceneGraph/aipython/09-picking.md

@@ -0,0 +1,90 @@
+# `osgx` + `osgx.imgui`: the mouse-capture race
+
+Sibling to [`07-camera-manual.md`](07-camera-manual.md)'s Rule 3, which
+covers a different, earlier picking fix (window-origin subtraction). This
+file is about `osgx` coexisting with an `osgx.imgui.Widget` panel in
+the same window: three independent guards, all in `~/dev/osgx`
+(`Picking.cpp`/`Picking.hpp`) — needs a rebuild to take effect; check
+`PYOSG_OSGX_SOURCE_DIR` in your build dir's `CMakeCache.txt` first (see the
+repo's `CLAUDE.md`).
+
+Ship all three together. Each closes a different failure mode; removing any
+one reopens a real, reproducible bug.
+
+## Guard 1: `PickHandler` must check `ea.getHandled()` itself
+
+`osgViewer::Viewer::eventTraversal()` calls **every** handler in the list for
+**every** event — it never stops early just because an earlier handler
+returned `true`. Every stock OSG handler
+(`StatsHandler`/`HelpHandler`/the manipulators) opens `handle()` with
+`if (ea.getHandled()) return false;` for exactly this reason. Without the
+same check, `PickHandler` keeps recording mouse position from events an
+`osgx.imgui.Widget` already claimed (`Widget` registers at the front of the
+handler list via `push_front`, so it always runs first for a given event —
+ordering is never the problem here).
+
+## Guard 2: a one-shot `invalidate()` isn't enough — suspend continuously
+
+`PickCameraSync`'s continuous per-frame readback re-samples whatever
+`mouseX()`/`mouseY()` currently is, every frame, regardless of events. Guard
+1 stops `PickHandler` from updating that position while ImGui has capture,
+but the frozen position is still real, valid geometry — so the next
+continuous-readback frame re-detects it as hovered, undoing a single
+`invalidate()` call (visible as flickering tint, not a clean off).
+
+Fix: `PickReadback::setSuspended(bool)`/`isSuspended()`, set from
+`PickHandler::handle()` on every dispatched event, and
+`PickCameraSync::operator()` calls `invalidate()` every frame for as long as
+`isSuspended()` stays true — the same pattern already used for "cursor left
+the OS window" (`platform::isCursorInWindow()`).
+
+## Guard 3: `WantCaptureMouse` itself lags one frame behind the event that set it
+
+The subtlest guard, and the one that survives Guards 1+2. `osgx::imgui::Widget`'s
+MOVE/DRAG handler does, in one call:
+
+```cpp
+io.AddMousePosEvent(ea.getX(), io.DisplaySize.y - ea.getY());
+return io.WantCaptureMouse;
+```
+
+Dear ImGui only *recomputes* `WantCaptureMouse` inside its own `NewFrame()`
+(run later, from `Widget`'s `PreDraw` callback), so this read reflects the
+**previous** frame's hover result. The first MOVE event whose coordinates
+land on an ImGui panel is still judged against the old (still-`false`)
+capture state, so it comes through with `ea.getHandled() == false`.
+`isSuspended()` never gets set for that event, and `PickHandler` stores that
+real but genuinely out-of-viewport coordinate as `mouseX()`/`mouseY()`. If
+the cursor stops moving right there, picking stays pinned to that bad sample
+indefinitely — an inherent one-frame lag in immediate-mode GUI input, not an
+event-ordering bug, so don't re-chase Guard 1/2 if this specific symptom
+recurs.
+
+Fix: a third, purely geometric guard in `PickCameraSync::operator()`, immune
+to the lag because it depends only on this frame's own numbers:
+
+```cpp
+int localX = _rb->mouseX() - originX;
+int localY = _rb->mouseY() - originY;
+bool cursorInViewport = localX >= 0 && localX < width && localY >= 0 && localY < height;
+
+if (!cursorInViewport) _rb->invalidate();
+```
+
+The pick1x1 sub-frustum block only runs when `cursorInViewport` is true;
+otherwise the pick camera gets the plain (un-aimed) projection matrix, since
+nothing downstream observes it.
+
+## Why not JUST the geometric check?
+
+It's tempting to drop Guards 1/2 and rely on Guard 3 alone — simpler, no
+lag, no `ea.getHandled()`/event-chain reasoning. It would even fix a
+fixed-dock ImGui layout, where the dock exactly coincides with "outside
+`camera.viewport`". But a floating/undocked ImGui window, a popup, a
+tooltip, or a context menu drawn ON TOP of the 3D viewport's own rectangle
+puts the cursor geometrically *inside* the viewport while ImGui still
+legitimately has capture — Guard 3 alone waves that through (click-fallthrough
+again), while Guard 1/2's `ea.getHandled()`-driven `isSuspended()` still
+correctly reflects "some handler already claimed this," regardless of screen
+position. Keep both: the event-based guard generalizes across UI layouts, the
+geometric guard closes the timing hole the event-based one cannot.

OpenSceneGraph/aipython/10-rtt.md

@@ -0,0 +1,199 @@
+# Render-to-texture and multi-camera scene graphs, built live
+
+## `osg.Camera()` accepts the same kwargs constructor as `osg.Group`
+
+`osg.Camera(children=(a, b), clearColor=..., renderOrder=..., viewport=...)`
+works — `Camera`'s `kwargs_base` chain (`pyosg/pyosg.hpp`) runs through
+`Transform` → `Group`, so `Group`'s `kwargs_init_own` (which handles
+`children=`) applies to `Camera` too, on top of `Camera`'s own kwargs
+(`viewport`, `clearColor`, `clearMask`, `projectionMatrix`, `viewMatrix`,
+`renderOrder`, `graphicsContext`, `renderTargetImplementation`,
+`allowEventFocus`, `computeNearFarMode`, `nearFarRatio`, draw callbacks —
+see `pyosg/osg/Camera.cpp`). Building without kwargs is still fine:
+
+```python
+cam = osg.Camera()
+cam.children.append(some_node)
+```
+
+## `Group.children.remove()`/`del`/`.pop()` work
+
+`pyx::SequenceTraits<osg::Group>::del()` (`pyosg/osg/Group.hpp` →
+`removeChild()`) backs `SequenceProxy`'s conditional deletable methods
+(`remove`/`pop`/`del`/`clear`):
+
+```python
+rtt_cam.children.remove(model)  # works
+```
+
+If some OTHER `SequenceProxy`-backed container raises `AttributeError` on
+`.remove()`/`.pop()`/`del container[i]`, that type's `SequenceTraits`
+specialization likely doesn't implement `del()` yet — don't assume the whole
+proxy mechanism is broken, check that one type's traits file first.
+
+## PRE_RENDER RTT cameras need `referenceFrame = osg.Transform.ABSOLUTE_RF`
+
+If an RTT camera has its own explicit `viewMatrix`/`projectionMatrix` (not
+meant to inherit the parent's transform — the normal case for an offscreen
+"render this from a fixed angle" pass), set:
+
+```python
+rtt_cam.referenceFrame = osg.Transform.ABSOLUTE_RF
+```
+
+Without this, the RTT camera's own `viewMatrix` (typically a `lookAt` matrix
+with the eye far from the origin) gets composed into the *parent scene's
+bound computation* — `osg::Camera` IS-A `osg::Transform`, and by default
+(`RELATIVE_RF`) a Transform's matrix is applied to its children's bounds when
+computing the parent's overall bound, exactly like `osg::MatrixTransform`.
+This silently produces a wildly wrong combined scene bound, and
+`TrackballManipulator`'s "home" framing ends up looking at nothing — the
+symptom is a screenshot/window that's just solid black or shows nothing
+recognizable, with nothing else actually broken. Confirm by checking
+`root.bound` before/after setting `ABSOLUTE_RF`: it should snap to a sane
+bound matching your *visible* geometry, not something enormous or offset.
+
+Any RTT/shadow-style camera with its own independent view should be
+`ABSOLUTE_RF` (matches `osgx::shadow::ShadowMap::create()`, `~/dev/osgx/src/Shadow.cpp`,
+which sets it on its own `camera` — the Lighting Series' `08-shadows.py` builds
+its shadow pass via `osgx.ShadowMap.create()` rather than a hand-rolled
+`osg.Camera()`).
+
+## A fullscreen-quad pass re-targeted to an FBO renders a single flat color
+
+A fullscreen-quad camera (`ABSOLUTE_RF`, identity view/projection: composite,
+SSAO, bloom, deferred lighting) must own its own depth state:
+
+```python
+cam.stateSet.modes[GL_DEPTH_TEST] = osg.StateAttribute.OFF
+```
+
+Without it, such a pass works only by accident while it draws to the
+backbuffer — the main camera clears depth to 1.0 every frame, so the quad
+happens to pass `GL_LESS`. Re-target that same camera to an FBO
+(`renderOrder = PRE_RENDER` + `attach()`) and OSG attaches an implicit depth
+renderbuffer that a color-only `clearMask` never clears. Undefined depth,
+every fragment discarded, and the attachment keeps only its clear color.
+
+The failure is silent: the FBO is valid, the viewport is right, the draw
+call is issued, no GL errors — reads exactly like a broken shader.
+
+> "It renders fine today" is not evidence a pass owns its depth state — only
+> that something else cleared depth for it. Every backbuffer-only fullscreen
+> pass is a latent instance of this bug; re-targeting is what exposes it.
+
+### Diagnosing a pass that outputs one flat color
+
+1. **Dump the texture and count distinct colors** rather than judging by
+   eye — a "flat gray" that's exactly the *master camera's* clear color
+   repeated proves you're looking at another framebuffer's contents:
+
+   ```python
+   from PIL import Image
+   from collections import Counter
+   px = list(Image.open("dump.png").convert("RGB").getdata())
+   print(len(set(px)), Counter(px).most_common(5))
+   ```
+
+2. **Set a deliberately absurd clear color** (magenta) on the suspect camera
+   — separates "FBO live but nothing drew," "never rendered," and "shaded to
+   black," which are indistinguishable at the default black.
+
+3. **Probe from a draw callback on the pass's own geometry** — proves
+   whether the draw happens at all, and whether an FBO is really bound:
+
+   ```python
+   # GL_DRAW_FRAMEBUFFER_BINDING == 0x8CA6; 0 means the DEFAULT framebuffer
+   ```
+
+4. **Add a temporary flag/toggle to a known-good example** instead of
+   writing a fresh repro, so the A/B differs by exactly one variable in one
+   binary.
+
+### A debug blit must not disable the camera that writes the texture
+
+A "visualize mode" that `nodeMask`s off a pass and then blits that pass's own
+RTT output samples an attachment nothing rendered into this frame —
+undefined, spatially uniform, unaffected by camera movement. That looks
+exactly like a broken render pass and is purely a broken instrument. Toggle
+only cameras that draw to the **backbuffer**; leave every `PRE_RENDER`/FBO
+stage running in all modes.
+
+## Z-up convention: a quad grid built in the XY plane is invisible
+
+This project's examples default to Z-up (`up = (0, 0, 1)` in `lookAt` calls,
+matching `TrackballManipulator`'s default framing along `-Y`). A
+fullscreen/instanced quad grid whose vertex shader writes `vec4(x, y, z, 1.0)`
+with the 2D grid spread across `x`/`y` and depth along `z` lies in the **XY
+plane** — edge-on to the default camera view, reading as a thin,
+nearly-invisible line.
+
+Build the grid in **X/Z**, with the explode-depth axis on **Y**:
+
+```glsl
+// WRONG for this project's Z-up default framing:
+gl_Position = osg_ModelViewProjectionMatrix * vec4(gridX, gridY, depth, 1.0);
+
+// RIGHT:
+gl_Position = osg_ModelViewProjectionMatrix * vec4(gridX, -depth, gridZ, 1.0);
+```
+
+## Verified-working RTT setup shape (`pyosg-rtt.py`)
+
+```python
+cb = osg.Texture2D()
+cb.size = (w, h)
+cb.internalFormat = GL_RGBA
+cb.filter = (osg.Texture.LINEAR, osg.Texture.LINEAR)
+
+db = osg.Texture2D()
+db.size = (w, h)
+db.internalFormat = GL_DEPTH_COMPONENT24
+db.sourceFormat = GL_DEPTH_COMPONENT
+db.sourceType = GL_FLOAT
+db.filter = (osg.Texture.NEAREST, osg.Texture.NEAREST)
+
+cam = osg.Camera()
+cam.renderOrder = osg.Camera.PRE_RENDER
+cam.renderTargetImplementation = osg.Camera.FRAME_BUFFER_OBJECT
+cam.clearMask = GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT
+cam.clearColor = osg.Vec4(0.1, 0.1, 0.1, 1.0)
+cam.viewport = osg.Viewport(0, 0, w, h)
+cam.attach(osg.Camera.COLOR_BUFFER, cb)
+cam.attach(osg.Camera.DEPTH_BUFFER, db)
+# If this camera has its own explicit view — see ABSOLUTE_RF note above:
+cam.referenceFrame = osg.Transform.ABSOLUTE_RF
+cam.viewMatrix = osg.Matrix.lookAt(eye, center, osg.Vec3(0, 0, 1))
+cam.projectionMatrix = osg.Matrix.perspective(40.0, aspect, near, far)
+```
+
+A downstream drawable samples `cb` as an ordinary texture:
+
+```python
+stateSet.textureAttributes[0] = cb
+stateSet.uniforms["someTexUniform"] = 0  # texture UNIT index, not the texture object
+```
+
+## Reparenting a node without disturbing its own transform
+
+If a loaded model (e.g. from glTF) is already an `osg.MatrixTransform`
+holding a real, load-bearing matrix (commonly a Y-up-to-Z-up axis
+conversion), do not overwrite `.matrix` directly to animate it — that
+destroys the conversion. Check first:
+
+```python
+print(model.matrix)  # if this isn't identity, it's doing real work
+```
+
+Wrap it in a new transform dedicated to the animation instead:
+
+```python
+spin_xform = osg.MatrixTransform()
+spin_xform.children.append(model)
+# parent.children.append(spin_xform), not model directly
+spin_xform.updateCallback = lambda node, nv, osg=osg: setattr(
+    node, "matrix", osg.Matrix.rotate(nv.frameStamp.simulationTime * 0.4, osg.Vec3(0, 0, 1))
+)
+```
+
+(See [`01-core.md`](01-core.md) rule 2 for why `osg=osg` is required here.)