From 48639293a17046b655c57e4628f216801cfa8e4e Mon Sep 17 00:00:00 2001
From: Tobias Frisch <tfrisch@uni-koblenz.de>
Date: Mon, 29 Aug 2022 19:43:59 +0200
Subject: [PATCH] Adjusted doxygen to get rid of internal code in docs and
added remaining new classes
Signed-off-by: Tobias Frisch <tfrisch@uni-koblenz.de>
---
Doxyfile | 3 +-
include/vkcv/DispatchSize.hpp | 63 +++++++++++++++++++++++++++
include/vkcv/ShaderStage.hpp | 6 +++
include/vkcv/TypeGuard.hpp | 80 ++++++++++++++++++++++++++++++++++-
src/vkcv/TypeGuard.cpp | 16 -------
5 files changed, 148 insertions(+), 20 deletions(-)
diff --git a/Doxyfile b/Doxyfile
index 706626db..a7c5c76b 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -874,8 +874,7 @@ WARN_LOGFILE =
# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
# Note: If this tag is empty the current directory is searched.
-INPUT = src \
- include \
+INPUT = include \
modules
# This tag can be used to specify the character encoding of the source files
diff --git a/include/vkcv/DispatchSize.hpp b/include/vkcv/DispatchSize.hpp
index 66878260..39f11950 100644
--- a/include/vkcv/DispatchSize.hpp
+++ b/include/vkcv/DispatchSize.hpp
@@ -10,13 +10,30 @@
namespace vkcv {
+ /**
+ * @brief Class representing a dispatch size to invoke a compute pipeline with.
+ */
class DispatchSize final {
private:
std::array<uint32_t, 3> m_Dispatch;
public:
+ /**
+ * Implicit constructor to convert an unsigned integer to a
+ * one dimensional dispatch size.
+ *
+ * @param[in] count Count of invocations
+ */
DispatchSize(uint32_t count);
+ /**
+ * Explicit constructor to create a dispatch size with two or
+ * three dimensions setting each value specifically.
+ *
+ * @param[in] dimensionX Size of X dimension
+ * @param[in] dimentionY Size of Y dimension
+ * @param[in] dimensionZ Size of Z dimension (optional)
+ */
DispatchSize(uint32_t dimensionX, uint32_t dimentionY, uint32_t dimensionZ = 1);
DispatchSize(const DispatchSize& other) = default;
@@ -27,25 +44,71 @@ namespace vkcv {
DispatchSize& operator=(const DispatchSize& other) = default;
DispatchSize& operator=(DispatchSize&& other) = default;
+ /**
+ * Returns the raw data of the dispatch size as readonly unsigned
+ * integer pointer.
+ *
+ * @return Pointer to data
+ */
[[nodiscard]]
const uint32_t* data() const;
+ /**
+ * Returns the size value of the dispatch size by a given index.
+ *
+ * @param[in] index Size index
+ * @return Size value by index
+ */
[[nodiscard]]
uint32_t operator[](size_t index) const;
+ /**
+ * Returns the value for the X dimension of the dispatch size.
+ *
+ * @return Size of X dimension
+ */
[[nodiscard]]
uint32_t x() const;
+ /**
+ * Returns the value for the Y dimension of the dispatch size.
+ *
+ * @return Size of Y dimension
+ */
[[nodiscard]]
uint32_t y() const;
+ /**
+ * Returns the value for the Z dimension of the dispatch size.
+ *
+ * @return Size of Z dimension
+ */
[[nodiscard]]
uint32_t z() const;
+ /**
+ * Checks whether the dispatch size is valid for compute shader
+ * invocations and returns the result as boolean value.
+ *
+ * @return True if the dispatch size is valid, otherwise false.
+ */
bool check() const;
};
+ /**
+ * Returns the proper dispatch size by dividing a global amount of invocations
+ * as three dimensional dispatch size into invocations of a fixed group size
+ * for the used work groups of the compute shader.
+ *
+ * This function will generate over fitted results to make sure all global
+ * invocations get computed. So make sure the used compute shader handles those
+ * additional invocations out of bounds from the original global invocations.
+ *
+ * @param[in] globalInvocations Size of planned global invocations
+ * @param[in] groupSize Size of work group in compute stage
+ * @return Dispatch size respecting the actual work group size
+ */
[[nodiscard]]
DispatchSize dispatchInvocations(DispatchSize globalInvocations, DispatchSize groupSize);
diff --git a/include/vkcv/ShaderStage.hpp b/include/vkcv/ShaderStage.hpp
index 39b250e8..d143b776 100644
--- a/include/vkcv/ShaderStage.hpp
+++ b/include/vkcv/ShaderStage.hpp
@@ -33,6 +33,9 @@ namespace vkcv {
}
+/**
+ * @cond VULKAN_TYPES
+ */
namespace vk {
template<>
@@ -58,6 +61,9 @@ namespace vk {
};
}
+/**
+ * @endcond
+ */
namespace vkcv {
diff --git a/include/vkcv/TypeGuard.hpp b/include/vkcv/TypeGuard.hpp
index 64d0f1db..cac170c0 100644
--- a/include/vkcv/TypeGuard.hpp
+++ b/include/vkcv/TypeGuard.hpp
@@ -10,6 +10,9 @@
namespace vkcv {
+ /**
+ * @brief Class bringing type safety during runtime to other classes.
+ */
class TypeGuard {
private:
#ifndef NDEBUG
@@ -25,20 +28,60 @@ namespace vkcv {
bool checkTypeSize(size_t size) const;
public:
+ /**
+ * Explicit constructor to create a type guard by a specific
+ * size only. The guard will not verify an individual type but
+ * whether its size matches the requirement.
+ *
+ * @param[in] size Size of type
+ */
explicit TypeGuard(size_t size = 0);
+
+ /**
+ * Explicit constructor to create a type guard by a types
+ * ID information and its size. The guard will verify a type
+ * by all available information in debug mode.
+ *
+ * @param[in] info ID information of type
+ * @param[in] size Size of type
+ */
TypeGuard(const std::type_info &info, size_t size);
TypeGuard(const TypeGuard &other) = default;
- TypeGuard(TypeGuard &&other) noexcept;
+ TypeGuard(TypeGuard &&other) noexcept = default;
~TypeGuard() = default;
TypeGuard& operator=(const TypeGuard &other) = default;
- TypeGuard& operator=(TypeGuard &&other) noexcept;
+ TypeGuard& operator=(TypeGuard &&other) noexcept = default;
+ /**
+ * Operator to compare two type guards and returns
+ * whether their stored type information and size
+ * match as boolean value.
+ *
+ * @param[in] other Other type guard
+ * @return True if the details match, otherwise false.
+ */
bool operator==(const TypeGuard &other) const;
+
+ /**
+ * Operator to compare two type guards and returns
+ * whether their stored type information and size
+ * do not match as boolean value.
+ *
+ * @param[in] other Other type guard
+ * @return True if the details differ, otherwise false.
+ */
bool operator!=(const TypeGuard &other) const;
+ /**
+ * Checks whether a type from a template parameter
+ * matches with the used type by the given guard.
+ *
+ * @tparam T Type to check against
+ * @return True if both types match, otherwise false.
+ */
template<typename T>
[[nodiscard]]
bool check() const {
@@ -49,27 +92,60 @@ namespace vkcv {
#endif
}
+ /**
+ * Returns the size of this guards type in bytes.
+ *
+ * @return Size of type
+ */
[[nodiscard]]
size_t typeSize() const;
};
+ /**
+ * Creates a new type guard with a given type specified
+ * as template parameter.
+ *
+ * @tparam T Type
+ * @return New type guard
+ */
template<typename T>
TypeGuard typeGuard() {
static TypeGuard guard (typeid(T), sizeof(T));
return guard;
}
+ /**
+ * Creates a new type guard with a given type specified
+ * as template parameter by the passed parameter.
+ *
+ * @tparam T Type
+ * @return New type guard
+ */
template<typename T>
TypeGuard typeGuard(T) {
return typeGuard<T>();
}
+ /**
+ * Creates a new type guard with a given type specified
+ * as template parameter by the passed parameter.
+ *
+ * @tparam T Type
+ * @return New type guard
+ */
template<typename T>
TypeGuard typeGuard(const T&) {
return typeGuard<T>();
}
+ /**
+ * Creates a new type guard with a given type specified
+ * as template parameter by the passed parameter.
+ *
+ * @tparam T Type
+ * @return New type guard
+ */
template<typename T>
TypeGuard typeGuard(T&&) {
return typeGuard<T>();
diff --git a/src/vkcv/TypeGuard.cpp b/src/vkcv/TypeGuard.cpp
index 06e566a1..31a75891 100644
--- a/src/vkcv/TypeGuard.cpp
+++ b/src/vkcv/TypeGuard.cpp
@@ -69,22 +69,6 @@ namespace vkcv {
#endif
m_typeSize(size)
{}
-
- TypeGuard::TypeGuard(TypeGuard &&other) noexcept :
-#ifndef NDEBUG
- m_typeName(other.m_typeName), m_typeHash(other.m_typeHash),
-#endif
- m_typeSize(other.m_typeSize)
- {}
-
- TypeGuard& TypeGuard::operator=(TypeGuard &&other) noexcept {
-#ifndef NDEBUG
- m_typeName = other.m_typeName;
- m_typeHash = other.m_typeHash;
-#endif
- m_typeSize = other.m_typeSize;
- return *this;
- }
bool TypeGuard::operator==(const TypeGuard &other) const {
#ifndef NDEBUG
--
GitLab