Scene API

Headers: src/scene/scene.h, src/scene/sceneGraph.h, src/scene/camera.h, src/scene/sceneLoader.h
Namespace: glitter::scene

---

glitter::scene::SceneGraph

The live, in-memory scene hierarchy. A tree of SceneNodes that tracks where everything lives in the world. Manages cameras and provides traversal utilities. Retrieve via engine::sceneGraph().

Node management

Member	Returns	Description
root()	SceneNode&	The root node (always present; no object attached)
addNode(name, obj?)	SceneNode&	Add a named top-level node parented to root; optionally attach a SceneObject
addNode(name, shared_ptr<SceneObject>)	SceneNode&	Add a top-level node with a shared-ownership object
addNode(parent, name, obj?)	SceneNode&	Add a named node as a child of parent
findNode(name)	SceneNode*	BFS find by name; returns nullptr if not found

Camera management

Member	Returns	Description
setActiveCamera(cameraNode)	void	Designate a node as the active camera
activeCamera()	SceneNode*	Current active camera node (nullptr if none set)
allCameras()	std::vector<SceneNode*>	All nodes whose object is a Camera instance

Ambient light

Member	Returns	Description
setAmbientColor(color)	void	Set the scene-wide ambient light colour (glm::vec3)
ambientColor()	const glm::vec3&	Current ambient colour

State & traversal

Member	Returns	Description
clear()	void	Remove all nodes (except a fresh root), reset the active camera and ambient colour
traverse(visitor)	void	Depth-first pre-order traversal. Calls visitor(SceneNode&) for every node including root.

---

glitter::scene::Scene

Factory and weak-ref cache for scene objects. Retrieve via engine::scene().

Constructor

Methods

Member	Returns	Description
loadSceneObject(schemaUri)	unique_ptr<SceneObject>	Load a fresh (uncached) scene object from a model descriptor URI. GPU upload is the caller's responsibility.
addSceneObject(schemaUri)	shared_ptr<SceneObject>	Load a scene object and register it in the internal weak-ref cache. Subsequent calls with the same URI return the live shared instance; GPU data is only uploaded once.

---

glitter::scene::SceneLoader

Reads a scene JSON file and populates a SceneGraph. Retrieve indirectly via engine::loadScene(), or construct directly to unit-test in isolation using a stub ModelFactory.

Types

src/scene/sceneLoader.h

// Called for every "model" node. May return nullptr to skip the node.
using ModelFactory = std::function<std::shared_ptr<SceneObject>(const uri<void>&)>;

Constructor

src/scene/sceneLoader.h

SceneLoader(resources& res, SceneGraph& graph, ModelFactory modelFactory)

Methods

Member	Returns	Description
load(sceneUri)	expected<LoadedScene, string>	Parse and load the scene JSON at the given URI. Returns LoadedScene on success or an error string on failure.
parseTransform(nodeJson) (static)	glm::mat4	Parse the optional "transform" block from a node JSON object into a matrix. Exposed for unit testing.

LoadedScene

Field	Type	Description
settings	SceneSettings	Scene-wide settings (ambient colour, etc.)
activeCamera	SceneNode*	Non-owning pointer to the node flagged as active camera (nullptr if none)
environmentUri	optional<string>	URI string of the IBL environment descriptor, if one was specified in the scene
environmentBlur	float	Skydome blur amount from "properties": { "blur": … } (defaults to 0.0)

SceneSettings

Field	Type	Default	Description
ambient	glm::vec3	{0.04, 0.05, 0.08}	Scene-wide ambient light colour

---

glitter::scene::Camera

Perspective camera component. Attached to a SceneNode when the scene loader encounters a "camera" node. View and projection matrices are computed from the owning node's world transform.

Constructor

src/scene/camera.h

explicit Camera(PerspectiveParams params = {})

Methods

Member	Returns	Description
viewMatrix(worldTransform)	glm::mat4	Compute the view matrix as inverse(worldTransform)
projectionMatrix(aspectRatio)	glm::mat4	Compute the perspective projection matrix
setParams(params)	void	Replace the perspective parameters
params()	const PerspectiveParams&	Read the current perspective parameters

PerspectiveParams

Field	Type	Default	Description
fovDegrees	float	75.0	Vertical field of view in degrees
nearPlane	float	0.1	Near clip plane distance
farPlane	float	100.0	Far clip plane distance
focalLength	optional<float>	nullopt	Focal length in mm (overrides fovDegrees when both focalLength and sensorSize are set)
sensorSize	optional<glm::vec2>	nullopt	Sensor dimensions in mm [width, height]
aperture	float	2.8	f-stop (used for depth-of-field and exposure)
focusDistance	float	1e6	Focus distance in metres
exposureCompensation	float	0.0	Exposure compensation in EV