Add header comment blocks to and small code tweaks

janhsimon · janhsimon · commit b64da55306a7 · 2022-12-17T18:46:07.000+01:00
diff --git a/src/Buffer.cpp b/src/Buffer.cpp
@@ -29,14 +29,14 @@ Buffer::Buffer(const VkDevice device,
   vkGetPhysicalDeviceMemoryProperties(physicalDevice, &supportedMemoryProperties);
 
   const VkMemoryPropertyFlags typeFilter = memoryRequirements.memoryTypeBits;
-  uint32_t memoryTypeIndex = 0u;
+  uint32_t suitableMemoryTypeIndex = 0u;
   bool memoryTypeFound = false;
-  for (uint32_t i = 0u; i < supportedMemoryProperties.memoryTypeCount; ++i)
+  for (uint32_t memoryTypeIndex = 0u; memoryTypeIndex < supportedMemoryProperties.memoryTypeCount; ++memoryTypeIndex)
   {
-    const VkMemoryPropertyFlags propertyFlags = supportedMemoryProperties.memoryTypes[i].propertyFlags;
-    if (typeFilter & (1 << i) && (propertyFlags & memoryProperties) == memoryProperties)
+    const VkMemoryPropertyFlags propertyFlags = supportedMemoryProperties.memoryTypes[memoryTypeIndex].propertyFlags;
+    if (typeFilter & (1 << memoryTypeIndex) && (propertyFlags & memoryProperties) == memoryProperties)
     {
-      memoryTypeIndex = i;
+      suitableMemoryTypeIndex = memoryTypeIndex;
       memoryTypeFound = true;
       break;
     }
@@ -51,7 +51,7 @@ Buffer::Buffer(const VkDevice device,
 
   VkMemoryAllocateInfo memoryAllocateInfo{ VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO };
   memoryAllocateInfo.allocationSize = memoryRequirements.size;
-  memoryAllocateInfo.memoryTypeIndex = memoryTypeIndex;
+  memoryAllocateInfo.memoryTypeIndex = suitableMemoryTypeIndex;
   if (vkAllocateMemory(device, &memoryAllocateInfo, nullptr, &deviceMemory) != VK_SUCCESS)
   {
     std::stringstream s;
diff --git a/src/Buffer.h b/src/Buffer.h
@@ -2,6 +2,11 @@
 
 #include <vulkan/vulkan.h>
 
+/*
+ * The buffer class is used to store Vulkan data buffers, namely the uniform buffer and the vertex/index buffer. It is
+ * unrelated to Vulkan image buffers used for the depth buffer for example. Note that is good for performance to keep
+ * Vulkan buffers mapped until destruction. This class offers functionality to do so, but doesn't enfore the principle.
+ */
 class Buffer final
 {
 public:
diff --git a/src/Context.cpp b/src/Context.cpp
@@ -285,9 +285,9 @@ Context::Context()
       return;
     }
 
-    for (uint32_t i = 0u; i < requiredExtensionCount; ++i)
+    for (uint32_t extensionIndex = 0u; extensionIndex < requiredExtensionCount; ++extensionIndex)
     {
-      vulkanInstanceExtensions.push_back(buffer[i]);
+      vulkanInstanceExtensions.push_back(buffer[extensionIndex]);
     }
   }
 
diff --git a/src/Context.h b/src/Context.h
@@ -3,9 +3,14 @@
 #include <vulkan/vulkan.h>
 
 #define XR_USE_GRAPHICS_API_VULKAN
-#include <openxr/openxr.h>
 #include <openxr/openxr_platform.h>
 
+/*
+ * The context class handles the initial loading of both OpenXR and Vulkan base functionality such as instances, OpenXR
+ * sessions, Vulkan devices and queues, and so on. It also loads debug utility messengers for both OpenXR and Vulkan if
+ * the preprocessor macro DEBUG is defined. This enables console output that is crucial to finding potential issues in
+ * OpenXR or Vulkan.
+ */
 class Context final
 {
 public:
diff --git a/src/Controllers.h b/src/Controllers.h
@@ -6,6 +6,11 @@
 
 #include <vector>
 
+/*
+ * The controllers class handles OpenXR controller support. It represents the controller system as a whole, not an
+ * individual controller. This is more convenient due to the OpenXR API. It allows the application to retrieve the
+ * current transform of a controller, which is then used to accuretely pose the hand models in the scene.
+ */
 class Controllers final
 {
 public:
@@ -20,10 +25,10 @@ class Controllers final
 private:
   bool valid = true;
 
-  XrSession session;
+  XrSession session = nullptr;
   std::vector<XrPath> paths;
-  XrActionSet actionSet;
-  XrAction action;
+  XrActionSet actionSet = nullptr;
+  XrAction action = nullptr;
   std::vector<XrSpace> spaces;
   std::vector<glm::mat4> transforms;
 };
diff --git a/src/Headset.cpp b/src/Headset.cpp
@@ -4,6 +4,8 @@
 #include "RenderTarget.h"
 #include "Util.h"
 
+#include <glm/mat4x4.hpp>
+
 #include <array>
 #include <sstream>
 
@@ -226,14 +228,14 @@ Headset::Headset(const Context* context) : context(context)
 
     const VkMemoryPropertyFlags memoryProperties = VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT;
     const VkMemoryPropertyFlags typeFilter = memoryRequirements.memoryTypeBits;
-    uint32_t memoryTypeIndex = 0u;
+    uint32_t suitableMemoryTypeIndex = 0u;
     bool memoryTypeFound = false;
-    for (uint32_t i = 0u; i < supportedMemoryProperties.memoryTypeCount; ++i)
+    for (uint32_t memoryTypeIndex = 0u; memoryTypeIndex < supportedMemoryProperties.memoryTypeCount; ++memoryTypeIndex)
     {
-      const VkMemoryPropertyFlags propertyFlags = supportedMemoryProperties.memoryTypes[i].propertyFlags;
-      if (typeFilter & (1 << i) && (propertyFlags & memoryProperties) == memoryProperties)
+      const VkMemoryPropertyFlags propertyFlags = supportedMemoryProperties.memoryTypes[memoryTypeIndex].propertyFlags;
+      if (typeFilter & (1 << memoryTypeIndex) && (propertyFlags & memoryProperties) == memoryProperties)
       {
-        memoryTypeIndex = i;
+        suitableMemoryTypeIndex = memoryTypeIndex;
         memoryTypeFound = true;
         break;
       }
@@ -248,7 +250,7 @@ Headset::Headset(const Context* context) : context(context)
 
     VkMemoryAllocateInfo memoryAllocateInfo{ VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO };
     memoryAllocateInfo.allocationSize = memoryRequirements.size;
-    memoryAllocateInfo.memoryTypeIndex = memoryTypeIndex;
+    memoryAllocateInfo.memoryTypeIndex = suitableMemoryTypeIndex;
     if (vkAllocateMemory(device, &memoryAllocateInfo, nullptr, &depthMemory) != VK_SUCCESS)
     {
       std::stringstream s;
diff --git a/src/Headset.h b/src/Headset.h
@@ -1,6 +1,6 @@
 #pragma once
 
-#include <glm/mat4x4.hpp>
+#include <glm/fwd.hpp>
 
 #include <openxr/openxr.h>
 
@@ -11,6 +11,12 @@
 class Context;
 class RenderTarget;
 
+/*
+ * The headset class facilitates rendering into the device. It holds functionality to begin and end rendering a frame,
+ * to find out when the user has quit the application through the headset's operating system, as opposed to the mirror
+ * view window, and to retrieve the current orientation of the device. It relies on both OpenXR and Vulkan to provide
+ * these features.
+ */
 class Headset final
 {
 public:
diff --git a/src/MeshData.cpp b/src/MeshData.cpp
@@ -23,10 +23,8 @@ bool MeshData::loadModel(const std::string& filename,
 
   for (const tinyobj::shape_t& shape : shapes)
   {
-    for (size_t i = 0u; i < shape.mesh.indices.size(); ++i)
+    for (const tinyobj::index_t& index : shape.mesh.indices)
     {
-      const tinyobj::index_t index = shape.mesh.indices.at(i);
-
       Vertex vertex;
 
       vertex.position = { attrib.vertices[3 * index.vertex_index + 0], attrib.vertices[3 * index.vertex_index + 1],
diff --git a/src/MeshData.h b/src/MeshData.h
@@ -7,13 +7,23 @@
 
 struct Model;
 
+/*
+ * The vertex struct provides the vertex definition used for all geometry in the project.
+ */
 struct Vertex final
 {
   glm::vec3 position;
   glm::vec3 normal;
   glm::vec3 color;
 };
 
+/*
+ * The mesh data class consists of a vertex and index collection for geometric data. It is not intended to stay alive in
+ * memory after loading is done. It's purpose is rather to serve as a container for geometry data read in from OBJ model
+ * files until that gets uploaded to a Vulkan vertex/index buffer on the GPU. Note that the models in the mesh data
+ * class should be unique, a model that is rendered several times only needs to be loaded once. As many model structs as
+ * required can then be derived from the same data.
+ */
 class MeshData final
 {
 public:
diff --git a/src/MirrorView.cpp b/src/MirrorView.cpp
@@ -8,6 +8,8 @@
 
 #include <glfw/glfw3.h>
 
+#include <glm/common.hpp>
+
 #include <sstream>
 
 namespace
diff --git a/src/MirrorView.h b/src/MirrorView.h
@@ -9,6 +9,11 @@ struct GLFWwindow;
 class Headset;
 class Renderer;
 
+/*
+ * The mirror view class handles the creation, updating, resizing, and eventual closing of the desktop window that shows
+ * a copy of what is rendered into the headset. It depends on GLFW for handling the operating system, and Vulkan for the
+ * blitting into the window surface.
+ */
 class MirrorView final
 {
 public:
diff --git a/src/Model.h b/src/Model.h
@@ -2,6 +2,11 @@
 
 #include <glm/mat4x4.hpp>
 
+/*
+ * The model struct holds all required information to orientate and render a model. It handles orientation with a world
+ * transformation matrix and has its indexing information populated by the mesh data class. This struct represents a
+ * single draw call and is used by the renderer class to know how and where to draw a model.
+ */
 struct Model final
 {
   size_t firstIndex = 0u;
diff --git a/src/Pipeline.h b/src/Pipeline.h
@@ -5,6 +5,10 @@
 #include <string>
 #include <vector>
 
+/*
+ * The pipeline class wraps a Vulkan pipeline for convenience. It describes the rendering technique to use, including
+ * shaders, culling, scissoring, and other aspects.
+ */
 class Pipeline final
 {
 public:
diff --git a/src/RenderProcess.h b/src/RenderProcess.h
@@ -9,6 +9,13 @@
 
 class Buffer;
 
+/*
+ * The render process class consolidates all the resources that needs to be duplicated for each frame that can be
+ * rendered to in parallel. The renderer owns a render process for each frame that can be processed at the same time,
+ * and each render process holds their own uniform buffer, command buffer, semaphores and memory fence. With this
+ * duplication, the application can be sure that one frame does not modify a resource that is still in use by another
+ * simultaneous frame.
+ */
 class RenderProcess final
 {
 public:
diff --git a/src/RenderTarget.h b/src/RenderTarget.h
@@ -2,6 +2,10 @@
 
 #include <vulkan/vulkan.h>
 
+/*
+ * The render target class represents a convenient combination of an image and a framebuffer in Vulkan. The class is
+ * used for the Vulkan swapchain images retrieved by OpenXR for the headset displays.
+ */
 class RenderTarget final
 {
 public:
diff --git a/src/Renderer.h b/src/Renderer.h
@@ -12,6 +12,12 @@ struct Model;
 class Pipeline;
 class RenderProcess;
 
+/*
+ * The renderer class facilitates rendering with Vulkan. It is initialized with a constant list of models to render and
+ * holds the vertex/index buffer, the pipelines that define the rendering techniques to use, as well as a number of
+ * render processes. Note that all resources that need to be duplicated in order to be able to render several frames in
+ * parallel is held by this number of render processes.
+ */
 class Renderer final
 {
 public:
diff --git a/src/Util.h b/src/Util.h
@@ -4,9 +4,7 @@
 
 #include <vulkan/vulkan.h>
 
-#define XR_USE_GRAPHICS_API_VULKAN
 #include <openxr/openxr.h>
-#include <openxr/openxr_platform.h>
 
 #include <string>
 #include <vector>
@@ -26,6 +24,9 @@ enum class Error
   WindowFailure
 };
 
+/*
+ * The util namespaces offers a wide variety of useful utility functions.
+ */
 namespace util
 {
 // Reports an error with optional details through a system-native message box

Original file line number	Diff line number	Diff line change
`@@ -285,9 +285,9 @@ Context::Context()`
`285`	`285`	`return;`
`286`	`286`	`}`
`287`	`287`
`288`		`- for (uint32_t i = 0u; i < requiredExtensionCount; ++i)`
	`288`	`+ for (uint32_t extensionIndex = 0u; extensionIndex < requiredExtensionCount; ++extensionIndex)`
`289`	`289`	`{`
`290`		`- vulkanInstanceExtensions.push_back(buffer[i]);`
	`290`	`+ vulkanInstanceExtensions.push_back(buffer[extensionIndex]);`
`291`	`291`	`}`
`292`	`292`	`}`
`293`	`293`
Original file line number	Diff line number	Diff line change
`@@ -23,10 +23,8 @@ bool MeshData::loadModel(const std::string& filename,`
`23`	`23`
`24`	`24`	`for (const tinyobj::shape_t& shape : shapes)`
`25`	`25`	`{`
`26`		`- for (size_t i = 0u; i < shape.mesh.indices.size(); ++i)`
	`26`	`+ for (const tinyobj::index_t& index : shape.mesh.indices)`
`27`	`27`	`{`
`28`		`- const tinyobj::index_t index = shape.mesh.indices.at(i);`
`29`		`-`
`30`	`28`	`Vertex vertex;`
`31`	`29`
`32`	`30`	`vertex.position = { attrib.vertices[3 * index.vertex_index + 0], attrib.vertices[3 * index.vertex_index + 1],`