From 7cee5dad98779ed7a14366a79056c8275037be3e Mon Sep 17 00:00:00 2001 From: John Turner <7strbass@gmail.com> Date: Tue, 24 Oct 2023 16:57:58 -0400 Subject: [PATCH] --Docs cleanup (#2238) * --add gh tag * --fix ref in doc strings * --fix more refs in docstrings --- docs/namespaces.dox | 36 +++ docs/pages/attributesJSON.rst | 14 +- src/esp/agent/Agent.h | 156 ++++++++++-- src/esp/assets/Asset.h | 75 +++++- src/esp/assets/BaseMesh.h | 20 +- src/esp/assets/CollisionMeshData.h | 2 +- src/esp/assets/GenericMeshData.h | 14 +- src/esp/assets/GenericSemanticMeshData.h | 110 +++++--- src/esp/assets/ResourceManager.h | 50 ++-- src/esp/assets/RigManager.h | 5 +- src/esp/bindings/Bindings.h | 72 +++++- src/esp/core/Buffer.h | 7 +- src/esp/core/Check.h | 16 +- src/esp/core/Configuration.cpp | 6 +- src/esp/core/Configuration.h | 240 ++++++++++++++++-- .../managedContainers/AbstractManagedObject.h | 10 +- .../core/managedContainers/ManagedContainer.h | 22 +- .../managedContainers/ManagedContainerBase.h | 6 +- .../ManagedFileBasedContainer.h | 40 +-- src/esp/gfx/DrawableConfiguration.h | 6 +- src/esp/metadata/MetadataMediator.h | 22 +- src/esp/metadata/URDFParser.h | 18 +- src/esp/metadata/attributes/AttributesBase.h | 5 +- .../metadata/attributes/AttributesEnumMaps.h | 80 +++--- .../managers/ObjectAttributesManager.h | 2 +- .../managers/PhysicsAttributesManager.h | 2 +- .../managers/SceneDatasetAttributesManager.h | 2 +- .../managers/SceneInstanceAttributesManager.h | 2 +- .../managers/StageAttributesManager.h | 2 +- src/esp/physics/PhysicsManager.h | 20 +- src/esp/physics/PhysicsObjectBase.h | 14 +- .../physics/bullet/BulletArticulatedObject.h | 6 +- src/esp/physics/bullet/BulletBase.h | 6 +- src/esp/physics/bullet/BulletRigidObject.h | 2 +- .../objectManagers/ArticulatedObjectManager.h | 2 +- .../physics/objectManagers/RigidBaseManager.h | 4 +- .../objectManagers/RigidObjectManager.h | 15 +- src/esp/sim/Simulator.h | 10 +- src/esp/sim/SimulatorConfiguration.h | 10 + tests/test_configs.py | 2 +- 40 files changed, 846 insertions(+), 287 deletions(-) diff --git a/docs/namespaces.dox b/docs/namespaces.dox index 1748b75e7e..21da4cbe20 100644 --- a/docs/namespaces.dox +++ b/docs/namespaces.dox @@ -8,6 +8,22 @@ namespace esp { * @brief Root namespace */ +/** @namespace esp::agent + * @brief Agent library + */ + +/** @namespace esp::assets + * @brief Assets library + */ + +/** @namespace esp::core + * @brief Core Habitat functionality + */ + +/** @namespace esp::core::config + * @brief Configuration functionality + */ + /** @namespace esp::gfx * @brief GFX library */ @@ -20,4 +36,24 @@ namespace esp { * @brief logging library */ +/** @namespace esp::metadata + * @brief Metadata management + */ + +/** @namespace esp::metadata::attributes + * @brief Metadata Attributes library + */ + +/** @namespace esp::metadata::managers + * @brief Metadata Attribute Managers library + */ + +/** @namespace esp::metadata::URDF + * @brief URDF parsing library + */ + +/** @namespace esp::physics + * @brief Physics library + */ + } diff --git a/docs/pages/attributesJSON.rst b/docs/pages/attributesJSON.rst index 7fa0c59732..ab90b198a2 100644 --- a/docs/pages/attributesJSON.rst +++ b/docs/pages/attributesJSON.rst @@ -41,7 +41,7 @@ A *SceneDataset* enumerates and aggregates the various assets and metadata neces .scene_dataset_config.json -`An example of an appropriately configured SceneDataset Attributes file can be found below `_: +:gh:`An example of an appropriately configured SceneDataset Attributes file can be found below `: .. include:: ../../data/test_assets/dataset_tests/dataset_0/test_dataset_0.scene_dataset_config.json :code: json @@ -256,7 +256,7 @@ A *stage* in Habitat-Sim is the set of STATIC mesh components which make up the .stage_config.json -`An example of an appropriately configured Stage Attributes file can be found below `_: +:gh:`An example of an appropriately configured Stage Attributes file can be found below `: .. include:: ../../data/test_assets/scenes/stage_floor1.stage_config.json :code: json @@ -343,7 +343,7 @@ Below are stage-specific physical and object-related quantities. These values w .ao_config.json -`An example of an appropriately configured Articulated Object Attributes file can be found below `_: +:gh:`An example of an appropriately configured Articulated Object Attributes file can be found below `: .. include:: ../../data/test_assets/urdf/skinned_prism.ao_config.json :code: json @@ -400,7 +400,7 @@ Articulated Object Configuration And Rendering .object_config.json -`An example of an appropriately configured object Attributes file can be found below `_: +:gh:`An example of an appropriately configured Object Attributes file can be found below `: .. include:: ../../data/test_assets/objects/donut.object_config.json :code: json @@ -490,7 +490,7 @@ Below are object-specific physical quantities. These values will override simil .lighting_config.json -`An example of an appropriately configured LightLayoutAttributes file can be found below `_: +:gh:`An example of an appropriately configured LightLayoutAttributes file can be found below `: .. include:: ../../data/test_assets/lights/test_lights.lighting_config.json :code: json @@ -524,7 +524,7 @@ The :ref:`LightLayoutAttributes` JSON should contain a single cell named "lights .pbr_config.json -`An example of an appropriately configured PBRShader Attributes file can be found below `_: +:gh:`An example of an appropriately configured PBRShader Attributes file can be found below `: .. include:: ../../data/test_assets/pbr/example.pbr_config.json :code: json @@ -629,7 +629,7 @@ These parameters control the enabling or disabling of particular extension layer .physics_config.json -`An example of an appropriately configured Physics Manager Attributes file can be found below `_: +:gh:`An example of an appropriately configured Physics Manager Attributes file can be found below `: .. include:: ../../data/test_assets/testing.physics_config.json :code: json diff --git a/src/esp/agent/Agent.h b/src/esp/agent/Agent.h index a8b10a4325..ca94bd442a 100644 --- a/src/esp/agent/Agent.h +++ b/src/esp/agent/Agent.h @@ -24,42 +24,87 @@ class SensorSuite; } // namespace sensor namespace agent { -// Represents the physical state of an agent +/** + * @brief Struct describing the physical state of an agent + */ struct AgentState { + /** + * @brief the position of the agent + */ vec3f position = {0, 0, 0}; - // TODO: rotation below exposes quaternion x,y,z,w as vec4f for pybind11 - // interop, replace with quatf when we have custom pybind11 type conversion - // for quaternions + /** + * @brief the agent's rotation. TODO : This exposes the rotation quaternion + * x,y,z,w as vec4f for pybind11 interop, replace with quatf when we have + * custom pybind11 type conversion for quaternions + */ vec4f rotation = {0, 0, 0, 1}; ESP_SMART_POINTERS(AgentState) }; +/** + * @brief Type to describe the characteristics of an action (i.e. angle to turn + * for a turn action) + */ typedef std::map ActuationMap; -// Specifies an action (i.e. name -> agent actuation). +/** + * @brief Struct describing an action (i.e. name -> agent actuation). + */ struct ActionSpec { + /** + * @brief Constructor + */ explicit ActionSpec(const std::string& _name, const ActuationMap& _actuation) : name(_name), actuation(_actuation) {} - // action name + /** + * @brief action name + */ std::string name; - // linear, angular forces, joint torques, sensor actuation + /** + * @brief linear, angular forces, joint torques, sensor actuation + */ ActuationMap actuation; ESP_SMART_POINTERS(ActionSpec) }; + +/** + * @brief Verify @ref ActionSpec equality. + */ bool operator==(const ActionSpec& a, const ActionSpec& b); + +/** + * @brief Verify @ref ActionSpec inequality. + */ bool operator!=(const ActionSpec& a, const ActionSpec& b); -// Represents a set of possible agent actions. +/** + * @brief Represents a set of possible agent actions. + */ typedef std::map ActionSpace; -// Represents a configuration for an embodied Agent +/** + * @brief Struct describing a configuration for an embodied Agent + */ struct AgentConfiguration { + /** + * @brief The agent's height + */ float height = 1.5; + + /** + * @brief The radius of the colliding capsule around the agent + */ float radius = 0.1; + /** + * @brief A vector of @ref esp::sensor::SensorSpec that describe the sensors attached to this agent. + */ std::vector> sensorSpecifications = {}; - ActionSpace actionSpace = { // default ActionSpace + /** + * @brief The default ActionSpace for this agent + */ + ActionSpace actionSpace = { {"moveForward", ActionSpec::create("moveForward", ActuationMap{{"amount", 0.25f}})}, {"lookUp", ActionSpec::create("lookUp", ActuationMap{{"amount", 10.0f}})}, @@ -69,52 +114,111 @@ struct AgentConfiguration { ActionSpec::create("turnLeft", ActuationMap{{"amount", 10.0f}})}, {"turnRight", ActionSpec::create("turnRight", ActuationMap{{"amount", 10.0f}})}}; + /** + * @brief The body type of this agent. + */ std::string bodyType = "cylinder"; ESP_SMART_POINTERS(AgentConfiguration) }; + +/** + * @brief Verify @ref AgentConfiguration equality. + */ bool operator==(const AgentConfiguration& a, const AgentConfiguration& b); + +/** + * @brief Verify @ref AgentConfiguration inequality. + */ bool operator!=(const AgentConfiguration& a, const AgentConfiguration& b); -// Represents an agent that can act within an environment +/** + * @brief Class that represents an agent that can act within an environment + */ class Agent : public Magnum::SceneGraph::AbstractFeature3D { public: - // constructor: the status of the agent, sensors is "valid" after - // construction; user can use them immediately + /** + * @brief constructor: the status of the agent, sensors is "valid" after + * construction; user can use them immediately + */ explicit Agent(scene::SceneNode& agentNode, const AgentConfiguration& cfg); ~Agent() override; - // Get the scene node being attached to. + /** + * @brief Get the scene node being attached to. + */ scene::SceneNode& node() { return object(); } + + /** + * @brief Get the scene node being attached to. + */ const scene::SceneNode& node() const { return object(); } - // Overloads to avoid confusion + /** + * @brief Overloads to avoid confusion + */ scene::SceneNode& object() { return static_cast( Magnum::SceneGraph::AbstractFeature3D::object()); } + + /** + * @brief Overloads to avoid confusion + */ const scene::SceneNode& object() const { return static_cast( Magnum::SceneGraph::AbstractFeature3D::object()); } + /** + * @brief Perform an action. + * @param actionName the name of the action to perform + * @return Whether the named action is available to the agent + */ bool act(const std::string& actionName); + /** + * @brief Verify whether the named action is available to the agent. + * @param actionName the name of the action to perform + * @return Whether the named action is available to the agent + */ bool hasAction(const std::string& actionName) const; + /** + * @brief Return the agent to the saved @p initialState_ + */ void reset(); + /** + * @brief Populate the passed state with the agent's current positon and + * rotation. + * @param state The @ref AgentState variable to populate with the current state of this agent. + */ void getState(const AgentState::ptr& state) const; + /** + * @brief Set the agent to the passsed state. + * @param state The state to set the agent to + * @param resetSensors Whether to reset the agent's sensors or not. + */ void setState(const AgentState& state, bool resetSensors = true); + /** + * @brief Set the agent to the passsed state and set that state to be the @p + * initialState_ + * @param state The state to set to, and save as initial state + * @param resetSensors Whether to reset the agent's sensors or not. + */ void setInitialState(const AgentState& state, const bool resetSensors = true) { initialState_ = state; setState(state, resetSensors); } + /** + * @brief Retrieve the @ref esp::scene::ObjectControls specified for this agent. + */ std::shared_ptr getControls() { return controls_; } /** @@ -136,17 +240,31 @@ class Agent : public Magnum::SceneGraph::AbstractFeature3D { return node().getSubtreeSensors(); } + /** + * @brief Retrieve a const reference to this agent's configuration. + */ const AgentConfiguration& getConfig() const { return configuration_; } + + /** + * @brief Retrieve a reference to this agent's configuration. + */ AgentConfiguration& getConfig() { return configuration_; } - // Set of actions that are applied to the body of the agent. These actions - // update both the absolute position/rotation of the agent and the sensor - // Non-body actions only effect the absolute position and rotation of the - // sensors (only effects their position/rotation relative to the agent's body) + /** + * @brief Set of actions that are applied to the body of the agent. These + * actions update both the absolute position/rotation of the agent and the + * sensor. Non-body actions only effect the absolute position and rotation of + * the sensors (only effects their position/rotation relative to the agent's + * body) + */ static const std::set BodyActions; private: + /** + * @brief The configuration of this agent. + */ AgentConfiguration configuration_; + std::shared_ptr controls_; AgentState initialState_; diff --git a/src/esp/assets/Asset.h b/src/esp/assets/Asset.h index 90fedbd543..f17e62298e 100644 --- a/src/esp/assets/Asset.h +++ b/src/esp/assets/Asset.h @@ -15,7 +15,9 @@ namespace esp { //! Asset management namespace namespace assets { -//! Supported Asset types +/** + * @brief Supported Asset types + */ enum class AssetType { UNKNOWN, MP3D_MESH, @@ -25,31 +27,72 @@ enum class AssetType { PRIMITIVE, }; -// loading and asset info with filepath == EMPTY_SCENE creates a scene graph -// with no scene mesh (ie. an empty scene) +/** + * @brief loading an asset info with filepath == EMPTY_SCENE creates a scene + * graph with no scene mesh (ie. an empty scene) + */ constexpr char EMPTY_SCENE[] = "NONE"; -//! stores basic Phong compatible color properties for procedural override -//! material construction +/** + * @brief stores basic Phong compatible color properties for procedural override + * material construction + */ struct PhongMaterialColor { + /** + * @brief the ambient color of the Phong material + */ Magnum::Color4 ambientColor{0.1}; + /** + * @brief the diffuse color of the Phong material + */ Magnum::Color4 diffuseColor{0.7}; + /** + * @brief the specular color of the Phong material + */ Magnum::Color4 specularColor{0.2}; }; - +/** + * @brief Verify @ref PhongMaterialColor equality. + */ bool operator==(const PhongMaterialColor& a, const PhongMaterialColor& b); +/** + * @brief Verify @ref PhongMaterialColor inequality. + */ bool operator!=(const PhongMaterialColor& a, const PhongMaterialColor& b); -//! AssetInfo stores information necessary to identify and load an Asset +/** + * @brief AssetInfo stores information necessary to identify and load an Asset + */ struct AssetInfo { + /** + * @brief The type of the asset + */ AssetType type = AssetType::UNKNOWN; + /** + * @brief The path to the asset's source on disk + */ std::string filepath = EMPTY_SCENE; // empty scene + /** + * The @ref esp::geo::CoordinateFrame describing the default orientation of the asset + */ geo::CoordinateFrame frame{}; + /** + * @brief Conversion factor from units specified in asset source to meters + */ float virtualUnitToMeters = 1.0f; + + /** + * @brief Whether to force this asset to be flat shaded. + */ bool forceFlatShading = true; + /** + * @brief Whether supported semantic meshes should be split + */ bool splitInstanceMesh = true; // only applies to AssetType::INSTANCE_MESH - //! if set, override the asset material with a procedural Phong material + /** + * @brief if set, override the asset material with a procedural Phong material + */ Cr::Containers::Optional overridePhongMaterial = Cr::Containers::NullOpt; /** @@ -74,10 +117,18 @@ struct AssetInfo { ESP_SMART_POINTERS(AssetInfo) }; +/** + * @brief Verify @ref AssetInfo equality. + */ bool operator==(const AssetInfo& a, const AssetInfo& b); +/** + * @brief Verify @ref AssetInfo equality. + */ bool operator!=(const AssetInfo& a, const AssetInfo& b); -//! Wrapper for all valid asset types +/** + * @brief Wrapper for all valid asset types + */ template struct Asset { //! Create Asset wrapper given AssetInfo and created asset @@ -90,7 +141,13 @@ struct Asset { T& get() { return asset_; } protected: + /** + * @brief The @ref AssetInfo for this asset + */ AssetInfo info_; + /** + * @brief the asset + */ T& asset_; ESP_SMART_POINTERS(Asset) }; diff --git a/src/esp/assets/BaseMesh.h b/src/esp/assets/BaseMesh.h index 6d34f01a5e..686e4404f0 100644 --- a/src/esp/assets/BaseMesh.h +++ b/src/esp/assets/BaseMesh.h @@ -35,27 +35,28 @@ namespace assets { */ enum SupportedMeshType { /** - * Undefined mesh types are created programmatically without a specific + * @brief Undefined mesh types are created programmatically without a specific * format or loaded from an unknown format. Support for this type and behavior * is likely limited. Object type is likely @ref BaseMesh. */ NOT_DEFINED = ID_UNDEFINED, /** - * Instance meshes loaded from sources including segmented object + * @brief Instance meshes loaded from sources including segmented object * identifier data (e.g. semantic data: chair, table, etc...). Sources include * .ply files and reconstructions of Matterport scans. Object is likely of * type @ref GenericSemanticMeshData. */ INSTANCE_MESH = 0, /** - * Meshes loaded from gltf format (i.e. .glb file), or instances of Magnum + * @brief Meshes loaded from gltf format (i.e. .glb file), or instances of + * Magnum * Primitives. Object is likely type @ref GenericMeshData. */ GENERIC_MESH = 1, /** - * Number of enumerated supported types. + * @brief Number of enumerated supported types. */ NUM_SUPPORTED_MESH_TYPES = 2, }; @@ -114,6 +115,10 @@ class BaseMesh { * sub-component of the asset. */ virtual Magnum::GL::Mesh* getMagnumGLMesh(int) { return nullptr; } + + /** + * @brief Retrieve a reference to the @p meshData_ for this mesh; + */ Corrade::Containers::Optional& getMeshData() { return meshData_; } @@ -155,9 +160,10 @@ class BaseMesh { std::vector& colorMapToUse) const; /** - * @brief Populate an array of colors of the correct type from the given - * @p srcColors. Generally used for semantic processing/rendering. - * @param srcColors The source colors + * @brief Populate an array of colors of the correct type from colors held in + * the given + * @p srcMeshData. Generally used for semantic processing/rendering. + * @param srcMeshData The meshdata containing the colors we wish to query * @param convertToSRGB Whether the source vertex colors from the @p * srcMeshData should be converted to SRGB * @param [out] destColors The per-element array of colors to be built. diff --git a/src/esp/assets/CollisionMeshData.h b/src/esp/assets/CollisionMeshData.h index a63a4fb19f..b88defbc63 100644 --- a/src/esp/assets/CollisionMeshData.h +++ b/src/esp/assets/CollisionMeshData.h @@ -26,7 +26,7 @@ struct CollisionMeshData { /** * @brief Primitive type (has to be triangle for Bullet to work). * - * See @ref BulletRigidObject::constructConvexShapesFromMeshes. + * See @ref esp::physics::BulletRigidObject::constructConvexShapesFromMeshes. */ Magnum::MeshPrimitive primitive{}; diff --git a/src/esp/assets/GenericMeshData.h b/src/esp/assets/GenericMeshData.h index 416eacf773..cad9d67887 100644 --- a/src/esp/assets/GenericMeshData.h +++ b/src/esp/assets/GenericMeshData.h @@ -22,7 +22,7 @@ namespace assets { /** * @brief Mesh data storage and loading for gltf format assets. See @ref - * ResourceManager::loadGeneralMeshData. + * ResourceManager::loadMeshes. */ class GenericMeshData : public BaseMesh { public: @@ -36,8 +36,9 @@ class GenericMeshData : public BaseMesh { Magnum::GL::Mesh mesh; }; - /** @brief Constructor. Sets @ref SupportedMeshType::GENERIC_MESH to identify - * the asset type.*/ + /** + * @brief Constructor. Sets asset type to be SupportedMeshType::GENERIC_MESH . + */ explicit GenericMeshData(bool needsNormals = true) : BaseMesh(SupportedMeshType::GENERIC_MESH), needsNormals_{needsNormals} {}; @@ -54,9 +55,9 @@ class GenericMeshData : public BaseMesh { void uploadBuffersToGPU(bool forceReload = false) override; /** - * @brief Set mesh data from external source, and sets the @ref collisionMesh_ + * @brief Set mesh data from external source, and sets the @p collisionMesh_ * references. Can be used for meshDatas that are manually synthesized, such - * as NavMesh. Sets the @ref collisionMesh_ references. + * as NavMesh. * @param meshData the meshData to be assigned. */ void setMeshData(Magnum::Trade::MeshData&& meshData); @@ -105,6 +106,9 @@ class GenericMeshData : public BaseMesh { */ std::unique_ptr renderingBuffer_ = nullptr; + /** + * @brief Whether this mesh should have smooth normals generated + */ bool needsNormals_ = true; private: diff --git a/src/esp/assets/GenericSemanticMeshData.h b/src/esp/assets/GenericSemanticMeshData.h index 723be46bd6..d7a7a938d1 100644 --- a/src/esp/assets/GenericSemanticMeshData.h +++ b/src/esp/assets/GenericSemanticMeshData.h @@ -27,26 +27,37 @@ namespace assets { /** * @brief Mesh data storage and loading for ply format assets used primarily for * Semantic Scene meshes, including manage vertex colors and vertex IDs for - * semantic visualization and rendering. See @ref - * ResourceManager::loadRenderAssetIMesh. + * semantic visualization and rendering. */ class GenericSemanticMeshData : public BaseMesh { public: + /** + * @brief Stores render data for the mesh. + */ struct RenderingBuffer { + /** + * @brief Compiled openGL render data for the mesh. + */ Magnum::GL::Mesh mesh; }; + /** + * @brief Constructor. Builds semantic mesh data, and sets type to passed + * SupportedMeshType + */ explicit GenericSemanticMeshData(SupportedMeshType type) : BaseMesh{type} {}; + /** + * @brief Constructor. Builds semantic mesh data, and sets type to + * SupportedMeshType::INSTANCE_MESH + */ explicit GenericSemanticMeshData() : GenericSemanticMeshData{SupportedMeshType::INSTANCE_MESH} {}; ~GenericSemanticMeshData() override = default; /** - * @brief Build one ore more @ref GenericSemanticMeshData based on the - * contents of the passed @p meshData, splitting the result into multiples if - * specified and if the source file's objectIds are compatibly configured to - * do so. + * @brief Build the @ref GenericSemanticMeshData based on the + * contents of the passed @p meshData, * @param meshData The imported meshData. * @param semanticFilename Path-less Filename of source mesh. * @param [out] colorMapToUse An array holding the semantic colors to use for @@ -54,8 +65,7 @@ class GenericSemanticMeshData : public BaseMesh { * @param convertToSRGB Whether the source vertex colors from the @p meshData * should be converted to SRGB * @param semanticScene The SSD for the semantic mesh being loaded. - * @return vector holding one or more mesh results from the semantic asset - * file. + * @return reference to the @ref GenericSemanticMeshData. */ static std::unique_ptr buildSemanticMeshData( const Magnum::Trade::MeshData& meshData, @@ -65,30 +75,17 @@ class GenericSemanticMeshData : public BaseMesh { const std::shared_ptr& semanticScene = nullptr); /** - * @brief Build one ore more @ref GenericSemanticMeshData based on the - * contents of the passed @p meshData, splitting the result into multiples if - * specified and if the source file's objectIds are compatibly configured to - * do so. - * @param meshData The imported meshData. - * @param semanticFilename Path-less Filename of source mesh. - * @param splitMesh Whether or not the resultant mesh should be split into - * multiple components based on objectIds, for frustum culling. - * @param [out] colorMapToUse An array holding the semantic colors to use for - * visualization or matching to semantic IDs. - * @param convertToSRGB Whether the source vertex colors from the @p meshData - * should be converted to SRGB - * @param semanticScene The SSD for the semantic mesh being loaded. - * @return vector holding one or more mesh results from the semantic asset - * file. + * @brief Partition the passed @ref GenericSemanticMeshData to facilitate culling. + * @param semanticMeshData + * @return vector holding one or more @ref GenericSemanticMeshData */ - static std::vector> partitionSemanticMeshData( const std::unique_ptr& semanticMeshData); /** - * @build a per-color/per-semantic ID map of all bounding boxes for each CC - * found in the mesh, and the count of verts responsible for each. + * @brief Build a per-color/per-semantic ID map of all bounding boxes for each + * CC found in the mesh, and the count of verts responsible for each. * @param semanticScene The SSD for the current semantic mesh. Used to query * semantic objs. If nullptr, this function returns hex-color-keyed map, * otherwise returns SemanticID-keyed map. @@ -99,22 +96,45 @@ class GenericSemanticMeshData : public BaseMesh { const std::shared_ptr& semanticScene); // ==== rendering ==== + /** + * @brief Upload the mesh data to GPU memory. + */ void uploadBuffersToGPU(bool forceReload = false) override; + + /** + * @brief Retrieve a pointer to the rendering buffer for this @ref GenericSemanticMeshData. + */ RenderingBuffer* getRenderingBuffer() { return renderingBuffer_.get(); } + /** + * @brief Retrieve a pointer to the Magnum GL Mesh behind this @ref GenericSemanticMeshData. + */ Magnum::GL::Mesh* getMagnumGLMesh() override; + /** + * @brief Retrive a reference to this @ref GenericSemanticMeshData 's vertex buffer + */ const std::vector& getVertexBufferObjectCPU() const { return cpu_vbo_; } + + /** + * @brief Retrive a reference to this @ref GenericSemanticMeshData 's color buffer + */ const std::vector& getColorBufferObjectCPU() const { return cpu_cbo_; } + /** + * @brief Retrive a reference to this @ref GenericSemanticMeshData 's index buffer + */ const std::vector& getIndexBufferObjectCPU() const { return cpu_ibo_; } + /** + * @brief Retrive a reference to this @ref GenericSemanticMeshData 's object id buffer + */ const std::vector& getObjectIdsBufferObjectCPU() const { return objectIds_; } @@ -141,21 +161,28 @@ class GenericSemanticMeshData : public BaseMesh { * @brief build a string array holding mapping information for colors found on * verts and colors found in semantic scene descriptor aggregated during load. */ - std::vector getVertColorSSDReport( const std::string& semanticFilename, const std::vector& colorMapToUse, const std::shared_ptr& semanticScene); protected: - // temporary holding structures to hold any non-SSD vert colors, so that - // the nonSSDObjID for new colors can be incremented appropriately - // not using set to avoid extra include. Key is color, value is semantic - // ID assigned for unknown color + /** + * @brief temporary holding structures to hold any non-SSD vert color IDs, so + * that the nonSSDObjID for new colors can be incremented appropriately not + * using set to avoid extra include. Key is color, value is semantic ID + * assigned for unknown color + */ std::unordered_map nonSSDVertColorIDs{}; + /** + * @brief temporary holding structures to hold any non-SSD vert color counts. + * Key is color, value is semantic ID assigned for unknown color + */ std::unordered_map nonSSDVertColorCounts{}; - // record of semantic object IDXs with no presence in any verts + /** + * @brief record of semantic object IDXs with no presence in any verts + */ std::vector unMappedObjectIDXs{}; /** @@ -172,12 +199,26 @@ class GenericSemanticMeshData : public BaseMesh { */ bool meshUsesSSDPartitionIDs = false; + /** + * @brief This class is intended to provide a concise interface to build the + * appropriate mesh data + */ class PerPartitionIdMeshBuilder { public: + /** + * @brief Build the per-partition @ref GenericSemanticMeshData structure + */ PerPartitionIdMeshBuilder(GenericSemanticMeshData& data, uint16_t partitionId) : data_{data}, partitionId{partitionId} {} + /** + * @brief Add a vertex to the @ref GenericSemanticMeshData + * @param vertexId The Id of the vertex + * @param vertex The location of the vertex + * @param color The vertex color + * @param objectId The object/semantic Id of the vertex + */ void addVertex(uint32_t vertexId, const Mn::Vector3& vertex, const Mn::Color3ub& color, @@ -189,8 +230,13 @@ class GenericSemanticMeshData : public BaseMesh { std::unordered_map vertexIdToVertexIndex_; }; + /** + * @brief update the meshdata positions and indices with the data from the + * member vectors + */ void updateCollisionMeshData(); + private: // ==== rendering ==== std::unique_ptr renderingBuffer_ = nullptr; std::vector cpu_vbo_; diff --git a/src/esp/assets/ResourceManager.h b/src/esp/assets/ResourceManager.h index 44ab46b8e8..37cc2928f2 100644 --- a/src/esp/assets/ResourceManager.h +++ b/src/esp/assets/ResourceManager.h @@ -94,6 +94,9 @@ using metadata::attributes::ObjectInstanceShaderType; */ class ResourceManager { public: + /** + * @brief Whether the renderer should be created or not. + */ bool getCreateRenderer() const; /** @brief Stores references to a set of drawable elements */ @@ -109,7 +112,7 @@ class ResourceManager { ~ResourceManager(); /** - * @brief This function will build the various @ref Importers used by the + * @brief This function will build the various Magnum importers used by the * system. */ void buildImporters(); @@ -166,8 +169,8 @@ class ResourceManager { void buildSemanticColorMap(); /** - * @brief Build @ref semanticColorAsInt_ (array of colors as integers) from - * the current @ref semanticColorMapBeingUsed_ map. The @ref + * @brief Build @p semanticColorAsInt_ (array of colors as integers) from + * the current @p semanticColorMapBeingUsed_ map. The @p * semanticColorAsInt_ is used when building the color matrix for conversion * of colors found in semantic textures to their semantic IDs. When semantic * textures are preprocessed, this will not need to be performed. @@ -207,12 +210,12 @@ class ResourceManager { * If parent and drawables are not specified, the assets are loaded, but no * new @ref gfx::Drawable is added for the scene (i.e. it will not be * rendered). - * @param stageAttributes The @ref StageAttributes that describes the + * @param stageAttributes The @ref metadata::attributes::StageAttributes that describes the * stage - * @param stageInstanceAttributes The @ref SceneObjectInstanceAttributes that + * @param stageInstanceAttributes The @ref metadata::attributes::SceneObjectInstanceAttributes that * describes this particular instance of the stage. If nullptr then not * created by SceneInstanceAttributes. - * @param _physicsManager The currently defined @ref physics::PhysicsManager. + * @param _physicsManager The currently defined @ref esp::physics::PhysicsManager. * @param sceneManagerPtr Pointer to scene manager, to fetch drawables and * parent node. * @param [out] activeSceneIDs active scene ID is in idx 0, if semantic scene @@ -331,7 +334,7 @@ class ResourceManager { const MeshMetaData& getMeshMetaData(const std::string& metaDataName) const; /** - * @brief Get a named @ref LightSetup + * @brief Get a named @ref esp::gfx::LightSetup * * @param key The key identifying the light setup in shaderManager_. * @return The LightSetup object. @@ -342,13 +345,13 @@ class ResourceManager { } /** - * @brief Set a named @ref LightSetup + * @brief Set a named @ref esp::gfx::LightSetup * - * If this name already exists, the @ref LightSetup is updated and all @ref + * If this name already exists, the @ref esp::gfx::LightSetup is updated and all @ref * Drawables using this setup are updated. * * @param setup Light setup this key will now reference - * @param key Key to identify this @ref LightSetup + * @param key Key to identify this @ref esp::gfx::LightSetup */ void setLightSetup(gfx::LightSetup setup, const Mn::ResourceKey& key = Mn::ResourceKey{ @@ -396,7 +399,7 @@ class ResourceManager { * child. * @param drawables The @ref DrawableGroup with which the object @ref * gfx::Drawable will be rendered. - * @param lightSetupKey The @ref LightSetup key that will be used + * @param lightSetupKey The @ref esp::gfx::LightSetup key that will be used * for the added component. * @param[out] visNodeCache Cache for pointers to all nodes created as the * result of this process. @@ -432,12 +435,8 @@ class ResourceManager { * @param meshAttributeFlags flags for the attributes of the render mesh * @param node The @ref scene::SceneNode to which the drawable will be * attached. - * @param lightSetupKey The @ref LightSetup key that will be used - * for the drawable. - * @param materialKey The @ref MaterialData key that will be used - * for the drawable. - * @param group Optional @ref DrawableGroup with which the render the @ref - * gfx::Drawable. + * @param drawableCfg The @ref esp::gfx::DrawableConfiguration that describes + * the drawable being created. */ void createDrawable(Mn::GL::Mesh* mesh, @@ -445,11 +444,6 @@ class ResourceManager { scene::SceneNode& node, gfx::DrawableConfiguration& drawableCfg); - // const Mn::ResourceKey& lightSetupKey, - // const Mn::ResourceKey& materialKey, - // DrawableGroup* group = nullptr, - // const std::shared_ptr& skinData = nullptr); - /** * @brief Remove the specified primitive mesh. * @@ -686,7 +680,7 @@ class ResourceManager { * @param filename the name of the file describing this mesh * @param objectAttributes the object attributes owning * this mesh. - * @param assetType either "render" or "collision" (for error log output) + * @param meshType either "render" or "collision" (for error log output) * @param forceFlatShading whether to force this asset to be rendered via * flat shading. * @return whether or not the mesh was loaded successfully @@ -800,7 +794,7 @@ class ResourceManager { * the meshes, textures, materials, and component hierarchy of the asset. * @param parent The @ref scene::SceneNode of which the component will be a * child. - * @param lightSetupKey The @ref LightSetup key that will be used + * @param lightSetupKey The @ref esp::gfx::LightSetup key that will be used * for the added component. * @param drawables The @ref DrawableGroup with which the component will be * rendered. @@ -1281,11 +1275,17 @@ class ResourceManager { * @brief Colormap to use for visualizing currently loaded semantic scene. */ std::vector semanticColorMapBeingUsed_{}; + + /** + * @brief Cache semantic colors as ints. + */ std::vector semanticColorAsInt_{}; // ======== Physical parameter data ======== - //! tracks primitive mesh ids + /** + * @brief tracks primitive mesh ids + */ int nextPrimitiveMeshId = 0; /** * @brief Primitive meshes available for instancing via @ref diff --git a/src/esp/assets/RigManager.h b/src/esp/assets/RigManager.h index 1b54380db9..02d99694ac 100644 --- a/src/esp/assets/RigManager.h +++ b/src/esp/assets/RigManager.h @@ -10,7 +10,10 @@ namespace esp { namespace assets { -// Tracks the rig instances in a simulator (skinned articulated objects). +/** + * @brief Tracks the rig instances in a simulator (skinned articulated + * objects). + */ class RigManager { public: /** diff --git a/src/esp/bindings/Bindings.h b/src/esp/bindings/Bindings.h index 2cf144f14a..536163d330 100644 --- a/src/esp/bindings/Bindings.h +++ b/src/esp/bindings/Bindings.h @@ -12,55 +12,115 @@ namespace esp { namespace core { +/** + * @brief Specify core bindings + */ void initCoreBindings(pybind11::module& m); namespace config { - +/** + * @brief Specify bindings for @ref esp::core::config::Configuration + */ void initConfigBindings(pybind11::module& m); } // namespace config } // namespace core namespace geo { +/** + * @brief Specify bindings for @ref esp::geo::OBB and @ref esp::geo::Ray + */ void initGeoBindings(pybind11::module& m); -} +} // namespace geo namespace gfx { + +/** + * @brief Specify bindings for constructs in esp::gfx namespace + */ void initGfxBindings(pybind11::module& m); namespace replay { +/** + * @brief Specify bindings for constructs in esp::gfx::replay namespace + */ void initGfxReplayBindings(pybind11::module& m); } // namespace replay } // namespace gfx namespace metadata { +/** + * @brief Specify bindings for attributes in esp::metadata::attributes namespace + */ void initAttributesBindings(pybind11::module& m); +/** + * @brief Specify bindings for @ref esp::metadata::MetadataMediator + */ void initMetadataMediatorBindings(pybind11::module& m); + namespace managers { +/** + * @brief Specify bindings for attributes in esp::metadata::managers namespace + */ void initAttributesManagersBindings(pybind11::module& m); } // namespace managers } // namespace metadata namespace nav { +/** + * @brief Specify bindings for @ref esp::nav::HitRecord , @ref esp::nav::ShortestPath , + * @ref esp::nav::MultiGoalShortestPath, @ref esp::nav::NavMeshSettings, @ref esp::nav::PathFinder, and + * @ref esp::nav::GreedyGeodesicFollowerImpl + */ void initShortestPathBindings(pybind11::module& m); -} +} // namespace nav namespace physics { +/** + * @brief Specify bindings for @ref esp::physics::VelocityControl , + * @ref esp::physics::JointMotorSettings , + * @ref esp::physics::RigidConstraintSettings , + * @ref esp::physics::RayHitInfo , + * @ref esp::physics::RaycastResults , + * @ref esp::physics::ContactPointData , + * and @ref esp::physics::CollisionGroupHelper + */ void initPhysicsBindings(pybind11::module& m); +/** + * @brief Specify bindings for the various esp::physics wrapper objects. + */ void initPhysicsObjectBindings(pybind11::module& m); +/** + * @brief Specify bindings for the various esp::physics wrapper object managers. + */ void initPhysicsWrapperManagerBindings(pybind11::module& m); } // namespace physics namespace scene { +/** + * @brief Specify bindings for @ref esp::scene::SceneNode , @ref esp::scene::SceneGraph , + * @ref esp::scene::SceneManager , @ref esp::scene::SemanticCategory , + * @ref esp::scene::Mp3dObjectCategory , @ref esp::scene::Mp3dRegionCategory + * @ref esp::scene::SemanticObject , @ref esp::scene::SemanticRegion , + * @ref esp::scene::SemanticLevel , @ref esp::scene::SemanticScene , and + * @ref esp::scene::ObjectControls + */ void initSceneBindings(pybind11::module& m); -} +} // namespace scene namespace sensor { +/** + * @brief Specify bindings for various esp::sensor classes. + */ void initSensorBindings(pybind11::module& m); -} +} // namespace sensor namespace sim { +/** + * @brief Specify bindings for @ref esp::sim::SimulatorConfiguration , @ref esp::sim::Simulator , + * @ref esp::sim::ReplayRendererConfiguration , @ref esp::sim::AbstractReplayRenderer , + */ void initSimBindings(pybind11::module& m); -} +} // namespace sim } // namespace esp diff --git a/src/esp/core/Buffer.h b/src/esp/core/Buffer.h index 732404e3aa..091cfd85b0 100644 --- a/src/esp/core/Buffer.h +++ b/src/esp/core/Buffer.h @@ -12,7 +12,9 @@ namespace esp { namespace core { -// Enumeration of data +/** + * @brief Enumeration of data + */ enum class DataType { DT_NONE = 0, DT_INT8 = 1, @@ -27,6 +29,9 @@ enum class DataType { DT_DOUBLE = 10, }; +/** + * @brief A class act as a data buffer. + */ class Buffer { public: explicit Buffer() = default; diff --git a/src/esp/core/Check.h b/src/esp/core/Check.h index f15acf221f..b03a831736 100644 --- a/src/esp/core/Check.h +++ b/src/esp/core/Check.h @@ -51,18 +51,24 @@ namespace esp { namespace core { -/* The throwInPython function pointer gets filled during Python bindings - startup. If it's nullptr, we're in plain C++ code. */ +/** + * @brief The throwInPython function pointer gets filled during Python bindings + * startup. If it's nullptr, we're in plain C++ code. + */ extern void (*throwInPython)(const char*); -// For use in ESP_CHECK +/** + * @brief For use in ESP_CHECK + */ [[noreturn]] void throwIfInPythonOtherwiseAbort(const char* message); } // namespace core } // namespace esp -/* A runtime check that must pass, otherwise we consider this a fatal runtime -error. The program terminates with the supplied error message. */ +/** + * @brief A runtime check that must pass, otherwise we consider this a fatal + * runtime error. The program terminates with the supplied error message. + */ #define ESP_CHECK(condition, ...) \ do { \ if (!(condition)) { \ diff --git a/src/esp/core/Configuration.cpp b/src/esp/core/Configuration.cpp index 3a767acc68..b70ad0ecff 100644 --- a/src/esp/core/Configuration.cpp +++ b/src/esp/core/Configuration.cpp @@ -537,9 +537,9 @@ io::JsonGenericValue Configuration::writeToJsonObject( /** * @brief Retrieves a shared pointer to a copy of the subConfig @ref - * esp::core::Configuration that has the passed @p name . This will create a - * pointer to a new sub-configuration if none exists already with that name, - * but will not add this configuration to this Configuration's internal + * esp::core::config::Configuration that has the passed @p name . This will + * create a pointer to a new sub-configuration if none exists already with that + * name, but will not add this configuration to this Configuration's internal * storage. * * @param name The name of the configuration to retrieve. diff --git a/src/esp/core/Configuration.h b/src/esp/core/Configuration.h index 2d22dd3201..c57d583076 100644 --- a/src/esp/core/Configuration.h +++ b/src/esp/core/Configuration.h @@ -26,20 +26,50 @@ namespace config { /** * @brief This enum lists every type of value that can be currently stored - * directly in an @ref esp::core::Configuration. All supported types should - * have entries in this enum class. All non-trivial types should have their - * enums placed below @p _nonTrivialTypes tag. + * directly in an @ref esp::core::config::Configuration. All supported types + * should have entries in this enum class. All non-trivial types should have + * their enums placed below @p _nonTrivialTypes tag. */ enum class ConfigStoredType { + /** + * @brief Unknown type + */ Unknown = ID_UNDEFINED, + /** + * @brief boolean type + */ Boolean, + /** + * @brief integer type + */ Integer, + /** + * @brief double type + */ Double, + /** + * @brief Magnum::Vector2 type + */ MagnumVec2, + /** + * @brief Magnum::Vector3 type + */ MagnumVec3, + /** + * @brief Magnum::Vector4 type + */ MagnumVec4, + /** + * @brief Magnum::Matrix3 (3x3) type + */ MagnumMat3, + /** + * @brief Magnum::Quaternion type + */ MagnumQuat, + /** + * @brief Magnum::Rad angle type + */ MagnumRad, _nonTrivialTypes, @@ -74,50 +104,93 @@ constexpr ConfigStoredType configStoredTypeFor() { return {}; } +/** + * @brief Returns @ref ConfigStoredType::Boolean type enum for specified type + */ template <> constexpr ConfigStoredType configStoredTypeFor() { return ConfigStoredType::Boolean; } +/** + * @brief Returns @ref ConfigStoredType::Integer type enum for specified type + */ template <> constexpr ConfigStoredType configStoredTypeFor() { return ConfigStoredType::Integer; } +/** + * @brief Returns @ref ConfigStoredType::Double type enum for specified type + */ template <> constexpr ConfigStoredType configStoredTypeFor() { return ConfigStoredType::Double; } +/** + * @brief Returns @ref ConfigStoredType::String type enum for specified type + */ + template <> constexpr ConfigStoredType configStoredTypeFor() { return ConfigStoredType::String; } +/** + * @brief Returns @ref ConfigStoredType::MagnumVec2 type enum for specified type + */ template <> constexpr ConfigStoredType configStoredTypeFor() { return ConfigStoredType::MagnumVec2; } +/** + * @brief Returns @ref ConfigStoredType::MagnumVec3 type enum for specified type + */ template <> constexpr ConfigStoredType configStoredTypeFor() { return ConfigStoredType::MagnumVec3; } + +/** + * @brief Returns @ref ConfigStoredType::MagnumVec3 type enum for specified type + */ template <> constexpr ConfigStoredType configStoredTypeFor() { return ConfigStoredType::MagnumVec3; } + +/** + * @brief Returns @ref ConfigStoredType::MagnumVec4 type enum for specified type + */ template <> constexpr ConfigStoredType configStoredTypeFor() { return ConfigStoredType::MagnumVec4; } + +/** + * @brief Returns @ref ConfigStoredType::MagnumVec4 type enum for specified type + */ template <> constexpr ConfigStoredType configStoredTypeFor() { return ConfigStoredType::MagnumVec4; } + +/** + * @brief Returns @ref ConfigStoredType::MagnumMat3 type enum for specified type + */ template <> constexpr ConfigStoredType configStoredTypeFor() { return ConfigStoredType::MagnumMat3; } + +/** + * @brief Returns @ref ConfigStoredType::MagnumQuat type enum for specified type + */ template <> constexpr ConfigStoredType configStoredTypeFor() { return ConfigStoredType::MagnumQuat; } + +/** + * @brief Returns @ref ConfigStoredType::MagnumRad type enum for specified type + */ template <> constexpr ConfigStoredType configStoredTypeFor() { return ConfigStoredType::MagnumRad; @@ -173,14 +246,34 @@ class ConfigValue { void deleteCurrentValue(); public: + /** + * @brief Constructor + */ ConfigValue() = default; + /** + * @brief Copy Constructor + */ ConfigValue(const ConfigValue& otr); + /** + * @brief Move Constructor + */ ConfigValue(ConfigValue&& otr) noexcept; ~ConfigValue(); + + /** + * @brief Copy assignment + */ ConfigValue& operator=(const ConfigValue& otr); + /** + * @brief Move assignment + */ ConfigValue& operator=(ConfigValue&& otr) noexcept; + /** + * @brief Whether this @ref ConfigValue is valid. + * @return Whether or not the specified type of this @ref ConfigValue is known. + */ bool isValid() const { return _type != ConfigStoredType::Unknown; } /** @@ -188,6 +281,11 @@ class ConfigValue { */ io::JsonGenericValue writeToJsonObject(io::JsonAllocator& allocator) const; + /** + * @brief Set the passed @p value as the data for this @ref ConfigValue, while also setting the appropriate type. + * @tparam The type of the @p value being set. Must be a handled type as specified by @ref ConfigStoredType. + * @param value The value to store in this @ref ConfigValue + */ template void set(const T& value) { deleteCurrentValue(); @@ -216,6 +314,10 @@ class ConfigValue { new (_data) T{value}; } + /** + * @brief Retrieve an appropriately cast copy of the data stored in this @ref ConfigValue + * @tparam The type the data should be cast as. + */ template const T& get() const { ESP_CHECK(_type == configStoredTypeFor(), @@ -237,8 +339,7 @@ class ConfigValue { std::string getAsString() const; /** - * @brief Copy this @ref ConfigValue into the passed @ref - * Cr::Utility::ConfigurationGroup + * @brief Copy this @ref ConfigValue into the passed @ref Corrade::Utility::ConfigurationGroup */ bool putValueInConfigGroup(const std::string& key, Cr::Utility::ConfigurationGroup& cfg) const; @@ -247,6 +348,9 @@ class ConfigValue { ESP_SMART_POINTERS(ConfigValue) }; // ConfigValue +/** + * @brief provide debug stream support for @ref ConfigValue + */ MAGNUM_EXPORT Mn::Debug& operator<<(Mn::Debug& debug, const ConfigValue& value); /** @@ -255,12 +359,23 @@ MAGNUM_EXPORT Mn::Debug& operator<<(Mn::Debug& debug, const ConfigValue& value); */ class Configuration { public: - // convenience typedefs + /** + * @brief Convenience typedef for the value map + */ typedef std::unordered_map ValueMapType; + /** + * @brief Convenience typedef for the subconfiguration map + */ typedef std::map> ConfigMapType; + /** + * @brief Constructor + */ Configuration() = default; + /** + * @brief Copy Constructor + */ Configuration(const Configuration& otr) : configMap_(), valueMap_(otr.valueMap_) { for (const auto& entry : otr.configMap_) { @@ -268,6 +383,9 @@ class Configuration { } } // copy ctor + /** + * @brief Move Constructor + */ Configuration(Configuration&& otr) noexcept : configMap_(std::move(otr.configMap_)), valueMap_(std::move(otr.valueMap_)) {} // move ctor @@ -405,14 +523,33 @@ class Configuration { } // ****************** Setters ****************** + + /** + * @brief Save the passed @p value using specified @p key + * @tparam The type of the value to be saved. + * @param key The key to assign to the passed value. + * @param value The value to save at given @p key + */ template void set(const std::string& key, const T& value) { valueMap_[key].set(value); } + /** + * @brief Save the passed @p value char* as a string to the configuration at + * the passed @p key. + * @param key The key to assign to the passed value. + * @param value The char* to save at given @p key as a string. + */ void set(const std::string& key, const char* value) { valueMap_[key].set(std::string(value)); } + /** + * @brief Save the passed float @p value as a double using the specified @p + * key . + * @param key The key to assign to the passed value. + * @param value The float value to save at given @p key as a double. + */ void set(const std::string& key, float value) { valueMap_[key].set(static_cast(value)); } @@ -486,6 +623,12 @@ class Configuration { return valueMap_.count(key) > 0; } + /** + * @brief Whether passed @p key references a @ref ConfigValue of passed @ref ConfigStoredType @p desiredType + * @param key The key to check the type of. + * @param desiredType the @ref ConfigStoredType to compare the value's type to + * @return Whether @p key references a value that is of @p desiredType. + */ bool hasKeyOfType(const std::string& key, ConfigStoredType desiredType) { ValueMapType::const_iterator mapIter = valueMap_.find(key); return (mapIter != valueMap_.end() && @@ -504,8 +647,8 @@ class Configuration { std::vector findValue(const std::string& key) const; /** - * @brief Builds and returns @ref Cr::Utility::ConfigurationGroup - * holding the values in this esp::core::Configuration. + * @brief Builds and returns @ref Corrade::Utility::ConfigurationGroup + * holding the values in this esp::core::config::Configuration. * * @return a reference to a configuration group for this configuration * object. @@ -542,10 +685,11 @@ class Configuration { /** * @brief Templated subconfig copy getter. Retrieves a shared pointer to a - * copy of the subConfig @ref esp::core::Configuration that has the passed @p - * name . + * copy of the subConfig @ref esp::core::config::Configuration that has the + * passed @p name . * - * @tparam Type to return. Must inherit from @ref esp::core::Configuration + * @tparam Type to return. Must inherit from @ref + * esp::core::config::Configuration * @param name The name of the configuration to retrieve. * @return A pointer to a copy of the configuration having the requested name, * cast to the appropriate type, or nullptr if not found. @@ -580,14 +724,14 @@ class Configuration { /** * @brief Templated Version. Retrieves the stored shared pointer to the - * subConfig @ref esp::core::Configuration that has the passed @p name , cast - * to the specified type. This will create a shared pointer to a new + * subConfig @ref esp::core::config::Configuration that has the passed @p name + * , cast to the specified type. This will create a shared pointer to a new * sub-configuration if none exists and return it, cast to specified type. * * Use this function when you wish to modify this configuration's * subgroup, possibly creating it in the process. - * @tparam The type to cast the @ref esp::core::Configuration to. Type is - * checked to verify that it inherits from Configuration. + * @tparam The type to cast the @ref esp::core::config::Configuration to. Type + * is checked to verify that it inherits from Configuration. * @param name The name of the configuration to edit. * @return The actual pointer to the configuration having the requested * name, cast to the specified type. @@ -602,7 +746,10 @@ class Configuration { } /** - * @brief move specified subgroup config into configMap at desired name + * @brief move specified subgroup config into configMap at desired name. Will + * replace any subconfiguration at given name without warning if present. + * @param name The name of the subconfiguration to add + * @param configPtr A pointer to a subconfiguration to add. */ template void setSubconfigPtr(const std::string& name, std::shared_ptr& configPtr) { @@ -613,17 +760,30 @@ class Configuration { configMap_[name] = std::move(configPtr); } // setSubconfigPtr - std::shared_ptr removeSubconfig(const std::string& key) { - ConfigMapType::const_iterator mapIter = configMap_.find(key); + /** + * @brief Removes and returns the named subconfig. If not found, returns an + * empty subconfig with a warning. + * @param name The name of the subconfiguration to delete + * @return a shared pointer to the removed subconfiguration. + */ + std::shared_ptr removeSubconfig(const std::string& name) { + ConfigMapType::const_iterator mapIter = configMap_.find(name); if (mapIter != configMap_.end()) { configMap_.erase(mapIter); return mapIter->second; } - ESP_WARNING() << "Key :" << key + ESP_WARNING() << "Name :" << name << "not present in map of subconfigurations."; return {}; } + /** + * @brief Retrieve the number of entries held by the subconfig with the give + * name + * @param name The name of the subconfig to query. If not found, returns 0 + * with a warning. + * @return The number of entries in the named subconfig + */ int getSubconfigNumEntries(const std::string& name) const { auto configIter = configMap_.find(name); if (configIter != configMap_.end()) { @@ -637,7 +797,7 @@ class Configuration { * @brief Merges configuration pointed to by @p config into this * configuration, including all subconfigs. Passed config overwrites * existing data in this config. - * @param config The source of configuration data we wish to merge into this + * @param src The source of configuration data we wish to merge into this * configuration. */ void overwriteWithConfig(const std::shared_ptr& src) { @@ -706,7 +866,7 @@ class Configuration { /** * @brief Take the passed @p key and query the config value for that key, - * writing it to @p jsonName within the passed jsonObj. + * writing it to @p jsonName within the passed @p jsonObj. * @param key The key of the data in the configuration * @param jsonName The tag to use in the json file * @param jsonObj The json object to write to @@ -717,6 +877,13 @@ class Configuration { io::JsonGenericValue& jsonObj, io::JsonAllocator& allocator) const; + /** + * @brief Take the passed @p key and query the config value for that key, + * writing it to tag with @p key as name within the passed @p jsonObj. + * @param key The key of the data in the configuration + * @param jsonObj The json object to write to + * @param allocator The json allocator to use to build the json object + */ void writeValueToJson(const char* key, io::JsonGenericValue& jsonObj, io::JsonAllocator& allocator) const { @@ -783,23 +950,30 @@ class Configuration { return result.first->second; } - // Map to hold configurations as subgroups + /** + * @brief Map to hold configurations as subgroups + */ ConfigMapType configMap_{}; - // Map that haolds all config values + /** + * @brief Map that holds all config values + */ ValueMapType valueMap_{}; ESP_SMART_POINTERS(Configuration) }; // class Configuration +/** + * @brief provide debug stream support for a @ref Configuration + */ MAGNUM_EXPORT Mn::Debug& operator<<(Mn::Debug& debug, const Configuration& value); /** * @brief Retrieves a shared pointer to a copy of the subConfig @ref - * esp::core::Configuration that has the passed @p name . This will create a - * pointer to a new sub-configuration if none exists already with that name, - * but will not add this configuration to this Configuration's internal + * esp::core::config::Configuration that has the passed @p name . This will + * create a pointer to a new sub-configuration if none exists already with that + * name, but will not add this configuration to this Configuration's internal * storage. * * @param name The name of the configuration to retrieve. @@ -810,11 +984,23 @@ MAGNUM_EXPORT Mn::Debug& operator<<(Mn::Debug& debug, template <> std::shared_ptr Configuration::getSubconfigCopy( const std::string& name) const; - +/** + * @brief Retrieve a shared pointer to the actual subconfiguration given by @p + * name, or a new subconfiguration with that name, if none exists. + * + * @param name The name of the desired subconfiguration + * @return A pointer to the configuration having the requested + * name, or a pointer to an empty configuration. + */ template <> std::shared_ptr Configuration::editSubconfig( const std::string& name); +/** + * @brief Save the passed @ref Configuration pointed to by @p configPtr at location specified by @p name + * @param name The name to save the subconfiguration by + * @param configPtr A pointer to the @ref Configuration to save with the given @p name . + */ template <> void Configuration::setSubconfigPtr( const std::string& name, diff --git a/src/esp/core/managedContainers/AbstractManagedObject.h b/src/esp/core/managedContainers/AbstractManagedObject.h index 335c99cc64..3de1b854f5 100644 --- a/src/esp/core/managedContainers/AbstractManagedObject.h +++ b/src/esp/core/managedContainers/AbstractManagedObject.h @@ -13,9 +13,10 @@ namespace managedContainers { /** * @brief This abstract base class provides the interface of expected * functionality for an object to be manageable by @ref - * esp::core::ManagedContainer class template specializations. Any class that - * inherits from this class properly can be managed by a @ref - * esp::core::ManagedContainer specilization. + * esp::core::managedContainers::ManagedContainer class template + * specializations. Any class that inherits from this class properly can be + * managed by a @ref esp::core::managedContainers::ManagedContainer + * specilization. */ class AbstractManagedObject { public: @@ -23,7 +24,8 @@ class AbstractManagedObject { /** * @brief Get the instancing class of the ManagedObject instance. Should * only be set from implementer's constructor. Used as key in constructor - * function pointer maps in @ref esp::core::ManagedContainer. + * function pointer maps in @ref + * esp::core::managedContainers::ManagedContainer. */ virtual std::string getClassKey() const = 0; diff --git a/src/esp/core/managedContainers/ManagedContainer.h b/src/esp/core/managedContainers/ManagedContainer.h index 31e78ae671..f17870c051 100644 --- a/src/esp/core/managedContainers/ManagedContainer.h +++ b/src/esp/core/managedContainers/ManagedContainer.h @@ -6,8 +6,9 @@ #define ESP_CORE_MANAGEDCONTAINER_H_ /** @file - * @brief Class Template @ref esp::core::ManagedContainer : container - * functionality to manage @ref esp::core::AbstractManagedObject objects + * @brief Class Template @ref esp::core::managedContainers::ManagedContainer : + * container functionality to manage @ref + * esp::core::managedContainers::AbstractManagedObject objects */ #include "ManagedContainerBase.h" @@ -37,10 +38,10 @@ enum class ManagedObjectAccess { /** * @brief Class template defining responsibilities and functionality for - * managing @ref esp::core::AbstractManagedObject constructs. + * managing @ref esp::core::managedContainers::AbstractManagedObject constructs. * @tparam T the type of managed object a particular specialization of * this class works with. Must inherit from @ref - * esp::core::AbstractManagedObject. + * esp::core::managedContainers::AbstractManagedObject. * @tparam Access Whether the default access (getters) for this * container provides copies of the objects held, or the actual objects * themselves. @@ -54,7 +55,7 @@ class ManagedContainer : public ManagedContainerBase { /** * @brief Alias for shared pointer to the @ref - * esp::core::AbstractManagedObject this container manages. + * esp::core::managedContainers::AbstractManagedObject this container manages. */ typedef std::shared_ptr ManagedPtr; @@ -111,7 +112,8 @@ class ManagedContainer : public ManagedContainerBase { } // ManagedContainer::createDefault /** - * @brief Add a copy of @ref esp::core::AbstractManagedObject to the @ref + * @brief Add a copy of @ref + * esp::core::managedContainers::AbstractManagedObject to the @ref * objectLibrary_. * * @param managedObject The managed object. @@ -470,8 +472,8 @@ class ManagedContainer : public ManagedContainerBase { /** * @brief Set the object to provide default values upon construction of @ref - * esp::core::AbstractManagedObject. Override if object should not have - * defaults + * esp::core::managedContainers::AbstractManagedObject. Override if object + * should not have defaults * @param _defaultObj the object to use for defaults; */ virtual void setDefaultObject(ManagedPtr& _defaultObj) { @@ -560,8 +562,8 @@ class ManagedContainer : public ManagedContainerBase { } // ManagedContainer:: /** - * @brief Build an @ref esp::core::AbstractManagedObject object of type - * associated with passed object. + * @brief Build an @ref esp::core::managedContainers::AbstractManagedObject + * object of type associated with passed object. * @param origAttr The ptr to the original AbstractManagedObject object to * copy */ diff --git a/src/esp/core/managedContainers/ManagedContainerBase.h b/src/esp/core/managedContainers/ManagedContainerBase.h index 99891c7c2a..c5d51d711f 100644 --- a/src/esp/core/managedContainers/ManagedContainerBase.h +++ b/src/esp/core/managedContainers/ManagedContainerBase.h @@ -6,9 +6,9 @@ #define ESP_CORE_MANAGEDCONTAINERBASE_H_ /** @file - * @brief Abstract Class @ref esp::core::ManagedContainerBase : type-independent - * container functionality consumed by @ref esp::core::ManagedContainer to cut - * down on code bload. + * @brief Abstract Class @ref esp::core::managedContainers::ManagedContainerBase + * : type-independent container functionality consumed by @ref + * esp::core::managedContainers::ManagedContainer to cut down on code bload. */ #include diff --git a/src/esp/core/managedContainers/ManagedFileBasedContainer.h b/src/esp/core/managedContainers/ManagedFileBasedContainer.h index 404226baa8..84fa141000 100644 --- a/src/esp/core/managedContainers/ManagedFileBasedContainer.h +++ b/src/esp/core/managedContainers/ManagedFileBasedContainer.h @@ -6,9 +6,10 @@ #define ESP_CORE_MANAGEDFILEBASEDCONTAINER_H_ /** @file - * @brief Class Template @ref esp::core::ManagedFileBasedContainer : @ref - * esp::core::ManagedContainer functionality specifically for file-based @ref - * esp::core::AbstractManagedObject objects + * @brief Class Template @ref + * esp::core::managedContainers::ManagedFileBasedContainer : @ref + * esp::core::managedContainers::ManagedContainer functionality specifically for + * file-based @ref esp::core::managedContainers::AbstractManagedObject objects */ #include "AbstractFileBasedManagedObject.h" @@ -30,11 +31,11 @@ namespace core { namespace managedContainers { /** * @brief Class template defining file-io-based responsibilities and - * functionality for managing @ref esp::core::AbstractFileBasedManagedObject - * constructs. + * functionality for managing @ref + * esp::core::managedContainers::AbstractFileBasedManagedObject constructs. * @tparam T the type of managed object a particular specialization of * this class works with. Must inherit from @ref - * esp::core::AbstractFileBasedManagedObject. + * esp::core::managedContainers::AbstractFileBasedManagedObject. * @tparam Access Whether the default access (getters) for this * container provides copies of the objects held, or the actual objects * themselves. @@ -153,11 +154,13 @@ class ManagedFileBasedContainer : public ManagedContainer { const io::JsonGenericValue& jsonConfig) = 0; /** - * @brief Saves the @ref esp::core::AbstractFileBasedManagedObject with handle + * @brief Saves the @ref + * esp::core::managedContainers::AbstractFileBasedManagedObject with handle * @p objectHandle to a JSON file using a non-colliding version (if @p * overwrite is false) of the object's handle, with appropriate extension * denoting type of JSON, as file name, to the @ref - * esp::core::AbstractFileBasedManagedObject's specified file directory. + * esp::core::managedContainers::AbstractFileBasedManagedObject's specified + * file directory. * @param objectHandle The name of the object to save. If not found, returns * false. * @param overwrite Whether or not an existing json file with the same name @@ -183,7 +186,8 @@ class ManagedFileBasedContainer : public ManagedContainer { * @brief Saves the passed @p managedObject to a JSON file using a * non-colliding version (if @p overwrite is false) of the object's handle, * with appropriate extension denoting type of JSON, as file name, to the @ref - * esp::core::AbstractFileBasedManagedObject's specified file directory. + * esp::core::managedContainers::AbstractFileBasedManagedObject's specified + * file directory. * @param managedObject Theobject to save. * @param overwrite Whether or not an existing json file with the same name * should be overwritten. @@ -193,7 +197,8 @@ class ManagedFileBasedContainer : public ManagedContainer { bool overwrite) const; /** - * @brief Saves the @ref esp::core::AbstractFileBasedManagedObject with handle + * @brief Saves the @ref + * esp::core::managedContainers::AbstractFileBasedManagedObject with handle * @p objectHandle to a JSON file using the specified, fully-qualified @p * fullFilename, with appropriate type extension appended if not present. Will * overwrite any file with same name found. @@ -265,11 +270,13 @@ class ManagedFileBasedContainer : public ManagedContainer { /** * @brief Return a properly formated JSON file name for the @ref - * esp::core::AbstractFileBasedManagedObject managed by this manager. This - * will change the extension to the appropriate json extension. + * esp::core::managedContainers::AbstractFileBasedManagedObject managed by + * this manager. This will change the extension to the appropriate json + * extension. * @param filename The original filename * @return a candidate JSON file name for the @ref - * esp::core::AbstractFileBasedManagedObject managed by this manager. + * esp::core::managedContainers::AbstractFileBasedManagedObject managed by + * this manager. */ std::string getFormattedJSONFileName(const std::string& filename) { return this->convertFilenameToPassedExt(filename, this->JSONTypeExt_); @@ -277,7 +284,8 @@ class ManagedFileBasedContainer : public ManagedContainer { /** * @brief Returns the config file type and file extension used for the files - * that build the @ref esp::core::AbstractFileBasedManagedObject managed by + * that build the @ref + * esp::core::managedContainers::AbstractFileBasedManagedObject managed by * this manager. */ std::string getJSONTypeExt() const { return JSONTypeExt_; } @@ -438,8 +446,8 @@ class ManagedFileBasedContainer : public ManagedContainer { /** * @brief Get directory component of managed object handle and call @ref - * esp::core::AbstractManagedObject::setFileDirectory if a legitimate - * directory exists in handle. + * esp::core::managedContainers::AbstractFileBasedManagedObject::setFileDirectory + * if a legitimate directory exists in handle. * * @param object pointer to managed object to set */ diff --git a/src/esp/gfx/DrawableConfiguration.h b/src/esp/gfx/DrawableConfiguration.h index 80bdbca462..def2441f1b 100644 --- a/src/esp/gfx/DrawableConfiguration.h +++ b/src/esp/gfx/DrawableConfiguration.h @@ -13,9 +13,9 @@ namespace esp { namespace gfx { class DrawableGroup; -/** - * This class will hold configuration values and utilities for Drawables and the - * shaders that they own. +/** @file + * @brief This class will hold configuration values and utilities for Drawables + * and the shaders that they own. */ class DrawableConfiguration { public: diff --git a/src/esp/metadata/MetadataMediator.h b/src/esp/metadata/MetadataMediator.h index 85c0bd9ed4..c16d7d3d00 100644 --- a/src/esp/metadata/MetadataMediator.h +++ b/src/esp/metadata/MetadataMediator.h @@ -146,8 +146,7 @@ class MetadataMediator { /** * @brief Return manager for construction and access to asset attributes for * current dataset. - * @return The current dataset's @ref esp::metadata::managers::AssetAttributesManager::ptr, - * or nullptr if no current dataset. + * @return A shared pointer to the current dataset's @ref esp::metadata::managers::AssetAttributesManager. */ const managers::AssetAttributesManager::ptr& getAssetAttributesManager() { return getActiveDSAttribs()->getAssetAttributesManager(); @@ -156,9 +155,8 @@ class MetadataMediator { /** * @brief Return manager for construction and access to object attributes for * current dataset. - * @return The current dataset's @ref - * managers::LightLayoutAttributesManager::ptr, or nullptr if no current - * dataset. + * @return A shared pointer to the current dataset's @ref + * esp::metadata::managers::LightLayoutAttributesManager. */ const managers::LightLayoutAttributesManager::ptr& getLightLayoutAttributesManager() { @@ -167,8 +165,7 @@ class MetadataMediator { /** * @brief Return manager for construction and access to articulated object * attributes for current dataset. - * @return The current dataset's @ref esp::metadata::managers::AOAttributesManager::ptr, - * or nullptr if no current dataset. + * @return A shared pointer to the current dataset's @ref esp::metadata::managers::AOAttributesManager. */ const managers::AOAttributesManager::ptr& getAOAttributesManager() { return getActiveDSAttribs()->getAOAttributesManager(); @@ -176,8 +173,7 @@ class MetadataMediator { /** * @brief Return manager for construction and access to object attributes for * current dataset. - * @return The current dataset's @ref esp::metadata::managers::ObjectAttributesManager::ptr, - * or nullptr if no current dataset. + * @return A shared pointer to the current dataset's @ref esp::metadata::managers::ObjectAttributesManager. */ const managers::ObjectAttributesManager::ptr& getObjectAttributesManager() { return getActiveDSAttribs()->getObjectAttributesManager(); @@ -186,6 +182,7 @@ class MetadataMediator { /** * @brief Return manager for construction and access to physics world * attributes. + * @return A shared pointer to the current @ref esp::metadata::managers::PhysicsAttributesManager. */ const managers::PhysicsAttributesManager::ptr& getPhysicsAttributesManager() const { @@ -203,8 +200,8 @@ class MetadataMediator { /** * @brief Return manager for construction and access to * @ref esp::attributes::SceneInstanceAttributes for current dataset. - * @return The current dataset's @ref - * managers::SceneInstanceAttributesManager::ptr, or nullptr if no current + * @return A shared pointer to the current dataset's @ref + * managers::SceneInstanceAttributesManager or nullptr if no current * dataset. */ const managers::SceneInstanceAttributesManager::ptr& @@ -215,8 +212,7 @@ class MetadataMediator { /** * @brief Return manager for construction and access to stage attributes for * current dataset. - * @return The current dataset's @ref esp::metadata::managers::StageAttributesManager::ptr, - * or nullptr if no current dataset. + * @return A shared pointer to the current dataset's @ref esp::metadata::managers::StageAttributesManager */ const managers::StageAttributesManager::ptr& getStageAttributesManager() { return getActiveDSAttribs()->getStageAttributesManager(); diff --git a/src/esp/metadata/URDFParser.h b/src/esp/metadata/URDFParser.h index 38457b25be..2a352c0c49 100644 --- a/src/esp/metadata/URDFParser.h +++ b/src/esp/metadata/URDFParser.h @@ -20,15 +20,15 @@ /** @file * @brief Storage classes for articulated object metadata and URDF file parsing - * functionality. Struct @ref metadata::URDF::MaterialColor, struct @ref - * metadata::URDF::Material, enum @ref metadata::URDF::JointTypes, enum @ref - * metadata::URDF::GeomTypes, struct @ref metadata::URDF::Geometry, struct @ref - * metadata::URDF::Shape, struct @ref metadata::URDF::VisualShape, enum @ref - * metadata::URDF::CollisionFlags, struct @ref metadata::URDF::CollisionShape, - * struct @ref metadata::URDF::Inertia, struct @ref metadata::URDF::Joint, enum - * @ref metadata::URDF::LinkContactFlags, struct @ref - * metadata::URDF::LinkContactInfo, struct @ref metadata::URDF::Link, class @ref - * metadata::URDF::Model, class @ref metadata::URDF::Parser. + * functionality. Struct @ref esp::metadata::URDF::MaterialColor, struct @ref + * esp::metadata::URDF::Material, enum @ref esp::metadata::URDF::JointTypes, enum @ref + * esp::metadata::URDF::GeomTypes, struct @ref esp::metadata::URDF::Geometry, struct @ref + * esp::metadata::URDF::Shape, struct @ref esp::metadata::URDF::VisualShape, enum @ref + * esp::metadata::URDF::CollisionFlags, struct @ref esp::metadata::URDF::CollisionShape, + * struct @ref esp::metadata::URDF::Inertia, struct @ref esp::metadata::URDF::Joint, enum + * @ref esp::metadata::URDF::LinkContactFlags, struct @ref + * esp::metadata::URDF::LinkContactInfo, struct @ref esp::metadata::URDF::Link, class @ref + * esp::metadata::URDF::Model, class @ref esp::metadata::URDF::Parser. */ namespace tinyxml2 { diff --git a/src/esp/metadata/attributes/AttributesBase.h b/src/esp/metadata/attributes/AttributesBase.h index fceaa88c60..c4be0b5a63 100644 --- a/src/esp/metadata/attributes/AttributesBase.h +++ b/src/esp/metadata/attributes/AttributesBase.h @@ -43,8 +43,9 @@ std::string getMeshTypeName(esp::assets::AssetType meshTypeEnum); /** * @brief Base class for all implemented attributes. Inherits from @ref - * esp::core::AbstractFileBasedManagedObject so the attributes can be managed by - * a @ref esp::core::ManagedContainer. + * esp::core::managedContainers::AbstractFileBasedManagedObject so the + * attributes can be managed by a @ref + * esp::core::managedContainers::ManagedContainer. */ class AbstractAttributes : public esp::core::managedContainers::AbstractFileBasedManagedObject, diff --git a/src/esp/metadata/attributes/AttributesEnumMaps.h b/src/esp/metadata/attributes/AttributesEnumMaps.h index a8a78cbc28..4563b50a31 100644 --- a/src/esp/metadata/attributes/AttributesEnumMaps.h +++ b/src/esp/metadata/attributes/AttributesEnumMaps.h @@ -24,23 +24,23 @@ namespace attributes { enum class ArticulatedObjectBaseType { /** - * Represents the user not specifying the type of base/root joint. + * @brief Represents the user not specifying the type of base/root joint. * Resorts to any previously known/set value. */ Unspecified = ID_UNDEFINED, /** - * The Articulated Object is joined to the world with a free joint and + * @brief The Articulated Object is joined to the world with a free joint and * is free to move around in the world. */ Free, /** - * The Articulated Object is connected to the world with a fixed joint + * @brief The Articulated Object is connected to the world with a fixed joint * at a specific location in the world and is unable to move within the world. */ Fixed, /** - * End cap value - no Articulated Object base type enums should be defined - * at or past this enum. + * @brief End cap value - no Articulated Object base type enums should be + * defined at or past this enum. */ EndAOBaseType, }; @@ -51,22 +51,22 @@ enum class ArticulatedObjectBaseType { */ enum class ArticulatedObjectInertiaSource { /** - * Represents the user not specifying the source of the inertia values + * @brief Represents the user not specifying the source of the inertia values * to use. Resorts to any previously known/set value. */ Unspecified = ID_UNDEFINED, /** - * Use inertia values computed from the collision shapes when the model + * @brief Use inertia values computed from the collision shapes when the model * is loaded. This is usually more stable and is the default value. */ Computed, /** - * Use the interia values specified in the URDF file. + * @brief Use the interia values specified in the URDF file. */ URDF, /** - * End cap value - no Articulated Object intertia source enums should be - * defined at or past this enum. + * @brief End cap value - no Articulated Object intertia source enums should + * be defined at or past this enum. */ EndAOInertiaSource, }; @@ -77,20 +77,21 @@ enum class ArticulatedObjectInertiaSource { */ enum class ArticulatedObjectLinkOrder { /** - * Represents the user not specifying which link ordering to use. Resorts - * to any previously known/set value + * @brief Represents the user not specifying which link ordering to use. + * Resorts to any previously known/set value */ Unspecified = ID_UNDEFINED, /** - * Use the link order specified in the source URDF file. + * @brief Use the link order specified in the source URDF file. */ URDFOrder, /** - * Use the link order derived from a tree traversal of the Articulated Object. + * @brief Use the link order derived from a tree traversal of the Articulated + * Object. */ TreeTraversal, /** - * End cap value - no Articulated Object link order enums should be + * @brief End cap value - no Articulated Object link order enums should be * defined at or past this enum. */ EndAOLinkOrder, @@ -103,36 +104,36 @@ enum class ArticulatedObjectLinkOrder { */ enum class ArticulatedObjectRenderMode { /** - * Represents the user not specifying which rendering mode to use. Resorts - * to any previously known/set value + * @brief Represents the user not specifying which rendering mode to use. + * Resorts to any previously known/set value */ Unspecified = ID_UNDEFINED, /** - * Render the Articulated Object using its skin if it has one, otherwise - * render it using the urdf-defined link meshes/primitives. + * @brief Render the Articulated Object using its skin if it has one, + * otherwise render it using the urdf-defined link meshes/primitives. */ Default, /** - * Render the Articulated Object using its skin. + * @brief Render the Articulated Object using its skin. */ Skin, /** - * Render the Articulated Object using urdf-defined meshes/primitives to - * respresent each link. + * @brief Render the Articulated Object using urdf-defined meshes/primitives + * to respresent each link. */ LinkVisuals, /** - * + * @brief Do not render the Articulated Object. */ None, /** - * Render the Articulated Object using both the skin and the urdf-defined link - * meshes/primitives. + * @brief Render the Articulated Object using both the skin and the + * urdf-defined link meshes/primitives. */ Both, /** - * End cap value - no Articulated Object render mode enums should be defined - * at or past this enum. + * @brief End cap value - no Articulated Object render mode enums should be + * defined at or past this enum. */ EndAORenderMode, }; @@ -143,31 +144,32 @@ enum class ArticulatedObjectRenderMode { */ enum class ObjectInstanceShaderType { /** - * Represents the user not specifying which shader type choice to use. Resort - * to defaults for object type. + * @brief Represents the user not specifying which shader type choice to use. + * Resort to defaults for object type. */ Unspecified = ID_UNDEFINED, /** - * Override any config-specified or default shader-type values to use the - * material-specified shader. + * @brief Override any config-specified or default shader-type values to use + * the material-specified shader. */ Material, /** - * Refers to flat shading, pure color and no lighting. This is often used for - * textured objects + * @brief Refers to flat shading, pure color and no lighting. This is often + * used for textured objects */ Flat, /** - * Refers to phong shading with pure diffuse color. + * @brief Refers to phong shading with pure diffuse color. */ Phong, /** - * Refers to using a shader built with physically-based rendering models. + * @brief Refers to using a shader built with physically-based rendering + * models. */ PBR, /** - * End cap value - no shader type enums should be defined at or past this - * enum. + * @brief End cap value - no shader type enums should be defined at or past + * this enum. */ EndShaderType, }; @@ -200,8 +202,8 @@ enum class SceneInstanceTranslationOrigin { */ COM, /** - * End cap value - no instance translation origin type enums should be defined - * at or past this enum. + * @brief End cap value - no instance translation origin type enums should be + * defined at or past this enum. */ EndTransOrigin, }; diff --git a/src/esp/metadata/managers/ObjectAttributesManager.h b/src/esp/metadata/managers/ObjectAttributesManager.h index 57b0075f7b..1e5b0c3303 100644 --- a/src/esp/metadata/managers/ObjectAttributesManager.h +++ b/src/esp/metadata/managers/ObjectAttributesManager.h @@ -193,7 +193,7 @@ class ObjectAttributesManager * attributesManager-specific upon template removal, such as removing a * specific template handle from the list of file-based template handles in * ObjectAttributesManager. This should only be called @ref - * esp::core::ManagedContainerBase. + * esp::core::managedContainers::ManagedContainerBase. * * @param templateID the ID of the template to remove * @param templateHandle the string key of the attributes desired. diff --git a/src/esp/metadata/managers/PhysicsAttributesManager.h b/src/esp/metadata/managers/PhysicsAttributesManager.h index 89360c19c0..cccb4cffa1 100644 --- a/src/esp/metadata/managers/PhysicsAttributesManager.h +++ b/src/esp/metadata/managers/PhysicsAttributesManager.h @@ -92,7 +92,7 @@ class PhysicsAttributesManager * attributesManager-specific upon template removal, such as removing a * specific template handle from the list of file-based template handles in * ObjectAttributesManager. This should only be called @ref - * esp::core::ManagedContainerBase. + * esp::core::managedContainers::ManagedContainerBase. * * @param templateID the ID of the template to remove * @param templateHandle the string key of the attributes desired. diff --git a/src/esp/metadata/managers/SceneDatasetAttributesManager.h b/src/esp/metadata/managers/SceneDatasetAttributesManager.h index 9ba14db4df..c64011529e 100644 --- a/src/esp/metadata/managers/SceneDatasetAttributesManager.h +++ b/src/esp/metadata/managers/SceneDatasetAttributesManager.h @@ -165,7 +165,7 @@ class SceneDatasetAttributesManager * attributesManager-specific upon template removal, such as removing a * specific template handle from the list of file-based template handles in * ObjectAttributesManager. This should only be called @ref - * esp::core::ManagedContainerBase. + * esp::core::managedContainers::ManagedContainerBase. * * @param templateID the ID of the template to remove * @param templateHandle the string key of the attributes desired. diff --git a/src/esp/metadata/managers/SceneInstanceAttributesManager.h b/src/esp/metadata/managers/SceneInstanceAttributesManager.h index 4dda7064fb..e4443b83ea 100644 --- a/src/esp/metadata/managers/SceneInstanceAttributesManager.h +++ b/src/esp/metadata/managers/SceneInstanceAttributesManager.h @@ -151,7 +151,7 @@ class SceneInstanceAttributesManager * attributesManager-specific upon template removal, such as removing a * specific template handle from the list of file-based template handles in * ObjectAttributesManager. This should only be called @ref - * esp::core::ManagedContainerBase. + * esp::core::managedContainers::ManagedContainerBase. * * @param templateID the ID of the template to remove * @param templateHandle the string key of the attributes desired. diff --git a/src/esp/metadata/managers/StageAttributesManager.h b/src/esp/metadata/managers/StageAttributesManager.h index 60ea990858..2f6f587097 100644 --- a/src/esp/metadata/managers/StageAttributesManager.h +++ b/src/esp/metadata/managers/StageAttributesManager.h @@ -127,7 +127,7 @@ class StageAttributesManager * attributesManager-specific upon template removal, such as removing a * specific template handle from the list of file-based template handles in * ObjectAttributesManager. This should only be called internally from @ref - * esp::core::ManagedContainerBase. + * esp::core::managedContainers::ManagedContainerBase. * * @param templateID the ID of the template to remove * @param templateHandle the string key of the attributes desired. diff --git a/src/esp/physics/PhysicsManager.h b/src/esp/physics/PhysicsManager.h index ae50480c5e..843ad11e84 100644 --- a/src/esp/physics/PhysicsManager.h +++ b/src/esp/physics/PhysicsManager.h @@ -49,7 +49,9 @@ class PhysicsManagerAttributes; namespace physics { -/** @brief Holds information about one ray hit instance. */ +/** + * @brief Holds information about one ray hit instance. + */ struct RayHitInfo { /** @brief The id of the object hit by this ray. Stage hits are -1. */ int objectId{}; @@ -67,7 +69,9 @@ struct RayHitInfo { ESP_SMART_POINTERS(RayHitInfo) }; -/** @brief Holds information about all ray hit instances from a ray cast. */ +/** + * @brief Holds information about all ray hit instances from a ray cast. + */ struct RaycastResults { std::vector hits; esp::geo::Ray ray; @@ -84,7 +88,9 @@ struct RaycastResults { ESP_SMART_POINTERS(RaycastResults) }; -/** @brief based on Bullet b3ContactPointData */ +/** + * @brief based on Bullet b3ContactPointData + */ struct ContactPointData { int objectIdA = -2; // stage is -1 int objectIdB = -2; @@ -115,7 +121,9 @@ struct ContactPointData { ESP_SMART_POINTERS(ContactPointData) }; -/** @brief describes the type of a rigid constraint.*/ +/** + * @brief describes the type of a rigid constraint. + */ enum class RigidConstraintType { /** @brief lock a point in one frame to a point in another with no orientation * constraint @@ -127,7 +135,9 @@ enum class RigidConstraintType { Fixed }; // enum class RigidConstraintType -/** @brief Stores rigid constraint parameters for creation and updates.*/ +/** + * @brief Stores rigid constraint parameters for creation and updates. + */ struct RigidConstraintSettings { public: RigidConstraintSettings() = default; diff --git a/src/esp/physics/PhysicsObjectBase.h b/src/esp/physics/PhysicsObjectBase.h index cf3a551f73..d2881e484d 100644 --- a/src/esp/physics/PhysicsObjectBase.h +++ b/src/esp/physics/PhysicsObjectBase.h @@ -26,7 +26,7 @@ class ResourceManager; namespace physics { /** - * @brief Motion type of a @ref RigidObject. + * @brief Motion type of a @ref esp::physics::RigidObject. * Defines its treatment by the simulator and operations which can be performed * on it. */ @@ -40,13 +40,13 @@ enum class MotionType { /** * The object is not expected to move and should not allow kinematic updates. * Likely treated as static collision geometry. See @ref - * RigidObjectType::SCENE. + * esp::physics::RigidStage. */ STATIC, /** * The object is expected to move kinematically, but is not simulated. Default - * behavior of @ref RigidObject with no physics simulator defined. + * behavior of @ref esp::physics::RigidObject with no physics simulator defined. */ KINEMATIC, @@ -87,7 +87,7 @@ class PhysicsObjectBase : public Magnum::SceneGraph::AbstractFeature3D { Magnum::SceneGraph::AbstractFeature3D::object()); } /** - * @brief Get the @ref physics::MotionType of the object. See @ref + * @brief Get the @ref MotionType of the object. See @ref * setMotionType. * @return The object's current @ref MotionType. */ @@ -541,9 +541,9 @@ class PhysicsObjectBase : public Magnum::SceneGraph::AbstractFeature3D { /** * @brief Stores user-defined attributes for this object, held as a smart - * pointer to a @ref esp::core::Configuration. These attributes are not - * internally processed by habitat, but provide a "scratch pad" for the user - * to access and save important information and metadata. + * pointer to a @ref esp::core::config::Configuration. These attributes are + * not internally processed by habitat, but provide a "scratch pad" for the + * user to access and save important information and metadata. */ core::config::Configuration::ptr userAttributes_ = nullptr; diff --git a/src/esp/physics/bullet/BulletArticulatedObject.h b/src/esp/physics/bullet/BulletArticulatedObject.h index f965ddc2a2..4227c22cd7 100644 --- a/src/esp/physics/bullet/BulletArticulatedObject.h +++ b/src/esp/physics/bullet/BulletArticulatedObject.h @@ -371,7 +371,7 @@ class BulletArticulatedObject : public ArticulatedObject { /** * @brief Create a new JointMotor from a JointMotorSettings. * - * Note: No base implementation. See @ref bullet::BulletArticulatedObject. + * Note: No base implementation. See @ref BulletArticulatedObject. * @param linkIndex the index of the link for which the parent joint will have * a motor attached * @param settings The settings for the joint motor. Must have JointMotorType @@ -396,7 +396,7 @@ class BulletArticulatedObject : public ArticulatedObject { * @brief Create a new set of default JointMotors for all valid dofs in an * ArticulatedObject. * - * Note: No base implementation. See @ref bullet::BulletArticulatedObject. + * Note: No base implementation. See @ref BulletArticulatedObject. * * @return A map of motorIds to link/joint indices for the new motors. */ @@ -412,7 +412,7 @@ class BulletArticulatedObject : public ArticulatedObject { * this object. This function will safely skip states for joints which don't * support JointMotors. * - * Note: No base implementation. See @ref bullet::BulletArticulatedObject. + * Note: No base implementation. See @ref BulletArticulatedObject. * * @param stateTargets Full length joint position or velocity array for this * object. diff --git a/src/esp/physics/bullet/BulletBase.h b/src/esp/physics/bullet/BulletBase.h index 422e69414c..58290d30c5 100644 --- a/src/esp/physics/bullet/BulletBase.h +++ b/src/esp/physics/bullet/BulletBase.h @@ -78,13 +78,13 @@ class BulletBase { virtual ~BulletBase() { bWorld_.reset(); } /** @brief Get the scalar collision margin of an object. Retun 0.0 for a @ref - * RigidObjectType::SCENE. See @ref btCompoundShape::getMargin. + * esp::physics::RigidStage. See @ref btCompoundShape::getMargin. * @return The scalar collision margin of the object. */ virtual double getMargin() const { return 0.0; } /** @brief Set the scalar collision margin of an object. Does not affect @ref - * RigidObjectType::SCENE. See @ref btCompoundShape::setMargin. + * esp::physics::RigidStage. See @ref btCompoundShape::setMargin. * @param margin The new scalar collision margin of the object. */ virtual void setMargin(CORRADE_UNUSED const double margin) {} @@ -138,7 +138,7 @@ class BulletBase { * @ref btMultiBodyDynamicsWorld.*/ std::shared_ptr bWorld_; - /** @brief Static data: All components of a @ref RigidObjectType::SCENE are + /** @brief Static data: All components of a @ref esp::physics::RigidStage are * stored here. Also, all objects set to STATIC are stored here. */ std::vector> bStaticCollisionObjects_; diff --git a/src/esp/physics/bullet/BulletRigidObject.h b/src/esp/physics/bullet/BulletRigidObject.h index 94053669ca..a2687b0120 100644 --- a/src/esp/physics/bullet/BulletRigidObject.h +++ b/src/esp/physics/bullet/BulletRigidObject.h @@ -482,7 +482,7 @@ class BulletRigidObject : public BulletBase, */ Magnum::Range3D getCollisionShapeAabb() const override; - /** @brief Object data: All components of a @ref RigidObjectType::OBJECT are + /** @brief Object data: All components of a @ref esp::physics::RigidObjectType::OBJECT are * wrapped into one @ref btRigidBody. */ std::unique_ptr bObjectRigidBody_; diff --git a/src/esp/physics/objectManagers/ArticulatedObjectManager.h b/src/esp/physics/objectManagers/ArticulatedObjectManager.h index 68b7548877..152bca45b4 100644 --- a/src/esp/physics/objectManagers/ArticulatedObjectManager.h +++ b/src/esp/physics/objectManagers/ArticulatedObjectManager.h @@ -239,7 +239,7 @@ class ArticulatedObjectManager * @brief This method will remove articulated objects from physics manager. * The wrapper has already been removed by the time this method is called * (this is called from @ref - * esp::core::ManagedContainerBase::deleteObjectInternal) + * esp::core::managedContainers::ManagedContainerBase::deleteObjectInternal) * * @param objectID the ID of the managed object to remove * @param objectHandle the string key of the managed object to remove. diff --git a/src/esp/physics/objectManagers/RigidBaseManager.h b/src/esp/physics/objectManagers/RigidBaseManager.h index cb6c946cf8..dec766d480 100644 --- a/src/esp/physics/objectManagers/RigidBaseManager.h +++ b/src/esp/physics/objectManagers/RigidBaseManager.h @@ -12,10 +12,10 @@ namespace physics { /** * @brief Class template defining responsibilities and functionality shared for - * managing all @ref esp::physics::ManagedRigidBase wrappers. + * managing all @ref esp::physics::AbstractManagedRigidBase wrappers. * @tparam T the type of managed physics object a particular specialization * of this class works with. Must inherit from @ref - * esp::physics::ManagedRigidBase + * esp::physics::AbstractManagedRigidBase */ template diff --git a/src/esp/physics/objectManagers/RigidObjectManager.h b/src/esp/physics/objectManagers/RigidObjectManager.h index d3f2819a02..9cb8af1289 100644 --- a/src/esp/physics/objectManagers/RigidObjectManager.h +++ b/src/esp/physics/objectManagers/RigidObjectManager.h @@ -98,9 +98,9 @@ class RigidObjectManager /** * @brief Overload of standard @ref - * esp::core::ManagedContainer::removeObjectByID to allow for the retention - * of scene node or visual node of the underlying RigidObject after it and - * its wrapper's removal. + * esp::core::managedContainers::ManagedContainer::removeObjectByID to allow + * for the retention of scene node or visual node of the underlying + * RigidObject after it and its wrapper's removal. * * @param objectID The ID of the managed object to be deleted. * @param deleteObjectNode If true, deletes the object's scene node. @@ -119,9 +119,9 @@ class RigidObjectManager /** * @brief Overload of standard @ref - * esp::core::ManagedContainer::removeObjectByHandle to allow for the - * retention of scene node or visual node of the underlying RigidObject - * after it and its wrapper's removal. + * esp::core::managedContainers::ManagedContainer::removeObjectByHandle to + * allow for the retention of scene node or visual node of the underlying + * RigidObject after it and its wrapper's removal. * * @param objectHandle The handle of the managed object to be deleted. * @param deleteObjectNode If true, deletes the object's scene node. @@ -141,7 +141,8 @@ class RigidObjectManager /** * @brief This method will remove rigid objects from physics manager. The * wrapper has already been removed by the time this method is called (this is - * called from @ref esp::core::ManagedContainerBase::deleteObjectInternal) + * called from @ref + * esp::core::managedContainers::ManagedContainerBase::deleteObjectInternal) * * @param objectID the ID of the managed object to remove * @param objectHandle the string key of the managed object to remove. diff --git a/src/esp/sim/Simulator.h b/src/esp/sim/Simulator.h index 24e232f42d..46e42fe6f1 100644 --- a/src/esp/sim/Simulator.h +++ b/src/esp/sim/Simulator.h @@ -249,7 +249,7 @@ class Simulator { } /** - * @brief Builds a @ref esp::metadata::SceneInstanceAttributes describing the + * @brief Builds a @ref esp::metadata::attributes::SceneInstanceAttributes describing the * current scene configuration, and saves it to a JSON file, using @p * saveFileName . * @param saveFilename The name to use to save the current scene instance. @@ -258,7 +258,7 @@ class Simulator { bool saveCurrentSceneInstance(const std::string& saveFilename) const; /** - * @brief Builds a @ref esp::metadata::SceneInstanceAttributes describing + * @brief Builds a @ref esp::metadata::attributes::SceneInstanceAttributes describing * the current scene configuration, and saves it to a JSON file, using the * current scene attributes' filename, or an incremented version if @p * overwrite == false. @@ -864,7 +864,7 @@ class Simulator { /** * @brief Instance the stage for the current scene based on * curSceneInstanceAttributes_, the currently active scene's @ref - * esp::metadata::SceneInstanceAttributes + * esp::metadata::attributes::SceneInstanceAttributes * @param curSceneInstanceAttributes The attributes describing the current * scene instance. * @return whether stage creation is completed successfully @@ -876,7 +876,7 @@ class Simulator { /** * @brief Instance all the objects in the scene based on * curSceneInstanceAttributes_, the currently active scene's @ref - * esp::metadata::SceneInstanceAttributes. + * esp::metadata::attributes::SceneInstanceAttributes. * @param curSceneInstanceAttributes The attributes describing the current * scene instance. * @return whether object creation and placement is completed successfully @@ -888,7 +888,7 @@ class Simulator { /** * @brief Instance all the articulated objects in the scene based * on curSceneInstanceAttributes_, the currently active scene's @ref - * esp::metadata::SceneInstanceAttributes. + * esp::metadata::attributes::SceneInstanceAttributes. * @param curSceneInstanceAttributes The attributes describing the current * scene instance. * @return whether articulated object creation and placement is completed diff --git a/src/esp/sim/SimulatorConfiguration.h b/src/esp/sim/SimulatorConfiguration.h index 35471a1fad..7008c65afd 100644 --- a/src/esp/sim/SimulatorConfiguration.h +++ b/src/esp/sim/SimulatorConfiguration.h @@ -17,6 +17,9 @@ namespace Cr = Corrade; namespace esp { namespace sim { +/** + * @brief Class to hold configuration for a simulator + */ struct SimulatorConfiguration { //! Name of scene or stage config or asset to load std::string activeSceneName; @@ -108,9 +111,16 @@ struct SimulatorConfiguration { ESP_SMART_POINTERS(SimulatorConfiguration) }; + +/** + * @brief Validate @ref SimulatorConfiguration equality + */ bool operator==(const SimulatorConfiguration& a, const SimulatorConfiguration& b); +/** + * @brief Validate @ref SimulatorConfiguration inequality + */ bool operator!=(const SimulatorConfiguration& a, const SimulatorConfiguration& b); diff --git a/tests/test_configs.py b/tests/test_configs.py index f8a749cf8f..8a92157fbf 100644 --- a/tests/test_configs.py +++ b/tests/test_configs.py @@ -21,7 +21,7 @@ def test_config_eq(): def test_core_configuration(): - # test bindings for esp::core::Configuration class + # test bindings for esp::core::config::Configuration class config = Configuration() config.set("test", "test statement") assert config.has_value("test")