Improve swapchain extension API.

com.io7m.jcoronado.api/src/main/java/com/io7m/jcoronado/api/VulkanLogicalDeviceType.java

@@ -1016,6 +1016,21 @@ VulkanEventStatus getEventStatus(
     VulkanEventType event)
     throws VulkanException;
 
+  /**
+   * Retrieve the current value of a semaphore object.
+   *
+   * @param semaphore The semaphore
+   *
+   * @return The semaphore value
+   *
+   * @throws VulkanException On errors
+   */
+
+  @VulkanAPIFunctionType(vulkanFunction = "vkGetSemaphoreCounterValue")
+  long getSemaphoreCounterValue(
+    VulkanSemaphoreTimelineType semaphore)
+    throws VulkanException;
+
   /**
    * Retrieve the status of a fence object.
    *
@@ -1169,6 +1184,65 @@ default List<VulkanPipelineType> createComputePipelines(
     return this.createComputePipelines(Optional.empty(), pipeline_infos);
   }
 
+  /**
+   * Wait for one or more semaphores to become signaled.
+   *
+   * @param semaphores   The semaphores upon which to wait
+   * @param waitAll      {@code true} if all semaphores must become signalled to
+   *                     stop waiting, {@code false} if any semaphore can become
+   *                     signalled
+   * @param timeoutNanos The timeout period in units of nanoseconds.
+   *
+   * @return A value indicating whether waiting succeeded or timed out
+   *
+   * @throws VulkanException On errors
+   */
+
+  @VulkanAPIFunctionType(vulkanFunction = "vkWaitSemaphores")
+  VulkanWaitStatus waitForTimelineSemaphores(
+    List<VulkanSemaphoreTimelineWait> semaphores,
+    boolean waitAll,
+    long timeoutNanos)
+    throws VulkanException;
+
+  /**
+   * Wait for a semaphore to become signaled.
+   *
+   * @param semaphore    The semaphores upon which to wait
+   * @param timeoutNanos The timeout period in units of nanoseconds.
+   *
+   * @return A value indicating whether waiting succeeded or timed out
+   *
+   * @throws VulkanException On errors
+   */
+
+  @VulkanAPIFunctionType(vulkanFunction = "vkWaitSemaphores")
+  default VulkanWaitStatus waitForTimelineSemaphore(
+    final VulkanSemaphoreTimelineWait semaphore,
+    final long timeoutNanos)
+    throws VulkanException
+  {
+    return this.waitForTimelineSemaphores(
+      List.of(semaphore),
+      true,
+      timeoutNanos);
+  }
+
+  /**
+   * Signal a timeline semaphore.
+   *
+   * @param semaphore The semaphore
+   * @param value     The value
+   *
+   * @throws VulkanException On errors
+   */
+
+  @VulkanAPIFunctionType(vulkanFunction = "vkSignalSemaphore")
+  void signalTimelineSemaphore(
+    VulkanSemaphoreTimelineType semaphore,
+    long value)
+    throws VulkanException;
+
   /**
    * The result of fetching data for a pipeline cache.
    */

com.io7m.jcoronado.api/src/main/java/com/io7m/jcoronado/api/VulkanSemaphoreTimelineWait.java

@@ -0,0 +1,44 @@
+/*
+ * Copyright © 2024 Mark Raynsford <[email protected]> https://www.io7m.com
+ *
+ * Permission to use, copy, modify, and/or distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
+ * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+ * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ */
+
+
+package com.io7m.jcoronado.api;
+
+import java.util.Objects;
+
+/**
+ * A request to wait until the given semaphore has at least the given value.
+ *
+ * @param semaphore The semaphore
+ * @param value     The value
+ */
+
+public record VulkanSemaphoreTimelineWait(
+  VulkanSemaphoreTimelineType semaphore,
+  long value)
+{
+  /**
+   * A request to wait until the given semaphore has at least the given value.
+   *
+   * @param semaphore The semaphore
+   * @param value     The value
+   */
+
+  public VulkanSemaphoreTimelineWait
+  {
+    Objects.requireNonNull(semaphore, "semaphore");
+  }
+}

com.io7m.jcoronado.examples/src/main/java/com/io7m/jcoronado/examples/HelloVulkan.java

