From 3fdb48d2425720d2367919518e826a305222d7a2 Mon Sep 17 00:00:00 2001
From: Tobias Frisch <tfrisch@uni-koblenz.de>
Date: Mon, 25 Apr 2022 15:44:21 +0200
Subject: [PATCH] Adjusted some doxygen comments in features, file and handles
Signed-off-by: Tobias Frisch <tfrisch@uni-koblenz.de>
---
include/vkcv/FeatureManager.hpp | 49 +++++++++++++++++++++++++++++++++
include/vkcv/Features.hpp | 16 +++++++++++
include/vkcv/File.hpp | 6 ++--
include/vkcv/Handles.hpp | 37 +++++++++++++++++++++++--
4 files changed, 104 insertions(+), 4 deletions(-)
diff --git a/include/vkcv/FeatureManager.hpp b/include/vkcv/FeatureManager.hpp
index 0e7fb2a5..de71292b 100644
--- a/include/vkcv/FeatureManager.hpp
+++ b/include/vkcv/FeatureManager.hpp
@@ -46,6 +46,7 @@ namespace vkcv {
/**
* @brief Checks support of the @p vk::PhysicalDeviceFeatures.
+ *
* @param features The features
* @param required True, if the @p features are required, else false
* @return @p True, if the @p features are supported, else @p false
@@ -55,6 +56,7 @@ namespace vkcv {
/**
* @brief Checks support of the @p vk::PhysicalDevice16BitStorageFeatures.
+ *
* @param features The features
* @param required True, if the @p features are required, else false
* @return @p True, if the @p features are supported, else @p false
@@ -64,6 +66,7 @@ namespace vkcv {
/**
* @brief Checks support of the @p vk::PhysicalDevice8BitStorageFeatures.
+ *
* @param features The features
* @param required True, if the @p features are required, else false
* @return @p True, if the @p features are supported, else @p false
@@ -73,6 +76,7 @@ namespace vkcv {
/**
* @brief Checks support of the @p vk::PhysicalDeviceBufferDeviceAddressFeatures.
+ *
* @param features The features
* @param required True, if the @p features are required, else false
* @return @p True, if the @p features are supported, else @p false
@@ -82,6 +86,7 @@ namespace vkcv {
/**
* @brief Checks support of the @p vk::PhysicalDeviceDescriptorIndexingFeatures.
+ *
* @param features The features
* @param required True, if the @p features are required, else false
* @return @p True, if the @p features are supported, else @p false
@@ -91,6 +96,7 @@ namespace vkcv {
/**
* @brief Checks support of the @p vk::PhysicalDeviceHostQueryResetFeatures.
+ *
* @param features The features
* @param required True, if the @p features are required, else false
* @return @p True, if the @p features are supported, else @p false
@@ -100,6 +106,7 @@ namespace vkcv {
/**
* @brief Checks support of the @p vk::PhysicalDeviceImagelessFramebufferFeatures.
+ *
* @param features The features
* @param required True, if the @p features are required, else false
* @return @p True, if the @p features are supported, else @p false
@@ -109,6 +116,7 @@ namespace vkcv {
/**
* @brief Checks support of the @p vk::PhysicalDeviceMultiviewFeatures.
+ *
* @param features The features
* @param required True, if the @p features are required, else false
* @return @p True, if the @p features are supported, else @p false
@@ -118,6 +126,7 @@ namespace vkcv {
/**
* @brief Checks support of the @p vk::PhysicalDeviceProtectedMemoryFeatures.
+ *
* @param features The features
* @param required True, if the @p features are required, else false
* @return @p True, if the @p features are supported, else @p false
@@ -127,6 +136,7 @@ namespace vkcv {
/**
* @brief Checks support of the @p vk::PhysicalDeviceSamplerYcbcrConversionFeatures.
+ *
* @param features The features
* @param required True, if the @p features are required, else false
* @return @p True, if the @p features are supported, else @p false
@@ -136,6 +146,7 @@ namespace vkcv {
/**
* @brief Checks support of the @p vk::PhysicalDeviceScalarBlockLayoutFeatures.
+ *
* @param features The features
* @param required True, if the @p features are required, else false
* @return @p True, if the @p features are supported, else @p false
@@ -145,6 +156,7 @@ namespace vkcv {
/**
* @brief Checks support of the @p vk::PhysicalDeviceSeparateDepthStencilLayoutsFeatures.
+ *
* @param features The features
* @param required True, if the @p features are required, else false
* @return @p True, if the @p features are supported, else @p false
@@ -154,6 +166,7 @@ namespace vkcv {
/**
* @brief Checks support of the @p vk::PhysicalDeviceShaderAtomicInt64Features.
+ *
* @param features The features
* @param required True, if the @p features are required, else false
* @return @p True, if the @p features are supported, else @p false
@@ -163,6 +176,7 @@ namespace vkcv {
/**
* @brief Checks support of the @p vk::PhysicalDeviceShaderFloat16Int8Features.
+ *
* @param features The features
* @param required True, if the @p features are required, else false
* @return @p True, if the @p features are supported, else @p false
@@ -172,6 +186,7 @@ namespace vkcv {
/**
* @brief Checks support of the @p vk::PhysicalDeviceShaderSubgroupExtendedTypesFeatures.
+ *
* @param features The features
* @param required True, if the @p features are required, else false
* @return @p True, if the @p features are supported, else @p false
@@ -181,6 +196,7 @@ namespace vkcv {
/**
* @brief Checks support of the @p vk::PhysicalDeviceTimelineSemaphoreFeatures.
+ *
* @param features The features
* @param required True, if the @p features are required, else false
* @return @p True, if the @p features are supported, else @p false
@@ -190,6 +206,7 @@ namespace vkcv {
/**
* @brief Checks support of the @p vk::PhysicalDeviceUniformBufferStandardLayoutFeatures.
+ *
* @param features The features
* @param required True, if the @p features are required, else false
* @return @p True, if the @p features are supported, else @p false
@@ -199,6 +216,7 @@ namespace vkcv {
/**
* @brief Checks support of the @p vk::PhysicalDeviceVariablePointersFeatures.
+ *
* @param features The features
* @param required True, if the @p features are required, else false
* @return @p True, if the @p features are supported, else @p false
@@ -208,6 +226,7 @@ namespace vkcv {
/**
* @brief Checks support of the @p vk::PhysicalDeviceVulkanMemoryModelFeatures.
+ *
* @param features The features
* @param required True, if the @p features are required, else false
* @return @p True, if the @p features are supported, else @p false
@@ -217,6 +236,7 @@ namespace vkcv {
/**
* @brief Checks support of the @p vk::PhysicalDeviceMeshShaderFeaturesNV.
+ *
* @param features The features
* @param required True, if the @p features are required, else false
* @return @p True, if the @p features are supported, else @p false
@@ -224,14 +244,29 @@ namespace vkcv {
[[nodiscard]]
bool checkSupport(const vk::PhysicalDeviceMeshShaderFeaturesNV& features, bool required) const;
+ /**
+ * @brief Checks support of the @p vk::PhysicalDeviceShaderAtomicFloatFeaturesEXT.
+ *
+ * @param features The features
+ * @param required True, if the @p features are required, else false
+ * @return @p True, if the @p features are supported, else @p false
+ */
[[nodiscard]]
bool checkSupport(const vk::PhysicalDeviceShaderAtomicFloatFeaturesEXT& features, bool required) const;
+ /**
+ * @brief Checks support of the @p vk::PhysicalDeviceShaderAtomicFloat2FeaturesEXT.
+ *
+ * @param features The features
+ * @param required True, if the @p features are required, else false
+ * @return @p True, if the @p features are supported, else @p false
+ */
[[nodiscard]]
bool checkSupport(const vk::PhysicalDeviceShaderAtomicFloat2FeaturesEXT& features, bool required) const;
/**
* @brief Checks support of the @p vk::PhysicalDeviceVulkan12Features.
+ *
* @param features The features
* @param required True, if the @p features are required, else false
* @return @p True, if the @p features are supported, else @p false
@@ -241,6 +276,7 @@ namespace vkcv {
/**
* @brief Checks support of the @p vk::PhysicalDeviceVulkan11Features.
+ *
* @param features The features
* @param required True, if the @p features are required, else false
* @return @p True, if the @p features are supported, else @p false
@@ -250,6 +286,7 @@ namespace vkcv {
/**
* @brief Checks support of the @p vk::PhysicalDeviceAccelerationStructureFeaturesKHR.
+ *
* @param features The features
* @param required True, if the @p features are required, else false
* @return @p True, if the @p features are supported, else @p false
@@ -259,6 +296,7 @@ namespace vkcv {
/**
* @brief Checks support of the @p vk::PhysicalDeviceRayTracingPipelineFeaturesKHR.
+ *
* @param features The features
* @param required True, if the @p features are required, else false
* @return @p True, if the @p features are supported, else @p false
@@ -268,6 +306,7 @@ namespace vkcv {
/**
* @brief Searches for a base structure of a given structure type.
+ *
* @param type Structure type
* @return Pointer to first matching base structure or nullptr
*/
@@ -277,6 +316,7 @@ namespace vkcv {
public:
/**
* @brief Constructor of a feature manager with a given physical device.
+ *
* @param physicalDevice Physical device
*/
explicit FeatureManager(vk::PhysicalDevice& physicalDevice);
@@ -285,6 +325,7 @@ namespace vkcv {
/**
* @brief Move-constructor of a feature manager.
+ *
* @param other Other feature manager instance
*/
FeatureManager(FeatureManager&& other) noexcept;
@@ -298,6 +339,7 @@ namespace vkcv {
/**
* @brief Move-operator of a feature manager.
+ *
* @param other Other feature manager instance
* @return Reference to the feature manager itself
*/
@@ -305,6 +347,7 @@ namespace vkcv {
/**
* @brief Check if a specific extension is supported by the managers physical device.
+ *
* @param extension Extension identifier string
* @return @p True, if the @p extension is supported, else @p false
*/
@@ -313,6 +356,7 @@ namespace vkcv {
/**
* @brief Activate a specific extension if supported by the managers physical device.
+ *
* @param extension Extension identifier string
* @param required True, if the @p extension is required, else false
* @return @p True, if the @p extension could be activated, else @p false
@@ -321,6 +365,7 @@ namespace vkcv {
/**
* @brief Check if a specific extension is activated by the manager.
+ *
* @param extension Extension identifier string
* @return @p True, if the @p extension is activated, else @p false
*/
@@ -329,6 +374,7 @@ namespace vkcv {
/**
* @brief Return list of activated extensions for usage.
+ *
* @return List of activated extensions
*/
[[nodiscard]]
@@ -336,6 +382,7 @@ namespace vkcv {
/**
* @brief Request specific features for optional or required usage ( only core Vulkan 1.0 ).
+ *
* @param featureFunction Function or lambda to request specific features
* @param required True, if the @p features are required, else false
* @return @p True, if the requested features could be activated, else @p false
@@ -344,6 +391,7 @@ namespace vkcv {
/**
* @brief Request specific features for optional or required usage.
+ *
* @tparam T Template parameter to use specific base structure types
* @param featureFunction Function or lambda to request specific features
* @param required True, if the @p features are required, else false
@@ -393,6 +441,7 @@ namespace vkcv {
/**
* @brief Return feature structure chain to request activated features.
+ *
* @return Head of feature structure chain
*/
[[nodiscard]]
diff --git a/include/vkcv/Features.hpp b/include/vkcv/Features.hpp
index 2e841aa6..0fe03ca4 100644
--- a/include/vkcv/Features.hpp
+++ b/include/vkcv/Features.hpp
@@ -36,18 +36,21 @@ namespace vkcv {
/**
* @brief Constructor of a features instance with a given list of extension identifier strings.
+ *
* @param list List of extension identifier strings
*/
Features(const std::initializer_list<std::string>& list);
/**
* @brief Copy-constructor of a features instance.
+ *
* @param other Other features instance
*/
Features(const Features& other) = default;
/**
* @brief Move-constructor of a features instance.
+ *
* @param other Other features instance
*/
Features(Features&& other) = default;
@@ -59,6 +62,7 @@ namespace vkcv {
/**
* @brief Copy-operator of a features instance.
+ *
* @param other Other features instance
* @return Reference to the features instance itself
*/
@@ -66,6 +70,7 @@ namespace vkcv {
/**
* @brief Move-operator of a features instance.
+ *
* @param other Other features instance
* @return Reference to the features instance itself
*/
@@ -73,12 +78,14 @@ namespace vkcv {
/**
* @brief Request a specific extension as required.
+ *
* @param extension Extension identifier string
*/
void requireExtension(const std::string& extension);
/**
* @brief Request a specific extension and some of its features as required ( only core Vulkan 1.0 ).
+ *
* @param extension Extension identifier string
* @param featureFunction
*/
@@ -87,6 +94,7 @@ namespace vkcv {
/**
* @brief Request a specific extension and some of its features as required.
+ *
* @tparam T Template parameter to use specific base structure types
* @param extension Extension identifier string
* @param featureFunction Function or lambda to request specific features
@@ -104,12 +112,14 @@ namespace vkcv {
/**
* @brief Request a specific set of features as required ( only core Vulkan 1.0 ).
+ *
* @param featureFunction Function or lambda to request specific features
*/
void requireFeature(const std::function<void(vk::PhysicalDeviceFeatures&)>& featureFunction);
/**
* @brief Request a specific set of features as required.
+ *
* @tparam T Template parameter to use specific base structure types
* @param featureFunction Function or lambda to request specific features
*/
@@ -122,12 +132,14 @@ namespace vkcv {
/**
* @brief Request a specific extension as optional.
+ *
* @param extension Extension identifier string
*/
void tryExtension(const std::string& extension);
/**
* @brief Request a specific extension and some of its features as optional ( only core Vulkan 1.0 ).
+ *
* @param extension Extension identifier string
* @param featureFunction Function or lambda to request specific features
*/
@@ -136,6 +148,7 @@ namespace vkcv {
/**
* @brief Request a specific extension and some of its features as optional.
+ *
* @tparam T Template parameter to use specific base structure types
* @param extension Extension identifier string
* @param featureFunction Function or lambda to request specific features
@@ -153,12 +166,14 @@ namespace vkcv {
/**
* @brief Request a specific set of features as optional ( only core Vulkan 1.0 ).
+ *
* @param featureFunction Function or lambda to request specific features
*/
void tryFeature(const std::function<void(vk::PhysicalDeviceFeatures&)>& featureFunction);
/**
* @brief Request a specific set of features as optional.
+ *
* @tparam T Template parameter to use specific base structure types
* @param featureFunction Function or lambda to request specific features
*/
@@ -171,6 +186,7 @@ namespace vkcv {
/**
* @brief Return list of feature requests.
+ *
* @return List of feature requests
*/
[[nodiscard]]
diff --git a/include/vkcv/File.hpp b/include/vkcv/File.hpp
index dc41b169..4d81f368 100644
--- a/include/vkcv/File.hpp
+++ b/include/vkcv/File.hpp
@@ -10,13 +10,15 @@
namespace vkcv {
/**
- * Generate a new temporary file path and return it.
+ * @brief Generate a new temporary file path and return it.
+ *
* @return A unique path for a temporary file
*/
std::filesystem::path generateTemporaryFilePath();
/**
- * Generate a new temporary directory path and return it.
+ * @brief Generate a new temporary directory path and return it.
+ *
* @return A unique path for a temporary directory
*/
std::filesystem::path generateTemporaryDirectoryPath();
diff --git a/include/vkcv/Handles.hpp b/include/vkcv/Handles.hpp
index 40383aea..42b13679 100644
--- a/include/vkcv/Handles.hpp
+++ b/include/vkcv/Handles.hpp
@@ -24,12 +24,22 @@ namespace vkcv
HandleDestroyFunction m_destroy;
protected:
+ /**
+ * @brief Constructor of an invalid handle
+ */
Handle();
+ /**
+ * @brief Constructor of a valid handle with an
+ * unique id and an optional destroy callback.
+ *
+ * @param id Unique handle id
+ * @param destroy Destroy callback (optional)
+ */
explicit Handle(uint64_t id, const HandleDestroyFunction& destroy = nullptr);
/**
- * Returns the actual handle id of a handle.
+ * @brief Returns the actual handle id of a handle.
*
* @return Handle id
*/
@@ -37,7 +47,7 @@ namespace vkcv
uint64_t getId() const;
/**
- * Returns the reference counter of a handle
+ * @brief Returns the reference counter of a handle
*
* @return Reference counter
*/
@@ -53,7 +63,18 @@ namespace vkcv
Handle& operator=(const Handle& other);
Handle& operator=(Handle&& other) noexcept;
+ /**
+ * @brief Returns whether a handle is valid to use.
+ *
+ * @return True, if the handle is valid, else false.
+ */
explicit operator bool() const;
+
+ /**
+ * @brief Returns whether a handle is invalid to use.
+ *
+ * @return True, if the handle is invalid, else false.
+ */
bool operator!() const;
};
@@ -108,9 +129,21 @@ namespace vkcv
private:
using Handle::Handle;
public:
+ /**
+ * @brief Returns whether the handle represents an swapchain image.
+ *
+ * @return True, if the handle represents a swapchain image, else false.
+ */
[[nodiscard]]
bool isSwapchainImage() const;
+ /**
+ * @brief Creates a valid image handle to represent a swapchain image
+ * using an optional destroy callback.
+ *
+ * @param destroy Destroy callback (optional)
+ * @return New swapchain image handle
+ */
static ImageHandle createSwapchainImageHandle(const HandleDestroyFunction& destroy = nullptr);
};
--
GitLab