Updated documentation for Buffer, BufferView, BLAS, Dearchiver and BlendState

TheMostDiligent · TheMostDiligent · commit 5afffa1fd57d · 2025-04-09T20:15:15.000-07:00
diff --git a/Graphics/GraphicsEngine/include/DearchiverBase.hpp b/Graphics/GraphicsEngine/include/DearchiverBase.hpp
@@ -1,5 +1,5 @@
 /*
- *  Copyright 2019-2022 Diligent Graphics LLC
+ *  Copyright 2019-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.
@@ -255,8 +255,8 @@ RefCntAutoPtr<IPipelineResourceSignature> DearchiverBase::UnpackResourceSignatur
 
     PRS.Desc.SRBAllocationGranularity = DeArchiveInfo.SRBAllocationGranularity;
 
-    const auto  DevType = GetArchiveDeviceType(DeArchiveInfo.pDevice);
-    const auto& Data    = pObjArchive->GetDeviceSpecificData(PRSData::ArchiveResType, DeArchiveInfo.Name, DevType);
+    const DeviceType      DevType = GetArchiveDeviceType(DeArchiveInfo.pDevice);
+    const SerializedData& Data    = pObjArchive->GetDeviceSpecificData(PRSData::ArchiveResType, DeArchiveInfo.Name, DevType);
     if (!Data)
         return {};
 
@@ -272,7 +272,7 @@ RefCntAutoPtr<IPipelineResourceSignature> DearchiverBase::UnpackResourceSignatur
     if (SpecialDesc)
     {
         // The signature uses a special description that differs from the common
-        const auto* Name = PRS.Desc.Name;
+        const Char* Name = PRS.Desc.Name;
         PRS.Desc         = {};
         if (!PRS.Deserialize(Name, Ser))
         {
@@ -289,7 +289,7 @@ RefCntAutoPtr<IPipelineResourceSignature> DearchiverBase::UnpackResourceSignatur
     }
     VERIFY_EXPR(Ser.IsEnded());
 
-    auto* pRenderDevice = ClassPtrCast<RenderDeviceImplType>(DeArchiveInfo.pDevice);
+    RenderDeviceImplType* pRenderDevice = ClassPtrCast<RenderDeviceImplType>(DeArchiveInfo.pDevice);
     pRenderDevice->CreatePipelineResourceSignature(PRS.Desc, InternalData, &pSignature);
 
     if (!IsImplicit)
diff --git a/Graphics/GraphicsEngine/interface/BlendState.h b/Graphics/GraphicsEngine/interface/BlendState.h
@@ -1,5 +1,5 @@
 /*
- *  Copyright 2019-2023 Diligent Graphics LLC
+ *  Copyright 2019-2025 Diligent Graphics LLC
  *  Copyright 2015-2019 Egor Yusov
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
@@ -413,12 +413,13 @@ struct BlendStateDesc
 
     /// \param [in] RHS - reference to the structure to perform comparison with
     /// \return
-    /// - True if all members are of the two structures equal.
-    ///   \note The operator performs *bitwise comparison* of the two structures.
-    ///   That is if for instance both structures have IndependentBlendEnable set to False,
-    ///   but differ in render target other than 0, the operator will return False
-    ///   even though the two blend states created from these structures will be identical.
-    /// - False otherwise
+    /// - `True` if all members are of the two structures equal.
+    /// - `False` otherwise.
+    ///
+    ///  \note The operator performs *bitwise comparison* of the two structures.
+    ///        That is if for instance both structures have IndependentBlendEnable set to False,
+    ///        but differ in render target other than 0, the operator will return False
+    ///        even though the two blend states created from these structures will be identical.
     constexpr bool operator==(const BlendStateDesc& RHS) const
     {
         bool bRTsEqual = true;
diff --git a/Graphics/GraphicsEngine/interface/BottomLevelAS.h b/Graphics/GraphicsEngine/interface/BottomLevelAS.h
@@ -1,5 +1,5 @@
 /*
- *  Copyright 2019-2023 Diligent Graphics LLC
+ *  Copyright 2019-2025 Diligent Graphics LLC
  *  Copyright 2015-2019 Egor Yusov
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
@@ -54,29 +54,33 @@ static DILIGENT_CONSTEXPR Uint32 INVALID_INDEX = DILIGENT_INVALID_INDEX;
 struct BLASTriangleDesc
 {
     /// Geometry name.
+
     /// The name is used to map triangle data (BLASBuildTriangleData) to this geometry.
     const Char*               GeometryName          DEFAULT_INITIALIZER(nullptr);
 
     /// The maximum vertex count in this geometry.
+
     /// Current number of vertices is defined in BLASBuildTriangleData::VertexCount.
     Uint32                    MaxVertexCount        DEFAULT_INITIALIZER(0);
 
     /// The type of vertices in this geometry, see Diligent::VALUE_TYPE.
-    ///
+
     /// \remarks Only the following values are allowed: VT_FLOAT32, VT_FLOAT16, VT_INT16.
     ///          VT_INT16 defines 16-bit signed normalized vertex components.
     VALUE_TYPE                VertexValueType       DEFAULT_INITIALIZER(VT_UNDEFINED);
 
     /// The number of components in the vertex.
-    ///
+
     /// \remarks Only 2 or 3 are allowed values. For 2-component formats, the third component is assumed 0.
     Uint8                     VertexComponentCount  DEFAULT_INITIALIZER(0);
 
     /// The maximum primitive count in this geometry.
+
     /// The current number of primitives is defined in BLASBuildTriangleData::PrimitiveCount.
     Uint32                    MaxPrimitiveCount     DEFAULT_INITIALIZER(0);
 
     /// Index type of this geometry, see Diligent::VALUE_TYPE.
+
     /// Must be VT_UINT16, VT_UINT32 or VT_UNDEFINED.
     /// If not defined then vertex array is used instead of indexed vertices.
     VALUE_TYPE                IndexType             DEFAULT_INITIALIZER(VT_UNDEFINED);
@@ -208,8 +212,8 @@ struct BottomLevelASDesc DILIGENT_DERIVE(DeviceObjectAttribs)
 
     /// \param [in] RHS - reference to the structure to compare with.
     ///
-    /// \return     true if all members of the two structures *except for the Name* are equal,
-    ///             and false otherwise.
+    /// \return     `true` if all members of the two structures *except for the Name* are equal,
+    ///             and `false` otherwise.
     ///
     /// \note   The operator ignores the Name field as it is used for debug purposes and
     ///         doesn't affect the BLAS properties.
diff --git a/Graphics/GraphicsEngine/interface/Buffer.h b/Graphics/GraphicsEngine/interface/Buffer.h
@@ -1,5 +1,5 @@
 /*
- *  Copyright 2019-2023 Diligent Graphics LLC
+ *  Copyright 2019-2025 Diligent Graphics LLC
  *  Copyright 2015-2019 Egor Yusov
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
@@ -73,7 +73,8 @@ DILIGENT_TYPED_ENUM(BUFFER_MODE, Uint8)
 /// Miscellaneous buffer flags.
 DILIGENT_TYPED_ENUM(MISC_BUFFER_FLAGS, Uint8)
 {
-    MISC_BUFFER_FLAG_NONE          = 0,
+    /// No special flags are set.
+    MISC_BUFFER_FLAG_NONE            = 0,
 
     /// For a sparse buffer, allow binding the same memory region in different buffer ranges
     /// or in different sparse buffers.
@@ -99,8 +100,7 @@ struct BufferDesc DILIGENT_DERIVE(DeviceObjectAttribs)
     /// Buffer usage, see Diligent::USAGE for details
     USAGE Usage                     DEFAULT_INITIALIZER(USAGE_DEFAULT);
 
-    /// CPU access flags or 0 if no CPU access is allowed,
-    /// see Diligent::CPU_ACCESS_FLAGS for details.
+    /// CPU access flags or 0 if no CPU access is allowed, see Diligent::CPU_ACCESS_FLAGS for details.
     CPU_ACCESS_FLAGS CPUAccessFlags DEFAULT_INITIALIZER(CPU_ACCESS_NONE);
 
     /// Buffer mode, see Diligent::BUFFER_MODE
@@ -221,7 +221,7 @@ struct SparseBufferProperties
     Uint64  AddressSpaceSize  DEFAULT_INITIALIZER(0);
 
     /// The size of the sparse memory block.
-    ///
+
     /// \note Offset in the buffer, memory offset and memory size that are used in sparse resource
     ///       binding command, must be multiples of the block size.
     ///       In Direct3D11 and Direct3D12, the block size is always 64Kb.
@@ -320,8 +320,8 @@ DILIGENT_BEGIN_INTERFACE(IBuffer, IDeviceObject)
     ///
     /// \note   This method must never be used for USAGE_DYNAMIC buffers.
     ///
-    ///         When a mapped buffer is unmapped it is automatically flushed by
-    ///         the engine if necessary.
+    /// When a mapped buffer is unmapped it is automatically flushed by
+    /// the engine if necessary.
     VIRTUAL void METHOD(FlushMappedRange)(THIS_
                                           Uint64 StartOffset,
                                           Uint64 Size) PURE;
@@ -341,8 +341,8 @@ DILIGENT_BEGIN_INTERFACE(IBuffer, IDeviceObject)
     ///
     /// \note   This method must never be used for USAGE_DYNAMIC buffers.
     ///
-    ///         When a mapped buffer is unmapped it is automatically invalidated by
-    ///         the engine if necessary.
+    /// When a mapped buffer is unmapped, it is automatically invalidated by
+    /// the engine if necessary.
     VIRTUAL void METHOD(InvalidateMappedRange)(THIS_
                                                Uint64 StartOffset,
                                                Uint64 Size) PURE;
diff --git a/Graphics/GraphicsEngine/interface/BufferView.h b/Graphics/GraphicsEngine/interface/BufferView.h
@@ -1,5 +1,5 @@
 /*
- *  Copyright 2019-2023 Diligent Graphics LLC
+ *  Copyright 2019-2025 Diligent Graphics LLC
  *  Copyright 2015-2019 Egor Yusov
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
@@ -47,6 +47,7 @@ struct BufferFormat
     VALUE_TYPE ValueType    DEFAULT_INITIALIZER(VT_UNDEFINED);
 
     /// Number of components. Allowed values: 1, 2, 3, 4.
+
     /// For a formatted buffer, this value cannot be 0
     Uint8 NumComponents     DEFAULT_INITIALIZER(0);
 
@@ -96,10 +97,10 @@ struct BufferViewDesc DILIGENT_DERIVE(DeviceObjectAttribs)
     struct BufferFormat Format;
 
     /// Offset in bytes from the beginning of the buffer to the start of the
-    /// buffer region referenced by the view
+    /// buffer region referenced by the view.
     Uint64 ByteOffset       DEFAULT_INITIALIZER(0);
 
-    /// Size in bytes of the referenced buffer region
+    /// Size in bytes of the referenced buffer region.
     Uint64 ByteWidth        DEFAULT_INITIALIZER(0);
 
 
@@ -164,7 +165,7 @@ DILIGENT_BEGIN_INTERFACE(IBufferView, IDeviceObject)
     /// Returns pointer to the referenced buffer object.
 
     /// The method does *NOT* increment the reference counter of the returned object,
-    /// so Release() must not be called.
+    /// so Release() **must not** be called.
     VIRTUAL struct IBuffer* METHOD(GetBuffer)(THIS) CONST PURE;
 };
 DILIGENT_END_INTERFACE
diff --git a/Graphics/GraphicsEngine/interface/Dearchiver.h b/Graphics/GraphicsEngine/interface/Dearchiver.h
@@ -1,5 +1,5 @@
 /*
- *  Copyright 2019-2023 Diligent Graphics LLC
+ *  Copyright 2019-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.
@@ -77,6 +77,7 @@ typedef struct ResourceSignatureUnpackInfo ResourceSignatureUnpackInfo;
 /// Pipeline state archive flags
 DILIGENT_TYPED_ENUM(PSO_ARCHIVE_FLAGS, Uint32)
 {
+    /// No flags are set
     PSO_ARCHIVE_FLAG_NONE = 0u,
 
     /// By default, shader reflection information will be preserved
@@ -101,6 +102,7 @@ DEFINE_FLAG_ENUM_OPERATORS(PSO_ARCHIVE_FLAGS)
 /// Pipeline state unpack flags
 DILIGENT_TYPED_ENUM(PSO_UNPACK_FLAGS, Uint32)
 {
+    /// No flags are set
     PSO_UNPACK_FLAG_NONE = 0u,
 
     /// Do not perform validation when unpacking the pipeline state.
@@ -149,26 +151,25 @@ struct PipelineStateUnpackInfo
     /// Optional PSO cache.
     IPipelineStateCache* pCache DEFAULT_INITIALIZER(nullptr);
 
-    /// An optional function to be called by the dearchiver to let the application modify
-    /// the pipeline state create info.
-    ///
-    /// \remarks    An application should check the pipeline type (PipelineCI.Desc.PipelineType) and cast
-    ///             the reference to the appropriate PSO create info struct, e.g. for PIPELINE_TYPE_GRAPHICS:
+    /// An optional function to be called by the dearchiver to let the application modify the pipeline state create info.
+    
+    /// An application should check the pipeline type (PipelineCI.Desc.PipelineType) and cast
+    /// the reference to the appropriate PSO create info struct, e.g. for PIPELINE_TYPE_GRAPHICS:
     ///
-    ///                 auto& GraphicsPipelineCI = static_cast<GraphicsPipelineStateCreateInfo>(PipelineCI);
+    ///     auto& GraphicsPipelineCI = static_cast<GraphicsPipelineStateCreateInfo>(PipelineCI);
     ///
-    ///             Modifying graphics pipeline states (e.g. rasterizer, depth-stencil, blend, render
-    ///             target formats, etc.) is the most expected usage of the callback.
+    /// Modifying graphics pipeline states (e.g. rasterizer, depth-stencil, blend, render
+    /// target formats, etc.) is the most expected usage of the callback.
     ///
-    ///             The following members of the structure must not be modified:
-    ///             - PipelineCI.PSODesc.PipelineType
-    ///             - PipelineCI.PSODesc.ResourceLayout
-    ///             - PipelineCI.ppResourceSignatures
-    ///             - PipelineCI.ResourceSignaturesCount
+    /// The following members of the structure must not be modified:
+    /// - `PipelineCI.PSODesc.PipelineType`
+    /// - `PipelineCI.PSODesc.ResourceLayout`
+    /// - `PipelineCI.ppResourceSignatures`
+    /// - `PipelineCI.ResourceSignaturesCount`
     ///
-    ///             An application may modify shader pointers (e.g. GraphicsPipelineCI.pVS), but it must
-    ///             ensure that the shader layout is compatible with the pipeline state, otherwise hard-to-debug
-    ///             errors will occur.
+    /// An application may modify shader pointers (e.g. GraphicsPipelineCI.pVS), but it must
+    /// ensure that the shader layout is compatible with the pipeline state, otherwise hard-to-debug
+    /// errors will occur.
     void (*ModifyPipelineStateCreateInfo)(PipelineStateCreateInfo REF PipelineCI, void* pUserData) DEFAULT_INITIALIZER(nullptr);
 
     /// A pointer to the user data to pass to the ModifyPipelineStateCreateInfo function.
@@ -266,7 +267,7 @@ DILIGENT_BEGIN_INTERFACE(IDearchiver, IObject)
     ///
     /// \note   Resource signatures used by the PSO will be unpacked from the same archive.
     ///
-    ///         This method is thread-safe.
+    /// \note   This method is thread-safe.
     VIRTUAL void METHOD(UnpackPipelineState)(THIS_
                                              const PipelineStateUnpackInfo REF UnpackInfo,
                                              IPipelineState**                  ppPSO) PURE;
diff --git a/Graphics/GraphicsEngine/src/BottomLevelASBase.cpp b/Graphics/GraphicsEngine/src/BottomLevelASBase.cpp
@@ -1,5 +1,5 @@
 /*
- *  Copyright 2019-2022 Diligent Graphics LLC
+ *  Copyright 2019-2025 Diligent Graphics LLC
  *  Copyright 2015-2019 Egor Yusov
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
@@ -58,7 +58,7 @@ void ValidateBottomLevelASDesc(const BottomLevelASDesc& Desc) noexcept(false)
 
         for (Uint32 i = 0; i < Desc.TriangleCount; ++i)
         {
-            const auto& tri = Desc.pTriangles[i];
+            const BLASTriangleDesc& tri = Desc.pTriangles[i];
 
             if (tri.GeometryName == nullptr)
                 LOG_BLAS_ERROR_AND_THROW("pTriangles[", i, "].GeometryName must not be null.");
@@ -92,7 +92,7 @@ void ValidateBottomLevelASDesc(const BottomLevelASDesc& Desc) noexcept(false)
 
         for (Uint32 i = 0; i < Desc.BoxCount; ++i)
         {
-            const auto& box = Desc.pBoxes[i];
+            const BLASBoundingBoxDesc& box = Desc.pBoxes[i];
 
             if (box.GeometryName == nullptr)
                 LOG_BLAS_ERROR_AND_THROW("pBoxes[", i, "].GeometryName must not be null.");
@@ -120,12 +120,12 @@ void CopyBLASGeometryDesc(const BottomLevelASDesc& SrcDesc,
 
         MemPool.Reserve();
 
-        auto* pTriangles = MemPool.CopyArray(SrcDesc.pTriangles, SrcDesc.TriangleCount);
+        BLASTriangleDesc* pTriangles = MemPool.CopyArray(SrcDesc.pTriangles, SrcDesc.TriangleCount);
 
         // Copy strings
         for (Uint32 i = 0; i < SrcDesc.TriangleCount; ++i)
         {
-            const auto* GeoName        = MemPool.CopyString(SrcDesc.pTriangles[i].GeometryName);
+            const char* GeoName        = MemPool.CopyString(SrcDesc.pTriangles[i].GeometryName);
             pTriangles[i].GeometryName = GeoName;
 
             Uint32 ActualIndex = INVALID_INDEX;
@@ -155,12 +155,12 @@ void CopyBLASGeometryDesc(const BottomLevelASDesc& SrcDesc,
 
         MemPool.Reserve();
 
-        auto* pBoxes = MemPool.CopyArray(SrcDesc.pBoxes, SrcDesc.BoxCount);
+        BLASBoundingBoxDesc* pBoxes = MemPool.CopyArray(SrcDesc.pBoxes, SrcDesc.BoxCount);
 
         // Copy strings
         for (Uint32 i = 0; i < SrcDesc.BoxCount; ++i)
         {
-            const auto* GeoName    = MemPool.CopyString(SrcDesc.pBoxes[i].GeometryName);
+            const char* GeoName    = MemPool.CopyString(SrcDesc.pBoxes[i].GeometryName);
             pBoxes[i].GeometryName = GeoName;
 
             Uint32 ActualIndex = INVALID_INDEX;
diff --git a/Graphics/GraphicsEngine/src/BufferBase.cpp b/Graphics/GraphicsEngine/src/BufferBase.cpp
@@ -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");
@@ -45,8 +45,8 @@ namespace Diligent
 
 void ValidateBufferDesc(const BufferDesc& Desc, const IRenderDevice* pDevice) noexcept(false)
 {
-    const auto& MemoryInfo = pDevice->GetAdapterInfo().Memory;
-    const auto& Features   = pDevice->GetDeviceInfo().Features;
+    const AdapterMemoryInfo& MemoryInfo = pDevice->GetAdapterInfo().Memory;
+    const DeviceFeatures&    Features   = pDevice->GetDeviceInfo().Features;
 
     static_assert(BIND_FLAG_LAST == 0x800L, "Please update this function to handle the new bind flags");
 
@@ -128,7 +128,7 @@ void ValidateBufferDesc(const BufferDesc& Desc, const IRenderDevice* pDevice) no
 
         case USAGE_SPARSE:
         {
-            const auto& SparseRes = pDevice->GetAdapterInfo().SparseResources;
+            const SparseResourceProperties& SparseRes = pDevice->GetAdapterInfo().SparseResources;
             VERIFY_BUFFER(Features.SparseResources, "sparse buffer requires SparseResources feature");
             VERIFY_BUFFER(Desc.CPUAccessFlags == CPU_ACCESS_NONE, "sparse buffers can't have any CPU access flags set.");
             VERIFY_BUFFER(Desc.Size <= SparseRes.ResourceSpaceSize, "sparse buffer size (", Desc.Size, ") must not exceed the ResourceSpaceSize (", SparseRes.ResourceSpaceSize, ")");
@@ -196,7 +196,7 @@ void ValidateBufferInitData(const BufferDesc& Desc, const BufferData* pBuffData)
 
     if (pBuffData != nullptr && pBuffData->pContext != nullptr)
     {
-        const auto& CtxDesc = pBuffData->pContext->GetDesc();
+        const DeviceContextDesc& CtxDesc = pBuffData->pContext->GetDesc();
         if (CtxDesc.IsDeferred)
             LOG_BUFFER_ERROR_AND_THROW("Deferred contexts can't be used to initialize resources");
         if ((Desc.ImmediateContextMask & (Uint64{1} << CtxDesc.ContextId)) == 0)
@@ -251,7 +251,7 @@ void ValidateAndCorrectBufferViewDesc(const BufferDesc& BuffDesc,
                 LOG_ERROR_AND_THROW("Incorrect number of components (", Uint32{ViewDesc.Format.NumComponents}, "). 1, 2, 3, or 4 are allowed values");
             if (ViewDesc.Format.ValueType == VT_FLOAT32 || ViewDesc.Format.ValueType == VT_FLOAT16)
                 ViewDesc.Format.IsNormalized = false;
-            auto ViewElementStride = GetValueSize(ViewDesc.Format.ValueType) * Uint32{ViewDesc.Format.NumComponents};
+            Uint32 ViewElementStride = GetValueSize(ViewDesc.Format.ValueType) * Uint32{ViewDesc.Format.NumComponents};
             if (BuffDesc.Mode == BUFFER_MODE_RAW && BuffDesc.ElementByteStride == 0)
                 LOG_ERROR_AND_THROW("To enable formatted views of a raw buffer, element byte must be specified during buffer initialization");
             if (ViewElementStride != BuffDesc.ElementByteStride)
diff --git a/Graphics/GraphicsEngine/src/DearchiverBase.cpp b/Graphics/GraphicsEngine/src/DearchiverBase.cpp
