Program Listing for File FrameCollider.h#
↰ Return to documentation for file (include/Karana/Collision/FrameCollider.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 FrameCollider class and the FrameContact struct.
*/
#pragma once
#include "Karana/Frame/Frame.h"
#include "Karana/KCore/SharedPointer.h"
#include "Karana/ProxyScene/ProxyScene.h"
#include "Karana/Scene/CollisionScene.h"
#include "Karana/Scene/CollisionScenePart.h"
#include <functional>
namespace Karana::Collision {
/// Data for a contact between a pair of Frames
struct FrameContact {
/// The first Frame involved in the contact
Karana::Core::ks_ptr<Karana::Frame::Frame> frame_1;
/// The first CollisionScenePart involved in the contact
Karana::Core::ks_ptr<Karana::Scene::CollisionScenePart> part_1;
/// Contact location on the first Frame relative to the first Frame and expressed in the
/// first frame
Karana::Math::Vec3 location_1;
/// Contact normal expressed first Frame
Karana::Math::Vec3 normal_1;
/// The second Frame involved in the contact
Karana::Core::ks_ptr<Karana::Frame::Frame> frame_2;
/// The second CollisionScenePart involved in the contact
Karana::Core::ks_ptr<Karana::Scene::CollisionScenePart> part_2;
/// Contact location on the second Frame relative to the second Frame and expressed in the
/// second frame
Karana::Math::Vec3 location_2;
/// Contact normal expressed second Frame
Karana::Math::Vec3 normal_2;
/// Maximum penetration distance
float penetration;
};
/**
* @class FrameCollider
* @brief Helper to bridge CollisionScene collisions to Frames
*
* See \sref{collision_dynamics_sec} for more discussion on
* contact and collision dynamics.
*/
class FrameCollider {
public:
/// Type alias for collision handler callbacks
using col_func = std::function<void(const FrameContact &)>;
/// Type alias for collision filter callbacks
using filter_func = std::function<bool(const Karana::Scene::CollisionScenePart &,
const Karana::Scene::CollisionScenePart &)>;
/**
* @brief FrameCollider constructor.
* @param proxy_scene - The ProxyScene managing the CollisionScene
* @param collision_scene - The CollisionScene instance
*/
FrameCollider(const Karana::Core::ks_ptr<Karana::Scene::ProxyScene> &proxy_scene,
const Karana::Core::ks_ptr<Karana::Scene::CollisionScene> &collision_scene);
/**
* @brief FrameCollider copy constructor.
* @param other - The FrameCollider to copy.
*/
FrameCollider(const FrameCollider &other) = default;
/**
* @brief FrameCollider copy assignment operator.
* @param other - The FrameCollider to copy.
* @return This FrameCollider.
*/
FrameCollider &operator=(const FrameCollider &other) = default;
virtual ~FrameCollider();
/**
* @brief Process all collisions
*
* Sweeps through all contacts between geometries attached to Frames,
* calling the collision handler for each unfiltered contact.
*
* @param collision_handler - Callback to handle a contact
* @param filter - Callback to skip potential collisions in the
* broadphase.
*/
void collide(col_func collision_handler, filter_func filter = nullptr);
/**
* @brief Get the Frame that a CollisionScenePart is attached to
* @param part - A CollisionScenePart managed by ProxyScene
* @return The ancestor Frame for the part.
*/
Karana::Core::ks_ptr<Karana::Frame::Frame>
lookupPartFrame(const Karana::Scene::CollisionScenePart &part);
/**
* @brief Get the Frame that a CollisionScenePart is attached to
* @param id - The id of a CollisionScenePart managed by ProxyScene
* @return The ancestor Frame for the part.
*/
Karana::Core::ks_ptr<Karana::Frame::Frame> lookupPartFrame(Karana::Core::id_t id);
/**
* @brief Ignore collisions between a pair of frames
* @param frame1 The first frame in the pair
* @param frame2 The second frame in the pair
*/
void ignoreFramePair(const Karana::Core::ks_ptr<Karana::Frame::Frame> &frame1,
const Karana::Core::ks_ptr<Karana::Frame::Frame> &frame2);
/**
* @brief Stop ignoring collisions between a pair of frames
* @param frame1 The first frame in the pair
* @param frame2 The second frame in the pair
*/
void unignoreFramePair(const Karana::Core::ks_ptr<Karana::Frame::Frame> &frame1,
const Karana::Core::ks_ptr<Karana::Frame::Frame> &frame2);
/**
* @brief Call ignoreFramePair for each pair with a collision
*/
void ignoreAllCurrentlyTouchingPairs();
/**
* @brief Stop ignoring any frame-pair collisions
*/
void clearIgnoredFramePairs();
/**
* @brief Return the ProxyScene used by this FrameCollider.
*
* @returns The ProxyScene used by this FrameCollider.
*/
const Karana::Core::ks_ptr<Karana::Scene::ProxyScene> &getProxyScene() const;
/**
* @brief Return the CollisionScene used by this FrameCollider.
*
* @returns The CollisionScene used by this FrameCollider.
*/
const Karana::Core::ks_ptr<Karana::Scene::CollisionScene> &getCollisionScene() const;
private:
Karana::Core::ks_ptr<Karana::Scene::ProxyScene> _proxy_scene;
Karana::Core::ks_ptr<Karana::Scene::CollisionScene> _collision_scene;
Karana::Core::ks_ptr<class CollisionFilter> _filter;
};
} // namespace Karana::Collision