Program Listing for File CoalScene.h#
↰ Return to documentation for file (include/Karana/CoalScene/CoalScene.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 CoalScene class.
*/
#pragma once
#include "Karana/CoalScene/CoalGeometryCache.h"
#include "Karana/CoalScene/CoalSceneFileObject.h"
#include "Karana/CoalScene/CoalSceneNode.h"
#include "Karana/CoalScene/CoalScenePart.h"
#include "Karana/KCore/SharedPointer.h"
#include "Karana/Scene/CollisionInfo.h"
#include "Karana/Scene/CollisionScene.h"
#include "Karana/Scene/Material.h"
#include "Karana/Scene/StaticGeometry.h"
#include <memory>
namespace coal {
class BroadPhaseCollisionManager; // forward declaration. Full class included in the cc file.
}
namespace Karana::Scene {
class CoalScenePart; // forward declare. Full class included in the cc file.
/**
* @class CoalScene
* @brief CollisionScene implementation using the COAL library
*
* See \sref{scene_layer_sec} for more discussion on
* the scene layer.
*/
class CoalScene : public CollisionScene {
// Access needed for create/discard
friend class CoalSceneNode;
friend class CoalScenePart;
friend class CoalSceneFileObject;
public:
/**
* @brief CoalScene constructor.
* @param name - Name for the CoalScene.
*/
CoalScene(std::string_view name);
~CoalScene();
/**
* @brief Create a CoalScene
* @param name - Name for the CoalScene
* @return The created CoalScene
*/
// Adding suppression, as CodeChecker complains this method
// has the same name as a method in the base version. This is
// just a CodeChecker false positive.
// codechecker_suppress [cppcheck-duplInheritedMember]
static Karana::Core::ks_ptr<CoalScene> create(std::string_view name);
void broadphase(std::function<void(const CollisionScenePart &, const CollisionScenePart &)>
callback) override;
void sweep(const std::function<void(const CollisionInfo &collision)> &callback,
const std::function<bool(const CollisionScenePart &, const CollisionScenePart &)>
&filter = nullptr) override;
const std::vector<CollisionInfo> &cachedCollisions() const override;
const Karana::Core::ks_ptr<CollisionScenePart> &
lookupPart(Karana::Core::id_t) const override;
/**
* @brief Get the maximum number of contact points that we track between any two scene parts
*
* @return size_t
*/
size_t getMaxNumContacts();
/**
* @brief Set the maximum number of contact points that we track between any two scene
* parts.
*
* Also broadcasts this information to every existing CoalScenePart
*
* @param max_contacts New maximum count
*/
void setMaxNumContacts(size_t max_contacts);
/**
* @brief Get the tolerance used by the GJK and EPA narrowphase solvers.
* @return The shared GJK/EPA tolerance.
*/
double getGJKEPATolerance() const;
/**
* @brief Set the tolerance used by the GJK and EPA narrowphase solvers.
*
* Also broadcasts this value to every existing CoalScenePart.
*
* @param tolerance Positive, finite solver tolerance.
*/
void setGJKEPATolerance(double tolerance);
/**
* @brief Return whether contact-patch refinement is enabled.
* @return True when ordinary contacts use COAL contact-patch centers.
*/
bool getUseContactPatchRefinement() const;
/**
* @brief Enable or disable contact-patch refinement.
*
* When enabled, ordinary contacts place the force at the center of the contact area
* reported by COAL. When disabled, ordinary contacts use COAL's contact points directly.
* Local plane approximation ignores this setting for height fields.
*
* @param enabled Whether contact-patch refinement is enabled.
*/
void setUseContactPatchRefinement(bool enabled);
/**
* @brief Get the distance tolerance used to choose contact force locations.
* @return Positive contact-patch tolerance in meters.
*/
double getContactPatchTolerance() const;
/**
* @brief Set the distance tolerance used to choose contact force locations.
*
* This setting controls which nearby surface points are included when choosing where
* the contact force acts. It is separate from the collision solver's accuracy setting.
* Smaller values can turn a nearly flat contact area into an edge or point contact.
* This does not affect local plane approximation.
* The default patch tolerance is 1e-3 meters.
*
* @param tolerance Positive, finite patch tolerance in meters.
*/
void setContactPatchTolerance(double tolerance);
/**
* @brief Return whether terrain contacts use local plane approximation.
* @return True when approximation is enabled; false by default.
*/
bool getUseLocalPlaneApproximation() const;
/**
* @brief Enable or disable local plane approximation for terrain contacts.
*
* Approximation smooths terrain (height field) peaks and valleys beneath supported convex
* objects. Non-convex meshes fall back to ordinary collision detection. This flag affects
* all current and future height field scene parts for this scene.
*
*
* @param enabled Whether to enable approximation.
*/
void setUseLocalPlaneApproximation(bool enabled);
/**
* @brief Get the scaling factor for the ellipsoid used to fit the local terrain plane.
* @return Positive, finite scaling factor; defaults to 1.
*/
double getLocalPlaneApproximationSupport() const;
/**
* @brief Set the ellipsoidal footprint used to fit the local terrain plane.
*
* A value of 1 wraps an ellipsoid around the collider's local bounding box.
* The ellipsoid turns with the collider and projects straight down onto the terrain.
* Larger values average ground over a wider area. At terrain edges, the fit
* uses the available ground within that footprint. Numerically degenerate
* projections use ordinary collision detection rather than an artificial width.
* This changes the fitted surface, not the collision geometry's dimensions.
* Changes apply to existing and future parts without enabling approximation.
*
* @param support Positive, finite scaling factor with no upper bound.
* @throws std::invalid_argument If support is nonpositive or nonfinite.
*/
void setLocalPlaneApproximationSupport(double support);
protected:
/**
* @brief This does the work to discard the CoalScene.
* @param base - A Base pointer to the CoalScene to discard.
*/
virtual void _discard(Karana::Core::ks_ptr<Karana::Core::Base> &base) override;
private:
Karana::Core::ks_ptr<SceneNode> _createNodeBase(std::string_view name) override;
void _discardNodeBase(Karana::Core::ks_ptr<SceneNode> &node) override;
Karana::Core::ks_ptr<ScenePart> _createPartBase(std::string_view name,
const VarStaticGeometry &geometry,
const VarMaterial &material,
layer_t layers) override;
void _discardPartBase(Karana::Core::ks_ptr<ScenePart> &part) override;
Karana::Core::ks_ptr<SceneFileObject>
_createFileObjectBase(std::string_view name,
const std::filesystem::path &path,
layer_t layers,
bool is_convex) override;
void _discardFileObjectBase(Karana::Core::ks_ptr<SceneFileObject> &file_obj) override;
const CoalGeometryCache _geometry_cache;
const std::unique_ptr<coal::BroadPhaseCollisionManager> _broadphase;
std::unordered_map<Karana::Core::id_t, Karana::Core::ks_ptr<CollisionScenePart>> _part_map;
Karana::Core::RegistryList<CoalScenePart> _parts;
Karana::Core::RegistryList<CoalSceneNode> _nodes;
std::vector<CollisionInfo> _cached_collisions = {};
/// Maximum number of contact pairs each scene part can produce at once
size_t _num_max_contacts;
/// Tolerance shared by the GJK and EPA narrowphase solvers.
double _gjk_epa_tolerance;
/// Whether raw contacts are refined to one contact per patch centroid.
bool _use_contact_patch_refinement;
/// Thickness of the separating-plane support sets used to build patches.
double _contact_patch_tolerance;
/// Whether terrain contacts use local plane approximation.
bool _use_local_plane_approximation = false;
/// Scaling factor for the bounding ellipsoid used to fit a plane to the local terrain.
double _local_plane_approximation_support = 1.0;
};
} // namespace Karana::Scene