From 5c5e8a97ede0f4e64aebec64d79c8b73f4a36d64 Mon Sep 17 00:00:00 2001
From: Tobias Frisch <tfrisch@uni-koblenz.de>
Date: Tue, 14 Sep 2021 17:39:52 +0200
Subject: [PATCH] [#96] Added doxygen comments to upscaling and material
Signed-off-by: Tobias Frisch <tfrisch@uni-koblenz.de>
---
.../include/vkcv/material/Material.hpp | 107 ++++++++++++++++--
.../vkcv/upscaling/BilinearUpscaling.hpp | 21 +++-
.../include/vkcv/upscaling/FSRUpscaling.hpp | 87 ++++++++++++--
.../include/vkcv/upscaling/Upscaling.hpp | 24 +++-
4 files changed, 216 insertions(+), 23 deletions(-)
diff --git a/modules/material/include/vkcv/material/Material.hpp b/modules/material/include/vkcv/material/Material.hpp
index f03bd13f..81a48608 100644
--- a/modules/material/include/vkcv/material/Material.hpp
+++ b/modules/material/include/vkcv/material/Material.hpp
@@ -17,8 +17,14 @@ namespace vkcv::material {
* Enum to handle standardized material types.
*/
enum class MaterialType {
+ /**
+ * The material can be used for physically based rendering.
+ */
PBR_MATERIAL = 1,
-
+
+ /**
+ * The type is unknown.
+ */
UNKNOWN = 0
};
@@ -28,18 +34,51 @@ namespace vkcv::material {
*/
class Material {
private:
+
+ /**
+ * A nested structure for textures used by a material.
+ */
struct Texture {
+ /**
+ * The image handle of a texture.
+ */
ImageHandle m_Image;
+
+ /**
+ * The sampler handle of a texture.
+ */
SamplerHandle m_Sampler;
+
+ /**
+ * The list of custom factors for a given texture.
+ */
std::vector<float> m_Factors;
};
-
+
+ /**
+ * The type of a material.
+ */
MaterialType m_Type;
+
+ /**
+ * The descriptor set handle of a material.
+ */
DescriptorSetHandle m_DescriptorSet;
+
+ /**
+ * The descriptor set layout used by a material.
+ */
DescriptorSetLayoutHandle m_DescriptorSetLayout;
+
+ /**
+ * The list of textures used by a material.
+ */
std::vector<Texture> m_Textures;
public:
+ /**
+ * Default constructor to create an invalid material instance.
+ */
Material();
~Material() = default;
@@ -48,22 +87,72 @@ namespace vkcv::material {
Material& operator=(const Material& other) = default;
Material& operator=(Material&& other) = default;
-
+
+ /**
+ * Returns the type of a material as MaterialType.
+ * @return Type of material
+ */
[[nodiscard]]
MaterialType getType() const;
-
+
+ /**
+ * Returns the descriptor set handle of the material.
+ * @return Descriptor set handle
+ */
[[nodiscard]]
const DescriptorSetHandle& getDescriptorSet() const;
+ /**
+ * Returns the descriptor set layout handle used by the material.
+ * @return Descriptor set layout handle
+ */
[[nodiscard]]
const DescriptorSetLayoutHandle& getDescriptorSetLayout() const;
-
+
+ /**
+ * Checks if the material is valid and returns the status
+ * as boolean value.
+ * @return true if the material is valid, otherwise false
+ */
explicit operator bool() const;
-
+
+ /**
+ * Checks if the material is invalid and returns the status
+ * as boolean value.
+ * @return true if the material is invalid, otherwise false
+ */
bool operator!() const;
-
- static const std::unordered_map<uint32_t ,DescriptorBinding>& getDescriptorBindings(MaterialType type);
-
+
+ /**
+ * Returns the descriptor bindings required by a given material
+ * type to create the descriptor set layout.
+ * @param[in] type Type of material
+ * @return Descriptor bindings of a material type
+ */
+ static const DescriptorBindings& getDescriptorBindings(MaterialType type);
+
+ /**
+ * Creates a new valid material which supports physically based
+ * rendering.
+ * @param[in,out] core Reference to Core instance
+ * @param[in] colorImg Base color image handle
+ * @param[in] colorSmp Base color sampler handle
+ * @param[in] normalImg Normal map image handle
+ * @param[in] normalSmp Normal map sampler handle
+ * @param[in] metRoughImg Metallic and roughness image handle
+ * @param[in] metRoughSmp Metallic and roughness sampler handle
+ * @param[in] occlusionImg Occlusion map image handle
+ * @param[in] occlusionSmp Occlusion map sampler handle
+ * @param[in] emissiveImg Emissive image handle
+ * @param[in] emissiveSmp Emissive sampler handle
+ * @param[in] baseColorFactor 4D vector of base color factors
+ * @param[in] metallicFactor Metallic factor
+ * @param[in] roughnessFactor Roughness factor
+ * @param[in] normalScale Scale of normal map
+ * @param[in] occlusionStrength Strength of occlusion
+ * @param[in] emissiveFactor 3D vector of emmisive factors
+ * @return New material instance
+ */
static Material createPBR(Core &core,
const ImageHandle &colorImg,
const SamplerHandle &colorSmp,
diff --git a/modules/upscaling/include/vkcv/upscaling/BilinearUpscaling.hpp b/modules/upscaling/include/vkcv/upscaling/BilinearUpscaling.hpp
index 08ef6c8c..52569467 100644
--- a/modules/upscaling/include/vkcv/upscaling/BilinearUpscaling.hpp
+++ b/modules/upscaling/include/vkcv/upscaling/BilinearUpscaling.hpp
@@ -8,12 +8,27 @@ namespace vkcv::upscaling {
* @addtogroup vkcv_upscaling
* @{
*/
-
+
+ /**
+ * A class to handle upscaling via bilinear interpolation.
+ */
class BilinearUpscaling : public Upscaling {
private:
public:
- BilinearUpscaling(Core& core);
-
+ /**
+ * Constructor to create instance for bilinear upscaling.
+ * @param[in,out] core Reference to a Core instance
+ */
+ explicit BilinearUpscaling(Core& core);
+
+ /**
+ * Record the comands of the bilinear upscaling instance to
+ * scale the image of the input handle to the resolution of
+ * the output image handle via bilinear interpolation.
+ * @param[in] cmdStream Command stream handle to record commands
+ * @param[in] input Input image handle
+ * @param[in] output Output image handle
+ */
void recordUpscaling(const CommandStreamHandle& cmdStream,
const ImageHandle& input,
const ImageHandle& output) override;
diff --git a/modules/upscaling/include/vkcv/upscaling/FSRUpscaling.hpp b/modules/upscaling/include/vkcv/upscaling/FSRUpscaling.hpp
index 56cc9741..2137249a 100644
--- a/modules/upscaling/include/vkcv/upscaling/FSRUpscaling.hpp
+++ b/modules/upscaling/include/vkcv/upscaling/FSRUpscaling.hpp
@@ -35,22 +35,63 @@ namespace vkcv::upscaling {
class FSRUpscaling : public Upscaling {
private:
-
+ /**
+ * The EASU compute pipeline of the FSR upscaling.
+ */
ComputePipelineHandle m_easuPipeline;
+
+ /**
+ * The RCAS compute pipeline of the FSR upscaling.
+ */
ComputePipelineHandle m_rcasPipeline;
+ /**
+ * The descriptor set layout of the EASU pipeline.
+ */
DescriptorSetLayoutHandle m_easuDescriptorSetLayout;
+ /**
+ * The descriptor set for the EASU pipeline.
+ */
DescriptorSetHandle m_easuDescriptorSet;
+ /**
+ * The descriptor set layout of the RCAS pipeline.
+ */
DescriptorSetLayoutHandle m_rcasDescriptorSetLayout;
+
+ /**
+ * The descriptor set for the RCAS pipeline.
+ */
DescriptorSetHandle m_rcasDescriptorSet;
-
+
+ /**
+ * The buffer template to handle FSR constants for
+ * the EASU pipeline.
+ */
Buffer<FSRConstants> m_easuConstants;
+
+ /**
+ * The buffer template to handle FSR constants for
+ * the RCAS pipeline.
+ */
Buffer<FSRConstants> m_rcasConstants;
+
+ /**
+ * The image handle to store the intermidiate state of
+ * the FSR upscaling.
+ */
ImageHandle m_intermediateImage;
+
+ /**
+ * The sampler handle to use for accessing the images
+ * in the FSR upscaling process.
+ */
SamplerHandle m_sampler;
-
+
+ /**
+ * Current state of HDR support.
+ */
bool m_hdr;
/**
@@ -67,20 +108,50 @@ namespace vkcv::upscaling {
float m_sharpness;
public:
+ /**
+ * Constructor to create instance for FSR upscaling.
+ * @param[in,out] core Reference to a Core instance
+ */
explicit FSRUpscaling(Core& core);
-
+
+ /**
+ * Record the comands of the FSR upscaling instance to
+ * scale the image of the input handle to the resolution of
+ * the output image handle via FidelityFX Super Resolution.
+ * @param[in] cmdStream Command stream handle to record commands
+ * @param[in] input Input image handle
+ * @param[in] output Output image handle
+ */
void recordUpscaling(const CommandStreamHandle& cmdStream,
const ImageHandle& input,
const ImageHandle& output) override;
-
+
+ /**
+ * Checks if HDR support is enabled and returns the status as boolean.
+ * @return true if HDR is supported, otherwise false
+ */
[[nodiscard]]
bool isHdrEnabled() const;
-
+
+ /**
+ * Changes the status of HDR support of the FSR upscaling instance.
+ * @param[in] enabled New status of HDR support
+ */
void setHdrEnabled(bool enabled);
-
+
+ /**
+ * Returns the amount of sharpness the FSR upscaling instance is using.
+ * @return The amount of sharpness
+ */
[[nodiscard]]
float getSharpness() const;
-
+
+ /**
+ * Changes the amount of sharpness of the FSR upscaling instance.
+ * The new sharpness value is restricted by 0.0f as lower and 1.0f
+ * as upper boundary.
+ * @param[in] sharpness New sharpness value
+ */
void setSharpness(float sharpness);
};
diff --git a/modules/upscaling/include/vkcv/upscaling/Upscaling.hpp b/modules/upscaling/include/vkcv/upscaling/Upscaling.hpp
index acc33c8e..12ba21a8 100644
--- a/modules/upscaling/include/vkcv/upscaling/Upscaling.hpp
+++ b/modules/upscaling/include/vkcv/upscaling/Upscaling.hpp
@@ -10,16 +10,34 @@ namespace vkcv::upscaling {
* A module to upscale an image from an internal resolution to a final resolution in realtime.
* @{
*/
-
+
+ /**
+ * An abstract class to handle upscaling of images in realtime.
+ */
class Upscaling {
protected:
+ /**
+ * Reference to the current Core instance.
+ */
Core& m_core;
public:
- Upscaling(Core& core);
+ /**
+ * Constructor to create an upscaling instance.
+ * @param[in,out] core Reference to a Core instance
+ */
+ explicit Upscaling(Core& core);
~Upscaling() = default;
-
+
+ /**
+ * Record the comands of the given upscaling instance to
+ * scale the image of the input handle to the resolution of
+ * the output image handle.
+ * @param[in] cmdStream Command stream handle to record commands
+ * @param[in] input Input image handle
+ * @param[in] output Output image handle
+ */
virtual void recordUpscaling(const CommandStreamHandle& cmdStream,
const ImageHandle& input,
const ImageHandle& output) = 0;
--
GitLab