diff --git a/filament/include/filament/Box.h b/filament/include/filament/Box.h index 740b515d34..570ec853d2 100644 --- a/filament/include/filament/Box.h +++ b/filament/include/filament/Box.h @@ -14,6 +14,8 @@ * limitations under the License. */ +//! \file + #ifndef TNT_FILAMENT_BOX_H #define TNT_FILAMENT_BOX_H @@ -26,50 +28,120 @@ namespace filament { +/** + * An axis aligned 3D box represented by its center and half-extent. + */ class UTILS_PUBLIC Box { public: + /** Center of the 3D box */ filament::math::float3 center = {}; + + /** Half extent from the center on all 3 axis */ filament::math::float3 halfExtent = {}; + /** + * Whether the box is empty, i.e.: it's volume is null. + * @return true if the volume of the box is null + */ constexpr bool isEmpty() const noexcept { return length2(halfExtent) == 0; } + /** + * Computes the lowest coordinates corner of the box. + * @return center - halfExtent + */ constexpr filament::math::float3 getMin() const noexcept { return center - halfExtent; } + /** + * Computes the largest coordinates corner of the box. + * @return center + halfExtent + */ constexpr filament::math::float3 getMax() const noexcept { return center + halfExtent; } + /** + * Initializes the 3D box from its min / max coordinates on each axis + * @param min lowest coordinates corner of the box + * @param max largest coordinates corner of the box + * @return + */ Box& set(const filament::math::float3& min, const filament::math::float3& max) noexcept { center = (max + min) * filament::math::float3(0.5f); halfExtent = (max - min) * filament::math::float3(0.5f); return *this; } + /** + * Computes the bounding box of the union of two boxes + * @param box The box to be combined with + * @return The boudning box of the union of *this and box + */ Box& unionSelf(const Box& box) noexcept { set(std::min(getMin(), box.getMin()), std::max(getMax(), box.getMax())); return *this; } + /** + * Translates the box *to* a given center position + * @param tr position to translate the box to + * @return A box centered in \p tr with the same extent than *this + */ constexpr Box translateTo(const filament::math::float3& tr) const noexcept { return Box{ tr, halfExtent }; } + /** + * Computes the smalest bounding sphere of the box. + * @return The smallest sphere defined by its center (.xyz) and radius (.w) that contains *this + */ filament::math::float4 getBoundingSphere() const noexcept { return { center, length(halfExtent) }; } + /** + * Computes the bounding box of a box transformed by a rigid transform + * @param box the box to transfrom + * @param m a 4x4 matrix that must be a rigid transform + * @return the bounding box of the transformed box. + * Result is undefined if \p m is not a rigid transform + */ friend Box rigidTransform(Box const& box, const filament::math::mat4f& m) noexcept; + + /** + * Computes the bounding box of a box transformed by a rigid transform + * @param box the box to transfrom + * @param m a 3x3 matrix that must be a rigid transform + * @return the bounding box of the transformed box. + * Result is undefined if \p m is not a rigid transform + */ friend Box rigidTransform(Box const& box, const filament::math::mat3f& m) noexcept; }; +/** + * An axis aligned box represented by its min and max coordinates + */ struct Aabb { + + /** min coordinates */ filament::math::float3 min = std::numeric_limits::max(); + + /** max coordinates */ filament::math::float3 max = std::numeric_limits::lowest(); + + /** + * Computes the center of the box. + * @return (min +max)/2 + */ filament::math::float3 center() const noexcept { return (min + max) * filament::math::float3(0.5f); } + + /** + * Whether the box is empty, i.e.: it's volume is null or negative. + * @return true if min >= max, i.e: the volume of the box is null or negative + */ bool isEmpty() const noexcept { return min >= max; } diff --git a/filament/include/filament/DebugRegistry.h b/filament/include/filament/DebugRegistry.h index e0644711d8..91d2b0f8f0 100644 --- a/filament/include/filament/DebugRegistry.h +++ b/filament/include/filament/DebugRegistry.h @@ -14,6 +14,8 @@ * limitations under the License. */ +//! \file + #ifndef TNT_FILAMENT_DEBUG_H #define TNT_FILAMENT_DEBUG_H @@ -32,38 +34,53 @@ namespace filament { +/** + * A regsitry of runtime properties used exclusively for debugging + * + * Filament exposes a few properties that can be queried and set, which control certain debugging + * features of the engine. These properties can be set at runtime at anytime. + * + */ class UTILS_PUBLIC DebugRegistry : public FilamentAPI { public: + /** + * Type of a property + */ enum Type { BOOL, INT, FLOAT, FLOAT2, FLOAT3, FLOAT4 }; + /** + * Information about a property + */ struct Property { - const char* name; - Type type; + const char* name; //!< property name + Type type; //!< property type }; + /** + * Queries the list of all available properties. + * + * @return A pair containing a pointer to a Property array and the size of this array. + */ std::pair getProperties() const noexcept; + /** + * Queries whether a property exists + * @param name The name of the property to query + * @return true if the property exists, false otherwise + */ bool hasProperty(const char* name) const noexcept; + /** + * Queries the address of a property's data from its name + * @param name Name of the property we want the data address of + * @return Address of the data of the \p name property + * @{ + */ void* getPropertyAddress(const char* name) noexcept; - bool setProperty(const char* name, bool v) noexcept; - bool setProperty(const char* name, int v) noexcept; - bool setProperty(const char* name, float v) noexcept; - bool setProperty(const char* name, filament::math::float2 v) noexcept; - bool setProperty(const char* name, filament::math::float3 v) noexcept; - bool setProperty(const char* name, filament::math::float4 v) noexcept; - - bool getProperty(const char* name, bool* v) const noexcept; - bool getProperty(const char* name, int* v) const noexcept; - bool getProperty(const char* name, float* v) const noexcept; - bool getProperty(const char* name, filament::math::float2* v) const noexcept; - bool getProperty(const char* name, filament::math::float3* v) const noexcept; - bool getProperty(const char* name, filament::math::float4* v) const noexcept; - template inline T* getPropertyAddress(const char* name) noexcept { return static_cast(getPropertyAddress(name)); @@ -74,6 +91,38 @@ public: *p = getPropertyAddress(name); return *p != nullptr; } + /** @}*/ + + /** + * Set the value of a property + * @param name Name of the property to set the value of + * @param v Value to set + * @return true if the operation was successful, false otherwise. + * @{ + */ + bool setProperty(const char* name, bool v) noexcept; + bool setProperty(const char* name, int v) noexcept; + bool setProperty(const char* name, float v) noexcept; + bool setProperty(const char* name, filament::math::float2 v) noexcept; + bool setProperty(const char* name, filament::math::float3 v) noexcept; + bool setProperty(const char* name, filament::math::float4 v) noexcept; + /** @}*/ + + /** + * Get the value of a property + * @param name Name of the property to get the value of + * @param v A pointer to a variable which will hold the result + * @return true if the call was successful and \p v was updated + * @{ + */ + bool getProperty(const char* name, bool* v) const noexcept; + bool getProperty(const char* name, int* v) const noexcept; + bool getProperty(const char* name, float* v) const noexcept; + bool getProperty(const char* name, filament::math::float2* v) const noexcept; + bool getProperty(const char* name, filament::math::float3* v) const noexcept; + bool getProperty(const char* name, filament::math::float4* v) const noexcept; + /** @}*/ + }; diff --git a/filament/include/filament/Fence.h b/filament/include/filament/Fence.h index becfb638ec..f908a97278 100644 --- a/filament/include/filament/Fence.h +++ b/filament/include/filament/Fence.h @@ -55,7 +55,7 @@ public: /** * Synchronization with the GPU * - * Calling wait() on a HARD fence will only wait for all commands prior to the Fence to + * Calling wait() on a HARD fence will wait for all commands prior to the Fence to * have completed on the GPU. */ HARD diff --git a/filament/include/filament/Frustum.h b/filament/include/filament/Frustum.h index 1292754f88..0e6917a259 100644 --- a/filament/include/filament/Frustum.h +++ b/filament/include/filament/Frustum.h @@ -14,6 +14,8 @@ * limitations under the License. */ +//! \file + #ifndef TNT_FILAMENT_FRUSTUM_H #define TNT_FILAMENT_FRUSTUM_H @@ -22,8 +24,6 @@ #include #include -#include -#include #include // Because we define NEAR and FAR in the Plane enum. @@ -33,6 +33,9 @@ namespace details { class Culler; } // namespace details; +/** + * A frustum defined by six planes + */ class UTILS_PUBLIC Frustum { public: enum class Plane : uint8_t { @@ -50,24 +53,55 @@ public: Frustum& operator=(const Frustum& rhs) = default; Frustum& operator=(Frustum&& rhs) noexcept = default; - // create a frustum from a projection matrix (usually the projection * view matrix) + /** + * Create a frustum from a projection matrix (usually the projection * view matrix) + * @param pv a 4x4 projection matrix + */ explicit Frustum(const filament::math::mat4f& pv); - // set the frustum from the given projection matrix + /** + * Set the frustum from the given projection matrix + * @param pv a 4x4 projection matrix + */ void setProjection(const filament::math::mat4f& pv); - // return the plane equation parameters with normalized normals + /** + * Return the plane equation parameters with normalized normals + * @param plane Identifier of the plane to retrieve the equation of + * @return A plane equation encoded a float4 R such as R.x*x + R.y*y + R.z*z = R.w + */ filament::math::float4 getNormalizedPlane(Plane plane) const noexcept; - // return frustum planes in left, right, bottom, top, far, near order + /** + * Return a copy of all six frustum planes in left, right, bottom, top, far, near order + * @param planes six plane equations encoded as in getNormalizedPlane() in + * left, right, bottom, top, far, near order + */ void getNormalizedPlanes(filament::math::float4 planes[6]) const noexcept; + /** + * Return all six frustum planes in left, right, bottom, top, far, near order + * @return six plane equations encoded as in getNormalizedPlane() in + * left, right, bottom, top, far, near order + */ filament::math::float4 const* getNormalizedPlanes() const noexcept { return mPlanes; } - // returns whether a box intersects the frustum (i.e. is visible) + /** + * Returns whether a box intersects the frustum (i.e. is visible) + * @param box The box to test against the frustum + * @return true if the box may intersects the frustum, false otherwise. In some situations + * a box that doesn't intersect the frustum might be reported as though it does. However, + * a box that does intersect the frustum is always reported correctly (true). + */ bool intersects(const Box& box) const noexcept; - // returns whether a sphere intersects the frustum (i.e. is visible) + /** + * Returns whether a sphere intersects the frustum (i.e. is visible) + * @param sphere A sphere encoded as a center + radius. + * @return true if the sphere may intersects the frustum, false otherwise. In some situations + * a sphere that doesn't intersect the frustum might be reported as though it does. However, + * a sphere that does intersect the frustum is always reported correctly (true). + */ bool intersects(const filament::math::float4& sphere) const noexcept; private: