OpenSceneGraph 0.1.2__cp313-cp313-win_amd64.whl

OpenSceneGraph/aipython/11-mrt.md

@@ -0,0 +1,104 @@
+# Multiple render targets, depth, and pass timing
+
+`pyosg-mrt.py` proves one geometry pass writing multiple color attachments;
+`pyosg-guided-blur.py` builds on that with normal/depth-guided post-processing.
+Read this before treating a G-buffer depth texture as a simple linear distance
+field.
+
+## Raw depth is correct, but it is not linear distance
+
+Attach depth normally and let the geometry pass write it through the ordinary
+depth test:
+
+```python
+cam.attach(osg.Camera.COLOR_BUFFER0, paint_tex)
+cam.attach(osg.Camera.COLOR_BUFFER1, normal_tex)
+cam.attach(osg.Camera.DEPTH_BUFFER, depth_tex)
+```
+
+The sampled `depth_tex` value is post-projection depth. It is excellent for
+visibility and has most precision near the camera, but comparing two samples
+as though `abs(a - b)` were a world-space distance gives depth-dependent
+results. A post-process needs the near/far parameters from the *same effective
+projection* that wrote the texture:
+
+```glsl
+float linearizeDepth(float d, float znear, float zfar) {
+	float z = d * 2.0 - 1.0;
+	return (2.0 * znear * zfar) / (zfar + znear - z * (zfar - znear));
+}
+```
+
+The raw-depth display may be nearly white; that is normal perspective-depth
+distribution, not proof the attachment is empty. Always expose both a raw
+depth debug view and a linear-depth debug view while bringing up a pass.
+
+## OSG's nominal camera projection is not necessarily the depth projection
+
+`viewer.camera.projectionMatrix` commonly remains the nominal lens (for
+example `0.1 - 1000`), while cull traversal tightens the actual projection
+used for a camera pass to improve depth precision. Do not use the nominal
+matrix to linearize an RTT depth texture when the pass uses OSG's automatic
+near/far computation.
+
+The reliable observation point is the depth-writing camera's **post-draw**
+callback: its `RenderInfo::State` still holds the cull-adjusted projection,
+and later render-order passes can consume uniforms updated there. Pre-draw is
+too early; its state can still be the preceding pass's projection.
+
+```python
+def update_depth_parameters(ri):
+	_fovy, _aspect, near, far = ri.state.projectionMatrix.getPerspective()
+	composite.stateSet.uniforms["znear"] = float(near)
+	composite.stateSet.uniforms["zfar"] = float(far)
+
+gbuffer_cam.postDrawCallback = update_depth_parameters
+```
+
+For a later guided blur, use a relative difference so the control has a stable
+meaning across distance:
+
+```glsl
+float delta = abs(zCenter - zSample) / max(zCenter, 0.001);
+float depthWeight = exp(-delta * depthRejection);
+```
+
+Use the same continuous shape for normal rejection. `pow(dot(N0, N1),
+strength)` has a misleading zero special case: any positive strength rejects a
+perpendicular sample completely, making `0` look like a binary mode switch.
+This bilateral form makes strength zero genuinely disable the guide and raises
+rejection smoothly:
+
+```glsl
+float normalDifference = 1.0 - clamp(dot(centerNormal, sampleNormal), 0.0, 1.0);
+float normalWeight = exp(-normalDifference * normalRejection);
+```
+
+## Draw callback slots have one owner
+
+`osg::Camera` has one pre-draw and one post-draw callback slot. Assigning
+`camera.preDrawCallback = other` replaces the existing callback; it does not
+append or compose it. `osgx.imgui.Widget` installs its own `PreDraw` and
+`PostDraw` callbacks on its configured draw camera during initialization, so
+installing another callback on that same camera before constructing the Widget
+silently loses it (and releases the replaced callback immediately).
+
+Use `osgx.CallbackGroup` when multiple systems must share a draw slot, or put
+a pass-specific callback on the pass camera instead. In the guided-blur
+example, the G-buffer camera's post-draw callback is the better location: it
+cannot collide with the Widget's composite-camera callbacks and it sees the
+right projection at the right time.
+
+## G-buffer debugging order
+
+When a depth-aware pass looks wrong, establish these facts in order:
+
+1. The raw depth attachment changes with the scene (`depthTex` debug view).
+2. The live `znear`/`zfar` values are not constructor defaults.
+3. Linearized depth has visible structure before tuning any rejection slider.
+4. With normal rejection at zero, depth rejection alone changes overlap/layer
+   behavior; then test normal rejection independently.
+
+Do not node-mask the G-buffer camera to inspect a later pass: its texture then
+contains no current-frame data. Keep every producer pass running and switch
+only the final backbuffer composite's display mode.