@@ -67,8 +67,8 @@
 import com.io7m.jcoronado.api.VulkanRenderPassCreateInfo;
 import com.io7m.jcoronado.api.VulkanResourceException;
 import com.io7m.jcoronado.api.VulkanSemaphoreBinaryCreateInfo;
+import com.io7m.jcoronado.api.VulkanSemaphoreBinaryType;
 import com.io7m.jcoronado.api.VulkanSemaphoreSubmitInfo;
-import com.io7m.jcoronado.api.VulkanSemaphoreType;
 import com.io7m.jcoronado.api.VulkanShaderModuleCreateInfo;
 import com.io7m.jcoronado.api.VulkanShaderModuleType;
 import com.io7m.jcoronado.api.VulkanSharingMode;
@@ -95,6 +95,11 @@
 import com.io7m.jcoronado.extensions.khr_swapchain.api.VulkanPresentInfoKHR;
 import com.io7m.jcoronado.extensions.khr_swapchain.api.VulkanPresentModeKHR;
 import com.io7m.jcoronado.extensions.khr_swapchain.api.VulkanSwapChainCreateInfo;
+import com.io7m.jcoronado.extensions.khr_swapchain.api.VulkanSwapChainNotReady;
+import com.io7m.jcoronado.extensions.khr_swapchain.api.VulkanSwapChainOK;
+import com.io7m.jcoronado.extensions.khr_swapchain.api.VulkanSwapChainOutOfDate;
+import com.io7m.jcoronado.extensions.khr_swapchain.api.VulkanSwapChainSubOptimal;
+import com.io7m.jcoronado.extensions.khr_swapchain.api.VulkanSwapChainTimedOut;
 import com.io7m.jcoronado.lwjgl.VulkanLWJGLHostAllocatorJeMalloc;
 import com.io7m.jcoronado.lwjgl.VulkanLWJGLInstanceProvider;
 import com.io7m.jcoronado.lwjgl.VulkanLWJGLTemporaryAllocator;
@@ -182,8 +187,8 @@ public HelloVulkan()
   private static void drawFrame(
     final VulkanExtKHRSwapChainType khrSwapchainExt,
     final VulkanKHRSwapChainType swapChain,
-    final VulkanSemaphoreType imageAvailable,
-    final VulkanSemaphoreType renderFinished,
+    final VulkanSemaphoreBinaryType imageAvailable,
+    final VulkanSemaphoreBinaryType renderFinished,
     final List<VulkanCommandBufferType> graphicsCommandBuffers,
     final VulkanQueueType graphicsQueue,
     final VulkanQueueType queuePresentation)
@@ -200,14 +205,29 @@ private static void drawFrame(
         0xffff_ffff_ffff_ffffL,
         imageAvailable);
 
