From 685dc4e9df9b42489108db4449003f2c8ab4a126 Mon Sep 17 00:00:00 2001
From: Tobias Frisch <tfrisch@uni-koblenz.de>
Date: Wed, 15 Sep 2021 15:46:41 +0200
Subject: [PATCH] [#96] Added some doxygen comments for the scene module and
fixed some other missing pieces in other modules
Signed-off-by: Tobias Frisch <tfrisch@uni-koblenz.de>
---
.../include/vkcv/camera/CameraController.hpp | 2 +-
modules/gui/include/vkcv/gui/GUI.hpp | 2 +-
modules/gui/src/vkcv/gui/GUI.cpp | 4 +-
modules/scene/include/vkcv/scene/Bounds.hpp | 136 +++++++++++++++---
modules/scene/include/vkcv/scene/Frustum.hpp | 20 ++-
modules/scene/include/vkcv/scene/Node.hpp | 112 +++++++++++++--
.../include/vkcv/shader/GLSLCompiler.hpp | 17 ++-
.../include/vkcv/upscaling/FSRUpscaling.hpp | 27 +++-
8 files changed, 277 insertions(+), 43 deletions(-)
diff --git a/modules/camera/include/vkcv/camera/CameraController.hpp b/modules/camera/include/vkcv/camera/CameraController.hpp
index 6d4d0209..143893a5 100644
--- a/modules/camera/include/vkcv/camera/CameraController.hpp
+++ b/modules/camera/include/vkcv/camera/CameraController.hpp
@@ -12,7 +12,7 @@ namespace vkcv::camera {
/**
* @brief Used as a base class for defining camera controller classes with different behaviors, e.g. the
- * #PilotCameraController.
+ * PilotCameraController.
*/
class CameraController {
diff --git a/modules/gui/include/vkcv/gui/GUI.hpp b/modules/gui/include/vkcv/gui/GUI.hpp
index 9a85e641..697d3615 100644
--- a/modules/gui/include/vkcv/gui/GUI.hpp
+++ b/modules/gui/include/vkcv/gui/GUI.hpp
@@ -77,7 +77,7 @@ namespace vkcv::gui {
* @param[in,out] core Valid Core instance of the framework
* @param[in,out] window Valid Window instance of the framework
*/
- GUI(Core& core, WindowHandle& windowHandle);
+ GUI(Core& core, WindowHandle& window);
GUI(const GUI& other) = delete;
GUI(GUI&& other) = delete;
diff --git a/modules/gui/src/vkcv/gui/GUI.cpp b/modules/gui/src/vkcv/gui/GUI.cpp
index 7ee33537..708a7d50 100644
--- a/modules/gui/src/vkcv/gui/GUI.cpp
+++ b/modules/gui/src/vkcv/gui/GUI.cpp
@@ -18,8 +18,8 @@ namespace vkcv::gui {
vkcv_log(LogLevel::ERROR, "ImGui has a problem with Vulkan! (%s)", vk::to_string(result).c_str());
}
- GUI::GUI(Core& core, WindowHandle& windowHandle) :
- m_windowHandle(windowHandle),
+ GUI::GUI(Core& core, WindowHandle& window) :
+ m_windowHandle(window),
m_core(core),
m_context(m_core.getContext()),
m_gui_context(nullptr) {
diff --git a/modules/scene/include/vkcv/scene/Bounds.hpp b/modules/scene/include/vkcv/scene/Bounds.hpp
index e31970ff..56d9e6b8 100644
--- a/modules/scene/include/vkcv/scene/Bounds.hpp
+++ b/modules/scene/include/vkcv/scene/Bounds.hpp
@@ -10,14 +10,35 @@ namespace vkcv::scene {
* @addtogroup vkcv_scene
* @{
*/
-
+
+ /**
+ * A basic class to represent axis aligned bounding boxes.
+ */
class Bounds {
private:
+ /**
+ * Minimum values of the box as 3D vector.
+ */
glm::vec3 m_min;
+
+ /**
+ * Maximum values of the box as 3D vector.
+ */
glm::vec3 m_max;
public:
+ /**
+ * Default constructor creating a zero volume axis aligned bounding
+ * box.
+ */
Bounds();
+
+ /**
+ * Constructor creating an axis aligned bounding box with given
+ * boundaries, defined through minimum and maximum values.
+ * @param[in] min Minimum values of the box as 3D vector
+ * @param[in] max Maximum values of the box as 3D vector
+ */
Bounds(const glm::vec3& min, const glm::vec3& max);
~Bounds() = default;
@@ -26,49 +47,130 @@ namespace vkcv::scene {
Bounds& operator=(const Bounds& other) = default;
Bounds& operator=(Bounds&& other) = default;
-
+
+ /**
+ * Set and replace the minimum values of the box
+ * via a 3D vector.
+ * @param[in] min New minimum values of the box as 3D vector
+ */
void setMin(const glm::vec3& min);
-
+
+ /**
+ * Return the current minimum values of the box as
+ * 3D vector.
+ * @return Minimum values of the box as 3D vector
+ */
[[nodiscard]]
const glm::vec3& getMin() const;
-
+
+ /**
+ * Set and replace the maximum values of the box
+ * via a 3D vector.
+ * @param[in] max New maximum values of the box as 3D vector
+ */
void setMax(const glm::vec3& max);
-
+
+ /**
+ * Return the current maximum values of the box as
+ * 3D vector.
+ * @return Maximum values of the box as 3D vector
+ */
[[nodiscard]]
const glm::vec3& getMax() const;
-
+
+ /**
+ * Set the new center of the box by moving it and keeping
+ * its current volume.
+ * @param[in] center New center as 3D vector
+ */
void setCenter(const glm::vec3& center);
-
+
+ /**
+ * Return the current center of the box as 3D vector.
+ * @return Center as 3D vector
+ */
[[nodiscard]]
glm::vec3 getCenter() const;
-
+
+ /**
+ * Set the new size of the box by scaling it from its center,
+ * keeping the center position but replacing its volume.
+ * @param[in] size New size as 3D vector
+ */
void setSize(const glm::vec3& size);
-
+
+ /**
+ * Return the current size of the box as 3D vector.
+ * @return Size as 3D vector
+ */
[[nodiscard]]
glm::vec3 getSize() const;
-
+
+ /**
+ * Return a fixed size array containing all corners of
+ * the box as 3D vectors in absolute positions.
+ * @return Array of corners as 3D vectors
+ */
[[nodiscard]]
std::array<glm::vec3, 8> getCorners() const;
-
+
+ /**
+ * Resize the box to include a given point, provided
+ * in absolute position as 3D vector.
+ * @param[in] point Point as 3D vector
+ */
void extend(const glm::vec3& point);
-
+
+ /**
+ * Return if a given point, provided in absolute position,
+ * is inside this box or not.
+ * @param[in] point Point as 3D vector
+ * @return true if the point is inside, otherwise false
+ */
[[nodiscard]]
bool contains(const glm::vec3& point) const;
-
+
+ /**
+ * Return if a given other axis aligned bounding box is
+ * inside this box or not.
+ * @param[in] other Other box as Bounds
+ * @return true if the box is inside, otherwise false
+ */
[[nodiscard]]
bool contains(const Bounds& other) const;
-
+
+ /**
+ * Return if a given other axis aligned bounding box is
+ * intersecting this box or not.
+ * @param[in] other Other box as Bounds
+ * @return true if the boxes are intersecting, otherwise false
+ */
[[nodiscard]]
bool intersects(const Bounds& other) const;
-
+
+ /**
+ * Return if the defined bounding box is valid (min <= max).
+ * @return true if the box is valid, otherwise false
+ */
[[nodiscard]]
explicit operator bool() const;
-
+
+ /**
+ * Return if the defined bounding box is invalid (min > max).
+ * @return true if the box is invalid, otherwise false
+ */
[[nodiscard]]
bool operator!() const;
};
-
+
+ /**
+ * Stream-operator of the axis aligned bounding box to print
+ * it as readable output to logs or the console.
+ * @param[out] out Output stream
+ * @param[in] bounds Axis aligned bounding box
+ * @return Accessed output stream
+ */
std::ostream& operator << (std::ostream& out, const Bounds& bounds);
/** @} */
diff --git a/modules/scene/include/vkcv/scene/Frustum.hpp b/modules/scene/include/vkcv/scene/Frustum.hpp
index 723eb0a8..040f53b9 100644
--- a/modules/scene/include/vkcv/scene/Frustum.hpp
+++ b/modules/scene/include/vkcv/scene/Frustum.hpp
@@ -9,9 +9,25 @@ namespace vkcv::scene {
* @addtogroup vkcv_scene
* @{
*/
-
+
+ /**
+ * Transform a given axis aligned bounding box into frustum coordinates
+ * using a given 4x4 transformation matrix to return a new axis aligned
+ * bounding box containing that transformed box.
+ * @param[in] transform Frustum defining 4x4 matrix
+ * @param[in] bounds Axis aligned bounding box
+ * @param[out] negative_w Flag if w-coordinate is negative (optional)
+ * @return Bounds containing box in frustum coordinates
+ */
Bounds transformBounds(const glm::mat4& transform, const Bounds& bounds, bool* negative_w = nullptr);
-
+
+ /**
+ * Check if an axis aligned bounding box is intersecting a given frustum
+ * defined by a 4x4 transformation matrix.
+ * @param[in] transform Frustum defining 4x4 matrix
+ * @param[in] bounds Axis aligned bounding box
+ * @return true if the box and frustum are intersecting, otherwise false
+ */
bool checkFrustum(const glm::mat4& transform, const Bounds& bounds);
/** @} */
diff --git a/modules/scene/include/vkcv/scene/Node.hpp b/modules/scene/include/vkcv/scene/Node.hpp
index dc82ab62..9fa79fa9 100644
--- a/modules/scene/include/vkcv/scene/Node.hpp
+++ b/modules/scene/include/vkcv/scene/Node.hpp
@@ -15,49 +15,135 @@ namespace vkcv::scene {
*/
class Scene;
-
+
+ /**
+ * A class to represent a graph node in a scene graph.
+ */
class Node {
friend class Scene;
private:
+ /**
+ * Parent scene of the node.
+ */
Scene& m_scene;
-
+
+ /**
+ * List of meshes added the node.
+ */
std::vector<Mesh> m_meshes;
+
+ /**
+ * List of child nodes added the node.
+ */
std::vector<Node> m_nodes;
+
+ /**
+ * Axis aligned bounding box of the node.
+ */
Bounds m_bounds;
-
+
+ /**
+ * Constructor of a new node with a given scene as parent.
+ * @param[in,out] scene Scene
+ */
explicit Node(Scene& scene);
-
+
+ /**
+ * Add a given mesh to this node for drawcall recording.
+ * @param[in] mesh Mesh
+ */
void addMesh(const Mesh& mesh);
-
+
+ /**
+ * Load and add a mesh from a scene preloaded with the asset loader.
+ * @param[in] asset_scene Scene structure from asset loader
+ * @param[in] asset_mesh Mesh structure from asset loader
+ */
void loadMesh(const asset::Scene& asset_scene, const asset::Mesh& asset_mesh);
-
+
+ /**
+ * Record drawcalls of all meshes of this node and its child nodes.
+ * @param[in] viewProjection View-transformation and projection as 4x4 matrix
+ * @param[out] pushConstants Structure to store push constants per drawcall
+ * @param[out] drawcalls List of drawcall structures
+ * @param[in] record Drawcall recording event function
+ */
void recordDrawcalls(const glm::mat4& viewProjection,
PushConstants& pushConstants,
std::vector<DrawcallInfo>& drawcalls,
const RecordMeshDrawcallFunction& record);
-
+
+ /**
+ * Splits child nodes into tree based graphs of nodes
+ * until all nodes contain an amount of meshes below
+ * a given maximum.
+ * @param[in] maxMeshesPerNode Maximum amount of meshes per node
+ */
void splitMeshesToSubNodes(size_t maxMeshesPerNode);
[[nodiscard]]
size_t getDrawcallCount() const;
-
+
+ /**
+ * Add a new node as child to the scene graph with this node
+ * as parent and return its index.
+ * @return Index of the new node
+ */
size_t addNode();
-
+
+ /**
+ * Get a reference to the child node with a given index.
+ * @param[in] index Valid index of a child node
+ * @return Matching child node
+ */
Node& getNode(size_t index);
-
+
+ /**
+ * Get a const reference to the child node with a given index.
+ * @param[in] index Valid index of a child node
+ * @return Matching child node
+ */
[[nodiscard]]
const Node& getNode(size_t index) const;
public:
+ /**
+ * Destructor of a scene node.
+ */
~Node();
-
+
+ /**
+ * Copy-constructor of a scene node.
+ * @param[in] other Other scene node
+ */
Node(const Node& other) = default;
+
+ /**
+ * Move-constructor of a scene node.
+ * @param[out] other Other scene node
+ */
Node(Node&& other) = default;
-
+
+ /**
+ * Copy-operator of a scene node.
+ * @param[in] other Other scene node
+ * @return Reference of this node
+ */
Node& operator=(const Node& other);
+
+ /**
+ * Move-operator of a scene node.
+ * @param[out] other Other scene node
+ * @return Reference of this node
+ */
Node& operator=(Node&& other) noexcept;
-
+
+ /**
+ * Return the axis aligned bounding box of the
+ * scene node.
+ * @return Axis aligned bounding box of this node
+ */
[[nodiscard]]
const Bounds& getBounds() const;
diff --git a/modules/shader_compiler/include/vkcv/shader/GLSLCompiler.hpp b/modules/shader_compiler/include/vkcv/shader/GLSLCompiler.hpp
index 66e2b1fb..e457874a 100644
--- a/modules/shader_compiler/include/vkcv/shader/GLSLCompiler.hpp
+++ b/modules/shader_compiler/include/vkcv/shader/GLSLCompiler.hpp
@@ -25,9 +25,14 @@ namespace vkcv::shader {
/**
* The copy-constructor of a runtime GLSL shader compiler instance.
- * @param other Other instance of a GLSL shader compiler instance
+ * @param[in] other Other instance of a GLSL shader compiler instance
*/
GLSLCompiler(const GLSLCompiler& other);
+
+ /**
+ * The move-constructor of a runtime GLSL shader compiler instance.
+ * @param[out] other Other instance of a GLSL shader compiler instance
+ */
GLSLCompiler(GLSLCompiler&& other) = default;
/**
@@ -37,11 +42,17 @@ namespace vkcv::shader {
/**
* The copy-operator of a runtime GLSL shader compiler instance.
- * @param other Other instance of a GLSL shader compiler instance
+ * @param[in] other Other instance of a GLSL shader compiler instance
* @return Reference to this instance
*/
GLSLCompiler& operator=(const GLSLCompiler& other);
- GLSLCompiler& operator=(GLSLCompiler&& other) = default;
+
+ /**
+ * The copy-operator of a runtime GLSL shader compiler instance.
+ * @param[out] other Other instance of a GLSL shader compiler instance
+ * @return Reference to this instance
+ */
+ GLSLCompiler& operator=(GLSLCompiler&& other) = default;
/**
* Compile a GLSL shader from source for a target stage with a custom shader
diff --git a/modules/upscaling/include/vkcv/upscaling/FSRUpscaling.hpp b/modules/upscaling/include/vkcv/upscaling/FSRUpscaling.hpp
index dde3379f..04f9ea72 100644
--- a/modules/upscaling/include/vkcv/upscaling/FSRUpscaling.hpp
+++ b/modules/upscaling/include/vkcv/upscaling/FSRUpscaling.hpp
@@ -72,11 +72,30 @@ namespace vkcv::upscaling {
* with the shaders used by FSR upscaling.
*/
struct FSRConstants {
+ /**
+ * 0th FSR constant.
+ */
uint32_t Const0 [4];
- uint32_t Const1 [4];
- uint32_t Const2 [4];
- uint32_t Const3 [4];
- uint32_t Sample [4];
+
+ /**
+ * 1st FSR constant.
+ */
+ uint32_t Const1 [4];
+
+ /**
+ * 2nd FSR constant.
+ */
+ uint32_t Const2 [4];
+
+ /**
+ * 3rd FSR constant.
+ */
+ uint32_t Const3 [4];
+
+ /**
+ * 4th FSR constant.
+ */
+ uint32_t Sample [4];
};
/**
--
GitLab