OpenSceneGraph/aipython/12-gbuffer.md

@@ -0,0 +1,48 @@
+# G-buffer contracts and deferred composition
+
+A G-buffer is a geometry pass that stores reusable per-visible-pixel data for
+later passes. It is not inherently PBR, IBL, glTF, or lighting: normal/depth
+guided blur, outlines, SSAO, watercolor diffusion, and deferred lighting can
+all consume the same kind of attachments.
+
+## Keep stored data canonical; derive interpretations in consumers
+
+Store the native depth attachment as raw depth. A consumer that needs linear
+camera distance should request the camera depth parameters and linearize it;
+one needing a full view-space position can reconstruct it from depth plus an
+inverse projection, or use a deliberately stored position attachment. This
+keeps `osgx::GBuffer` neutral and lets each pass choose the representation its
+algorithm actually needs.
+
+Likewise, normals are a geometric guide rather than an outline instruction.
+A guided blur can compare `dot(centerNormal, sampleNormal)` to preserve a
+crease, while an NPR edge pass can turn that same difference into an ink line.
+
+## Minimal useful layout
+
+The smallest general deferred/post-process layout is often:
+
+```text
+COLOR_BUFFER0  paint/albedo/working color
+COLOR_BUFFER1  view-space normal
+DEPTH_BUFFER   native visibility depth
+```
+
+Add attachments only for a demonstrated consumer: material factors for
+deferred PBR, emissive data for lighting, position for algorithms where
+reconstruction is inconvenient or too imprecise, IDs for picking, and so on.
+`pyosg-mrt.py` proves simultaneous color writes; `pyosg-guided-blur.py` proves
+the first downstream normal/depth-aware pass.
+
+## Deferred pipeline shape
+
+```text
+geometry -> G-buffer attachments
+G-buffer -> one or more RTT post-process passes
+all results -> final POST_RENDER composite/debug display
+```
+
+Every RTT producer must remain enabled while a later pass samples it. Debug
+by changing the final composite output, not by disabling the producer whose
+texture you are trying to inspect. For depth timing and callback ownership,
+read [`11-mrt.md`](11-mrt.md).

OpenSceneGraph/aipython/15-shader-hotswap.md