-    final var imageIndexOption = acquisition.imageIndex();
-    if (!imageIndexOption.isPresent()) {
-      LOG.error("could not acquire image");
-      return;
+    final int imageIndex;
+    switch (acquisition) {
+      case final VulkanSwapChainOK r -> {
+        imageIndex = r.imageIndex();
+      }
+      case final VulkanSwapChainNotReady r -> {
+        LOG.error("Could not acquire image ({})", r);
+        return;
+      }
+      case final VulkanSwapChainOutOfDate r -> {
+        LOG.error("Could not acquire image ({})", r);
+        return;
+      }
+      case final VulkanSwapChainSubOptimal r -> {
+        LOG.error("Could not acquire image ({})", r);
+        return;
+      }
+      case final VulkanSwapChainTimedOut r -> {
+        LOG.error("Could not acquire image ({})", r);
+        return;
+      }
     }
 
-    final var imageIndex =
-      imageIndexOption.getAsInt();
     final var graphicsCommandBuffer =
       graphicsCommandBuffers.get(imageIndex);
 
@@ -516,7 +536,7 @@ private static VulkanSurfaceFormatKHR pickSurfaceFormat(
 
     for (final var format : formats) {
       if (format.format() == VK_FORMAT_B8G8R8A8_UNORM
-        && format.colorSpace() == VK_COLOR_SPACE_SRGB_NONLINEAR_KHR) {
+          && format.colorSpace() == VK_COLOR_SPACE_SRGB_NONLINEAR_KHR) {
         return format;
       }
     }
@@ -950,11 +970,15 @@ public void execute()
        */
 
       final var graphicsQueue =
-        device.queue(graphicsQueueProps.queueFamilyIndex(), new VulkanQueueIndex(0))
+        device.queue(
+            graphicsQueueProps.queueFamilyIndex(),
+            new VulkanQueueIndex(0))
           .orElseThrow(() -> new IllegalStateException(
             "Could not find graphics queue"));
       final var presentationQueue =
-        device.queue(presentationQueueProps.queueFamilyIndex(), new VulkanQueueIndex(0))
+        device.queue(
+            presentationQueueProps.queueFamilyIndex(),
+            new VulkanQueueIndex(0))
           .orElseThrow(() -> new IllegalStateException(
             "Could not find presentation queue"));
 

com.io7m.jcoronado.examples/src/main/java/com/io7m/jcoronado/examples/HelloVulkanWithVMA.java

@@ -92,6 +92,7 @@
 import com.io7m.jcoronado.api.VulkanSamplerCreateInfo;
 import com.io7m.jcoronado.api.VulkanSamplerType;
 import com.io7m.jcoronado.api.VulkanSemaphoreBinaryCreateInfo;
+import com.io7m.jcoronado.api.VulkanSemaphoreBinaryType;
 import com.io7m.jcoronado.api.VulkanSemaphoreSubmitInfo;
 import com.io7m.jcoronado.api.VulkanSemaphoreType;
 import com.io7m.jcoronado.api.VulkanShaderModuleCreateInfo;
@@ -121,6 +122,11 @@
 import com.io7m.jcoronado.extensions.khr_swapchain.api.VulkanPresentInfoKHR;
 import com.io7m.jcoronado.extensions.khr_swapchain.api.VulkanPresentModeKHR;
 import com.io7m.jcoronado.extensions.khr_swapchain.api.VulkanSwapChainCreateInfo;
+import com.io7m.jcoronado.extensions.khr_swapchain.api.VulkanSwapChainNotReady;
+import com.io7m.jcoronado.extensions.khr_swapchain.api.VulkanSwapChainOK;
+import com.io7m.jcoronado.extensions.khr_swapchain.api.VulkanSwapChainOutOfDate;
+import com.io7m.jcoronado.extensions.khr_swapchain.api.VulkanSwapChainSubOptimal;
+import com.io7m.jcoronado.extensions.khr_swapchain.api.VulkanSwapChainTimedOut;
 import com.io7m.jcoronado.lwjgl.VMALWJGLAllocatorProvider;
 import com.io7m.jcoronado.lwjgl.VulkanLWJGLHostAllocatorJeMalloc;
 import com.io7m.jcoronado.lwjgl.VulkanLWJGLInstanceProvider;
@@ -628,7 +634,8 @@ private static List<VulkanDescriptorSetType> createDescriptorSets(
     LOG.trace(
       "swap chain has {} images, allocating {} descriptor sets",
       imageCount,
-      imageCount);
+      imageCount
+    );
 
     final var descriptorPoolUniformBuffer =
       VulkanDescriptorPoolSize.of(
@@ -1126,8 +1133,8 @@ private static ArrayList<VulkanBufferType> createUniformBuffers(
   private static void drawFrame(
     final VulkanExtKHRSwapChainType khr_swapchain_ext,
     final VulkanKHRSwapChainType swap_chain,
-    final VulkanSemaphoreType imageAvailable,
-    final VulkanSemaphoreType renderFinished,
+    final VulkanSemaphoreBinaryType imageAvailable,
+    final VulkanSemaphoreBinaryType renderFinished,
     final List<VulkanCommandBufferType> graphics_command_buffers,
     final VulkanQueueType graphics_queue,
     final VulkanQueueType queue_presentation)
@@ -1144,16 +1151,31 @@ private static void drawFrame(
         0xffff_ffff_ffff_ffffL,
         imageAvailable);
 
-    final var image_index_option = acquisition.imageIndex();
-    if (!image_index_option.isPresent()) {
-      LOG.error("could not acquire image");
-      return;
+    final int imageIndex;
+    switch (acquisition) {
+      case final VulkanSwapChainOK r -> {
+        imageIndex = r.imageIndex();
+      }
+      case final VulkanSwapChainNotReady r -> {
+        LOG.error("Could not acquire image ({})", r);
+        return;
+      }
+      case final VulkanSwapChainOutOfDate r -> {
+        LOG.error("Could not acquire image ({})", r);
+        return;
+      }
+      case final VulkanSwapChainSubOptimal r -> {
+        LOG.error("Could not acquire image ({})", r);
+        return;
+      }
+      case final VulkanSwapChainTimedOut r -> {
+        LOG.error("Could not acquire image ({})", r);
+        return;
+      }
     }
 
-    final var image_index =
-      image_index_option.getAsInt();
     final var graphicsCommandBuffer =
-      graphics_command_buffers.get(image_index);
+      graphics_command_buffers.get(imageIndex);
 
     /*
      * Wait until the image is available (via the image available semaphore) before writing
@@ -1189,7 +1211,7 @@ private static void drawFrame(
 
     final var presentation_info =
       VulkanPresentInfoKHR.builder()
-        .addImageIndices(image_index)
+        .addImageIndices(imageIndex)
         .addSwapChains(swap_chain)
         .addWaitSemaphores(renderFinished)
         .build();

com.io7m.jcoronado.extensions.khr_surface.api/src/main/java/com/io7m/jcoronado/extensions/khr_swapchain/api/VulkanExtKHRSwapChainType.java

@@ -23,7 +23,7 @@
 import com.io7m.jcoronado.api.VulkanImageType;
 import com.io7m.jcoronado.api.VulkanLogicalDeviceType;
 import com.io7m.jcoronado.api.VulkanQueueType;
-import com.io7m.jcoronado.api.VulkanSemaphoreType;
+import com.io7m.jcoronado.api.VulkanSemaphoreBinaryType;
 
 import java.util.List;
 
@@ -99,9 +99,9 @@ List<VulkanImageType> images()
      * @throws VulkanException On errors
      */
 
-    VulkanSwapChainImageAcquisition acquireImageWithSemaphore(
+    VulkanSwapChainAcquisitionResultType acquireImageWithSemaphore(
       long timeout,
-      VulkanSemaphoreType semaphore)
+      VulkanSemaphoreBinaryType semaphore)
       throws VulkanException;
 
     /**
@@ -117,7 +117,7 @@ VulkanSwapChainImageAcquisition acquireImageWithSemaphore(
      * @throws VulkanException On errors
      */
 
-    VulkanSwapChainImageAcquisition acquireImageWithFence(
+    VulkanSwapChainAcquisitionResultType acquireImageWithFence(
       long timeout,
       VulkanFenceType fence)
       throws VulkanException;
@@ -136,9 +136,9 @@ VulkanSwapChainImageAcquisition acquireImageWithFence(
      * @throws VulkanException On errors
      */
 
-    VulkanSwapChainImageAcquisition acquireImageWithSemaphoreAndFence(
+    VulkanSwapChainAcquisitionResultType acquireImageWithSemaphoreAndFence(
       long timeout,
-      VulkanSemaphoreType semaphore,
+      VulkanSemaphoreBinaryType semaphore,
       VulkanFenceType fence)
       throws VulkanException;
   }

com.io7m.jcoronado.extensions.khr_surface.api/src/main/java/com/io7m/jcoronado/extensions/khr_swapchain/api/VulkanSwapChainAcquisitionResultType.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright © 2024 Mark Raynsford <[email protected]> https://www.io7m.com
+ *
+ * Permission to use, copy, modify, and/or distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
+ * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+ * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ */
+
+
+package com.io7m.jcoronado.extensions.khr_swapchain.api;
+
+/**
+ * The result of trying to acquire a swapchain image.
+ */
+
+public sealed interface VulkanSwapChainAcquisitionResultType
+  permits VulkanSwapChainNotReady,
+  VulkanSwapChainOK,
+  VulkanSwapChainOutOfDate,
+  VulkanSwapChainSubOptimal,
+  VulkanSwapChainTimedOut
+{
+
+}