Updated documentation for post-effects

Author: TheMostDiligent

PostProcess/Bloom/interface/Bloom.hpp

@@ -1,5 +1,5 @@
 /*
- *  Copyright 2024 Diligent Graphics LLC
+ *  Copyright 2024-2025 Diligent Graphics LLC
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -25,6 +25,9 @@
  */
 #pragma once
 
+/// \file
+/// Defines Diligent::Bloom class implementing bloom post-process effect.
+
 #include <unordered_map>
 #include <vector>
 #include <memory>
@@ -47,6 +50,10 @@ namespace HLSL
 struct BloomAttribs;
 }
 
+
+/// Implements [bloom post-process effect](https://github.com/DiligentGraphics/DiligentFX/tree/master/PostProcess/Bloom).
+
+/// \include{doc} DiligentFX/PostProcess/Bloom/README.md
 class Bloom
 {
 public:
@@ -55,6 +62,7 @@ class Bloom
         FEATURE_FLAG_NONE = 0u
     };
 
+    /// Render attributes.
     struct RenderAttributes
     {
         /// Render device that may be used to create new objects needed for this frame, if any.
@@ -76,22 +84,33 @@ class Bloom
         const HLSL::BloomAttribs* pBloomAttribs = nullptr;
     };
 
+    /// Create info.
     struct CreateInfo
     {
+        /// Whether to enable asynchronous shader and pipeline state creation.
+
+        /// If enabled, the shaders and pipeline state objects will be created using
+        /// the engine's asynchronous creation mechanism. While shaders are being
+        /// compiled, the effect will do nothing and return a black texture.
         bool EnableAsyncCreation = false;
     };
 
 public:
+    /// Creates a new instance of the Bloom class.
     Bloom(IRenderDevice* pDevice, const CreateInfo& CI);
 
     ~Bloom();
 
+    /// Prepares the bloom effect for rendering.
     void PrepareResources(IRenderDevice* pDevice, IDeviceContext* pDeviceContext, PostFXContext* pPostFXContext, FEATURE_FLAGS FeatureFlags);
 
+    /// Executes the bloom effect.
     void Execute(const RenderAttributes& RenderAttribs);
 
+    /// Adds the ImGui controls to the UI.
     static bool UpdateUI(HLSL::BloomAttribs& Attribs, FEATURE_FLAGS& FeatureFlags);
 
+    /// Returns the shader resource view of the bloom texture.
     ITextureView* GetBloomTextureSRV() const;
 
 private:

PostProcess/DepthOfField/interface/DepthOfField.hpp

@@ -1,5 +1,5 @@
 /*
- *  Copyright 2024 Diligent Graphics LLC
+ *  Copyright 2024-2025 Diligent Graphics LLC
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -25,6 +25,9 @@
  */
 #pragma once
 
+/// \file
+/// Defines Diligent::DepthOfField class implementing depth-of-field post-process effect.
+
 #include <unordered_map>
 #include <memory>
 
@@ -46,16 +49,25 @@ namespace HLSL
 struct DepthOfFieldAttribs;
 }
 
