Updated documentation for Bound Box Renderer, Env Map Renderer and other components

Author: TheMostDiligent

Components/interface/BoundBoxRenderer.hpp

@@ -24,6 +24,11 @@
  *  of the possibility of such damages.
  */
 
+#pragma once
+
+/// \file
+/// Defines BoundBoxRenderer class
+
 #include <unordered_map>
 #include <vector>
 #include <memory>
@@ -39,34 +44,45 @@
 namespace Diligent
 {
 
-/// Renders the bounding box.
+/// Bounding box renderer.
 class BoundBoxRenderer
 {
 public:
+    /// Bound box renderer creation info.
     struct CreateInfo
     {
-        IRenderDevice*     pDevice          = nullptr;
-        IRenderStateCache* pStateCache      = nullptr;
-        IBuffer*           pCameraAttribsCB = nullptr;
+        /// Render device.
+        IRenderDevice* pDevice = nullptr;
+
+        /// An optional render state cache.
+        IRenderStateCache* pStateCache = nullptr;
+
+        /// A buffer that contains camera attributes.
+        IBuffer* pCameraAttribsCB = nullptr;
 
-        Uint8          NumRenderTargets                        = 1;
+        /// The number of render targets.
+        Uint8 NumRenderTargets = 1;
+
+        /// Render target formats.
         TEXTURE_FORMAT RTVFormats[DILIGENT_MAX_RENDER_TARGETS] = {TEX_FORMAT_RGBA8_UNORM_SRGB};
-        TEXTURE_FORMAT DSVFormat                               = TEX_FORMAT_D32_FLOAT;
+
+        /// Depth-stencil view format.
+        TEXTURE_FORMAT DSVFormat = TEX_FORMAT_D32_FLOAT;
 
         /// A bit mask that defines the render targets to render to.
-        ///
-        /// \remarks    If bit N is set, the N-th render target's color write mask will be set to
-        ///             COLOR_MASK_ALL. Otherwise, it will be set to COLOR_MASK_NONE.
+
+        /// If bit N is set, the N-th render target's color write mask will be set to
+        /// Diligent::COLOR_MASK_ALL. Otherwise, it will be set to Diligent::COLOR_MASK_NONE.
         Uint32 RenderTargetMask = 0x1u;
 
         const char* PSMainSource = nullptr;
 
         /// Whether shader matrices are laid out in row-major order in GPU memory.
-        ///
-        /// \remarks    By default, shader matrices are laid out in column-major order
-        ///             in GPU memory. If this option is set to true, shaders will be compiled
-        ///             with the SHADER_COMPILE_FLAG_PACK_MATRIX_ROW_MAJOR flag and
-        ///             use the row-major layout.
+
+        /// By default, shader matrices are laid out in column-major order
+        /// in GPU memory. If this option is set to true, shaders will be compiled
+        /// with the Diligent::SHADER_COMPILE_FLAG_PACK_MATRIX_ROW_MAJOR flag and
+        /// use the row-major layout.
         bool PackMatrixRowMajor = false;
 
         /// Whether to compile shaders asynchronously.
@@ -78,6 +94,7 @@ class BoundBoxRenderer
     /// Option flags.
     enum OPTION_FLAGS : Uint32
     {
+        /// No options.
         OPTION_FLAG_NONE = 0u,
 
         /// Manually convert shader output to sRGB color space.
@@ -90,28 +107,39 @@ class BoundBoxRenderer
         OPTION_FLAG_USE_REVERSE_DEPTH = 1u << 2u
     };
 
+    /// Render attributes.
     struct RenderAttribs
     {
         /// Bounding box transformation matrix.
+
         /// Can't be null.
         const float4x4* BoundBoxTransform = nullptr;
 
         /// Bounding box color.
+
         /// If null, white color will be used.
         const float4* Color = nullptr;
 
         /// Pattern length in pixels.
         float PatternLength = 32;
 
         /// Pattern mask.
+
         /// Each bit defines whether the corresponding 1/32 section of the pattern is filled or not.
         /// For example, use 0x0000FFFFu to draw a dashed line.
         Uint32 PatternMask = 0xFFFFFFFFu;
 
         /// Render options.
         OPTION_FLAGS Options = OPTION_FLAG_NONE;
     };
+
+    /// Prepares the renderer.
+
+    /// \param [in] pContext - Device context.
+    /// \param [in] Attribs  - Render attributes.
     void Prepare(IDeviceContext* pContext, const RenderAttribs& Attribs);
+
+    /// Renders the bounding box.
     void Render(IDeviceContext* pContext);
 
 private:

Components/interface/CoordinateGridRenderer.hpp

@@ -26,6 +26,9 @@
 
 #pragma once
 
+/// \file
+/// Defines CoordinateGridRenderer class
+
 #include <unordered_map>
 #include <vector>
 
@@ -47,21 +50,40 @@ struct CameraAttribs;
 struct CoordinateGridAttribs;
 } // namespace HLSL
 
+
+/// Coordinate grid renderer.
 class CoordinateGridRenderer
 {
 public:
+    /// Feature flags.
     enum FEATURE_FLAGS : Uint32
     {
-        FEATURE_FLAG_NONE            = 0u,
+        /// No feature flags.
+        FEATURE_FLAG_NONE = 0u,
+
+        /// Convert pixel shader output to sRGB.
         FEATURE_FLAG_CONVERT_TO_SRGB = 1u << 0u,
+
+        /// Render grid in YZ plane.
         FEATURE_FLAG_RENDER_PLANE_YZ = 1u << 1u,
+
+        /// Render grid in XZ plane.
         FEATURE_FLAG_RENDER_PLANE_XZ = 1u << 2u,
+
+        /// Render grid in XY plane.
         FEATURE_FLAG_RENDER_PLANE_XY = 1u << 3u,
-        FEATURE_FLAG_RENDER_AXIS_X   = 1u << 4u,
-        FEATURE_FLAG_RENDER_AXIS_Y   = 1u << 5u,
-        FEATURE_FLAG_RENDER_AXIS_Z   = 1u << 6u,
+
+        /// Render X axis.
+        FEATURE_FLAG_RENDER_AXIS_X = 1u << 4u,
+
+        /// Render Y axis.
+        FEATURE_FLAG_RENDER_AXIS_Y = 1u << 5u,
+
+        /// Render Z axis.
+        FEATURE_FLAG_RENDER_AXIS_Z = 1u << 6u,
     };
 
+    /// Render attributes.
     struct RenderAttributes
     {
         /// Render device that may be used to create new objects needed for this frame, if any.
@@ -92,18 +114,29 @@ class CoordinateGridRenderer
         const HLSL::CoordinateGridAttribs* pAttribs = nullptr;
     };
 
+    /// Create info.
     struct CreateInfo
     {
+        /// Whether shader matrices are laid out in row-major order in GPU memory.
+
+        /// By default, shader matrices are laid out in column-major order
+        /// in GPU memory. If this option is set to true, shaders will be compiled
+        /// with the Diligent::SHADER_COMPILE_FLAG_PACK_MATRIX_ROW_MAJOR flag and
+        /// use the row-major layout.
         bool PackMatrixRowMajor = false;
     };
 
 public:
+    /// Creates a new coordinate grid renderer.
     CoordinateGridRenderer(IRenderDevice* pDevice, const CreateInfo& CI);
 
+    /// Renders the coordinate grid.
     void Render(const RenderAttributes& Attribs);
 
+    /// Adds the coordinate grid UI elements.
     static bool UpdateUI(HLSL::CoordinateGridAttribs& Attribs, FEATURE_FLAGS& FeatureFlags);
 
+    /// Adds the coordinate grid shader macros.
     static void AddShaderMacros(FEATURE_FLAGS FeatureFlags, ShaderMacroHelper& Macros);
 
 private:

Components/interface/DepthRangeCalculator.hpp

@@ -24,6 +24,11 @@
  *  of the possibility of such damages.
  */
 
+#pragma once
+
+/// \file
+/// Defines DepthRangeCalculator class
+
 #include <memory>
 
 #include "../../../DiligentCore/Graphics/GraphicsEngine/interface/RenderDevice.h"
@@ -48,12 +53,12 @@ namespace Diligent
 ///         float SceneFarDepth;
 ///     };
 ///
-/// SceneNearZ is always less than SceneFarZ.
-/// SceneNearDepth is the depth value corresponding to SceneNearZ.
-/// SceneFarDepth is the depth value corresponding to SceneFarZ.
-/// Note that if reverse depth is used, SceneNearDepth will be greater than SceneFarDepth.
+/// * `SceneNearZ` is always less than `SceneFarZ`.
+/// * `SceneNearDepth` is the depth value corresponding to `SceneNearZ`.
+/// * `SceneFarDepth` is the depth value corresponding to `SceneFarZ`.
+/// * Note that if reverse depth is used, `SceneNearDepth` will be greater than `SceneFarDepth`.
 ///
-/// \remarks SceneNearZ and SceneFarZ must be positive values.
+/// \remarks `SceneNearZ` and `SceneFarZ` must be positive values.
 class DepthRangeCalculator
 {
 public:
@@ -68,10 +73,10 @@ class DepthRangeCalculator
 
         /// Whether shader matrices are laid out in row-major order in GPU memory.
         ///
-        /// \remarks    By default, shader matrices are laid out in column-major order
-        ///             in GPU memory. If this option is set to true, shaders will be compiled
-        ///             with the SHADER_COMPILE_FLAG_PACK_MATRIX_ROW_MAJOR flag and
-        ///             use the row-major layout.
+        /// By default, shader matrices are laid out in column-major order
+        /// in GPU memory. If this option is set to true, shaders will be compiled
+        /// with the SHADER_COMPILE_FLAG_PACK_MATRIX_ROW_MAJOR flag and
+        /// use the row-major layout.
         bool PackMatrixRowMajor = false;
 
         /// Whether to compile shaders asynchronously.
@@ -82,7 +87,7 @@ class DepthRangeCalculator
     };
 
     /// Constructs a depth range calculator object.
-    ///
+
     /// \param [in] CI  Create info.
     ///
     /// In case of failure, an exception is thrown.
@@ -105,7 +110,7 @@ class DepthRangeCalculator
         IDeviceContext* pContext = nullptr;
 
         /// Shader resource binding object.
-        ///
+
         /// The SRB must be created using the CreateSRB() method.
         IShaderResourceBinding* pSRB = nullptr;
 
@@ -117,11 +122,11 @@ class DepthRangeCalculator
     };
 
     /// Computes the depth range.
-    ///
+
     /// \param [in] Attribs  Method attributes.
     ///
     /// The near/far depth values are written to the depth range buffer.
-    /// If the ReadBackData option was set to true in the CreateInfo structure,
+    /// If the `ReadBackData` option was set to true in the `CreateInfo` structure,
     /// the depth range will also be read back to the CPU and can be accessed using
     /// the GetDepthRange() method.
     ///
@@ -148,7 +153,7 @@ class DepthRangeCalculator
     };
 
     /// Returns the depth range read back to the CPU.
-    ///
+
     /// \param [in] pCtx  If not null, the function will poll the read back queue for the latest data.
     /// \return           The depth range read back to the CPU.
     const DepthRange& GetDepthRange(IDeviceContext* pCtx = nullptr);