@@ -0,0 +1,72 @@
+# Live GLSL hot-swapping for shader-side debugging
+
+For debugging shader-side logic in a live REPL session, patch the actual GLSL
+source and hot-swap a new `osg.Program` onto the live node's `StateSet` —
+don't reimplement the shader's math in Python/NumPy and compare numbers.
+Matrix-convention mistakes (row vs. column vector, upload transpose) are easy
+to get subtly wrong reimplementing shader math by hand; a live edit that
+visualizes the GPU's *actual* computation (e.g. color-coding which branch of
+an `if` a fragment took) sidesteps that ambiguity.
+
+Find the `Program`'s owning node — often a child `Geode`, not the `Camera`
+itself (the shader is typically attached to the fullscreen-quad `Geode`, not
+the camera's own `StateSet`). Then, live in the REPL:
+
+```python
+src = COMPOSITE_FRAGMENT_SHADER  # the original global string
+assert src.count(marker) == 1  # a non-unique match silently patches the wrong occurrence
+src2 = src.replace(marker, patched_substring, 1)
+p = osg.Program(shaders=(
+    osg.Shader(osg.Shader.VERTEX, FULLSCREEN_VERTEX),
+    osg.Shader(osg.Shader.FRAGMENT, src2)
+))
+node.stateSet.setAttributeAndModes(p, osg.StateAttribute.ON | osg.StateAttribute.OVERRIDE)
+```
+
+No restart needed, no loss of current camera position/state.
+
+To prove the old `Program`/`Shader`s actually got destroyed (not just
+detached), add `debug=True` to each constructor call — see
+[`20-object-lifetime.md`](20-object-lifetime.md). Requires the type to be
+wired into `kwargs_init`; check the manifest if `debug=` raises a constructor
+mismatch instead of trusting the swap-and-drop-the-old-ref pattern on faith.
+
+## The deeper trap: a live variable reassignment silently not reaching the running callback
+
+Two layers, both real:
+
+**Layer 1 — wrong variable.** A per-frame callback may read a
+closure-captured local from setup time (e.g. `light_proj`, captured when the
+callback was defined) rather than the live object property it looks like it
+should read (e.g. `shadow_cam.projectionMatrix`, which may have since
+changed). Reassigning the object property silently no-ops if the callback
+never reads it. Grep the actual callback body for what it reads — don't
+assume based on the object's name alone.
+
+**Layer 2 — even the right variable name can fail.** Reassigning the correct
+bare name (`light_proj = new_value`) at the prompt — even via
+`exec(open(path).read())` — can silently fail to reach the namespace a
+running callback actually reads from, **despite `globals() is
+callback.__globals__` printing `True`**. Verify via
+`callback.__globals__['light_proj']` showing a different `id()` than a bare
+`light_proj` lookup in the same command before trusting a "fix had zero
+effect" conclusion.
+
+The reliable pattern — write through the callback's own `__globals__`
+explicitly:
+
+```python
+cb = shadow_cam.preDrawCallback
+g = cb.__globals__          # the namespace the callback ACTUALLY reads from
+g['light_proj'] = new_value
+g['shadow_cam'].projectionMatrix = new_value  # keep any live object property in sync too
+```
+
+Then re-verify by rebuilding the dependent live GPU uniform from `g[...]`
+and diffing it against the actual uniform value before drawing any
+conclusion from the visual result.
+
+See [`01-core.md`](01-core.md) rule 2 for the related but distinct
+free-variable `NameError` trap — that one is about a name never resolving at
+all; this one is about a name resolving to a *stale* value in a namespace
+that looks, but isn't, the same one.

OpenSceneGraph/aipython/17-particles.md

@@ -0,0 +1,189 @@
+# Building GPU-only, one-shot particle/burst effects live
+
+Patterns for instanced GPU effects (fire, explosions, shockwaves — a swarm of
+quads driven by a formula) built live via REPL. First built out in
+`examples/pyosg-fire.py`; design/TODO for that specific effect lives in
+`ai/context-todo-particles.md`, not here — this file is the reusable
+technique.
+
+## 1. Per-instance "seed" data: hash `gl_InstanceID`, don't reach for an SSBO
+
+If per-instance data (emission direction, size variance, phase) is
+read-once and never changes after upload, derive it from `gl_InstanceID`
+with an in-shader hash instead of an SSBO + CPU-side random buffer:
+
+```glsl
+float hash11(float p) {
+	p = fract(p * 0.1031);
+	p *= p + 33.33;
+	p *= p + p;
+	return fract(p);
+}
+
+vec4 hash14(float p) {
+	return vec4(hash11(p+0.13), hash11(p+7.71), hash11(p+23.9), hash11(p+91.7));
+}
+```
+
+No buffer object, no numpy RNG array, no upload step. An SSBO earns its keep
+only once something actually *writes* per-instance state over time (a
+compute-shader velocity sim, or multiple independently-triggered effects each
+needing their own origin) — not just to read constants once.
+
+## 2. One-shot triggering: a plain `triggerTime` uniform, not a looping `fract()`
+
+For an effect that fires once, drive it from `osg_SimulationTime`
+(auto-provided every frame) and a single `triggerTime` uniform, defaulted far
+in the past so it's invisible until triggered:
+
+```glsl
+uniform float osg_SimulationTime;
+uniform float triggerTime = -1000.0;
+uniform float duration = 1.2;
+
+float t = (osg_SimulationTime - triggerTime) / duration; // NOT fract()'d
+```
+
+An envelope like `smoothstep(0,0.08,t) * (1-smoothstep(0.5,1.0,t))` doubles
+as both the grow/shrink curve and the "invisible before t=0 and after t=1"
+gate — no separate visibility toggle needed.
+
+```python
+def trigger(node, viewer):
+	node.stateSet.uniforms["triggerTime"] = float(viewer.frameStamp.simulationTime)
+```
+
+Bind number keys to different nodes/presets (`osgGA.GUIEventHandler`,
+`ea.type == osgGA.GUIEventAdapter.KEYDOWN`, `ea.key == ord("1")`) for
+instant hands-on comparison of variants.
+
+## 3. Additive-blend saturation dominates the read of the effect — tune it first
+
+With a few hundred instances overlapping in a small screen area under
+`BlendFunc(GL_ONE, GL_ONE)`, even modest per-quad brightness sums to solid
+white fast:
+
+- Weight any secondary color-driving term (e.g. a height-based bias) low
+  relative to the primary noise term — `n * 1.0 + heightBias * 0.15`, not
+  `heightBias * 0.5`. Too high washes out noise detail into a flat blob.
+- Multiply final alpha by a damping factor (~0.5–0.6) so one quad's
+  contribution stays below full brightness, leaving room for overlaps to sum
+  into mid-ramp colors instead of instantly clipping white.
+
+## 4. A Program hot-swap does NOT reset uniforms already bound on the StateSet
+
+Extends [`15-shader-hotswap.md`](15-shader-hotswap.md). Swapping just the
+`Program` (`setAttributeAndModes(newProgram, ON|OVERRIDE)`) leaves any
+uniform already explicitly set from Python (`ss.uniforms["duration"] = 2.5`)
+bound on the StateSet — it silently overrides the new shader's own
+`uniform float duration = 1.2;` GLSL default. If a hot-swap changes intended
+defaults, explicitly re-set every uniform that changed.
+
+Reading a uniform's current value back out is `.value`, not `.getFloat()` or
+index `[0]`: `fire.stateSet.uniforms["duration"].value`.
+
+## 5. Verifying a fast one-shot effect: force a known `t`, don't chase real-time screenshots
+
+A `duration=1.2s` burst is easy to miss with `capture_framebuffer()` (see
+[`01-core.md`](01-core.md) rule 6). Set `triggerTime` to a known offset in
+the past instead of triggering "now" and hoping the capture lands mid-animation:
+
+```python
+now = float(viewer.frameStamp.simulationTime)
+node.stateSet.uniforms["triggerTime"] = now - 0.4  # force t ~= 0.4/duration, right now
+```
+
+For a flat/ground-plane effect (a shockwave ring, anything not billboarded),
+also consider the default trackball angle can leave it nearly edge-on and
+hidden behind a brighter overlapping effect — a temporary top-down
+`viewer.camera.viewMatrix = osg.Matrix.lookAt(...)` (gets overwritten by the
+live `CameraManipulator` next frame, so capture immediately after) rules that
+out before assuming the geometry is broken.
+
+## 6. `del viewer.eventHandlers[i]` can corrupt a LATER handler's Python identity
+
+With `[DebugHandler, HandlerA, HandlerB]`, `del viewer.eventHandlers[1]`
+leaves a surviving `HandlerB` that comes back from `__getitem__` as a bare
+base-class `osgGA.GUIEventHandler` — Python-side attributes set in its own
+`__init__` are gone, and its `handle()` override silently stops firing
+(falls back to the C++ base no-op). Not yet root-caused.
+
+**Workaround:** overwrite in place instead of delete —
+`viewer.eventHandlers[i] = new_handler` preserves identity correctly. Avoid
+`del`-ing a middle element of `eventHandlers` if anything after it needs to
+keep working.
+
+## 7. Don't guard a MappingProxy assignment with an existence check first
+
+`ss.uniforms[key] = value` already creates-or-updates on its own
+(`UniformsTag::apply()` in `pyosg/osg/State.hpp`). Writing
+`if key in ss.uniforms: ss.uniforms[key] = value` makes the assignment
+*conditional on the uniform already existing* — silently no-ops a node's
+very first trigger, since construction only sets the GLSL default, not a
+real bound uniform, until something actually assigns to it. An unconditional
+assignment through a `MappingProxy`/`ValueMappingProxy` is already the safe,
+correct form; adding an existence check in front of it is closer to
+introducing a bug than preventing one.
+
+## 8. Nested one-shot effects need a recursive `trigger()`, not a deeper positional walk
+
+When a builder wraps several effect groups in per-position
+`MatrixTransform`s — one level deeper than a flat 2–4 child layout a
+`trigger(node, viewer)` originally assumed — recurse to leaf nodes instead of
+adding a depth parameter:
+
+```python
+def trigger(node, viewer):
+	now = float(viewer.frameStamp.simulationTime)
+
+	def walk(n):
+		if isinstance(n, osg.Group):
+			for child in n.children:
+				walk(child)
+		else:
+			n.stateSet.uniforms["triggerTime"] = now
+
+	walk(node)
+```
+
+Strict superset of flat-layout behavior, and handles arbitrarily deeper
+nesting for free.
+
+## 9. Multi-instance variety: randomize kwargs per instance, not shared state
+
+When every tunable parameter is already "just a kwarg that flows straight to
+a uniform," giving each instance independently `random.uniform()`-jittered
+kwargs at construction time is close to free — prefer N independently
+parameterized instances of an existing single-instance builder over one
+shared preset placed N times, when the builder is already kwargs-shaped.
+
+## 10. Extending a deliberately-minimal ImGui "bin": add a knob only when needed
+
+`osgx.imgui` is intentionally not a general Dear ImGui wrapper — a small,
+fixed set of "knob" primitives (`slider_float`, `checkbox`, `radio_group`,
+...) each returning a `(changed, value)` tuple, since Python values aren't
+mutable references the way ImGui's C++ `&value` out-params expect. Add a
+primitive only when a concrete control is needed:
+
+- `button(label) -> bool`
+- `color_edit3(label, r, g, b) -> (changed, r, g, b)`
+
+Both are one-line `ImGui::` wrappers in `~/dev/osgx/src/ImGui.cpp` +
+`ext/python/osgx-imgui.cpp`, no new C++ classes. **C++-first, as always**
+(see [[feedback_cpp_first_design]]): the primitive lives in `osgx::imgui`
+proper, Python just calls it.
+
+Two sliders in *different* panel sections sharing the exact same label
+collide on the same ImGui ID — `Panel::draw()` only wraps a section in
+`PushID` when `expand=True`, so a naive per-layer helper reusing the raw
+uniform name as the label (`"duration"` for fire, shockwave, smoke, embers
+alike) silently merges all four sliders' drag state. Fix: prefix every
+control label with its section name ("Fire Duration", "Shockwave Duration", ...).
+
+A slider that *reads* a uniform's `.value` needs that uniform to already
+exist on the `StateSet` (unlike writing, reading is not create-or-update).
+Fragment-only tuning knobs that were only ever given a GLSL default (never
+assigned from Python) don't exist as a real uniform the first time a slider
+section tries to read them. Fix: seed every slider's uniform to its known
+default once, unconditionally, right before building the section — not a
+guarded "if missing" check (same antipattern as point 7, on the read side).

OpenSceneGraph/aipython/18-deterministic-captures.md

@@ -0,0 +1,157 @@
+# Deterministic captures of time-driven GPU effects
+
+`capture_framebuffer()` makes the GL context current; it does **not** choose
+which instant of an animation gets rendered. Triggering an effect and racing
+a capture against the next `viewer.frame()` is inherently unreliable.
+
+The fix is an effect-local clock with two modes: normal playback derives
+elapsed time from `osg_SimulationTime - triggerTime`; inspection playback
+supplies an explicit elapsed age in seconds.
+
+## Shader contract
+
+Add a uniform whose negative value means "use realtime":
+
+```glsl
+uniform float osg_SimulationTime;
+uniform float triggerTime = -1000.0;
+uniform float effectAge = -1.0;
+
+float elapsed = effectAge >= 0.0 ? effectAge : osg_SimulationTime - triggerTime;
+float t = clamp(elapsed / duration, 0.0, 1.0);
+```
+
+Use `elapsed`, not `osg_SimulationTime`, for **every** time-varying part of
+the effect that needs to match the captured instant: movement, noise scroll,
+flicker, size envelopes, fragment breakup. Freezing only the normalized `t`
+while a noise lookup still uses realtime leaves the result nondeterministic.
+
+Seed the uniform from Python during construction:
+
+```python
+ss.uniforms["effectAge"] = -1.0
+```
+
+## Trigger and scrub helpers
+
+For a nested effect, recurse to drawable-owning leaves. Starting realtime
+playback must explicitly clear a previously frozen age:
+
+```python
+def trigger(node, viewer):
+	now = float(viewer.frameStamp.simulationTime)
+
+	def walk(n):
+		if isinstance(n, osg.Group):
+			for child in n.children:
+				walk(child)
+		else:
+			n.stateSet.uniforms["effectAge"] = -1.0
+			n.stateSet.uniforms["triggerTime"] = now
+
+	walk(node)
+
+def set_age(node, effect_age):
+	"""Freeze at elapsed seconds; pass a negative value to resume realtime."""
+
+	def walk(n):
+		if isinstance(n, osg.Group):
+			for child in n.children:
+				walk(child)
+		else:
+			n.stateSet.uniforms["effectAge"] = effect_age
+
+	walk(node)
+```
+
+Age is measured in seconds rather than normalized phase, so layers with
+different durations stay synchronized to one source event: at age `1.2`,
+every layer evaluates itself 1.2 seconds after the trigger and applies its
+own duration naturally.
+
+## Live capture workflow
+
+In a tmux-backed `pyosg_repl.py` session, freeze the effect, then use the
+controller's queued capture (not a top-level `readPixels()`):
+
+```python
+set_age(effect, 1.2)
+await _osg_repl_controller.capture_framebuffer("/tmp/effect-age-1.2.png")
+```
+
+If a person may be at the same keyboard/mouse while this runs, wrap it in
+`_osg_repl_controller.locked_input()` (`examples/pyosg_repl.py`'s
+`AgentInputLock`) — otherwise a keypress that re-triggers or mutates the
+effect can land on the same frame as `set_age()`/the capture, unfreezing the
+very state being inspected:
+
+```python
+with _osg_repl_controller.locked_input():
+	set_age(effect, 1.2)
+	await _osg_repl_controller.capture_framebuffer("/tmp/effect-age-1.2.png")
+```
+
+To prove determinism rather than just eyeball a screenshot, capture the same
+frozen frame twice after letting realtime frames advance in between, then
+compare the files outside the REPL:
+
+```python
+with _osg_repl_controller.locked_input():
+	set_age(effect, 1.2)
+	await _osg_repl_controller.capture_framebuffer("/tmp/effect-a.png")
+	await asyncio.sleep(0.5)
+	await _osg_repl_controller.capture_framebuffer("/tmp/effect-b.png")
+```
+
+```bash
+sha256sum /tmp/effect-a.png /tmp/effect-b.png
+cmp -s /tmp/effect-a.png /tmp/effect-b.png
+```
+
+This proves only the frozen nodes are deterministic. To capture a whole
+composite effect, every visible time-driven layer must implement the same
+clock contract; hide or freeze unrelated animated scenery, UI, camera shake,
+and particle layers before comparing capture bytes.
+
+## Short realtime video captures
+
+For a short MP4 rather than a one-off PNG, use the model-controls facade's
+callback-driven recorder:
+
+```python
+_osg_repl_controls.capture.video("/tmp/take.mp4", fps=24, duration=5)
+```
+
+It samples in the final-draw callback on a monotonic wall-clock schedule and
+streams raw RGB frames directly to FFmpeg. Good for recording a user's live
+camera manipulation because the call returns immediately and leaves input
+unlocked by default. Pass `lock_input=True` when a script is posing the
+camera or updating uniforms and a human must not race it:
+
+```python
+_osg_repl_controls.capture.video(
+	"/tmp/deterministic-take.mp4",
+	fps=24,
+	duration=5,
+	lock_input=True,
+)
+```
+
+For a reproducible video, first set every time-driven visible effect to its
+explicit age (and keep unrelated animation frozen) before starting the
+recorder. The video sampler controls *which wall-clock moments are
+captured*; it does not make shader time deterministic by itself.
+
+Readback still uses synchronous `osg.Image.readPixels()` in the final-draw
+callback — not yet a PBO/fence-backed asynchronous GPU transfer.
+
+## Realtime handoff
+
+After inspecting an age, either resume the existing effect with
+`set_age(effect, -1.0)` or restart it with `trigger(effect, viewer)`. Prefer
+the latter when the effect may already have elapsed past its duration.
+
+`examples/pyosg-praxis.py` is the current minimal working reference. Promote
+this contract into `pyosg-fire.py` only as a coherent change across its
+fire, shockwave, smoke, and ember shaders — a partial conversion gives a
+misleading "frozen" composite whose remaining layers still race realtime.

OpenSceneGraph/aipython/20-object-lifetime.md

@@ -0,0 +1,77 @@
+# Object introspection and lifetime debugging
+
+Every `osg::Object` subclass in these bindings exposes a small cluster of
+introspection primitives — for "what is this node actually holding" and "did
+this object actually get destroyed," not just serialization.
+
+## `.dumps()` — OSGT text serialization
+
+```python
+print(node.dumps().decode())
+```
+
+Verifies what attributes, textures, and state are actually attached to a
+node/geometry without a separate viewer or tool. Works on live objects
+mid-session.
+
+## `.addr` — the real C++ memory address
+
+A `void*` to the actual object, not a vtable-offset pointer. Use to confirm
+two Python handles refer to the *same* underlying C++ object (`a.addr ==
+b.addr`) rather than two separate wrappers, or to correlate with addresses
+printed by C++-side `osg::notify()` output.
+
+## `.referenceCount` — `RefCounts(cpp=N, py=M)`
+
+The real OSG-side `ref_ptr` count and the Python-side refcount, separately.
+
+**The `py` count is artificially inflated inside an interactive IPython
+session** — `Out[]` history caching, `_`/`__`/`___`, and other REPL
+bookkeeping can hold references you didn't intentionally keep. A high `py`
+count does not by itself mean a leak. Removing an object from a scene graph
+container only drops *one* `cpp` ref; if a Python variable (or `Out[]`
+history) still points at it, the object stays fully alive.
+
+## `debug=True` / `debug=<callable>` — ground-truth destruction proof
+
+Pass as a kwarg to an `osg.Object`-derived constructor to attach a lifetime
+probe via the object's `UserDataContainer`:
+
+```python
+node = osg.Node(debug=True)                    # notify()'s "Observing"/"Destroying"
+node = osg.Node(debug=lambda addr, type_, name, deletions=deletions: ...)  # custom callback
+```
+
+**Only works for types wired into the binding layer's `kwargs_init` chain**
+(see `pyosg/pyosg.hpp`'s manifest — `kwargs_base<T>` + each type's own
+`kwargs_init_own`). Most `osg::Object` subclasses are, but it isn't automatic
+just from deriving from `osg::Object` in C++ — a type hand-written with plain
+`py::init<...>()` overloads silently rejects `debug=` (and `name=`,
+`dataVariance=`) with a constructor-overload-mismatch error rather than a
+clear "unsupported kwarg" message. If `debug=`/`name=` fails with
+`incompatible constructor arguments`, check whether the type is in that
+manifest before assuming the probe itself is broken.
+
+Since the probe lives inside the target's own `UserDataContainer`, its
+destructor fires at true C++ destruction — not "removed from the scene
+graph," not "Python variable went out of scope." This is the ground-truth
+tool for verifying an object is actually gone, as opposed to inferring it
+from refcounts alone.
+
+**The `debug=<callable>` callback is subject to the exact same
+cross-context free-variable `NameError` as any other C++-invoked Python
+callback** (see [`01-core.md`](01-core.md) rule 2) — bind anything it needs
+as a default argument: `def on_delete(addr, type_, name, deletions=deletions):
+...`. This applies even though the trigger here is an ordinary Python
+refcounting/GC destructor call on the main thread, not the render loop or any
+background thread.
+
+## How to combine these when investigating a leak
+
+1. `.dumps()` to see what's really attached.
+2. `.addr` + `.referenceCount` together to distinguish "detached from the
+   scene graph" (a removed-but-still-Python-referenced object shows `cpp` >
+   0) from "actually destroyed."
+3. `debug=` when you need proof, not inference — especially when the bug
+   might be in the binding layer itself (proxy/container implementation),
+   not application code.