diff --git a/include/tz/core/hier.hpp b/include/tz/core/hier.hpp index 50383471f7..f1ab546c90 100644 --- a/include/tz/core/hier.hpp +++ b/include/tz/core/hier.hpp @@ -7,38 +7,32 @@ namespace tz { - /** - * @ingroup tz_core - * @defgroup tz_core_hier Hierarchies - * @brief Create hierarchies of transforms with attached data. - */ - namespace detail{struct hier_t{};} /** - * @ingroup tz_core_hier + * @ingroup tz_core_transform * @brief Represents a single hierarchy. * * See @ref create_hier for details. */ using hier_handle = tz::handle; /** - * @ingroup tz_core_hier + * @ingroup tz_core_transform * @brief Represents a single node within a hierarchy. */ using node_handle = tz::handle; /** - * @ingroup tz_core_hier + * @ingroup tz_core_transform * @brief Create a new empty hierarchy. */ hier_handle create_hier(); /** - * @ingroup tz_core_hier + * @ingroup tz_core_transform * @brief Destroy an existing hierarchy, along with all of its nodes. */ void destroy_hier(hier_handle hier); /** - * @ingroup tz_core_hier + * @ingroup tz_core_transform * @brief Create a new node within the hierarchy. * * @param hier Hierarchy in which to create the node. @@ -49,7 +43,7 @@ namespace tz */ std::expected hier_create_node(hier_handle hier, tz::trs transform = {}, node_handle parent = tz::nullhand, void* userdata = nullptr); /** - * @ingroup tz_core_hier + * @ingroup tz_core_transform * @brief Destroy a node within the hierarchy. * * Any children are also destroyed. @@ -62,26 +56,26 @@ namespace tz tz::error_code hier_destroy_node(hier_handle hier, node_handle node); /** - * @ingroup tz_core_hier + * @ingroup tz_core_transform * @brief Retrieve the local transform of a node. * * @return @ref tz::error_code::invalid_value If `hier` or `node` are invalid or have previously been destroyed. */ std::expected hier_node_get_local_transform(hier_handle hier, node_handle node); /** - * @ingroup tz_core_hier + * @ingroup tz_core_transform * @brief Set the local transform of a node. */ void hier_node_set_local_transform(hier_handle hier, node_handle node, tz::trs transform); /** - * @ingroup tz_core_hier + * @ingroup tz_core_transform * @brief Retrieve the global transform of a node. * * @return @ref tz::error_code::invalid_value If `hier` or `node` are invalid or have previously been destroyed. */ std::expected hier_node_get_global_transform(hier_handle hier, node_handle node); /** - * @ingroup tz_core_hier + * @ingroup tz_core_transform * @brief Set the global transform of a node. */ void hier_node_set_global_transform(hier_handle hier, node_handle node, tz::trs transform); diff --git a/include/tz/core/trs.hpp b/include/tz/core/trs.hpp index 7ec3bb795a..f1fe10bd03 100644 --- a/include/tz/core/trs.hpp +++ b/include/tz/core/trs.hpp @@ -6,23 +6,61 @@ namespace tz { + /** + * @ingroup tz_core + * @defgroup tz_core_transform Transforms + * @brief Represent transformations and hierarchies of transformations in 3D space. + */ + + /** + * @ingroup tz_core_transform + * @brief Create a matrix that performs the given translation in 3D space. + */ tz::m4f matrix_translate(tz::v3f translate); + /** + * @ingroup tz_core_transform + * @brief Create a matrix that performs the given scale in 3D space. + */ tz::m4f matrix_scale(tz::v3f scale); + /** + * @ingroup tz_core_transform + * @brief Create an orthographic projection matrix. + */ tz::m4f matrix_ortho(float left, float right, float top, float bottom, float near, float far); + /** + * @ingroup tz_core_transform + * @brief Create a perspective projection matrix. + */ tz::m4f matrix_persp(float fov, float aspect_ratio, float near, float far); + /** + * @ingroup tz_core_transform + * @brief Create a perspective projection matrix with an infinitely-distant far plane. + */ tz::m4f matrix_persp_nofar(float fov, float aspect_ratio, float near); + /** + * @ingroup tz_core_transform + * @brief Encapsulates a combination of a Translation, Rotation, and Scale in 3D space. + */ struct trs { + /// Translation Component tz::v3f translate = tz::v3f::zero(); + /// Rotation Component tz::quat rotate = tz::quat::iden(); + /// Scale Component tz::v3f scale = tz::v3f::filled(1.0f); + /// Linearly interpolate between this transform and another based on a factor, and return that result. trs lerp(const trs& rhs, float factor) const; + /// Create a matrix that performs an identical transformation. m4f matrix() const; + /// Create a new TRS that performs the identical transformation to the given matrix. static trs from_matrix(m4f mat); + /// Return an inverse transform that does the exact opposite (such that multiplying a transform by its inverse yields no transformation). trs inverse() const; + /// Combine one transform with another, and return the result. @note TRS combine operations, like matrix multiplications, are not commutative. trs combine(const trs& rhs); bool operator==(const trs& rhs) const = default;