OpenSceneGraph 0.1.2__cp313-cp313-win_amd64.whl

OpenSceneGraph/aipython/40-typed-lights-gizmos.md

@@ -0,0 +1,218 @@
+# osgx typed direct lights (`osgx.LightSet`) + light gizmos
+
+Check `git log -1 -- src/osgx/PBR.hpp` in the configured osgx source dir (see
+the repo's `CLAUDE.md` on `PYOSG_OSGX_SOURCE_DIR`) if anything here looks
+stale — this describes an SSBO-backed contract that may still be uncommitted
+in some checkouts.
+
+## What this is
+
+`osgx::pbr::LightSet` (C++: `src/osgx/PBR.hpp`/`src/PBR.cpp`, Python:
+`osgx.LightSet`) is a typed direct-light rig. Per-light data
+(`osgx.MAX_LIGHTS` == 6 slots) lives in a single `std430` Shader Storage
+Buffer Object (`osgx_LightBuffer`/`osgx_lights[]`, binding 3 — C++
+`osgx::LIGHT_BINDING`, not currently exposed to Python) plus one
+`osgx_lightCount` uniform — not parallel flat uniform arrays. Three real
+types — Point, Directional, Spot — plus a "Sphere" light that is NOT a
+fourth type: it's `setPoint(..., sourceRadius>0)`, see below.
+
+Every consumer shader reaches the light array through one hook call,
+**`osgx_DirectLighting(N, V, worldPos, mat)`** — declared by
+`osgx.DIRECT_LIGHTING_DECL` (splice into your fragment shader's
+`#pragma osgx::pbr ...` line, alongside `MATERIAL_STRUCT`) and defined by
+`osgx.DIRECT_LIGHTING_HOOK_DEFAULT`, a second self-contained FRAGMENT
+shader object added to the same `Program`.
+`osgx.makeDirectLightingHookShader()` returns that shader object ready
+to append:
+
+```python
+program = osg.Program(name="my-shader", shaders=(
+	osg.Shader(osg.Shader.VERTEX, vertex_source),
+	osg.Shader(osg.Shader.FRAGMENT, osgx.resolveShaderLibs(fragment_source)),
+	osgx.makeDirectLightingHookShader(),
+))
+```
+
+This is the same "hook" pattern `osgSlug` uses: a base shader owns `main()`
+and only *declares* a fixed entry point; each consumer supplies — or accepts
+the library default for — that entry point's definition as a separate
+compiled shader object. It exists so the per-light dispatch loop lives in
+exactly one place instead of being hand-copied into every consumer's
+`main()`.
+
+`osgx::LightGizmos`/`osgx::LightMarkers` (C++: `src/osgx/Gizmos.hpp`/
+`src/Gizmos.cpp`, Python: `osgx.LightGizmos`/`osgx.LightMarkers` — flat under
+`osgx`, not a `gizmo` submodule) are the matching debug visualization: real
+depth-tested marker geometry for point/sphere/spot, plus a non-depth-tested
+overlay for directional (which has no position to place a marker at). Both
+take a live `osgx.LightSet` directly and read it through its typed
+accessors (`getCount`/`getType`/`getPosIntensity`/`getColor`/`getDirection`/
+`getSpotAngles`/`getSourceRadius`).
+
+## Minimal live REPL setup
+
+```python
+lights = osgx.LightSet.create(root.stateSet)  # allocates the SSBO buffer (size MAX_LIGHTS, zero-initialized) + osgx_lightCount on root.stateSet
+
+lights.setCount(1)  # how many of the 6 slots osgx_DirectLighting()'s loop actually reads this frame
+
+# Point -- inverse-square falloff, ideal (zero-size) specular highlight
+lights.setPoint(0, osg.Vec3(2.5, -2.5, 6.0), osg.Vec3(0.85, 0.55, 0.30), 12.0)
+
+# Directional -- "travel direction" (KHR_lights_punctual convention), no position, no falloff
+lights.setDirectional(0, osg.Vec3(0.2, 0.4, -1.0), osg.Vec3(0.75, 0.70, 0.60), 3.0)
+
+# Spot -- cone-attenuated point light; angles in RADIANS (use math.radians(), no osg.DegreesToRadians)
+import math
+lights.setSpot(
+	0, osg.Vec3(0.0, -4.0, 8.0), osg.Vec3(0.0, 1.0, -0.35), osg.Vec3(0.95, 0.85, 0.65),
+	40.0, math.radians(15.0), math.radians(32.0),
+)
+
+# Sphere -- NOT a separate call: setPoint(..., sourceRadius>0). Widens the SPECULAR highlight only
+# (Karis/UE4 representative-point trick) -- diffuse falloff is deliberately IDENTICAL to a plain
+# point light at the same position/intensity. Has visibly ZERO effect on a fully rough/matte
+# surface -- that's expected, not a bug.
+lights.setPoint(0, osg.Vec3(2.5, -2.5, 6.0), osg.Vec3(0.85, 0.55, 0.30), 12.0, sourceRadius=0.7)
+
+# Read back any field live:
+lights.getType(0), lights.getPosIntensity(0), lights.getColor(0), lights.getSourceRadius(0)
+```
+
+`LightSet.create()` REPLACES the SSBO buffer + `osgx_lightCount` on that
+StateSet — don't call it twice on the same live StateSet if you've already
+populated lights there, or you'll zero it out. To WRAP an already-populated
+StateSet's LightSet instead, construct `osgx.LightSet()` and set `.ss`
+directly — `LightSet` has exactly one field (`ss`); the setters/getters
+mutate the SSBO/uniforms that `ss` already carries, there is no separate
+`.lights` handle to assign:
+
+```python
+lights = osgx.LightSet()
+lights.ss = already_populated_stateset
+```
+
+A rig-building helper (`pyosg-match4-dice.py`'s `add_torch_rig()`):
+
+```python
+def add_torch_rig(stateset, torches):
+	"""Build an osgx.LightSet on `stateset` from (position, intensity, color) tuples."""
+	lights = osgx.LightSet.create(stateset)
+
+	for i, (pos, intensity, color) in enumerate(torches):
+		lights.setPoint(i, osg.Vec3(*pos), osg.Vec3(*color), intensity)
+
+	lights.setCount(len(torches))
+
+	return lights
+```
+
+## Gizmos
+
+`osgx.LightGizmos` is itself an `osg.Group` — construct it and add the one
+instance to the scene graph; its constructor already parents both the marker
+geometry and the directional overlay as its own children, so don't also
+add `.markers`/`.overlay` separately:
+
+```python
+gizmos = osgx.LightGizmos(lights, root, 0.4, 10.0)  # (LightSet, scene node for directional's bound-sizing, minMarkerRadius, spotConeLength)
+
+root.children.append(gizmos)
+```
+
+`.markers` (an `osgx.LightMarkers`) and `.overlay` (an `osg.Camera`) are
+read-only properties for reaching the two pieces individually — e.g. to
+toggle visibility:
+
+- `gizmos.markers`' point/spot markers are real scene geometry and DO get
+  depth-occluded by actual room geometry (no shadow-mapping in this system,
+  so occlusion only affects the debug marker's visibility, never the shading
+  math). Keep test-light Z below the real ceiling if you want to see the
+  marker.
+- `gizmos.overlay` is unaffected (`GL_DEPTH_TEST` off, `POST_RENDER`).
+- Toggle `gizmos.markers.nodeMask = 0` / `gizmos.overlay.nodeMask = 0` to
+  hide them without removing them.
+- `LightGizmos::computeBound()` is overridden to always return an empty
+  bound — gizmo geometry deliberately never affects `TrackballManipulator`
+  auto-fit/`home()` or cull's near/far, even though the overlay's own
+  plane/arrow are sized larger than the scene it annotates.
+
+## Live ImGui control panel
+
+`osgx.imgui`'s Python bindings are function-style wrappers (`slider_float`,
+`color_edit3`, `checkbox`, `radio_group`, `button`, `text`, `separator`,
+`input_text` — all return `(changed, *new_values)` tuples), not the raw C++
+`ImGui::` namespace. There is no `SliderFloat3`, `PushID`/`PopID`, or
+`SameLine`. Build a vec3 control from three `slider_float` calls, and give
+every widget label a `##<section-scope>` suffix — `Panel::draw()` only
+`PushID`s a section when `options.expand=True`, so plain sections share one
+global Dear ImGui id namespace and identical labels across sections (every
+light type has a "Position"/"Color"/"Intensity") fight over the same drag
+state without the suffix.
+
+Working shape — one collapsible section per light type, an
+Activate/Deactivate button driving a single shared "live" `LightSet` slot,
+sliders scoped per section:
+
+```python
+import math
+
+active_slot = 0  # the ONLY light -- lightCount stays 0 until a section is Activated
+
+class LightsState:
+	def __init__(self):
+		self.active_demo = None
+		self.point_position = [2.5, -2.5, 6.0]
+		self.point_color = [0.85, 0.55, 0.30]
+		self.point_intensity = 12.0
+		# ... directional_*, sphere_* (+radius), spot_* (+direction, inner/outer deg, source_radius)
+
+state = LightsState()
+
+def apply_state():
+	if state.active_demo is None:
+		lights.setCount(0)
+		return
+	lights.setCount(1)
+	if state.active_demo == "Point":
+		lights.setPoint(active_slot, osg.Vec3(*state.point_position), osg.Vec3(*state.point_color), state.point_intensity)
+	# ... Directional -> setDirectional, Sphere -> setPoint(..., sourceRadius=...), Spot -> setSpot(...)
+
+def point_section(ri):  # addSection()'s callback always takes one osg.RenderInfo arg, even if unused
+	# activate_button(name): text("ACTIVE"/"(inactive)") + Activate/Deactivate osgx.imgui.button(),
+	# calling apply_state() on either. Every widget label carries a "##point"-style scope suffix.
+	# vec3_sliders(prefix, scope, values, lo, hi): three osgx.imgui.slider_float() calls, one per axis.
+	activate_button("Point")
+	changed = vec3_sliders("Position", "ptpos", state.point_position, -10.0, 10.0)
+	c, r, g, b = osgx.imgui.color_edit3("Color##pt", *state.point_color)
+	state.point_color[:] = [r, g, b]
+	changed = changed or c
+	c, v = osgx.imgui.slider_float("Intensity##pt", state.point_intensity, 0.0, 30.0)
+	state.point_intensity = v
+	changed = changed or c
+	if changed and state.active_demo == "Point": apply_state()
+
+# directional_section / sphere_section / spot_section follow the same shape
+# (Sphere adds a "Source Radius" slider 0..3; Spot adds Direction, Inner/Outer
+# Cone (deg), Source Radius, and clamps inner < outer so GLSL's
+# smoothstep(cos(outer), cos(inner), ...) stays well-formed).
+
+lights = osgx.LightSet.create(root.stateSet)
+gizmos = osgx.LightGizmos(lights, root, 0.4, 10.0)
+root.children.append(gizmos)
+
+gui = osgx.imgui.Widget(viewer)
+gui.addSection("Directional", directional_section)
+gui.addSection("Point", point_section)
+gui.addSection("Sphere", sphere_section)
+gui.addSection("Spot", spot_section)
+```
+
+## Known gaps
+
+No `HookList`-style helper (mirroring osgSlug's `HookList`) yet for composing
+multiple fragment-stage hooks on one Program — `osgx_DirectLighting()` is the
+first hook, added by hand since there's only one so far. `PBRIBL.cpp`'s
+`evaluateIBL()` and the final tonemap/composite step are candidates for the
+same treatment once a real second consumer needs to override one
+specifically.

OpenSceneGraph/examples/__init__.py

@@ -0,0 +1,24 @@
+"""Curated, runnable examples installed with the OpenSceneGraph wheel.
+
+Each module here exposes ``build_scene(width, height) -> osg.Node`` and, optionally,
+``configure_viewer(viewer, root)``; see ``OpenSceneGraph.examples.__main__`` (the
+implementation behind the ``pyosg`` console script) for the shared runner that drives both
+hooks. Every module is also directly runnable on its own, e.g.
+``python -m OpenSceneGraph.examples.mrt``.
+
+This is a small, curated subset of the full example sandbox in the project's `examples/`
+source directory -- not everything there implements the build_scene()/configure_viewer()
+contract (yet), and most of that directory (the Lighting Series, GLSL experiments, data
+files, etc.) isn't meant to ship in the wheel at all.
+"""
+
+import sys as _sys
+from pathlib import Path as _Path
+
+# A couple of these examples do a bare `from pyosg_visitor import GatherVisitor` rather than
+# a package-relative import, matching how they're written to also run standalone straight out
+# of the project's examples/ directory (see pyosg-cli). Put this package's own directory on
+# sys.path so that resolves the same way here.
+_sys.path.insert(0, str(_Path(__file__).parent))
+
+del _sys, _Path

OpenSceneGraph/examples/__main__.py

@@ -0,0 +1,143 @@
+"""CLI backing the `pyosg` console script and `python -m OpenSceneGraph.examples <name>`.
+
+Runs one of this package's example modules standalone (no Qt, no aipython) by creating a
+bare osgViewer.Viewer, calling the example's build_scene(w, h), and its
+configure_viewer(viewer, root) if it defines one. Adapted from the pyosg-cli
+proof-of-concept in the project's repository root, which loads examples by file path out of
+examples/ instead -- useful for the full example sandbox, most of which doesn't implement
+this module's build_scene()/configure_viewer() contract (yet).
+"""
+
+import argparse
+import importlib
+import pkgutil
+import sys
+
+from OpenSceneGraph import *
+
+
+def _load_module(name):
+	try:
+		return importlib.import_module(f"OpenSceneGraph.examples.{name}")
+
+	except ModuleNotFoundError as error:
+		# Only turn failure to locate the requested example itself into the
+		# friendly availability list. A ModuleNotFoundError raised by one of the
+		# example's own imports is a real diagnostic and must not be disguised as
+		# an unknown runner name.
+		if error.name != f"OpenSceneGraph.examples.{name}":
+			raise
+
+		import OpenSceneGraph.examples as _examples
+
+		# pyosg_* are shared helper modules (pyosg_example, pyosg_visitor, pyosg_repl,
+		# pyosg_dice), not runnable examples -- they have no build_scene() and were never meant
+		# to appear here, same reason a leading "_" is already excluded.
+		available = sorted(
+			mod.name for mod in pkgutil.iter_modules(_examples.__path__)
+			if not mod.name.startswith("_") and not mod.name.startswith("pyosg_")
+		)
+
+		sys.exit(f"error: no such example: {name!r} (available: {', '.join(available)})")
+
+
+def run_module(module, width=800, height=600, extra_argv=(), name=None):
+	"""Shared runner core: viewer construction, window setup, build_scene()/configure_viewer(),
+	and the frame loop. Deliberately takes an already-loaded module object rather than a name --
+	`run()` below loads it from the installed OpenSceneGraph.examples package, while pyosg-cli
+	(repo root) loads an arbitrary examples/*.py file by path and calls this directly, so the
+	actual viewer-setup/frame-loop logic exists in exactly one place instead of two copies that
+	can silently drift (this bit pyosg-cli once already -- see PYOSG_BUILD_PACKAGE_OVERLAY/
+	setUpViewInWindow ordering history in project_pyosg_contract_conversion for the pyosg-
+	polyhaven.py --hdr bug that ordering mismatch caused)."""
+
+	if not hasattr(module, "build_scene"):
+		sys.exit(f"error: {name or module.__name__} has no build_scene(w, h)")
+
+	viewer = osgViewer.Viewer()
+
+	# Explicit window setup, driven by the same width/height build_scene() receives -- a single
+	# source of truth instead of every example hardcoding its own OSG_WINDOW env var string that
+	# has to be kept in sync by hand (and silently isn't, the moment --width/--height differs from
+	# an example's own hardcoded default). x/y match the "50 50 ..." every example's old OSG_WINDOW
+	# used.
+	viewer.setUpViewInWindow(50, 50, width, height)
+
+	viewer.cameraManipulator = osgGA.TrackballManipulator()
+
+	# Sandbox sys.argv for the duration of both hook calls below: some examples (e.g.
+	# blur's create_scene()) read sys.argv[1] lazily, from inside build_scene() itself, not
+	# just at module-import time. extra_argv forwards e.g. `pyosg blur -- foo.gltf` through
+	# to the example's own sys.argv[1:], matching `python -m OpenSceneGraph.examples.blur
+	# foo.gltf`.
+	saved_argv = sys.argv
+
+	sys.argv = [name or module.__name__, *extra_argv]
+
+	try:
+		root = module.build_scene(width, height)
+
+		viewer.sceneData = root
+
+		if hasattr(module, "configure_viewer"):
+			module.configure_viewer(viewer, root)
+
+	finally:
+		sys.argv = saved_argv
+
+	viewer.TODO()
+
+	# KNOWN ISSUE, deliberately not "fixed" with a sleep() here -- see feedback_runner_unthrottled_loop
+	# for the full writeup. Short version: a sleep() here treats the symptom (starves anything else
+	# on the process needing the GIL on a regular cadence, confirmed via audible clicking in
+	# pyosg-animusic-grid.py's sounddevice callback thread); the real fix under consideration is
+	# releasing the GIL inside viewer.frame()'s own pybind11 binding instead.
+	while not viewer.done:
+		viewer.frame()
+
+
+def run(name, width=800, height=600, extra_argv=()):
+	module = _load_module(name)
+
+	run_module(module, width, height, extra_argv, name=name)
+
+
+def main():
+	parser = argparse.ArgumentParser(
+		prog="pyosg",
+		description="Run an OpenSceneGraph.examples module standalone, no Qt required"
+	)
+
+	parser.add_argument("name", help="Example module name, e.g. 'mrt' for OpenSceneGraph.examples.mrt")
+	parser.add_argument("--width", type=int, default=800)
+	parser.add_argument("--height", type=int, default=600)
+
+	# Split on the FIRST literal "--" ourselves, before argparse ever sees it, and hand it
+	# only the part before that. argparse.add_argument("extra", nargs="*") looks like the
+	# obvious way to do this instead, but has a real, confirmed bug: "mrt -- foo.osgt" parses
+	# fine, but "mrt --width 640 -- foo.osgt" fails with "unrecognized arguments: -- foo.osgt"
+	# -- a known CPython argparse limitation around "--" interacting with a nargs="*"
+	# positional when other flags are interspersed, not something fixable by reordering our
+	# own argument definitions.
+	#
+	# KNOWN FRICTION (deferred, not fixed, same as pyosg-cli): every one of the target example's
+	# own arguments -- including its OWN required positionals/flags -- has to go after this "--",
+	# since this parser only knows about name/--width/--height. A `parse_known_args()`-based
+	# two-pass parse could remove the need for "--" in the common case; not attempted, needs real
+	# testing against the SAME argparse quirk documented above first.
+	argv = sys.argv[1:]
+
+	if "--" in argv:
+		i = argv.index("--")
+		own_argv, extra_argv = argv[:i], argv[i + 1:]
+
+	else:
+		own_argv, extra_argv = argv, []
+
+	args = parser.parse_args(own_argv)
+
+	run(args.name, args.width, args.height, extra_argv)
+
+
+if __name__ == "__main__":
+	main()