From ca79e9d420fc154a8c81eb6df4964669bba2bd66 Mon Sep 17 00:00:00 2001 From: Mathias Agopian Date: Mon, 11 Mar 2019 17:33:10 -0700 Subject: [PATCH] More doxygen documentation --- filament/include/filament/Color.h | 103 +++++++++------- filament/include/filament/IndexBuffer.h | 34 +++++- filament/include/filament/TextureSampler.h | 76 +++++++++++- filament/include/filament/TransformManager.h | 2 +- filament/include/filament/VertexBuffer.h | 111 +++++++++++++++--- filament/include/filament/View.h | 16 ++- filament/include/filament/Viewport.h | 49 ++++++-- .../include/filament/MaterialEnums.h | 101 ++++++++++------ .../include/filament/driver/DriverEnums.h | 2 +- 9 files changed, 383 insertions(+), 111 deletions(-) diff --git a/filament/include/filament/Color.h b/filament/include/filament/Color.h index 339867652e..b0643333ab 100644 --- a/filament/include/filament/Color.h +++ b/filament/include/filament/Color.h @@ -14,6 +14,8 @@ * limitations under the License. */ +//! \file + #ifndef TNT_FILAMENT_COLOR_H #define TNT_FILAMENT_COLOR_H @@ -24,88 +26,103 @@ namespace filament { -// RGB color in linear space +//! RGB color in linear space using LinearColor = filament::math::float3; -// RGB color in sRGB space + +//! RGB color in sRGB space using sRGBColor = filament::math::float3; -// RGBA color in linear space, with alpha +//! RGBA color in linear space, with alpha using LinearColorA = filament::math::float4; -// RGBA color in sRGB space, with alpha + +//! RGBA color in sRGB space, with alpha using sRGBColorA = filament::math::float4; -// types of RGB colors +//! types of RGB colors enum class UTILS_PUBLIC RgbType : uint8_t { - // the color is defined in sRGB space - sRGB, - // the color is defined in linear space - LINEAR, + sRGB, //!< the color is defined in sRGB space + LINEAR, //!< the color is defined in linear space }; -// types of RGBA colors +//! types of RGBA colors enum class UTILS_PUBLIC RgbaType : uint8_t { - // the color is defined in sRGB space and the RGB values - // have not been premultiplied by the alpha (for instance, a 50% - // transparent red is <1,0,0,0.5>) + /** + * the color is defined in sRGB space and the RGB values + * have not been premultiplied by the alpha (for instance, a 50% + * transparent red is <1,0,0,0.5>) + */ sRGB, - // the color is defined in linear space and the RGB values - // have not been premultiplied by the alpha (for instance, a 50% - // transparent red is <1,0,0,0.5>) + /** + * the color is defined in linear space and the RGB values + * have not been premultiplied by the alpha (for instance, a 50% + * transparent red is <1,0,0,0.5>) + */ LINEAR, - // the color is defined in sRGB space and the RGB values - // have been premultiplied by the alpha (for instance, a 50% - // transparent red is <0.5,0,0,0.5>) + /** + * the color is defined in sRGB space and the RGB values + * have been premultiplied by the alpha (for instance, a 50% + * transparent red is <0.5,0,0,0.5>) + */ PREMULTIPLIED_sRGB, - // the color is defined in linear space and the RGB values - // have been premultiplied by the alpha (for instance, a 50% - // transparent red is <0.5,0,0,0.5>) + /** + * the color is defined in linear space and the RGB values + * have been premultiplied by the alpha (for instance, a 50% + * transparent red is <0.5,0,0,0.5>) + */ PREMULTIPLIED_LINEAR }; -// type of color conversion to use when converting to/from sRGB and linear spaces +//! type of color conversion to use when converting to/from sRGB and linear spaces enum UTILS_PUBLIC ColorConversion { - // accurate conversion using the sRGB standard - ACCURATE, - // fast conversion using a simple gamma 2.2 curve - FAST + ACCURATE, //!< accurate conversion using the sRGB standard + FAST //!< fast conversion using a simple gamma 2.2 curve }; +/** + * Utilities to manipulate and convert colors + */ class UTILS_PUBLIC Color { public: - // converts an RGB color to linear space - // the conversion depends on the specified type + //! converts an RGB color to linear space, the conversion depends on the specified type static LinearColor toLinear(RgbType type, filament::math::float3 color); - // converts an RGBA color to linear space - // the conversion depends on the specified type + //! converts an RGBA color to linear space, the conversion depends on the specified type static LinearColorA toLinear(RgbaType type, filament::math::float4 color); - // converts an RGB color in sRGB space to an RGB color in linear space + //! converts an RGB color in sRGB space to an RGB color in linear space template static LinearColor toLinear(sRGBColor const& color); - // converts an RGB color in linear space to an RGB color in sRGB space + //! converts an RGB color in linear space to an RGB color in sRGB space template static sRGBColor toSRGB(LinearColor const& color); - // converts an RGBA color in sRGB space to an RGBA color in linear space - // the alpha component is left unmodified + /** + * converts an RGBA color in sRGB space to an RGBA color in linear space + * the alpha component is left unmodified + */ template static LinearColorA toLinear(sRGBColorA const& color); - // converts an RGBA color in linear space to an RGBA color in sRGB space - // the alpha component is left unmodified + /** + * converts an RGBA color in linear space to an RGBA color in sRGB space + * the alpha component is left unmodified + */ template static sRGBColorA toSRGB(LinearColorA const& color); - // converts a correlated color temperature to a linear RGB color in sRGB - // space the temperature must be expressed in kelvin and must be in the - // range 1,000K to 15,000K + /** + * converts a correlated color temperature to a linear RGB color in sRGB + * space the temperature must be expressed in kelvin and must be in the + * range 1,000K to 15,000K + */ static LinearColor cct(float K); - // converts a CIE standard illuminant series D to a linear RGB color in - // sRGB space the temperature must be expressed in kelvin and must be in - // the range 4,000K to 25,000K + /** + * converts a CIE standard illuminant series D to a linear RGB color in + * sRGB space the temperature must be expressed in kelvin and must be in + * the range 4,000K to 25,000K + */ static LinearColor illuminantD(float K); private: diff --git a/filament/include/filament/IndexBuffer.h b/filament/include/filament/IndexBuffer.h index 7f58314796..9d99cb96ff 100644 --- a/filament/include/filament/IndexBuffer.h +++ b/filament/include/filament/IndexBuffer.h @@ -14,6 +14,8 @@ * limitations under the License. */ +//! \file + #ifndef TNT_FILAMENT_INDEXBUFFER_H #define TNT_FILAMENT_INDEXBUFFER_H @@ -34,15 +36,27 @@ class FIndexBuffer; class Engine; +/** + * A buffer containing vertex indices into a VertexBuffer. Indices can be 16 or 32 bit. + * The buffer itself is a GPU resource, therefore mutating the data can be relatively slow. + * Typically these buffers are constant. + * + * It is possible, and even encouraged, to use a single index buffer for several Renderable. + * + * @see VertexBuffer, RenderableManager + */ class UTILS_PUBLIC IndexBuffer : public FilamentAPI { struct BuilderDetails; public: using BufferDescriptor = driver::BufferDescriptor; + /** + * Type of the index buffer + */ enum class IndexType : uint8_t { - USHORT = uint8_t(driver::ElementType::USHORT), - UINT = uint8_t(driver::ElementType::UINT), + USHORT = uint8_t(driver::ElementType::USHORT), //!< 16-bit indices + UINT = uint8_t(driver::ElementType::UINT), //!< 32-bit indices }; class Builder : public BuilderBase { @@ -55,11 +69,23 @@ public: Builder& operator=(Builder const& rhs) noexcept; Builder& operator=(Builder&& rhs) noexcept; + /** + * Size of the index buffer in element. + * @param indexCount Number of indices the IndexBuffer can hold. + * @return A reference to this Builder for chaining calls. + */ Builder& indexCount(uint32_t indexCount) noexcept; + + /** + * Type of the index buffer, 16-bit or 32-bit. + * @param indexType Type of indices stored in the IndexBuffer. + * @return A reference to this Builder for chaining calls. + */ Builder& bufferType(IndexType indexType) noexcept; /** - * Creates the IndexBuffer object and returns a pointer to it. + * Creates the IndexBuffer object and returns a pointer to it. After creation, the index + * buffer is uninitialized. Use IndexBuffer::setBuffer() to initialized the IndexBuffer. * * @param engine Reference to the filament::Engine to associate this IndexBuffer with. * @@ -69,6 +95,8 @@ public: * @exception utils::PostConditionPanic if a runtime error occurred, such as running out of * memory or other resources. * @exception utils::PreConditionPanic if a parameter to a builder function was invalid. + * + * @see IndexBuffer::setBuffer */ IndexBuffer* build(Engine& engine); private: diff --git a/filament/include/filament/TextureSampler.h b/filament/include/filament/TextureSampler.h index 8d43b7bcc5..24c91d3283 100644 --- a/filament/include/filament/TextureSampler.h +++ b/filament/include/filament/TextureSampler.h @@ -14,6 +14,8 @@ * limitations under the License. */ +//! \file + #ifndef TNT_FILAMENT_TEXTURESAMPLER_H #define TNT_FILAMENT_TEXTURESAMPLER_H @@ -25,6 +27,9 @@ namespace filament { +/** + * TextureSampler defines how a texture is accessed. + */ class UTILS_PUBLIC TextureSampler { public: using WrapMode = driver::SamplerWrapMode; @@ -33,8 +38,25 @@ public: using CompareMode = driver::SamplerCompareMode; using CompareFunc = driver::SamplerCompareFunc; + /** + * Creates a default sampler. + * The default parameters are: + * - filterMag : NEAREST + * - filterMin : NEAREST + * - wrapS : CLAMP_TO_EDGE + * - wrapT : CLAMP_TO_EDGE + * - wrapR : CLAMP_TO_EDGE + * - compareMode : NONE + * - compareFunc : Less or equal + * - no anisotropic filtering + */ TextureSampler() noexcept = default; + /** + * Creates a TextureSampler with the default parameters but setting the filtering and wrap modes. + * @param minMag filtering for both minification and magnification + * @param str wrapping mode for all texture coordinate axes + */ explicit TextureSampler(MagFilter minMag, WrapMode str = WrapMode::CLAMP_TO_EDGE) noexcept { mSamplerParams.filterMin = MinFilter(minMag); mSamplerParams.filterMag = minMag; @@ -43,6 +65,12 @@ public: mSamplerParams.wrapR = str; } + /** + * Creates a TextureSampler with the default parameters but setting the filtering and wrap modes. + * @param min filtering for minification + * @param mag filtering for magnification + * @param str wrapping mode for all texture coordinate axes + */ TextureSampler(MinFilter min, MagFilter mag, WrapMode str = WrapMode::CLAMP_TO_EDGE) noexcept { mSamplerParams.filterMin = min; mSamplerParams.filterMag = mag; @@ -51,6 +79,14 @@ public: mSamplerParams.wrapR = str; } + /** + * Creates a TextureSampler with the default parameters but setting the filtering and wrap modes. + * @param min filtering for minification + * @param mag filtering for magnification + * @param s wrap mode for the s (horizontal)texture coordinate + * @param t wrap mode for the t (vertical) texture coordinate + * @param r wrap mode for the r (depth) texture coordinate + */ TextureSampler(MinFilter min, MagFilter mag, WrapMode s, WrapMode t, WrapMode r) noexcept { mSamplerParams.filterMin = min; mSamplerParams.filterMag = mag; @@ -59,6 +95,11 @@ public: mSamplerParams.wrapR = r; } + /** + * Creates a TextureSampler with the default parameters but setting the compare mode and function + * @param mode Compare mode + * @param func Compare function + */ explicit TextureSampler(CompareMode mode, CompareFunc func = CompareFunc::LE) noexcept { mSamplerParams.compareMode = mode; mSamplerParams.compareFunc = func; @@ -67,28 +108,61 @@ public: TextureSampler(const TextureSampler& rhs) noexcept = default; TextureSampler& operator=(const TextureSampler& rhs) noexcept = default; + /** + * Sets the minification filter + * @param v Minification filter + */ void setMinFilter(MinFilter v) noexcept { mSamplerParams.filterMin = v; } + + /** + * Sets the magnification filter + * @param v Magnification filter + */ void setMagFilter(MagFilter v) noexcept { mSamplerParams.filterMag = v; } + + /** + * Sets the wrap mode for the s (horizontal) texture coordinate + * @param v wrap mode + */ void setWrapModeS(WrapMode v) noexcept { mSamplerParams.wrapS = v; } + + /** + * Sets the wrap mode for the t (vertical) texture coordinate + * @param v wrap mode + */ void setWrapModeT(WrapMode v) noexcept { mSamplerParams.wrapT = v; } + + /** + * Sets the wrap mode for the r (depth, for 3D textures) texture coordinate + * @param v wrap mode + */ void setWrapModeR(WrapMode v) noexcept { mSamplerParams.wrapR = v; } - // Amount of anisotropy, should be a power-of-two. + /** + * This controls anisotropic filtering. + * @param anisotropy Amount of anisotropy, should be a power-of-two. The default is 0. + * The maximum permissible value is 7. + */ void setAnisotropy(float anisotropy) noexcept { const int log2 = ilogbf(fabsf(anisotropy)); mSamplerParams.anisotropyLog2 = uint8_t(log2 < 7 ? log2 : 7); } + /** + * Sets the compare mode and function. + * @param mode Compare mode + * @param func Compare function + */ void setCompareMode(CompareMode mode, CompareFunc func = CompareFunc::LE) noexcept { mSamplerParams.compareMode = mode; mSamplerParams.compareFunc = func; diff --git a/filament/include/filament/TransformManager.h b/filament/include/filament/TransformManager.h index f7798ae024..aa3c6819a8 100644 --- a/filament/include/filament/TransformManager.h +++ b/filament/include/filament/TransformManager.h @@ -130,7 +130,7 @@ public: * Gets a list of children for a transform component. * * @param i The instance of the transform component to query. - * @param chidren Pointer to array-of-Entity. The array must have at least "count" elements. + * @param children Pointer to array-of-Entity. The array must have at least "count" elements. * @param count The maximum number of children to retrieve. * @return The number of children written to the pointer. */ diff --git a/filament/include/filament/VertexBuffer.h b/filament/include/filament/VertexBuffer.h index 6c564e42dc..65e48262a7 100644 --- a/filament/include/filament/VertexBuffer.h +++ b/filament/include/filament/VertexBuffer.h @@ -14,6 +14,8 @@ * limitations under the License. */ +//! \file + #ifndef TNT_FILAMENT_VERTEXBUFFER_H #define TNT_FILAMENT_VERTEXBUFFER_H @@ -35,6 +37,20 @@ class Engine; /** * Holds a set of buffers that define the geometry of a Renderable. + * + * The geometry of the Renderable itself is defined by a set of vertex attributes such as + * position, color, normals, tangents, etc... + * + * There is no need to have a 1-to-1 mapping between attributes and buffer. i.e. a buffer can + * hold the data of several attributes -- attributes are then referred as being "interleaved". + * + * The buffers themselves are GPU resources, therefore mutating their data can be relatively slow. + * For this reason, it is best to separate the constant data from the dynamic data into multiple + * buffers. + * + * It is possible, and even encouraged, to use a single vertex buffer for several Renderable. + * + * @see IndexBuffer, RenderableManager */ class UTILS_PUBLIC VertexBuffer : public FilamentAPI { struct BuilderDetails; @@ -53,16 +69,64 @@ public: Builder& operator=(Builder const& rhs) noexcept; Builder& operator=(Builder&& rhs) noexcept; - Builder& vertexCount(uint32_t vertexCount) noexcept; + /** + * Defines how many buffers will be created in this vertex buffer set. These buffers are + * later referenced by index from 0 to \p bufferCount - 1. + * + * This call is mandatory. The default is 0. + * + * @param bufferCount Number of buffers in this vertex buffer set. The maximum value is 8. + * @return A reference to this Builder for chaining calls. + */ Builder& bufferCount(uint8_t bufferCount) noexcept; - // no-op if attribute is an invalid enum - // no-op if bufferIndex is out of bounds + /** + * Size of each buffer in the set in vertex. + * + * @param vertexCount Number of vertices in each buffer in this set. + * @return A reference to this Builder for chaining calls. + */ + Builder& vertexCount(uint32_t vertexCount) noexcept; + + /** + * Sets up an attribute for this vertex buffer set. + * + * Using \p byteOffset and \p byteStride, attributes can be interleaved in the same buffer. + * + * @param attribute The attribute to set up. + * @param bufferIndex The index of the buffer containing the data for this attribute. Must + * be between 0 and bufferCount() - 1. + * @param attributeType The type of the attribute data (e.g. byte, float3, etc...) + * @param byteOffset Offset in *bytes* into the buffer \p bufferIndex + * @param byteStride Stride in *bytes* to the next element of this attribute. When set to + * zero the attribute size, as defined by \p attributeType is used. + * + * @return A reference to this Builder for chaining calls. + * + * @warning VertexAttribute::TANGENTS must be specified as a quaternion and is how normals + * are specified. + * + * @see VertexAttribute + * + * This is a no-op if the \p attribute is an invalid enum. + * This is a no-op if the \p bufferIndex is out of bounds. + * + */ Builder& attribute(VertexAttribute attribute, uint8_t bufferIndex, AttributeType attributeType, uint32_t byteOffset = 0, uint8_t byteStride = 0) noexcept; - // no-op if attribute is an invalid enum + /** + * Sets whether a given attribute should be normalized. By default attributes are not + * normalized. A normalized attribute is mapped between 0 and 1 in the shader. This applies + * only to integer types. + * + * @param attribute Enum of the attribute to set the normalization flag to. + * @param normalize true to automatically normalize the given attribute. + * @return A reference to this Builder for chaining calls. + * + * This is a no-op if the \p attribute is an invalid enum. + */ Builder& normalized(VertexAttribute attribute, bool normalize = true) noexcept; /** @@ -85,39 +149,46 @@ public: /** * Returns the vertex count. + * @return Number of vertices in this vertex buffer set. */ size_t getVertexCount() const noexcept; /** - * Moves the given buffer data into the slot at the given index. + * Asynchronously copy-initializes the specified buffer from the given buffer data. * - * Does nothing if bufferIndex >= bufferCount. + * @param engine Reference to the filament::Engine to associate this IndexBuffer with. + * @param bufferIndex Index of the buffer to initialize. Must be between 0 + * and Builder::bufferCount() - 1. + * @param buffer A BufferDescriptor representing the data used to initialize the buffer at + * index \p bufferIndex. BufferDescriptor points to raw, untyped data that will + * be copied as-is into the buffer. + * @param byteOffset Offset in *byte* into the buffer at index \p bufferIndex of this vertex + * buffer set. */ - void setBufferAt(Engine& engine, uint8_t bufferIndex, - BufferDescriptor&& buffer, + void setBufferAt(Engine& engine, uint8_t bufferIndex, BufferDescriptor&& buffer, uint32_t byteOffset = 0); /** * Specifies the quaternion type for the "populateTangentQuaternions" utility. */ enum QuatType { - HALF4, // 2 bytes per component as half-floats (8 bytes per quat) - SHORT4, // 2 bytes per component as normalized integers (8 bytes per quat) - FLOAT4, // 4 bytes per component as floats (16 bytes per quat) + HALF4, //!< 2 bytes per component as half-floats (8 bytes per quat) + SHORT4, //!< 2 bytes per component as normalized integers (8 bytes per quat) + FLOAT4, //!< 4 bytes per component as floats (16 bytes per quat) }; /** * Specifies the parameters for the "populateTangentQuaternions" utility. */ struct QuatTangentContext { - QuatType quatType; // desired quaternion type (required) - size_t quatCount; // number of quaternions (required) - void* outBuffer; // pre-allocated output buffer (required) - size_t outStride; // desired stride in bytes (optional) - const filament::math::float3* normals; // source normals (required) - size_t normalsStride; // normals stride in bytes (optional) - const filament::math::float4* tangents; // source tangents (optional) - size_t tangentsStride; // tangents stride in bytes (optional) + QuatType quatType; //!< desired quaternion type (required) + size_t quatCount; //!< number of quaternions (required) + void* outBuffer; //!< pre-allocated output buffer (required) + size_t outStride; //!< desired stride in bytes (optional) + const filament::math::float3* normals; //!< source normals (required) + size_t normalsStride; //!< normals stride in bytes (optional) + const filament::math::float4* tangents; //!< source tangents (optional) + size_t tangentsStride; //!< tangents stride in bytes (optional) }; /** @@ -135,6 +206,8 @@ public: * If supplied, the tangent vectors should be unit length and should be orthogonal to the * normals. The w component of the tangent is a sign (-1 or +1) indicating handedness of the * basis. + * + * @param ctx An initialized QuatTangentContext structure. */ static void populateTangentQuaternions(const QuatTangentContext& ctx); }; diff --git a/filament/include/filament/View.h b/filament/include/filament/View.h index 1ce8eb8150..72ec382f8d 100644 --- a/filament/include/filament/View.h +++ b/filament/include/filament/View.h @@ -132,6 +132,8 @@ public: * using an R11G11B10F opaque color buffer or an RGBA16F transparent color * buffer. With R11G11B10F colors in the LDR range have a precision of either * 6 bits (red and green channels) or 5 bits (blue channel). + * + * @see setRenderQuality, getAntiAliasing */ struct RenderQuality { QualityLevel hdrColorBuffer = QualityLevel::HIGH; //!< quality of the color buffer @@ -139,12 +141,14 @@ public: /** * List of available post-processing anti-aliasing techniques. + * @see setAntiAliasing, getAntiAliasing */ enum class AntiAliasing : uint8_t { - NONE = 0, - FXAA = 1 + NONE = 0, //!< no anti aliasing performed as part of post-processing + FXAA = 1 //!< FXAA is a low-quality but very efficient type of anti-aliasing. (default). }; + /** @see setDepthPrepass */ enum class DepthPrepass : int8_t { DEFAULT = -1, DISABLED, @@ -356,6 +360,10 @@ public: * n: sample count. Effective sample could be different depending on the * GPU capabilities. * + * @note Anti-aliasing can also be performed in the post-processing stage, generally at lower + * cost. See setAntialiasing. + * + * @see setAntialiasing */ void setSampleCount(uint8_t count = 1) noexcept; @@ -372,6 +380,10 @@ public: * MSAA can be enabled in addition, see setSampleCount(). * * @param type FXAA for enabling, NONE for disabling anti-aliasing. + * + * @note For MSAA anti-aliasing, see setSamplerCount(). + * + * @see setSampleCount */ void setAntiAliasing(AntiAliasing type) noexcept; diff --git a/filament/include/filament/Viewport.h b/filament/include/filament/Viewport.h index 668bb59430..1115151241 100644 --- a/filament/include/filament/Viewport.h +++ b/filament/include/filament/Viewport.h @@ -14,6 +14,8 @@ * limitations under the License. */ +//! \file + #ifndef TNT_FILAMENT_VIEWPORT_H #define TNT_FILAMENT_VIEWPORT_H @@ -29,38 +31,71 @@ namespace filament { -/* +/** * Viewport describes a view port in pixel coordinates + * + * A view port is represented by its left-bottom coordinate, width and height in pixels. */ class UTILS_PUBLIC Viewport : public driver::Viewport { public: - Viewport() noexcept : driver::Viewport{ 0, 0, 0, 0 } { - } + /** + * Creates a Viewport of zero width and height at the origin. + */ + Viewport() noexcept : driver::Viewport{} {} Viewport(const Viewport& viewport) noexcept = default; Viewport(Viewport&& viewport) noexcept = default; Viewport& operator=(const Viewport& viewport) noexcept = default; Viewport& operator=(Viewport&& viewport) noexcept = default; - /* - * Create a Viewport from its left-bottom coordinates and size in pixels + /** + * Creates a Viewport from its left-bottom coordinates, width and height in pixels + * + * @param left left coordinate in pixel + * @param bottom bottom coordinate in pixel + * @param width width in pixel + * @param height height in pixel */ Viewport(int32_t left, int32_t bottom, uint32_t width, uint32_t height) noexcept : driver::Viewport{ left, bottom, width, height } { } + /** + * Returns whether the area of the view port is null. + * + * @return true if either width or height is 0 pixel. + */ bool empty() const noexcept { return !width || !height; } + /** + * Computes a new scaled Viewport + * @param s scaling factor on the x and y axes. + * @return A new scaled Viewport. The coordinates and dimensions of the new Viewport are + * rounded to the nearest integer value. + */ Viewport scale(filament::math::float2 s) const noexcept; private: - friend bool operator==(Viewport const& rhs, Viewport const& lhs) noexcept { + + /** + * Compares two Viewports for equality + * @param lhs reference to the left hand side Viewport + * @param rhs reference to the rgiht hand side Viewport + * @return true if \p rhs and \p lhs are identical. + */ + friend bool operator==(Viewport const& lhs, Viewport const& rhs) noexcept { return (&rhs == &lhs) || (rhs.left == lhs.left && rhs.bottom == lhs.bottom && rhs.width == lhs.width && rhs.height == lhs.height); } - friend bool operator!=(Viewport const& rhs, Viewport const& lhs) noexcept { + /** + * Compares two Viewports for inequality + * @param lhs reference to the left hand side Viewport + * @param rhs reference to the rgiht hand side Viewport + * @return true if \p rhs and \p lhs are different. + */ + friend bool operator!=(Viewport const& lhs, Viewport const& rhs) noexcept { return !(rhs == lhs); } }; diff --git a/libs/filabridge/include/filament/MaterialEnums.h b/libs/filabridge/include/filament/MaterialEnums.h index af2c505faf..a924490c62 100644 --- a/libs/filabridge/include/filament/MaterialEnums.h +++ b/libs/filabridge/include/filament/MaterialEnums.h @@ -14,6 +14,8 @@ * limitations under the License. */ +//! \file + #ifndef TNT_FILAMENT_MATERIAL_ENUM_H #define TNT_FILAMENT_MATERIAL_ENUM_H @@ -24,57 +26,88 @@ namespace filament { +/** + * Supported shading models + */ enum class Shading : uint8_t { - UNLIT, // no lighting applied, emissive possible - LIT, // default, standard lighting - SUBSURFACE, // subsurface lighting model - CLOTH, // cloth lighting model + UNLIT, //!< no lighting applied, emissive possible + LIT, //!< default, standard lighting + SUBSURFACE, //!< subsurface lighting model + CLOTH, //!< cloth lighting model }; +/** + * Attribute interpolation types in the fragment shader + */ enum class Interpolation : uint8_t { - SMOOTH, // default, smooth interpolation - FLAT // flat interpolation + SMOOTH, //!< default, smooth interpolation + FLAT //!< flat interpolation }; +/** + * Supported blending modes + */ enum class BlendingMode : uint8_t { - OPAQUE, // material is opaque - TRANSPARENT, // material is transparent and color is alpha-pre-multiplied, - // affects diffuse lighting only - ADD, // material is additive (e.g.: hologram) - MASKED, // material is masked (i.e. alpha tested) - FADE // material is transparent and color is alpha-pre-multiplied, - // affects specular lighting - // when adding more entries, change the size of FRenderer::CommandKey::blending + //! material is opaque + OPAQUE, + //! material is transparent and color is alpha-pre-multiplied, affects diffuse lighting only + TRANSPARENT, + //! material is additive (e.g.: hologram) + ADD, + //! material is masked (i.e. alpha tested) + MASKED, + /** + * material is transparent and color is alpha-pre-multiplied, affects specular lighting + * when adding more entries, change the size of FRenderer::CommandKey::blending + */ + FADE }; +/** + * How transparent objects are handled + */ enum class TransparencyMode : uint8_t { - DEFAULT, // the transparent object is drawn honoring the raster state - TWO_PASSES_ONE_SIDE, // the transparent object is first drawn in the depth buffer, - // then in the color buffer, honoring the culling mode, but - // ignoring the depth test function - TWO_PASSES_TWO_SIDES // the transparent object is drawn twice in the color buffer, - // first with back faces only, then with front faces; the culling - // mode is ignored. Can be combined with two-sided lighting + //! the transparent object is drawn honoring the raster state + DEFAULT, + /** + * the transparent object is first drawn in the depth buffer, + * then in the color buffer, honoring the culling mode, but ignoring the depth test function + */ + TWO_PASSES_ONE_SIDE, + + /** + * the transparent object is drawn twice in the color buffer, + * first with back faces only, then with front faces; the culling + * mode is ignored. Can be combined with two-sided lighting + */ + TWO_PASSES_TWO_SIDES }; +/** + * Supported types of vertex domains. + */ enum class VertexDomain : uint8_t { - OBJECT, // vertices are in object space, default - WORLD, // vertices are in world space - VIEW, // vertices are in view space - DEVICE // vertices are in normalized device space + OBJECT, //!< vertices are in object space, default + WORLD, //!< vertices are in world space + VIEW, //!< vertices are in view space + DEVICE //!< vertices are in normalized device space // when adding more entries, make sure to update VERTEX_DOMAIN_COUNT }; -// Update hasIntegerTarget() in VertexBuffer when adding an attribute that will -// be read as integers in the shaders +/** + * Vertex attribute types + */ enum VertexAttribute : uint8_t { - POSITION = 0, // XYZ position (float3) - TANGENTS = 1, // tangent, bitangent and normal, encoded as a quaternion (float4) - COLOR = 2, // vertex color (float4) - UV0 = 3, // texture coordinates (float2) - UV1 = 4, // texture coordinates (float2) - BONE_INDICES = 5, // indices of 4 bones, as unsigned integers (uvec4) - BONE_WEIGHTS = 6, // weights of the 4 bones (normalized float4) + // Update hasIntegerTarget() in VertexBuffer when adding an attribute that will + // be read as integers in the shaders + + POSITION = 0, //!< XYZ position (float3) + TANGENTS = 1, //!< tangent, bitangent and normal, encoded as a quaternion (float4) + COLOR = 2, //!< vertex color (float4) + UV0 = 3, //!< texture coordinates (float2) + UV1 = 4, //!< texture coordinates (float2) + BONE_INDICES = 5, //!< indices of 4 bones, as unsigned integers (uvec4) + BONE_WEIGHTS = 6, //!< weights of the 4 bones (normalized float4) }; // can't really use std::underlying_type::type because the driver takes a uint32_t diff --git a/libs/filabridge/include/filament/driver/DriverEnums.h b/libs/filabridge/include/filament/driver/DriverEnums.h index 148dcc7f2d..ef16dd08eb 100644 --- a/libs/filabridge/include/filament/driver/DriverEnums.h +++ b/libs/filabridge/include/filament/driver/DriverEnums.h @@ -563,7 +563,7 @@ struct SamplerParams { SamplerWrapMode wrapR : 2; // CLAMP_TO_EDGE uint8_t anisotropyLog2 : 3; // 0 - SamplerCompareMode compareMode : 1; // NONE¡ + SamplerCompareMode compareMode : 1; // NONE bool depthStencil : 1; // false uint8_t padding0 : 1; // 0