Skip to content

Commit

Permalink
[core.trs] documentation pass for TRS. note that core.hier now lives …
Browse files Browse the repository at this point in the history
…in the doxygen module tz_core_transform along with TRS instead of its own module.
  • Loading branch information
harrand committed Nov 16, 2024
1 parent 95c6b4e commit 8353c5b
Show file tree
Hide file tree
Showing 2 changed files with 48 additions and 16 deletions.
26 changes: 10 additions & 16 deletions include/tz/core/hier.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -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<detail::hier_t>;
/**
* @ingroup tz_core_hier
* @ingroup tz_core_transform
* @brief Represents a single node within a hierarchy.
*/
using node_handle = tz::handle<hier_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.
Expand All @@ -49,7 +43,7 @@ namespace tz
*/
std::expected<node_handle, tz::error_code> 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.
Expand All @@ -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<tz::trs, tz::error_code> 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<tz::trs, tz::error_code> 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);
Expand Down
38 changes: 38 additions & 0 deletions include/tz/core/trs.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down

0 comments on commit 8353c5b

Please sign in to comment.