update Vulkan sample with external memory and semaphore sharing (#59)

* started to add interop functions but still crashes

* slightly working version

* successfully create an image from external memory

* revert a few other testing changes

* basic memory sharing is working

* fix dummy object codepath with host copy

* fix validation errors

* start to add external semaphore support

* add support for synchronization via semaphores

* reduce verbosity by default, start to add Linux support

* fix Linux builds

* fix dependency on OpenCL extension loader

* fix Linux function name typo

* remove nvidia workarounds, dependency on extension loader

* tidy up command line options, update readme

* remove unused vector of wait semaphores

* update readme to recommend installing the latest drivers

* fix incorrect handle type for external semaphore

* fix incorrect app name

* add a command-line option for VK_PRESENT_MODE_IMMEDIATE_KHR

* try to add support for dma_buf sharing on Linux

* fix whitespace

* add a command line option to disable device local images

Author: bashbaug

include/CL/opencl.hpp

@@ -1547,6 +1547,18 @@ CL_HPP_DECLARE_PARAM_TRAITS_(cl_command_buffer_info_khr, CL_COMMAND_BUFFER_STATE
 CL_HPP_DECLARE_PARAM_TRAITS_(cl_command_buffer_info_khr, CL_COMMAND_BUFFER_PROPERTIES_ARRAY_KHR, cl::vector<cl_command_buffer_properties_khr>)
 #endif // cl_khr_command_buffer
 
+#if defined(cl_khr_external_memory)
+CL_HPP_DECLARE_PARAM_TRAITS_(cl_platform_info, CL_PLATFORM_EXTERNAL_MEMORY_IMPORT_HANDLE_TYPES_KHR, cl::vector<cl_external_memory_handle_type_khr>)
+CL_HPP_DECLARE_PARAM_TRAITS_(cl_device_info, CL_DEVICE_EXTERNAL_MEMORY_IMPORT_HANDLE_TYPES_KHR, cl::vector<cl_external_memory_handle_type_khr>)
+#endif // cl_khr_external_memory
+
+#if defined(cl_khr_external_semaphore)
+CL_HPP_DECLARE_PARAM_TRAITS_(cl_platform_info, CL_PLATFORM_SEMAPHORE_IMPORT_HANDLE_TYPES_KHR, cl::vector<cl_external_semaphore_handle_type_khr>)
+CL_HPP_DECLARE_PARAM_TRAITS_(cl_platform_info, CL_PLATFORM_SEMAPHORE_EXPORT_HANDLE_TYPES_KHR, cl::vector<cl_external_semaphore_handle_type_khr>)
+CL_HPP_DECLARE_PARAM_TRAITS_(cl_device_info, CL_DEVICE_SEMAPHORE_IMPORT_HANDLE_TYPES_KHR, cl::vector<cl_external_semaphore_handle_type_khr>)
+CL_HPP_DECLARE_PARAM_TRAITS_(cl_device_info, CL_DEVICE_SEMAPHORE_EXPORT_HANDLE_TYPES_KHR, cl::vector<cl_external_semaphore_handle_type_khr>)
+#endif // cl_khr_external_semaphore
+
 #ifdef CL_PLATFORM_ICD_SUFFIX_KHR
 CL_HPP_DECLARE_PARAM_TRAITS_(cl_platform_info, CL_PLATFORM_ICD_SUFFIX_KHR, string)
 #endif

samples/vulkan/00_juliavk/CMakeLists.txt

@@ -1,4 +1,4 @@
-# Copyright (c) 2021 Ben Ashbaugh
+# Copyright (c) 2021-2022 Ben Ashbaugh
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -21,7 +21,7 @@
 add_opencl_sample(
     NUMBER 00
     TARGET juliavk
-    VERSION 120
+    VERSION 300 # clCreateImageWithProperties
     CATEGORY vulkan
     SOURCES main.cpp
     KERNELS juliavk.vert.spv juliavk.frag.spv

samples/vulkan/00_juliavk/README.md

@@ -6,12 +6,51 @@ This is a modified version of the earlier Julia set sample.
 Similar to the earlier Julia Set sample, an OpenCL kernel is used to generate a Julia set image.
 The main difference between this sample and the earlier sample is that in this sample the Julia set image is used as an Vulkan texture and rendered to the screen instead of writing it to a BMP file.
 
-This sample currently copies the result of the OpenCL kernel to the Vulkan texture on the host, however several new extensions were recently provisionally released to enable [interop between OpenCL and Vulkan devices](https://www.khronos.org/blog/khronos-releases-opencl-3.0-extensions-for-neural-network-inferencing-and-opencl-vulkan-interop).
-When drivers are available that support these extensions, this sample will be updated to use them!
+This sample can create an OpenCL image directly from the Vulkan texture when supported.
+In order to share the Vulkan texture with OpenCL, the OpenCL device must support [cl_khr_external_memory](https://registry.khronos.org/OpenCL/specs/3.0-unified/html/OpenCL_Ext.html#cl_khr_external_memory).
+Additionally, the Vulkan device must support exporting the Vulkan texture as an OS-specific external memory handle, and the OpenCL device must support importing external memory handles of that type.
+Creating the OpenCL image directly from the Vulkan texture avoids a memory copy and can improve performance.
+
+For Windows, the external memory handle types that are currently supported are:
+
+* `CL_EXTERNAL_MEMORY_HANDLE_OPAQUE_WIN32_KHR`
+
+For Linux, the external memory handle types that are currently supported are:
+
+* `CL_EXTERNAL_MEMORY_HANDLE_DMA_BUF_KHR`
+* `CL_EXTERNAL_MEMORY_HANDLE_OPAQUE_FD_KHR`
+
+This sample can also share semaphores between Vulkan and OpenCL when supported.
+In order to share a Vulkan semaphore with OpenCL, the OpenCL device must support [cl_khr_external_semaphore](https://registry.khronos.org/OpenCL/specs/3.0-unified/html/OpenCL_Ext.html#cl_khr_external_semaphore).
+Additionally, the Vulkan device must support exporting the Vulkan semaphore as an OS-specific external semaphore handle, and the OpenCL device must support importing external semaphore handles of that type.
+Sharing a semaphore object between Vulkan and OpenCL avoids synchronization on the host and can also improve performance.
+
+For Windows, the external semaphore handle types that are currently supported are:
+
+* `CL_SEMAPHORE_HANDLE_OPAQUE_WIN32_KHR`
+
+For Linux, the external semaphore handle types that are currently supported are:
+
+* `CL_SEMAPHORE_HANDLE_OPAQUE_FD_KHR`
+
+For more information about these extensions, please see [this blog post](https://www.khronos.org/blog/khronos-releases-opencl-3.0-extensions-for-neural-network-inferencing-and-opencl-vulkan-interop).
+When the extensions are not supported the sample will still run, although perhaps with lower performance.
+
+Important note: The OpenCL extensions used in this sample are very new!
+If the sample does not run correctly please ensure you are using the latest OpenCL drivers for your device, or use the command line option to force copying on the host.
 
 ## Key APIs and Concepts
 
-This example shows how to share an Vulkan texture with OpenCL.
+This example shows how to share an Vulkan texture and semaphore with OpenCL.
+
+```c
+clEnqueueAcquireExternalMemObjectsKHR
+clEnqueueReleaseExternalMemObjectsKHR
+
+clCreateSemaphoreWithPropertiesKHR
+clEnqueueSignalSemaphoresKHR
+clReleaseSemaphoreKHR
+```
 
 ## Command Line Options
 
@@ -21,10 +60,14 @@ Note: Many of these command line arguments are identical to the earlier Julia se
 |:--|:-:|:--|
 | `-d <index>` | 0 | Specify the index of the OpenCL device in the platform to execute on the sample on.
 | `-p <index>` | 0 | Specify the index of the OpenCL platform to execute the sample on.
+| `--hostcopy` | n/a | Do not use the `cl_khr_external_memory` extension and unconditionally copy on the host.
+| `--hostsync` | n/a | Do not use the `cl_khr_external_semaphore` extension and exclusively synchronize on the host.
+| `--nodevicelocal` | n/a | Do not use device local images (`VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT`).  May be useful for debugging.
 | `--gwx <number>` | 512 | Specify the global work size to execute, in the X direction.  This also determines the width of the generated image.
 | `--gwy <number>` | 512 | Specify the global work size to execute, in the Y direction.  This also determines the height of the generated image.
 | `--lwx <number>` | 0 | Specify the local work size in the X direction.  If either local works size dimension is zero a `NULL` local work size is used.
 | `--lwy <number>` | 0 | Specify the local work size in the Y direction.  If either local works size dimension is zero a `NULL` local work size is used.
+| `--immediate` | n/a | Prefer `VK_PRESENT_MODE_IMMEDIATE_KHR` (no vsync).  May result in faster framerates at the cost of visible tearing.
 
 ## Controls While Running