Scene Class

Represents a hierarchical SceneGraph that organizes all renderable and non-renderable objects within a scene. More...

Declaration

class helios::scene::Scene { ... }

Public Constructors Index

	Scene (const Scene &)=delete
	Prevent copying. More...
	Scene (Scene &&) noexcept=default
	Move constructor. More...
	Scene (std::unique_ptr< helios::scene::FrustumCullingStrategy > frustumCullingStrategy)
	Constructs a new Scene. More...
	Scene (std::unique_ptr< helios::scene::FrustumCullingStrategy > frustumCullingStrategy, const helios::engine::modules::scene::types::SceneId sceneId)
	Constructs a new Scene with a specific scene ID. More...

Public Destructor Index

	~Scene ()=default
	Destructor. More...

Public Operators Index

Scene &	operator= (const Scene &)=delete
	Prevent copy assignment. More...
Scene &	operator= (Scene &&) noexcept=default
	Move assignment operator. More...

Public Member Functions Index

SceneNode *	addNode (std::unique_ptr< SceneNode > node) const
	Adds a new SceneNode to this scene. More...
void	updateNodes () const
	Updates the world transformations of SceneNodes in the graph. More...
helios::engine::modules::scene::types::SceneId	sceneId () const noexcept
	Returns the unique identifier for this scene. More...
std::vector< const helios::scene::SceneNode * >	findVisibleNodes (const helios::scene::CameraSceneNode *cameraSceneNode) const
	Applies this Scene's frustumCullingStrategy and returns all nodes visible for the specified CameraSceneNode and its associated `Camera`. More...
helios::scene::SceneNode &	root () const noexcept
	Returns the root node of this Scene. More...
std::optional< Snapshot >	createSnapshot (const rendering::Viewport &viewport) const
	Creates a Snapshot of the Scene and returns it. More...

Private Member Functions Index

void	propagateWorldTransform (SceneNode &node, const math::mat4f &parentWorldTransform) const
	Internal helper function to force-propagate the worldTransformation of SceneNodes to their child nodes. More...
void	updateNodes (SceneNode &node, const math::mat4f &wt) const
	Selectively updates the world transformation of SceneNodes in the scene graph. More...

Private Member Attributes Index

SceneGraphKey	sceneGraphKey_ {}
	SceneGraphKey for internal use. More...
helios::math::mat4f	mat4fid = helios::math::mat4f::identity()
	4x4 identity matrix for internal use. More...
std::unique_ptr< SceneNode >	root_
	The root node of this scene. More...
helios::engine::modules::scene::types::SceneId	sceneId_ {helios::core::types::no_init}
	Unique identifier for this scene. More...
std::unique_ptr< helios::scene::FrustumCullingStrategy >	frustumCullingStrategy_
	The FrustumCullingStrategy used with this Scene. More...

Private Static Attributes Index

static const helios::util::log::Logger &	logger_ = ...
	The logger used with this Scene instance. More...

Description

Represents a hierarchical SceneGraph that organizes all renderable and non-renderable objects within a scene.

Every scene has one implicit root node all nodes are appended to when `addNode` is called.

A Scene is responsible for managing the SceneGraph, consisting of SceneNodes; it provides methods to frustum cull SceneNodes based on a specific `FrustumCullingStrategy` and a particular `CameraSceneNode` and also allows for propagating world transformations through the contained subtrees.

See Also

[RTR, pp. 828]

See Also

[Gre19, pp. 693]

See Also

[HDMS+14, pp. 138]

info

By default, we're not allowing copying/moving Scenes. These constraints may be relaxed in the future, depending on valid use cases.

Definition at line 55 of file Scene.ixx.

Public Constructors

Scene()

helios::scene::Scene::Scene (const Scene &)

delete

Prevent copying.

A Scene is not intended to be copied.

Definition at line 157 of file Scene.ixx.

Reference Scene.

Referenced by operator=, operator=, Scene, Scene, Scene, Scene and ~Scene.

Scene()

helios::scene::Scene::Scene (Scene &&)

noexcept default

Move constructor.

Definition at line 169 of file Scene.ixx.

Reference Scene.

Scene()

helios::scene::Scene::Scene (std::unique_ptr< helios::scene::FrustumCullingStrategy > frustumCullingStrategy)

inline explicit

Constructs a new Scene.

The root node for this scene is automatically created.

Parameters

frustumCullingStrategy

The frustum culling strategy to use with this Scene.

Definition at line 188 of file Scene.ixx.

188 explicit Scene(std::unique_ptr<helios::scene::FrustumCullingStrategy> frustumCullingStrategy) :

189 frustumCullingStrategy_(std::move(frustumCullingStrategy)), root_(std::make_unique<SceneNode>()) {

190

191 root_->setIsRoot(sceneGraphKey_);

192 }

Reference Scene.

Scene()

helios::scene::Scene::Scene (std::unique_ptr< helios::scene::FrustumCullingStrategy > frustumCullingStrategy, const helios::engine::modules::scene::types::SceneId sceneId)

inline explicit

Constructs a new Scene with a specific scene ID.

Parameters

