Add header comment blocks to and small code tweaks

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;

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:

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]);
     }
   }
 

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:

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;
 };

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;

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:

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],

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:

src/MirrorView.cpp

@@ -8,6 +8,8 @@
 
 #include <glfw/glfw3.h>
 
+#include <glm/common.hpp>
+
 #include <sstream>
 
 namespace

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:

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;

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:

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:

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:

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:

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