Program Listing for File SceneNode.h#
↰ Return to documentation for file (include/Karana/Scene/SceneNode.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 SceneNode class.
*/
#pragma once
#include "Karana/KCore/Base.h"
#include "Karana/KCore/DataCache.h"
#include "Karana/KCore/RegistryList.h"
#include "Karana/KCore/SharedPointer.h"
#include "Karana/Math/Defs.h"
#include "Karana/Math/SimTran.h"
#include "Karana/Math/UnitQuaternion.h"
namespace Karana::Scene {
class Scene;
/**
* @class SceneNode
* @brief Base for objects with a transform i n the scene hierarchy
*
* See \sref{scene_layer_sec} for more discussion on
* the scene layer.
*/
class SceneNode : public Karana::Core::Base {
protected:
/**
* @brief SceneNode Constructor.
* @param name - Name of the node.
* @param scene - The scene to add the node to.
*/
SceneNode(std::string_view name, const Karana::Core::ks_ptr<Scene> &scene);
public:
virtual ~SceneNode();
/**
* @brief Create a scene node.
* @param name - Name of the node.
* @param scene - The scene to add the node to.
* @return Shared pointer to a scene node
*/
static Karana::Core::ks_ptr<SceneNode> create(std::string_view name,
const Karana::Core::ks_ptr<Scene> &scene);
/**
* @brief Discard the given SceneNode non-recursively. Calling discard on
* a scene node will discard it and all of its children, which is the normal
* desired behavior. This specialized method will discard the node, but not
* its children.
* @param node - The node to discard
*/
static void discardNonRecursive(Karana::Core::ks_ptr<SceneNode> &node);
/**
* @brief Get position of the node relative to its parent
* @return The relative translation
*/
const Karana::Math::Vec3 &getTranslation() const;
/**
* @brief Set position of the node relative to its parent
* @param translation - The relative translation
*/
virtual void setTranslation(const Karana::Math::Vec3 &translation);
/**
* @brief Get rotation of the node relative to its parent
* @return The relative rotation as a unit quaternion
*/
const Karana::Math::UnitQuaternion &getUnitQuaternion() const;
/**
* @brief Set rotation of the node relative to its parent
* @param quaternion - The relative rotation as a unit quaternion
*/
virtual void setUnitQuaternion(const Karana::Math::UnitQuaternion &quaternion);
/**
* @brief Get uniform scale of the node relative to its parent
* @return The relative uniform scale
*/
double getScale() const;
/**
* @brief Set uniform of the node relative to its parent
* @param scale - The relative uniform scale
*/
virtual void setScale(double scale);
/**
* @brief Get similarity transform of the node relative to its parent
* @return The similarity transform
*/
const Karana::Math::SimTran &getTransform() const;
/**
* @brief Set similarity transform of the node relative to its parent
* @param transform - The similarity transform
*/
virtual void setTransform(const Karana::Math::SimTran &transform);
/**
* @brief Get similarity transform of the node relative to the scene's root
* @return The similarity transform
*/
const Karana::Math::SimTran &getWorldTransform() const;
/**
* @brief Get translation of the node relative to the scene's root
* @return The translation
*/
const Karana::Math::Vec3 &getWorldTranslation() const;
/**
* @brief Get rotation of the node relative to the scene's root
* @return The rotation as a unit quaternion
*/
const Karana::Math::UnitQuaternion &getWorldUnitQuaternion() const;
/**
* @brief Get uniform scale of the node relative to the scene's root
* @return The uniform scale
*/
double getWorldScale() const;
/**
* @brief Get the parent node
* @return The parent node or nullptr
*/
const Karana::Core::ks_ptr<SceneNode> &parent() const;
/**
* @brief Attach to a parent node
* @param parent - The parent node
* @param maintain_world_transform - If true, update the node's
* relative transform so that its overall world transform doesn't
* change after attaching it to the parent
*/
virtual void attachTo(const Karana::Core::ks_ptr<SceneNode> &parent,
bool maintain_world_transform = false);
/**
* @brief Detach the node from its parent
* @param maintain_world_transform - If true, update the node's
* relative transform so that its overall world transform doesn't
* change after detaching
*/
virtual void detach(bool maintain_world_transform = false);
/**
* @brief Get the node's children
* @return A list of the node's children
*/
Karana::Core::RegistryList<SceneNode> children();
/**
* @brief Set whether the object is visible
* @param visible - The visibility flag
*/
virtual void setVisible(bool visible);
/**
* @brief Get whether the object is visible
* @return The visibility flag
*/
bool getVisible() const;
/**
* @brief Get a SceneNode managing this one
* @return The managing scene node or nullptr
*/
Karana::Core::ks_ptr<SceneNode> getManager() const;
/**
* @brief Assign a managing scene node
* @param manager The scene node managing this one (nullable)
*/
void setManager(const Karana::Core::ks_ptr<SceneNode> &manager);
protected:
/**
* @brief Helper to compute the node's world transform
* @param transform - The new relative transform
*/
virtual void _computeWorldTransform(Karana::Math::SimTran &transform) const;
/// Cache to lazily recompute the world transform as needed
Karana::Core::ks_ptr<Karana::Core::DataCache<Karana::Math::SimTran>> _world_transform_cache;
/**
* @brief Discard the provided SceneNode.
* @param base - Base pointer to the SceneNode to discard.
*/
void _discard(Karana::Core::ks_ptr<Base> &base) override;
/// The SceneNode managing this one (if any)
std::weak_ptr<SceneNode> _manager;
/// Weak pointer to the scene. Used for discard.
std::weak_ptr<Scene> _scene;
private:
Karana::Math::SimTran _object_transform{};
Karana::Core::ks_ptr<SceneNode> _parent{};
Karana::Core::RegistryList<SceneNode> _children{};
bool _visible = true;
};
} // namespace Karana::Scene