frustumCullingStrategy	The frustum culling strategy to use with this Scene.
sceneId	Unique identifier for this scene.

Definition at line 200 of file Scene.ixx.

200 explicit Scene(

201 std::unique_ptr<helios::scene::FrustumCullingStrategy> frustumCullingStrategy,

202 const helios::engine::modules::scene::types::SceneId sceneId) :

203 Scene(std::move(frustumCullingStrategy))

204 {

205 sceneId_ = sceneId;

206 }

References Scene and sceneId.

Public Destructor

~Scene()

helios::scene::Scene::~Scene ()

default

Destructor.

Definition at line 179 of file Scene.ixx.

Reference Scene.

Public Operators

operator=()

Scene & helios::scene::Scene::operator= (const Scene &)

delete

Prevent copy assignment.

A Scene is not intended to be copied.

Definition at line 164 of file Scene.ixx.

Reference Scene.

operator=()

Scene & helios::scene::Scene::operator= (Scene &&)

noexcept default

Move assignment operator.

Definition at line 174 of file Scene.ixx.

Reference Scene.

Public Member Functions

addNode()

SceneNode * helios::scene::Scene::addNode (std::unique_ptr< SceneNode > node)

inline nodiscard

Adds a new SceneNode to this scene.

The SceneNode becomes a direct descendant of this scene's root.

Parameters

node	The SceneNode to add to this Scene.

Returns

The raw pointer to the newly added node, or `nullptr` if the node was not added.

Definition at line 217 of file Scene.ixx.

217 [[nodiscard]] SceneNode* addNode(std::unique_ptr<SceneNode> node) const {

218 assert(root_ && "Unexpected null-root");

219 if (!root_) {

220 logger_.error("Unexpected nullptr for this Scene's root.");

221 }

222 return root_->addNode(std::move(node));

223 }

createSnapshot()

std::optional< Snapshot > helios::scene::Scene::createSnapshot (const rendering::Viewport & viewport)

inline nodiscard

Creates a Snapshot of the Scene and returns it.

Taking a snapshot will frustum cull the SceneNodes and place their Renderables along with the current matrices of this scene into the Snapshot object. Only those SceneNodes are considered that were configured with a Renderable and have their `isActive`-flag set to true.

Parameters

viewport

The viewport for which the Snapshot is created.

Returns

An optional Snapshot created for this Scene, or `std::nullopt` if creation failed.

Todo

This should be refactored into a factory to prevent domain leakage between Scene and Rendering.

Definition at line 298 of file Scene.ixx.

298 createSnapshot(const rendering::Viewport& viewport) const {

299

300 const auto* cameraSceneNode = viewport.cameraSceneNode();

301

302 if (!cameraSceneNode) {

303 logger_.warn("Viewport was not configured with a camera, skipping createSnapshot()...");

304 return std::nullopt;

305 }

306

307 const auto nodes = findVisibleNodes(cameraSceneNode);

308

309 std::vector<SnapshotItem> renderables;

310 renderables.reserve(nodes.size());

311 for (const auto& node: nodes) {

312 if (node->isActive() && node->hasRenderable()) {

313 renderables.emplace_back(

314 node->renderable(),

315 node->cachedWorldTransform()

316 );

317 }

318 }

319

320 return std::make_optional<Snapshot>(

321 viewport,

322 cameraSceneNode->camera().projectionMatrix(),

323 cameraSceneNode->camera().viewMatrix(),

324 std::move(renderables)

325 );

326 }

References helios::scene::SceneNode::cachedWorldTransform, helios::rendering::Viewport::cameraSceneNode, findVisibleNodes, helios::scene::SceneNode::hasRenderable, helios::scene::SceneNode::isActive and helios::scene::SceneNode::renderable.

findVisibleNodes()

std::vector< const helios::scene::SceneNode * > helios::scene::Scene::findVisibleNodes (const helios::scene::CameraSceneNode * cameraSceneNode)

inline nodiscard

Applies this Scene's frustumCullingStrategy and returns all nodes visible for the specified CameraSceneNode and its associated `Camera`.

This method ensures that all nodes' world geometry is properly updated before culling is applied.

Parameters

cameraSceneNode

The cameraSceneNode used to determine the view frustum for culling.

Returns

A list of currently visible nodes (const pointers into the scene graph).

Definition at line 255 of file Scene.ixx.

255 [[nodiscard]] std::vector<const helios::scene::SceneNode*> findVisibleNodes(

256 const helios::scene::CameraSceneNode* cameraSceneNode

257 ) const {

258 assert(root_ && "Unexpected null-root");

259 if (!root_) {

260 logger_.error("Unexpected nullptr for this Scene's root.");

261 }

262

263 updateNodes();

264

265 return frustumCullingStrategy_->cull(cameraSceneNode, *root_);

266 }

Reference updateNodes.

Referenced by createSnapshot.

root()

helios::scene::SceneNode & helios::scene::Scene::root ()

inline nodiscard noexcept

Returns the root node of this Scene.

The root node is guaranteed to exist.

Returns

The root node of this Scene.

Definition at line 275 of file Scene.ixx.

275 [[nodiscard]] helios::scene::SceneNode& root() const noexcept {

276 assert(root_ && "Unexpected null-root");

277 if (!root_) {

278 logger_.error("Unexpected nullptr for this Scene's root.");

279 }

280 return *root_;

281 }

sceneId()

helios::engine::modules::scene::types::SceneId helios::scene::Scene::sceneId ()

inline nodiscard noexcept

Returns the unique identifier for this scene.

Returns

The SceneId for this scene.

Definition at line 240 of file Scene.ixx.

240 [[nodiscard]] helios::engine::modules::scene::types::SceneId sceneId() const noexcept {

241 return sceneId_;

242 }

Referenced by Scene.

updateNodes()

void helios::scene::Scene::updateNodes ()

inline

Updates the world transformations of SceneNodes in the graph.

The method traverses the Scene and propagates updated world transformations to their respective child nodes if the processed node is considered to be dirty.

Definition at line 231 of file Scene.ixx.

231 void updateNodes() const {

232 updateNodes(*root_, mat4fid);

233 }

Reference updateNodes.

Referenced by findVisibleNodes and updateNodes.

Private Member Functions

propagateWorldTransform()

void helios::scene::Scene::propagateWorldTransform (SceneNode & node, const math::mat4f & parentWorldTransform)

inline

Internal helper function to force-propagate the worldTransformation of SceneNodes to their child nodes.

Propagation is cancelled for this node if the resulting world transform is considered equal to the current world transform of the SceneNode.

Parameters

node	The current SceneNode for which to propagate the world transformation.
parentWorldTransform	The world transformation from the parent node.

See Also

updateNodes()

Definition at line 94 of file Scene.ixx.

94 void propagateWorldTransform(SceneNode& node, const math::mat4f& parentWorldTransform) const {

95

96 // if the worldTransform was not updated,

97 // branch back into selective updates

98 if (!node.applyWorldTransform(parentWorldTransform, sceneGraphKey_)) {

99 for (auto& child: node.children()) {

100 updateNodes(*child, node.cachedWorldTransform());

101 }

102 } else {

103 for (auto& child: node.children()) {

104 propagateWorldTransform(*child, node.cachedWorldTransform());

105 }

106 }

107 }

updateNodes()

void helios::scene::Scene::updateNodes (SceneNode & node, const math::mat4f & wt)

inline

Selectively updates the world transformation of SceneNodes in the scene graph.

A SceneNode is forced to update its own world transformation and the world transformation of its children as soon as a check for the dirty-state of the node is true.

Parameters

node	The current SceneNode processed.
wt	The world transform to apply.

info

It is important that this method is called before the next render pass, or before the scene graph is culled. This method must also consider CameraSceneNodes, making sure the associated `Camera` is updated with the view matrix.

Definition at line 123 of file Scene.ixx.

123 void updateNodes(SceneNode& node, const math::mat4f& wt) const {

124

125 if (node.needsUpdate()) {

126 propagateWorldTransform(node, wt);

127 } else {

128 const auto& parentWt = node.worldTransform();

129 for (auto& child: node.children()) {

130 updateNodes(*child, parentWt);

131 }

132 }

133 }

Private Member Attributes

frustumCullingStrategy_

std::unique_ptr<helios::scene::FrustumCullingStrategy> helios::scene::Scene::frustumCullingStrategy_

The FrustumCullingStrategy used with this Scene.

Definition at line 138 of file Scene.ixx.

138 std::unique_ptr<helios::scene::FrustumCullingStrategy> frustumCullingStrategy_;

mat4fid

helios::math::mat4f helios::scene::Scene::mat4fid = helios::math::mat4f::identity()

4x4 identity matrix for internal use.

Definition at line 69 of file Scene.ixx.

69 helios::math::mat4f mat4fid = helios::math::mat4f::identity();

root_

std::unique_ptr<SceneNode> helios::scene::Scene::root_

The root node of this scene.

All other SceneNodes are (in)direct children of this node.

Definition at line 76 of file Scene.ixx.

76 std::unique_ptr<SceneNode> root_;

sceneGraphKey_

SceneGraphKey helios::scene::Scene::sceneGraphKey_ {}

SceneGraphKey for internal use.

See Also

helios::scene::SceneNode::setWorldTransform()

Definition at line 64 of file Scene.ixx.

64 SceneGraphKey sceneGraphKey_{};

sceneId_

helios::engine::modules::scene::types::SceneId helios::scene::Scene::sceneId_ {helios::core::types::no_init}

Unique identifier for this scene.

Definition at line 81 of file Scene.ixx.

81 helios::engine::modules::scene::types::SceneId sceneId_{helios::core::types::no_init};

Private Static Attributes

logger_

const helios::util::log::Logger& helios::scene::Scene::logger_

static

The logger used with this Scene instance.

Initialiser

= helios::util::log::LogManager::loggerForScope( HELIOS_LOG_SCOPE )

Defaults to HELIOS_LOG_SCOPE.

Todo

constructor injection

Definition at line 147 of file Scene.ixx.

147 inline static const helios::util::log::Logger& logger_ = helios::util::log::LogManager::loggerForScope(

---

The documentation for this class was generated from the following file:

• Scene.ixx

---

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.