javadoc and comments

apps/src/main/resources/Shaders/Debug/HelloVSport.vert

@@ -3,10 +3,10 @@
  */
 #version 450
 
-layout(location = 0) in vec3 inPosition;  // locations from vertex buffer
-layout(location = 1) in vec2 inTexCoords; // texture coords from vertex buffer
+layout(location = 0) in vec3 inPosition;  // positions from a vertex buffer
+layout(location = 1) in vec2 inTexCoords; // texture coordinates from a vertex buffer
 
-layout(location = 1) out vec2 texCoords;    // texture coords to the frag shader
+layout(location = 1) out vec2 texCoords;  // texture coordinates to the frag shader
 
 layout(binding = 0) uniform UniformBufferObject {
     mat4 model;
@@ -18,9 +18,6 @@ void main() {
     // vertex position in clip space
     gl_Position = ubo.proj * ubo.view * ubo.model * vec4(inPosition, 1.0);
 
-    // interpolated vertex color
-    //vertexColor = inColor;
-
     // interpolated texture coordinates
     texCoords = inTexCoords;
 }

lib/src/main/java/com/github/stephengold/vsport/BaseApplication.java

@@ -254,7 +254,7 @@ public abstract class BaseApplication {
      */
     private static long pipelineHandle = VK10.VK_NULL_HANDLE;
     /**
-     * handle of the graphics-pipeline layour
+     * handle of the graphics-pipeline layout
      */
     private static long pipelineLayoutHandle = VK10.VK_NULL_HANDLE;
     /**
@@ -696,7 +696,7 @@ static void createImage(int width, int height, int format,
      * @param imageHandle the handle of the image
      * @param format the desired format for the view
      * @param aspectMask a bitmask of VK_IMAGE_ASPECT_... values
-     * @return the handle of the new image view
+     * @return the handle of the new VkImageView
      */
     static long createImageView(long imageHandle, int format, int aspectMask) {
         try (MemoryStack stack = MemoryStack.stackPush()) {
@@ -2126,8 +2126,8 @@ private static void initializeVulkan(String appName, int appVersion) {
         sampleMesh = new Mesh(indices, vertices);
 
         sampleTexture = new Texture("/Models/viking_room/viking_room.png");
-        createTextureSampler();
-        createDescriptorSetLayout();
+        createTextureSampler(); // depends on the logical device
+        createDescriptorSetLayout(); // depends on the logical device
 
         createChainResources();
     }

lib/src/main/java/com/github/stephengold/vsport/IndexBuffer.java

@@ -36,7 +36,7 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 import org.lwjgl.vulkan.VK10;
 
 /**
- * Wrapper class for the index buffer of a V-SPORT mesh, including its
+ * Wrapper class for the index buffer of a V-Sport mesh, including its
  * BufferResource.
  *
  * @author Stephen Gold sgold@sonic.net

lib/src/main/java/com/github/stephengold/vsport/SurfaceSummary.java

@@ -40,7 +40,7 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 import org.lwjgl.vulkan.VkSurfaceFormatKHR;
 
 /**
- * Summarize the swap-chain features of a physical device.
+ * Summarize the features of a particular VkSurfaceKHR.
  *
  * @author Stephen Gold sgold@sonic.net
  *
@@ -76,6 +76,7 @@ class SurfaceSummary {
      */
     SurfaceSummary(VkPhysicalDevice physicalDevice, long surfaceHandle,
             MemoryStack stack) {
+        // Obtain the capabilities of the VkSurfaceKHR:
         this.capabilities = VkSurfaceCapabilitiesKHR.malloc(stack);
         KHRSurface.vkGetPhysicalDeviceSurfaceCapabilitiesKHR(
                 physicalDevice, surfaceHandle, capabilities);
@@ -87,6 +88,7 @@ class SurfaceSummary {
         Utils.checkForError(retCode, "count surface formats");
         int numFormats = storeInt.get(0);
 
+        // Enumerate the available surface formats:
         this.formats = VkSurfaceFormatKHR.malloc(numFormats, stack);
         if (numFormats > 0) {
             KHRSurface.vkGetPhysicalDeviceSurfaceFormatsKHR(
@@ -99,6 +101,7 @@ class SurfaceSummary {
         Utils.checkForError(retCode, "count presentation modes");
         int numModes = storeInt.get(0);
 
+        // Enumerate the available surface-presentation modes:
         this.presentationModes = stack.mallocInt(numModes);
         if (numModes > 0) {
             retCode = KHRSurface.vkGetPhysicalDeviceSurfacePresentModesKHR(
@@ -155,8 +158,8 @@ VkSurfaceFormatKHR chooseSurfaceFormat() {
     /**
      * Choose an extent for the swap chain of the main window.
      *
-     * @param frameBufferWidth the width of the frame buffer
-     * @param frameBufferHeight the height of the frame buffer
+     * @param frameBufferWidth the desired width of the frame buffer
+     * @param frameBufferHeight the desired height of the frame buffer
      * @param stack for memory allocation (not null)
      * @return a new instance (may be temporary)
      */
@@ -192,21 +195,41 @@ int currentTransform() {
         return result;
     }
 
+    /**
+     * Test whether the surface has one or more surface formats available.
+     *
+     * @return true if formats are available, otherwise false
+     */
     boolean hasFormat() {
         boolean result = formats.hasRemaining();
         return result;
     }
 
+    /**
+     * Test whether the surface has one or more presentation modes available.
+     *
+     * @return true if modes are available, otherwise false
+     */
     boolean hasPresentationMode() {
         boolean result = presentationModes.hasRemaining();
         return result;
     }
 
+    /**
+     * Return the maximum number of swapchain images supported.
+     *
+     * @return the count (>1), or zero for no limit
+     */
     int maxImageCount() {
         int result = capabilities.maxImageCount();
         return result;
     }
 
+    /**
+     * Return the minimum number of swapchain images supported.
+     *
+     * @return the count (≥1)
+     */
     int minImageCount() {
         int result = capabilities.minImageCount();
         return result;

lib/src/main/java/com/github/stephengold/vsport/package-info.java

@@ -28,6 +28,6 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 /**
- * Core functionality of the V-SPORT graphics engine.
+ * Core functionality of the V-Sport graphics engine.
  */
 package com.github.stephengold.vsport;