Add type-safe binary and timeline semaphores.

README.in

@@ -23,10 +23,28 @@ Vulkan bindings, and adds a thin layer of immutable types and interfaces.
 
 ## Requirements
 
-The `jcoronado` package currently targets Vulkan 1.3 and up. It requires the
-`synchronization2` feature to be available and enabled. According to the
-[Vulkan hardware database](https://vulkan.gpuinfo.org/), this currently
-covers around `99.82%` of hardware.
+The `jcoronado` package currently targets Vulkan 1.3 and up. Some optional
+device features are _required_ by the package.
+
+### synchronization2
+
+The package requires the `synchronization2` feature to be available and enabled.
+This is necessary to avoid having a lot of branching code paths around queue
+submission and render passes.
+
+At the time of writing, according to the
+[Vulkan hardware database](https://vulkan.gpuinfo.org/listdevicescoverage.php?core=1.3&feature=synchronization2&platform=all),
+this feature is available on `99.82%` of hardware.
+
+### timelineSemaphore
+
+The package requires the `timelineSemaphore` feature to be available and
+enabled. This is necessary because timeline semaphores are a mandatory part
+of the API exposed by the package.
+
+At the time of writing, according to the
+[Vulkan hardware database](https://vulkan.gpuinfo.org/listdevicescoverage.php?core=1.2&feature=timelineSemaphore&platform=all),
+this feature is available on `99.88%` of hardware.
 
 ## Building
 

README.md

@@ -39,10 +39,28 @@ Vulkan bindings, and adds a thin layer of immutable types and interfaces.
 
 ## Requirements
 
-The `jcoronado` package currently targets Vulkan 1.3 and up. It requires the
-`synchronization2` feature to be available and enabled. According to the
-[Vulkan hardware database](https://vulkan.gpuinfo.org/), this currently
-covers around `99.82%` of hardware.
+The `jcoronado` package currently targets Vulkan 1.3 and up. Some optional
+device features are _required_ by the package.
+
+### synchronization2
+
+The package requires the `synchronization2` feature to be available and enabled.
+This is necessary to avoid having a lot of branching code paths around queue
+submission and render passes.
+
+At the time of writing, according to the
+[Vulkan hardware database](https://vulkan.gpuinfo.org/listdevicescoverage.php?core=1.3&feature=synchronization2&platform=all),
+this feature is available on `99.82%` of hardware.
+
+### timelineSemaphore
+
+The package requires the `timelineSemaphore` feature to be available and
+enabled. This is necessary because timeline semaphores are a mandatory part
+of the API exposed by the package.
+
+At the time of writing, according to the
+[Vulkan hardware database](https://vulkan.gpuinfo.org/listdevicescoverage.php?core=1.2&feature=timelineSemaphore&platform=all),
+this feature is available on `99.88%` of hardware.
 
 ## Building
 

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

@@ -589,18 +589,33 @@ default VulkanCommandBufferType createCommandBuffer(
   }
 
   /**
-   * Create a semaphore.
+   * Create a binary semaphore.
    *
-   * @param create_info The semaphore creation info
+   * @param info The semaphore creation info
    *
    * @return A semaphore
    *
    * @throws VulkanException On errors
    */
 
   @VulkanAPIFunctionType(vulkanFunction = "vkCreateSemaphore")
-  VulkanSemaphoreType createSemaphore(
-    VulkanSemaphoreCreateInfo create_info)
+  VulkanSemaphoreBinaryType createBinarySemaphore(
+    VulkanSemaphoreBinaryCreateInfo info)
+    throws VulkanException;
+
+  /**
+   * Create a timeline semaphore.
+   *
+   * @param info The semaphore creation info
+   *
+   * @return A semaphore
+   *
+   * @throws VulkanException On errors
+   */
+
+  @VulkanAPIFunctionType(vulkanFunction = "vkCreateSemaphore")
+  VulkanSemaphoreTimelineType createTimelineSemaphore(
+    VulkanSemaphoreTimelineCreateInfo info)
     throws VulkanException;
 
   /**

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

@@ -0,0 +1,35 @@
+/*
+ * Copyright © 2018 Mark Raynsford <[email protected]> http://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 com.io7m.immutables.styles.ImmutablesStyleType;
+import org.immutables.value.Value;
+
+/**
+ * The type of Vulkan semaphore creation information.
+ *
+ * @see "VkSemaphoreCreateInfo"
+ */
+
+@VulkanAPIStructType(vulkanStruct = "VkSemaphoreCreateInfo")
+@ImmutablesStyleType
+@Value.Immutable
+public non-sealed interface VulkanSemaphoreBinaryCreateInfoType
+  extends VulkanSemaphoreCreateInfoType
+{
+
+}

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

@@ -0,0 +1,30 @@
+/*
+ * Copyright © 2018 Mark Raynsford <[email protected]> http://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;
+
+/**
+ * A semaphore represents a GPU to GPU synchronization.
+ *
+ * @see "VkSemaphore"
+ */
+
+public non-sealed interface VulkanSemaphoreBinaryType
+  extends VulkanSemaphoreType
+{
+
+}
+

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

@@ -16,26 +16,16 @@
 
 package com.io7m.jcoronado.api;
 
-import com.io7m.immutables.styles.ImmutablesStyleType;
-import org.immutables.value.Value;
-
-import java.util.Set;
-
 /**
  * The type of Vulkan semaphore creation information.
  *
  * @see "VkSemaphoreCreateInfo"
  */
 
 @VulkanAPIStructType(vulkanStruct = "VkSemaphoreCreateInfo")
-@ImmutablesStyleType
-@Value.Immutable
-public interface VulkanSemaphoreCreateInfoType
+public sealed interface VulkanSemaphoreCreateInfoType
+  permits VulkanSemaphoreTimelineCreateInfoType,
+    VulkanSemaphoreBinaryCreateInfoType
 {
-  /**
-   * @return The semaphore creation flags
-   */
 
-  @Value.Parameter
-  Set<VulkanSemaphoreCreateFlag> flags();
 }

com.io7m.jcoronado.api/src/main/java/com/io7m/jcoronado/api/VulkanSemaphoreCreateFlag.java → com.io7m.jcoronado.api/src/main/java/com/io7m/jcoronado/api/VulkanSemaphoreTimelineCreateInfoType.java

@@ -16,34 +16,24 @@
 
 package com.io7m.jcoronado.api;
 
+import com.io7m.immutables.styles.ImmutablesStyleType;
+import org.immutables.value.Value;
+
 /**
- * Flags specified when creating semaphores.
- *
- * Vulkan 1.1 specification: "VkSemaphoreCreateFlags is a bitmask type for setting a mask, but is
- * currently reserved for future use."
+ * The type of Vulkan timeline semaphore creation information.
  *
- * @see "VkSemaphoreCreateFlags"
+ * @see "VkSemaphoreTypeCreateInfo"
  */
 
-@VulkanAPIEnumType(vulkanEnum = "VkSemaphoreCreateFlags")
-public enum VulkanSemaphoreCreateFlag implements VulkanEnumBitmaskType
+@VulkanAPIStructType(vulkanStruct = "VkSemaphoreTypeCreateInfo")
+@ImmutablesStyleType
+@Value.Immutable
+public non-sealed interface VulkanSemaphoreTimelineCreateInfoType
+  extends VulkanSemaphoreCreateInfoType
 {
   /**
-   * No flags set.
+   * @return The initial semaphore value
    */
 
-  VK_SEMAPHORE_CREATE_FLAG_NONE(0x0);
-
-  private final int value;
-
-  VulkanSemaphoreCreateFlag(final int i)
-  {
-    this.value = i;
-  }
-
-  @Override
-  public int value()
-  {
-    return this.value;
-  }
+  long initialValue();
 }

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

@@ -0,0 +1,30 @@
+/*
+ * Copyright © 2018 Mark Raynsford <[email protected]> http://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;
+
+/**
+ * A semaphore represents a GPU to GPU synchronization.
+ *
+ * @see "VkSemaphore"
+ */
+
+public non-sealed interface VulkanSemaphoreTimelineType
+  extends VulkanSemaphoreType
+{
+
+}
+

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

@@ -22,7 +22,9 @@
  * @see "VkSemaphore"
  */
 
-public interface VulkanSemaphoreType extends VulkanHandleNonDispatchableType
+public sealed interface VulkanSemaphoreType
+  extends VulkanHandleNonDispatchableType
+  permits VulkanSemaphoreTimelineType, VulkanSemaphoreBinaryType
 {
   @VulkanAPIFunctionType(vulkanFunction = "vkDestroySemaphore")
   @Override

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

@@ -66,7 +66,7 @@
 import com.io7m.jcoronado.api.VulkanRenderPassBeginInfo;
 import com.io7m.jcoronado.api.VulkanRenderPassCreateInfo;
 import com.io7m.jcoronado.api.VulkanResourceException;
-import com.io7m.jcoronado.api.VulkanSemaphoreCreateInfo;
+import com.io7m.jcoronado.api.VulkanSemaphoreBinaryCreateInfo;
 import com.io7m.jcoronado.api.VulkanSemaphoreSubmitInfo;
 import com.io7m.jcoronado.api.VulkanSemaphoreType;
 import com.io7m.jcoronado.api.VulkanShaderModuleCreateInfo;
@@ -1316,14 +1316,14 @@ public void execute()
        */
 
       final var renderFinished =
-        resources.add(device.createSemaphore(
-          VulkanSemaphoreCreateInfo.builder()
-            .build()));
+        resources.add(device.createBinarySemaphore(
+          VulkanSemaphoreBinaryCreateInfo.builder().build()
+        ));
 
       final var imageAvailable =
-        resources.add(device.createSemaphore(
-          VulkanSemaphoreCreateInfo.builder()
-            .build()));
+        resources.add(device.createBinarySemaphore(
+          VulkanSemaphoreBinaryCreateInfo.builder().build()
+        ));
 
       /*
        * Start recording commands.

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

@@ -91,7 +91,7 @@
 import com.io7m.jcoronado.api.VulkanResourceException;
 import com.io7m.jcoronado.api.VulkanSamplerCreateInfo;
 import com.io7m.jcoronado.api.VulkanSamplerType;
-import com.io7m.jcoronado.api.VulkanSemaphoreCreateInfo;
+import com.io7m.jcoronado.api.VulkanSemaphoreBinaryCreateInfo;
 import com.io7m.jcoronado.api.VulkanSemaphoreSubmitInfo;
 import com.io7m.jcoronado.api.VulkanSemaphoreType;
 import com.io7m.jcoronado.api.VulkanShaderModuleCreateInfo;
@@ -2110,9 +2110,13 @@ public void execute()
        */
 
       final var renderFinished =
-        resources.add(device.createSemaphore(VulkanSemaphoreCreateInfo.builder().build()));
+        resources.add(device.createBinarySemaphore(
+          VulkanSemaphoreBinaryCreateInfo.builder().build()
+        ));
       final var imageAvailable =
-        resources.add(device.createSemaphore(VulkanSemaphoreCreateInfo.builder().build()));
+        resources.add(device.createBinarySemaphore(
+          VulkanSemaphoreBinaryCreateInfo.builder().build()
+        ));
 
       /*
        * Start recording commands.

com.io7m.jcoronado.fake/src/main/java/com/io7m/jcoronado/fake/VFakeLogicalDevice.java

@@ -72,8 +72,10 @@
 import com.io7m.jcoronado.api.VulkanRenderPassType;
 import com.io7m.jcoronado.api.VulkanSamplerCreateInfo;
 import com.io7m.jcoronado.api.VulkanSamplerType;
-import com.io7m.jcoronado.api.VulkanSemaphoreCreateInfo;
-import com.io7m.jcoronado.api.VulkanSemaphoreType;
+import com.io7m.jcoronado.api.VulkanSemaphoreBinaryCreateInfo;
+import com.io7m.jcoronado.api.VulkanSemaphoreBinaryType;
+import com.io7m.jcoronado.api.VulkanSemaphoreTimelineCreateInfo;
+import com.io7m.jcoronado.api.VulkanSemaphoreTimelineType;
 import com.io7m.jcoronado.api.VulkanShaderModuleCreateInfo;
 import com.io7m.jcoronado.api.VulkanShaderModuleType;
 import com.io7m.jcoronado.api.VulkanSubresourceLayout;
@@ -348,11 +350,19 @@ public List<VulkanCommandBufferType> createCommandBuffers(
   }
 
   @Override
-  public VulkanSemaphoreType createSemaphore(
-    final VulkanSemaphoreCreateInfo create_info)
+  public VulkanSemaphoreBinaryType createBinarySemaphore(
+    final VulkanSemaphoreBinaryCreateInfo info)
     throws VulkanException
   {
-    throw errorNotImplemented("createSemaphore");
+    throw errorNotImplemented("createBinarySemaphore");
+  }
+
+  @Override
+  public VulkanSemaphoreTimelineType createTimelineSemaphore(
+    final VulkanSemaphoreTimelineCreateInfo info)
+    throws VulkanException
+  {
+    throw errorNotImplemented("createTimelineSemaphore");
   }
 
   @Override

com.io7m.jcoronado.lwjgl/src/main/java/com/io7m/jcoronado/lwjgl/internal/VulkanLWJGLExtDebugUtils.java

@@ -355,7 +355,10 @@ private static OptionalInt objectTypeOfHandleInt(
       case final VulkanLWJGLSampler _ -> {
         yield OptionalInt.of(VK10.VK_OBJECT_TYPE_SAMPLER);
       }
-      case final VulkanLWJGLSemaphore _ -> {
+      case final VulkanLWJGLSemaphoreTimeline _ -> {
+        yield OptionalInt.of(VK10.VK_OBJECT_TYPE_SEMAPHORE);
+      }
+      case final VulkanLWJGLSemaphoreBinary _ -> {
         yield OptionalInt.of(VK10.VK_OBJECT_TYPE_SEMAPHORE);
       }
       case final VulkanLWJGLShaderModule _ -> {