From c9461b43477e3f9c9778eb46354eeb30d8cbc45c Mon Sep 17 00:00:00 2001 From: parker Date: Wed, 20 Aug 2025 17:27:27 +0100 Subject: [PATCH] docs: add doxygen comments for GeometryOperator.h --- src/Engine/Operator/GeometryOpDef.h | 2 +- src/Engine/Operator/GeometryOperator.h | 113 +++++++++++++++++++++++-- 2 files changed, 109 insertions(+), 6 deletions(-) diff --git a/src/Engine/Operator/GeometryOpDef.h b/src/Engine/Operator/GeometryOpDef.h index 12f44c2..11e7c56 100644 --- a/src/Engine/Operator/GeometryOpDef.h +++ b/src/Engine/Operator/GeometryOpDef.h @@ -60,7 +60,7 @@ public: */ void throwError(std::string error); - /// @brief Returns the minimum number of input connections for the node to function required. Set by op::OpInfo when registering the operator. + /// @brief Returns the minimum number of input connections required for the node to function. Set by op::OpInfo when registering the operator. unsigned int getMinInputs() const; /// @brief Returns the maximum number of input connections accepted by the node. Set by op::OpInfo when registering the operator. unsigned int getMaxInputs() const; diff --git a/src/Engine/Operator/GeometryOperator.h b/src/Engine/Operator/GeometryOperator.h index 51091e3..f630bc8 100644 --- a/src/Engine/Operator/GeometryOperator.h +++ b/src/Engine/Operator/GeometryOperator.h @@ -11,46 +11,149 @@ namespace enzo::nt { std::weak_ptr connectOperators(enzo::nt::OpId inputOpId, unsigned int inputIndex, enzo::nt::OpId outputOpId, unsigned int outputIndex); +/** +* @class GeometryOperator +* @brief The unique runtime representation of a node +*/ class GeometryOperator { public: + /** + * @brief Constructs a new node + * + * @param opId the operator id assigned to this node. For most situations + * this should be set by the nt::NetworkManager + * @param opInfo The data class informing the node what its properties + * are that set it apart from other nodes. This is what makes a grid + * node different to a transform node. + */ GeometryOperator(enzo::nt::OpId opId, op::OpInfo opInfo); - // disable copying + /// @brief Deleted copy constructor to avoid accidental copies. GeometryOperator(const GeometryOperator&) = delete; + /// @brief Deleted copy assignment operator to avoid accidental copies. GeometryOperator& operator=(const GeometryOperator&) = delete; + /// @brief Computes the output geometry based on the [cookOp](@ref nt::GeometryOpDef::cookOp) + /// definition in nt::GeometryOpDef. This is set by the @p opInfo constructor parameter void cookOp(op::Context context); + + /** + * @brief Returns the current output geometry. + * + * Does not trigger a cook so if the geometry may be outdated if not cooked first. + * + * @todo Add option to force cook or cook if dirty. + */ geo::Geometry& getOutputGeo(unsigned int outputIndex) const; + /** @brief Adds a GeometryConnection to one of the inputs. Replacing old connections if needed. + * + * Which input is decided and stored on the connection. + * + * Nodes can only have one connection so it will automatically remove existing connections + * with the same index, prioritizing the new one. + */ void addInputConnection(std::shared_ptr connection); + + /** @brief Adds a GeometryConnection to one of the outputs. Replacing old connections if needed. + * + * Which output is decided and stored on the connection. + * + * Nodes can only have one connection so it will automatically remove existing connections + * with the same index, prioritizing the new one. + */ void addOutputConnection(std::shared_ptr connection); + /** @brief Removes an input from the node's container. + * + * Does not remove the connection from any other node it's connected + * to, likely causing undefined behavior if called incorrectly. + * + * @todo remove in favor of the rewrite suggested in GeometryConnection + * todo in which connections are handled by the network manager rather than individual nodes. + */ void removeInputConnection(unsigned int inputIndex); + + /** @brief Removes an output from the node's container. + * + * Does not remove the connection from any other node it's connected + * to, likely causing undefined behavior if called incorrectly. + * + * @todo remove in favor of the rewrite suggested in GeometryConnection + * todo in which connections are handled by the network manager rather than individual nodes. + */ void removeOutputConnection(const nt::GeometryConnection* connection); + /** + * @brief Returns a vector containing weak pointers for all input connections. + * + * Connections returned by this function are weak pointers to indicate + * ownership belongs to the node/network and can be modified or deleted at any time. + */ std::vector> getInputConnections() const; + + /** + * @brief Returns a vector containing weak pointers for all output connections. + * + * Connections returned by this function are weak pointers to indicate + * ownership belongs to the node/network and can be modified or deleted at any time. + */ std::vector> getOutputConnections() const; + + /** + * @brief Returns an optional connection from a specific input index. + * + * @returns Nullopt if the connection doesn't exist. + */ std::optional> getInputConnection(size_t index) const; + + /// @brief Returns all parameters belonging to this node. std::vector> getParameters(); + + /// @brief Returns a parameter with the given name belonging to this node. + /// @returns Empty default constructed std::weak_ptr() if no parameter of that name exists. std::weak_ptr getParameter(std::string parameterName); + /** + * @brief NOT YET IMPLEMENTED. Returns the runtime label given to this node as a unique identifier within it's scope. + * @todo implement + */ std::string getLabel(); // TODO: implement node labels + + /** + * @brief Returns the name belonging to this type of node (eg. grid or transform). Not to be confused with the label. + * + * The type name decided at compile time and is shared across all nodes + * of the given type. All grids nodes share the same type name. Labels + * on the other hand are unique identifiers for a given runtime node (eg. myGrid1, groundGrid, wall). + */ std::string getTypeName(); + /** + * @brief Marks the outputed geometry as outdated and notifies the network + * + * @param dirtyDescendents Sets whether all descendents (nodes connected + * directly or indirectly to the output of this node) are also dirtied. + * This is usually what you want. + */ void dirtyNode(bool dirtyDescendents=true); + + /// @brief Returns true if the node is dirty and false if the node is clean (does not need cooking). bool isDirty(); - + /// @brief Returns the minimum number of input connections required + /// for the node to function. These are in order so 3 would mean the + /// first three inputs must have a connection. unsigned int getMinInputs() const; + /// @brief Returns the maximum number of input connections accepted by the node. unsigned int getMaxInputs() const; + /// @brief Returns the number of available outputs the node provides. unsigned int getMaxOutputs() const; - // signals + /// @brief A signal emitted when the node is dirtied. This will usually notify the NetworkManager boost::signals2::signal nodeDirtied; - - private: void initParameters();