Scarfski/filament
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add doxygen documentation

Browse Source
This commit is contained in:
Mathias Agopian
2019-03-08 16:37:32 -08:00
committed by Mathias Agopian
parent 6e4491c852
commit b44717ae54
4 changed files with 180 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
filament/include/filament/Box.h
View File

@@ -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<float>::max();
/** max coordinates */
filament::math::float3 max = std::numeric_limits<float>::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;
}

81
filament/include/filament/DebugRegistry.h
View File

@@ -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<Property const*, size_t> 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<typename T>
inline T* getPropertyAddress(const char* name) noexcept {
return static_cast<T*>(getPropertyAddress(name));
@@ -74,6 +91,38 @@ public:
*p = getPropertyAddress<T>(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;
/** @}*/
};

2
filament/include/filament/Fence.h
View File

@@ -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

50
filament/include/filament/Frustum.h
View File

@@ -14,6 +14,8 @@
* limitations under the License.
*/
//! \file
#ifndef TNT_FILAMENT_FRUSTUM_H
#define TNT_FILAMENT_FRUSTUM_H
@@ -22,8 +24,6 @@
#include <utils/compiler.h>
#include <math/mat4.h>
#include <math/vec4.h>
#include <math/vec2.h>
#include <utils/unwindows.h> // 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: