Program Listing for File Scene.h#
↰ Return to documentation for file (include/Karana/Scene/Scene.h)
/*
* Copyright (c) 2024-2026 Karana Dynamics Pty Ltd. All rights reserved.
*
* NOTICE TO USER:
*
* This source code and/or documentation (the "Licensed Materials") is
* the confidential and proprietary information of Karana Dynamics Inc.
* Use of these Licensed Materials is governed by the terms and conditions
* of a separate software license agreement between Karana Dynamics and the
* Licensee ("License Agreement"). Unless expressly permitted under that
* agreement, any reproduction, modification, distribution, or disclosure
* of the Licensed Materials, in whole or in part, to any third party
* without the prior written consent of Karana Dynamics is strictly prohibited.
*
* THE LICENSED MATERIALS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.
* KARANA DYNAMICS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
* BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, AND
* FITNESS FOR A PARTICULAR PURPOSE.
*
* IN NO EVENT SHALL KARANA DYNAMICS BE LIABLE FOR ANY DAMAGES WHATSOEVER,
* INCLUDING BUT NOT LIMITED TO LOSS OF PROFITS, DATA, OR USE, EVEN IF
* ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, WHETHER IN CONTRACT, TORT,
* OR OTHERWISE ARISING OUT OF OR IN CONNECTION WITH THE LICENSED MATERIALS.
*
* U.S. Government End Users: The Licensed Materials are a "commercial item"
* as defined at 48 C.F.R. 2.101, and are provided to the U.S. Government
* only as a commercial end item under the terms of this license.
*
* Any use of the Licensed Materials in individual or commercial software must
* include, in the user documentation and internal source code comments,
* this Notice, Disclaimer, and U.S. Government Use Provision.
*/
/**
* @file
* @brief Contains the declarations for the Scene class.
*/
#pragma once
#include "Karana/KCore/BaseWithVars.h"
#include "Karana/KCore/UsageTrackingMap.h"
#include "Karana/Scene/Material.h"
#include "Karana/Scene/SceneNode.h"
#include "Karana/Scene/ScenePart.h"
#include "Karana/Scene/StaticGeometry.h"
namespace Karana::Scene {
class Scene;
/**
* @class SceneVars
* @brief The Vars for the Scene class.
*/
// class SceneVars : public Karana::Core::BaseVars {
class SceneVars : public kc::BaseVars {
public:
/**
* @brief SceneVars constructor. The constructor is not meant to be
* called directly. Please use the create(...) method instead to create
* an instance.
*
* @param scene The Scene associated with this SceneVars.
*/
SceneVars(const kc::ks_ptr<const Scene> &scene);
/**
* @brief Destructor.
*/
~SceneVars();
/**
* @brief Create an instance of the SceneVars.
*
* @param scene The Scene associated with this SceneVars.
* @returns A pointer to the newly created instance of SceneVars.
*/
static kc::ks_ptr<SceneVars> create(const kc::ks_ptr<const Scene> &scene);
/**
* @brief Get all the Vars that this VarHolder has.
*
* @returns A map of Vars, where the Var name is the key and the Var is the value.
*/
kc::NestedVars getAllVars() const override;
/// The number of scene nodes
kc::ks_ptr<Karana::Core::Var_T<int>> num_nodes;
};
/**
* @class Scene
* @brief Base container for a hierarchy of geometries
*
* See \sref{scene_layer_sec} for more discussion on
* the scene layer.
*/
class Scene : public Karana::Core::BaseWithVars {
// For create/discard methods
friend class SceneNode;
friend class ScenePart;
friend class ProxySceneNode;
friend class ProxyScenePart;
// for access to node usage tracking
friend class SceneVars;
protected:
/**
* @brief Scene constructor.
* @param name - Name of the Scene.
*/
Scene(std::string_view name);
public:
/**
* @brief Destructor.
*/
virtual ~Scene();
// Delete copy constructor and assignment operator
Scene(const Scene &) = delete;
Scene &operator=(const Scene &) = delete;
/**
* @brief Get the Scene managing this one
* @return The managing scene or nullptr
*/
Karana::Core::ks_ptr<Scene> getManager() const;
/**
* @brief Assign a managing scene
* @param manager The scene managing this one (nullable)
*/
void setManager(const Karana::Core::ks_ptr<Scene> &manager);
/**
* @brief Get the list of scene nodes in the scene
*
* @return The SceneNodes for this Scene.
*/
const std::vector<kc::ks_ptr<SceneNode>> getSceneNodes() const;
/**
* @brief Get the list of scene parts in the scene
*
* @param layers limit returned list to parts belong to the specified layers
* @return The SceneParts for this Scene.
*/
const std::vector<kc::ks_ptr<ScenePart>> getSceneParts(layer_t layers = LAYER_ALL) const;
/**
* @brief Get the layers that should be created by default
* @return The default layers
*/
virtual layer_t defaultLayers() const;
/**
* @brief Signal that many transform updates are about to occur
*
* This state should be exited by a corresponding
* endTransformUpdates call. Entering this state is reentrant,
* such that nested calls are ignored.
*
* To safely ensure the corresponding endTransformUpdates is
* called, prefer using the TransformUpdateScope class instead.
*/
void beginTransformUpdates();
/**
* @brief Signal the end of a prior beginTransformUpdates call
*
* This state should first be entered by a corresponding
* beginTransformUpdates call. This state is reentrant, such
* that nested calls are ignored.
*
* To safely ensure this is called, prefer using the
* TransformUpdateScope class instead.
*/
void endTransformUpdates();
protected:
Karana::Core::ks_ptr<Karana::Core::BaseVars> _getVars() const override;
/**
* @brief Discard the scene. Derived scenes need to implement this with the logic required
* to discard their scene.
* @param s - A pointer to the scene to discard.
*/
void _discard(Karana::Core::ks_ptr<Karana::Core::Base> &s) override = 0;
/**
* @brief Helper to create a SceneNode.
*
* Derived scenes should implement by calling their
* non-virtual createNode. This is to support
* derived return types.
*
* @param name - Name for the SceneNode.
* @return The created SceneNode.
*/
virtual Karana::Core::ks_ptr<SceneNode> _createNodeBase(std::string_view name) = 0;
/**
* @brief Discard the provided node.
* Derived scenes should implement downcasting and
* calling their non-abstract _discardNodeBase.
* @param node - The node to discard.
*/
virtual void _discardNodeBase(Karana::Core::ks_ptr<SceneNode> &node);
/**
* @brief Helper to create a ScenePart.
*
* Derived scenes should implement by calling their
* non-virtual createPart. This is to support
* derived return types.
*
* @param name - Name of the ScenePart.
* @param geometry - Geometry of the ScenePart.
* @param material - Material of the ScenePart.
* @param layers - Layers bitmask for the ScenePart.
* @return The created ScenePart.
*/
virtual Karana::Core::ks_ptr<ScenePart> _createPartBase(std::string_view name,
const VarStaticGeometry &geometry,
const VarMaterial &material,
layer_t layers) = 0;
/**
* @brief Helper to discard a ScenePart.
*
* Derived scenes should implement downcasting and
* calling their non-abstract _discardPartBase.
*
* @param part - The ScenePart to discard.
*/
virtual void _discardPartBase(Karana::Core::ks_ptr<ScenePart> &part);
/**
* @brief Track the usage of a SceneNode.
* @param node - The SceneNode to track.
*/
void _track(const Karana::Core::ks_ptr<SceneNode> &node);
/**
* @brief Stop tracking the usage of a SceneNode
* @param node - The SceneNode to stop tracking.
*/
void _untrack(Karana::Core::ks_ptr<SceneNode> &node);
/**
* @brief Signal that many transform updates are about to occur
*
* A Scene may implement this to make optimizations, for example
* by waiting until endTransformUpdates is called and doing a
* batch update.
*/
virtual void _doBeginTransformUpdates() {}
/**
* @brief Signal the end of a prior beginTransformUpdates call
*
* A Scene may implement this to make optimizations, for example
* by waiting until endTransformUpdates is called and doing a
* batch update.
*/
virtual void _doEndTransformUpdates() {}
protected:
/// The scene managing this one (if any)
std::weak_ptr<Scene> _manager;
private:
Karana::Core::UsageTrackingMap<Karana::Core::id_t, SceneNode> _node_tracking_map;
unsigned int _transform_updates_depth = 0;
};
} // namespace Karana::Scene