+/// Implements [depth-of-field post-process effect](https://github.com/DiligentGraphics/DiligentFX/tree/master/PostProcess/DepthOfField).
+
+/// \include{doc} DiligentFX/PostProcess/DepthOfField/README.md
 class DepthOfField
 {
 public:
+    /// Feature flags that control the behavior of the effect.
     enum FEATURE_FLAGS : Uint32
     {
-        FEATURE_FLAG_NONE                      = 0u,
+        /// No feature flags are set.
+        FEATURE_FLAG_NONE = 0u,
+
+        /// Enable temporal smoothing.
         FEATURE_FLAG_ENABLE_TEMPORAL_SMOOTHING = 1u << 0u,
-        FEATURE_FLAG_ENABLE_KARIS_INVERSE      = 1u << 1u
+
+        FEATURE_FLAG_ENABLE_KARIS_INVERSE = 1u << 1u
     };
 
+    /// Render attributes.
     struct RenderAttributes
     {
         /// Render device that may be used to create new objects needed for this frame, if any.
@@ -80,22 +92,33 @@ class DepthOfField
         const HLSL::DepthOfFieldAttribs* pDOFAttribs = nullptr;
     };
 
+    /// Create info.
     struct CreateInfo
     {
+        /// Whether to enable asynchronous shader and pipeline state creation.
+
+        /// If enabled, the shaders and pipeline state objects will be created using
+        /// the engine's asynchronous creation mechanism. While shaders are being
+        /// compiled, the effect will do nothing and return the input color.
         bool EnableAsyncCreation = false;
     };
 
 public:
+    /// Creates a new instance of the DepthOfField class.
     DepthOfField(IRenderDevice* pDevice, const CreateInfo& CI);
 
     ~DepthOfField();
 
+    /// Prepares resources for the effect.
     void PrepareResources(IRenderDevice* pDevice, IDeviceContext* pDeviceContext, PostFXContext* pPostFXContext, FEATURE_FLAGS FeatureFlags);
 
+    /// Executes the effect.
     void Execute(const RenderAttributes& RenderAttribs);
 
+    /// Adds the ImGui controls to the UI.
     static bool UpdateUI(HLSL::DepthOfFieldAttribs& Attribs, FEATURE_FLAGS& FeatureFlags);
 
+    /// Returns the shader resource view of the depth-of-field texture.
     ITextureView* GetDepthOfFieldTextureSRV() const;
 
 private:

PostProcess/EpipolarLightScattering/README.md

@@ -14,63 +14,63 @@ that start at the light source and interpolating the radiance between these samp
 `EpipolarLightScatteringAttribs` structure 
 The following parameters control the effect
 
-* uiNumEpipolarSlices - the total number of epipolar slices (lines). For high quality effect,
-                        set this value to (Screen Width + Screen Height)/2
-* uiMaxSamplesInSlice - Maximum number of samples on a single epipolar line.
-                        When epipolar light is short, the actual number of samples
-                        may be lower. For high quality effect, set this value to max(Screen Width, Screen Height)/2. 
-* uiInitialSampleStepInSlice - Initial ray marching sample spacing on an epipolar line. 
-                               Additional samples are added at discontinuities.
-* uiEpipoleSamplingDensityFactor - Sample density scale near the epipole where inscattering changes rapidly.
-                                   Note that sampling near the epipole is very cheap since only a few steps
-                                   required to perform ray marching.
-* fRefinementThreshold - Sampling refinement threshold that controls detection of discontinuities. Smaller values
-                         produce more samples and higher quality, but at a higher performance cost.
-* bShowSampling    - Whether to show epipolar sampling.
-* bCorrectScatteringAtDepthBreaks - Whether to correct inscattering at depth discontinuities. Improves quality
-                                    for additional cost. It may be preferable to increase the number of slices
-                                    and or maximum number of samples on an epipolar line instead.
-* bShowDepthBreaks  -  Whether to display pixels which are classified as depth discontinuities and which
-                       will be corrected. Only has effect when bCorrectScatteringAtDepthBreaks is TRUE.
-* bShowLightingOnly - Whether to show lighting only
-* bOptimizeSampleLocations - Optimize sample locations to avoid oversampling. This should generally be TRUE.
-* bEnableLightShafts  - Whether to enable light shafts or render unshadowed inscattering.
-                        Setting this to FALSE increases performance, but reduces visual quality.
-* uiInstrIntegralSteps  - Number of inscattering integral steps taken when computing unshadowed inscattering
-                          Default value is OK and should not be changed.
-* f2ShadowMapTexelSize  - Size of the shadowmap texel (1/width, 1/height)
-* uiMaxSamplesOnTheRay  - Maximum number of ray marching samples on a single ray. Typically this value should match the maximum 
-                          shadow map cascade resolution. Using lower value will improve performance but may result
-                          in moire patterns. Note that in most cases significantly less samples are actually taken.
-* uiMinMaxShadowMapResolution - Defines the number of samples at the lowest level of min-max binary tree
-                                and should match the maximum cascade shadow map resolution.
-* iNumCascades - Number of shadow map cascades
-* iFirstCascadeToRayMarch  -  First cascade to use for ray marching. Usually first few cascades are small, and ray
-                              marching them is inefficient.
-* fMaxShadowMapStep -  Cap on the maximum shadow map step in texels.
-* bUse1DMinMaxTree  -  Whether to use 1D min/max binary tree optimization. This improves
-                       performance for higher shadow map resolution. Test it.
-* bIs32BitMinMaxMipMap - Whether to use 32-bit float or 16-bit UNORM min-max binary tree. Usually 16-bit UNORM is OK.
-* uiLightSctrTechnique - Light scattering evaluation technique. The following two methods are available: epipolar and brute-force.
-                         Brute force light scattering performs expensive ray marching for every screen pixel. This method
-                         can be used as the quality reference.
-* uiCascadeProcessingMode  - Shadow map cascades processing mode.
-* uiRefinementCriterion  - Epipolar sampling refinement criterion. The two options are depth difference and scattering difference.
-                           Scattering difference is generally preferable way.
-* uiSingleScatteringMode - Single scattering evaluation mode. The following three methods are available:
+* `uiNumEpipolarSlices` - the total number of epipolar slices (lines). For high quality effect,
+                          set this value to (Screen Width + Screen Height)/2
+* `uiMaxSamplesInSlice` - Maximum number of samples on a single epipolar line.
+                          When epipolar light is short, the actual number of samples
+                          may be lower. For high quality effect, set this value to max(Screen Width, Screen Height)/2. 
+* `uiInitialSampleStepInSlice` - Initial ray marching sample spacing on an epipolar line. 
+                                 Additional samples are added at discontinuities.
+* `uiEpipoleSamplingDensityFactor` - Sample density scale near the epipole where inscattering changes rapidly.
+                                     Note that sampling near the epipole is very cheap since only a few steps
+                                     required to perform ray marching.
+* `fRefinementThreshold` - Sampling refinement threshold that controls detection of discontinuities. Smaller values
+                           produce more samples and higher quality, but at a higher performance cost.
+* `bShowSampling`    - Whether to show epipolar sampling.
+* `bCorrectScatteringAtDepthBreaks` - Whether to correct inscattering at depth discontinuities. Improves quality
+                                      for additional cost. It may be preferable to increase the number of slices
+                                      and or maximum number of samples on an epipolar line instead.
+* `bShowDepthBreaks`  -  Whether to display pixels which are classified as depth discontinuities and which
+                         will be corrected. Only has effect when bCorrectScatteringAtDepthBreaks is TRUE.
+* `bShowLightingOnly` - Whether to show lighting only
+* `bOptimizeSampleLocations` - Optimize sample locations to avoid oversampling. This should generally be TRUE.
+* `bEnableLightShafts`  - Whether to enable light shafts or render unshadowed inscattering.
+                          Setting this to FALSE increases performance, but reduces visual quality.
+* `uiInstrIntegralSteps`  - Number of inscattering integral steps taken when computing unshadowed inscattering
+                            Default value is OK and should not be changed.
+* `f2ShadowMapTexelSize`  - Size of the shadowmap texel (1/width, 1/height)
+* `uiMaxSamplesOnTheRay`  - Maximum number of ray marching samples on a single ray. Typically this value should match the maximum 
+                            shadow map cascade resolution. Using lower value will improve performance but may result
+                            in moire patterns. Note that in most cases significantly less samples are actually taken.
+* `uiMinMaxShadowMapResolution` - Defines the number of samples at the lowest level of min-max binary tree
+                                  and should match the maximum cascade shadow map resolution.
+* `iNumCascades` - Number of shadow map cascades
+* `iFirstCascadeToRayMarch`  -  First cascade to use for ray marching. Usually first few cascades are small, and ray
+                                marching them is inefficient.
+* `fMaxShadowMapStep` -  Cap on the maximum shadow map step in texels.
+* `bUse1DMinMaxTree`  -  Whether to use 1D min/max binary tree optimization. This improves
+                         performance for higher shadow map resolution. Test it.
+* `bIs32BitMinMaxMipMap` - Whether to use 32-bit float or 16-bit UNORM min-max binary tree. Usually 16-bit UNORM is OK.
+* `uiLightSctrTechnique` - Light scattering evaluation technique. The following two methods are available: epipolar and brute-force.
+                           Brute force light scattering performs expensive ray marching for every screen pixel. This method
+                           can be used as the quality reference.
+* `uiCascadeProcessingMode`  - Shadow map cascades processing mode.
+* `uiRefinementCriterion`  - Epipolar sampling refinement criterion. The two options are depth difference and scattering difference.
+                             Scattering difference is generally preferable way.
+* `uiSingleScatteringMode` - Single scattering evaluation mode. The following three methods are available:
   * None - no single scattering.
   * Integration (default) - evaluate single scattering with numerical integration.
   * Look-up table - use precomputed single-scattering look-up table.
-* uiMultipleScatteringMode - Higher-order scattering evaluation mode. The following three options are available:
+* `uiMultipleScatteringMode` - Higher-order scattering evaluation mode. The following three options are available:
   * None - no multiple scattering.
   * Unoccluded (default) - evaluate multiple scattering without shadowing.
   * Occluded - evaluate multiple scattering taking shadowing into account similar to single scattering.
-* uiExtinctionEvalMode - Atmospheric extinction evaluation mode.
-* bUseCustomSctrCoeffs - Whether to use custom scattering coefficients.
-* fAerosolDensityScale - Aerosol density scale to use for scattering coefficient computation.
-* fAerosolAbsorbtionScale - Aerosol absorption scale to use for scattering coefficient computation.
-* f4CustomRlghBeta - Custom Rayleigh coefficients.
-* f4CustomMieBeta  - Custom Mie coefficients.
+* `uiExtinctionEvalMode` - Atmospheric extinction evaluation mode.
+* `bUseCustomSctrCoeffs` - Whether to use custom scattering coefficients.
+* `fAerosolDensityScale` - Aerosol density scale to use for scattering coefficient computation.
+* `fAerosolAbsorbtionScale` - Aerosol absorption scale to use for scattering coefficient computation.
+* `f4CustomRlghBeta` - Custom Rayleigh coefficients.
+* `f4CustomMieBeta`  - Custom Mie coefficients.
 
 ## Integration
 

PostProcess/EpipolarLightScattering/interface/EpipolarLightScattering.hpp

@@ -1,5 +1,5 @@
 /*
- *  Copyright 2019-2024 Diligent Graphics LLC
+ *  Copyright 2019-2025 Diligent Graphics LLC
  *  Copyright 2015-2019 Egor Yusov
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
@@ -26,6 +26,9 @@
  */
 #pragma once
 
+/// \file
+/// Defines Diligent::EpipolarLightScattering class implementing epipolar light scattering post-process effect.
+
 #include "../../../../DiligentCore/Graphics/GraphicsEngine/interface/RenderDevice.h"
 #include "../../../../DiligentCore/Graphics/GraphicsEngine/interface/DeviceContext.h"
 #include "../../../../DiligentCore/Graphics/GraphicsEngine/interface/Buffer.h"
@@ -45,10 +48,13 @@ using uint = uint32_t;
 #include "Shaders/PostProcess/ToneMapping/public/ToneMappingStructures.fxh"
 #include "Shaders/PostProcess/EpipolarLightScattering/public/EpipolarLightScatteringStructures.fxh"
 
+/// Implements the [epipolar light scattering post-process effect](https://github.com/DiligentGraphics/DiligentFX/tree/master/PostProcess/EpipolarLightScattering).
 
+/// \include{doc} DiligentFX/PostProcess/EpipolarLightScattering/README.md
 class EpipolarLightScattering
 {
 public:
+    /// Frame attributes that are passed to the effect at the beginning of each frame.
     struct FrameAttribs
     {
         /// Render device that may be used to create new objects needed for this frame, if any.
@@ -60,13 +66,19 @@ class EpipolarLightScattering
         /// Device context that will record the rendering commands.
         IDeviceContext* pDeviceContext = nullptr;
 
+        /// The time elapsed since the last frame.
         double dElapsedTime = 0;
 
-        const LightAttribs*  pLightAttribs  = nullptr;
+        /// A pointer to the light attributes CPU data.
+        const LightAttribs* pLightAttribs = nullptr;
+
+        /// A pointer to the camera attributes CPU data.
         const CameraAttribs* pCameraAttribs = nullptr;
-        // If this parameter is null, the effect will use its own buffer.
+
+        /// If this parameter is null, the effect will use its own buffer.
         IBuffer* pcbLightAttribs = nullptr;
-        // If this parameter is null, the effect will use its own buffer.
+
+        /// If this parameter is null, the effect will use its own buffer.
         IBuffer* pcbCameraAttribs = nullptr;
 
         /// Shader resource view of the source color buffer.
@@ -85,19 +97,37 @@ class EpipolarLightScattering
         ITextureView* ptex2DShadowMapSRV = nullptr;
     };
 
+    /// Create info.
     struct CreateInfo
     {
-        IRenderDevice*       pDevice             = nullptr;
-        IRenderStateCache*   pStateCache         = nullptr;
-        IDeviceContext*      pContext            = nullptr;
-        TEXTURE_FORMAT       BackBufferFmt       = TEX_FORMAT_RGBA8_UNORM_SRGB;
-        TEXTURE_FORMAT       DepthBufferFmt      = TEX_FORMAT_D32_FLOAT;
-        TEXTURE_FORMAT       OffscreenBackBuffer = TEX_FORMAT_R11G11B10_FLOAT;
-        bool                 PackMatrixRowMajor  = false;
-        AirScatteringAttribs ScatteringAttibs    = {};
+        /// A pointer to the render device that will be used to create the effect.
+        IRenderDevice* pDevice = nullptr;
+
+        /// An optional render state cache to optimize state loading.
+        IRenderStateCache* pStateCache = nullptr;
+
+        /// The render device context that will be used to record the rendering commands.
+        IDeviceContext* pContext = nullptr;
+
+        /// Back buffer format.
+        TEXTURE_FORMAT BackBufferFmt = TEX_FORMAT_RGBA8_UNORM_SRGB;
+
+        /// Depth buffer format.
+        TEXTURE_FORMAT DepthBufferFmt = TEX_FORMAT_D32_FLOAT;
+
+        /// Offscreen back buffer format.
+        TEXTURE_FORMAT OffscreenBackBuffer = TEX_FORMAT_R11G11B10_FLOAT;
+
+        /// Whether to use row-major packing for the matrix data.
+        bool PackMatrixRowMajor = false;
+
+        /// Air scattering attributes.
+        AirScatteringAttribs ScatteringAttibs = {};
     };
 
+    /// Creates a new instance of the EpipolarLightScattering class.
     EpipolarLightScattering(const CreateInfo& CI);
+
     ~EpipolarLightScattering();
 
 
@@ -109,20 +139,28 @@ class EpipolarLightScattering
     void PrepareForNewFrame(FrameAttribs&                   FrameAttribs,
                             EpipolarLightScatteringAttribs& PPAttribs);
 
+    /// Computes the sun color and ambient light color based on the given direction on the sun and extraterrestrial sun color.
     void ComputeSunColor(const float3& vDirectionOnSun,
                          const float4& f4ExtraterrestrialSunColor,
                          float4&       f4SunColorAtGround,
                          float4&       f4AmbientLight);
 
+    /// Renders the sun.
     void RenderSun(TEXTURE_FORMAT RTVFormat,
                    TEXTURE_FORMAT DSVFormat,
                    Uint8          SampleCount);
 
+    /// Runs the post-processing effect.
     void PerformPostProcessing();
 
 
-    IBuffer*      GetMediaAttribsCB() { return m_pcbMediaAttribs; }
+    /// Returns the media attributes buffer.
+    IBuffer* GetMediaAttribsCB() { return m_pcbMediaAttribs; }
+
+    /// Returns the precomputed net density look-up texture.
     ITextureView* GetPrecomputedNetDensitySRV() { return m_ptex2DOccludedNetDensityToAtmTopSRV; }
+
+    /// Returns the ambient sky light texture.
     ITextureView* GetAmbientSkyLightSRV(IRenderDevice* pDevice, IRenderStateCache* pStateCache, IDeviceContext* pContext);
 
 private: