Program Listing for File ProxySceneNode.h#
↰ Return to documentation for file (include/Karana/ProxyScene/ProxySceneNode.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 ProxySceneNode class.
*/
#pragma once
#include "Karana/KCore/SharedPointer.h"
#include "Karana/ProxyScene/ClientRegistry.h"
#include "Karana/ProxyScene/ImplDatabase.h"
#include "Karana/Scene/CollisionSceneNode.h"
#include "Karana/Scene/GraphicalSceneNode.h"
#include "Karana/Scene/SceneNode.h"
#include <type_traits>
namespace Karana::Scene {
class ProxyScene;
/**
* @class ProxySceneNode
* @brief SceneNode acting as a proxy for client SceneNodes
*
* See \sref{scene_layer_sec} for more discussion on
* the scene layer.
*/
class ProxySceneNode : virtual public SceneNode {
// For access to _implement/_unimplement
friend ProxyScene;
public:
/**
* @brief ProxySceneNode constructor.
* @param name - Name of the ProxySceneNode.
* @param scene - The Scene to add the node to.
* @param client_registry - Helper to track registered client scenes
* @param impl_database - Helper to track implementations of objects
* for client scenes
*/
ProxySceneNode(std::string_view name,
const Karana::Core::ks_ptr<ProxyScene> &scene,
const Karana::Core::ks_ptr<ClientRegistry> &client_registry,
const Karana::Core::ks_ptr<ImplDatabase> &impl_database);
virtual ~ProxySceneNode();
/**
* @brief Create a ProxyScene node.
* @param name - The name of the ProxySceneNode.
* @param scene - The ProxyScene to add the node to.
* @return The created ProxySceneNode
*/
static kc::ks_ptr<ProxySceneNode> create(std::string_view name,
const Karana::Core::ks_ptr<ProxyScene> &scene);
/**
* @brief Update the transform for all clients if attached to a Frame
*/
virtual void update();
/**
* @brief Update the transform for a client if attached to a Frame
* @param scene - The client to update
*/
virtual void update(Scene &scene);
/**
* @brief Get the implementation for a given client
* @param scene - The client scene
* @return The implementation of this node for the client
*/
const Karana::Core::ks_ptr<SceneNode> &of(Scene &scene) const;
/**
* @brief Get a graphical implementation
* If there is more than one graphical
* implementation only the first one found
* is returned.
*
* @return A graphical implementation or nullptr
*/
Karana::Core::ks_ptr<GraphicalSceneNode> graphics() const;
/**
* @brief Get the graphical implementation for a client
*
* @param scene - The client scene
* @return The graphical implementation or for the client
*/
Karana::Core::ks_ptr<GraphicalSceneNode> graphics(Scene &scene) const;
/**
* @brief Get a collision implementation
* If there is more than one collision
* implementation only the first one found
* is returned.
*
* @return A collision implementation or nullptr
*/
Karana::Core::ks_ptr<CollisionSceneNode> collision() const;
/**
* @brief Get the collision implementation for a client
*
* @param scene - The client scene
* @return The collision implementation or for the client
*/
Karana::Core::ks_ptr<CollisionSceneNode> collision(Scene &scene) const;
void setUnitQuaternion(const Karana::Math::UnitQuaternion &quaternion) override;
void setTranslation(const Karana::Math::Vec3 &translation) override;
void setScale(double scale) override;
void setTransform(const Karana::Math::SimTran &transform) override;
void setVisible(bool visible) override;
/**
* @brief Attach the node to a Frame
* @param parent - The Frame to attach to
* @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
*/
void attachTo(const Karana::Core::ks_ptr<Karana::Frame::Frame> &parent,
bool maintain_world_transform = false);
void attachTo(const Karana::Core::ks_ptr<SceneNode> &parent,
bool maintain_world_transform = false) override;
void detach(bool maintain_world_transform = false) override;
/**
* @brief Get the unique Frame that an ancestor is attached to
* @return The Frame that this node or an ancestor is attached to
*/
const Karana::Core::ks_ptr<Karana::Frame::Frame> &ancestorFrame() const;
protected:
/**
* @brief Create the implementation for a client scene
*
* This is called automatically as needed and shouldn't need to be
* called outside of ProxyScene internals.
*
* @param scene - The client to create an implementation for.
*/
virtual void _implement(Scene &scene);
/**
* @brief Destroy the implementation for a client scene
*
* This is called automatically as needed and shouldn't need to be
* called outside of ProxyScene internals.
*
* @param scene - The client to destroy the implementation for.
*/
virtual void _unimplement(Scene &scene);
/**
* @brief Initialize the state of an implementation
* @param scene - The client the initialize the implementation for.
*/
virtual void _initialize(Scene &scene);
/// Helper to track registered client scenes
Karana::Core::ks_ptr<ClientRegistry> _client_registry;
/// Helper to track implementations
std::weak_ptr<ImplDatabase> _impl_database;
/// The Frame this node is attached to (if any)
Karana::Core::ks_ptr<Karana::Frame::Frame> _parent_frame;
/// Implementations for this node
std::unordered_map<Karana::Core::id_t, Karana::Core::ks_ptr<SceneNode>> _impls;
/**
* @brief Helper to invoke a callback for each implementation
* @param func - The callback function
*/
template <typename Func> void _forEachImpl(Func &&func) const {
constexpr bool accepts_node = std::is_invocable_v<Func, SceneNode &>;
constexpr bool accepts_client_data = std::is_invocable_v<Func, const ClientSceneData &>;
constexpr bool accepts_both =
std::is_invocable_v<Func, SceneNode &, const ClientSceneData &>;
static_assert(accepts_both || accepts_client_data || accepts_node,
"Func must be callable with one of\n\t(SceneNode&)\n\t(const "
"ClientSceneData&)\n\t(SceneNode&, const ClientSceneData&)");
for (auto &[id, impl] : _impls) {
if constexpr (accepts_both) {
const auto &client_data = _client_registry->at(id);
func(*impl, client_data);
} else if constexpr (accepts_client_data) {
const auto &client_data = _client_registry->at(id);
func(client_data);
} else if constexpr (accepts_node) {
func(*impl);
}
}
}
};
} // namespace Karana::Scene