Package org.lwjgl.vulkan

Class KHRSurface

java.lang.Object
org.lwjgl.vulkan.KHRSurface
public class KHRSurface extends Object
The VK_KHR_surface extension is an instance extension. It introduces VkSurfaceKHR objects, which abstract native platform surface or window objects for use with Vulkan. It also provides a way to determine whether a queue family in a physical device supports presenting to particular surface.

Separate extensions for each platform provide the mechanisms for creating VkSurfaceKHR objects, but once created they may be used in this and other platform-independent extensions, in particular the VK_KHR_swapchain extension.

Examples
Note

The example code for the VK_KHR_surface and VK_KHR_swapchain extensions was removed from the appendix after revision 1.0.29. This WSI example code was ported to the cube demo that is shipped with the official Khronos SDK, and is being kept up-to-date in that location (see: https://github.com/KhronosGroup/Vulkan-Tools/blob/main/cube/cube.c).

Name String
VK_KHR_surface
Extension Type
Instance extension
Registered Extension Number
1
Revision
25
Contact
Other Extension Metadata
Last Modified Date
2016-08-25
IP Status
No known IP claims.
Contributors
  • Patrick Doane, Blizzard
  • Ian Elliott, LunarG
  • Jesse Hall, Google
  • James Jones, NVIDIA
  • David Mao, AMD
  • Norbert Nopper, Freescale
  • Alon Or-bach, Samsung
  • Daniel Rakos, AMD
  • Graham Sellers, AMD
  • Jeff Vigil, Qualcomm
  • Chia-I Wu, LunarG
  • Faith Ekstrand, Intel

  • Field Details

  • Method Details

    • nvkDestroySurfaceKHR

      public static void nvkDestroySurfaceKHR(org.lwjgl.vulkan.VkInstance instance, long surface, long pAllocator)
      Unsafe version of: DestroySurfaceKHR

    • vkDestroySurfaceKHR

      public static void vkDestroySurfaceKHR(org.lwjgl.vulkan.VkInstance instance, long surface, @Nullable VkAllocationCallbacks pAllocator)
      Destroy a VkSurfaceKHR object.
      C Specification

      To destroy a VkSurfaceKHR object, call:

      
 void vkDestroySurfaceKHR(
     VkInstance                                  instance,
     VkSurfaceKHR                                surface,
     const VkAllocationCallbacks*                pAllocator);
      Description

      Destroying a VkSurfaceKHR merely severs the connection between Vulkan and the native surface, and does not imply destroying the native surface, closing a window, or similar behavior.

      Valid Usage
      • All VkSwapchainKHR objects created for surface must have been destroyed prior to destroying surface
      • If VkAllocationCallbacks were provided when surface was created, a compatible set of callbacks must be provided here
      • If no VkAllocationCallbacks were provided when surface was created, pAllocator must be NULL
      Valid Usage (Implicit)
      • instance must be a valid VkInstance handle
      • If surface is not NULL_HANDLE, surface must be a valid VkSurfaceKHR handle
      • If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure
      • If surface is a valid handle, it must have been created, allocated, or retrieved from instance
      Host Synchronization
      • Host access to surface must be externally synchronized
      See Also

      VkAllocationCallbacks

      Parameters:
      instance - the instance used to create the surface.
      surface - the surface to destroy.
      pAllocator - the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation).

    • nvkGetPhysicalDeviceSurfaceSupportKHR

      public static int nvkGetPhysicalDeviceSurfaceSupportKHR(org.lwjgl.vulkan.VkPhysicalDevice physicalDevice, int queueFamilyIndex, long surface, long pSupported)
      Unsafe version of: GetPhysicalDeviceSurfaceSupportKHR

    • vkGetPhysicalDeviceSurfaceSupportKHR

      public static int vkGetPhysicalDeviceSurfaceSupportKHR(org.lwjgl.vulkan.VkPhysicalDevice physicalDevice, int queueFamilyIndex, long surface, IntBuffer pSupported)
      Query if presentation is supported.
      C Specification

      To determine whether a queue family of a physical device supports presentation to a given surface, call:

      
 VkResult vkGetPhysicalDeviceSurfaceSupportKHR(
     VkPhysicalDevice                            physicalDevice,
     uint32_t                                    queueFamilyIndex,
     VkSurfaceKHR                                surface,
     VkBool32*                                   pSupported);
      Valid Usage
      • queueFamilyIndex must be less than pQueueFamilyPropertyCount returned by vkGetPhysicalDeviceQueueFamilyProperties for the given physicalDevice
      Valid Usage (Implicit)
      • physicalDevice must be a valid VkPhysicalDevice handle
      • surface must be a valid VkSurfaceKHR handle
      • pSupported must be a valid pointer to a VkBool32 value
      • Both of physicalDevice, and surface must have been created, allocated, or retrieved from the same VkInstance
      Return Codes
      On success, this command returns
      On failure, this command returns
      Parameters:
      physicalDevice - the physical device.
      queueFamilyIndex - the queue family.
      surface - the surface.
      pSupported - a pointer to a VkBool32. TRUE indicates support, and FALSE indicates no support.

    • nvkGetPhysicalDeviceSurfaceCapabilitiesKHR

      public static int nvkGetPhysicalDeviceSurfaceCapabilitiesKHR(org.lwjgl.vulkan.VkPhysicalDevice physicalDevice, long surface, long pSurfaceCapabilities)
      Unsafe version of: GetPhysicalDeviceSurfaceCapabilitiesKHR

    • vkGetPhysicalDeviceSurfaceCapabilitiesKHR

      public static int vkGetPhysicalDeviceSurfaceCapabilitiesKHR(org.lwjgl.vulkan.VkPhysicalDevice physicalDevice, long surface, VkSurfaceCapabilitiesKHR pSurfaceCapabilities)
      Query surface capabilities.
      C Specification

      To query the basic capabilities of a surface, needed in order to create a swapchain, call:

      
 VkResult vkGetPhysicalDeviceSurfaceCapabilitiesKHR(
     VkPhysicalDevice                            physicalDevice,
     VkSurfaceKHR                                surface,
     VkSurfaceCapabilitiesKHR*                   pSurfaceCapabilities);
      Valid Usage
      • surface must be a valid VkSurfaceKHR handle
      • surface must be supported by physicalDevice, as reported by GetPhysicalDeviceSurfaceSupportKHR or an equivalent platform-specific mechanism
      Valid Usage (Implicit)
      • physicalDevice must be a valid VkPhysicalDevice handle
      • surface must be a valid VkSurfaceKHR handle
      • pSurfaceCapabilities must be a valid pointer to a VkSurfaceCapabilitiesKHR structure
      • Both of physicalDevice, and surface must have been created, allocated, or retrieved from the same VkInstance
      Return Codes
      On success, this command returns
      On failure, this command returns
      See Also

      VkSurfaceCapabilitiesKHR

      Parameters:
      physicalDevice - the physical device that will be associated with the swapchain to be created, as described for CreateSwapchainKHR.
      surface - the surface that will be associated with the swapchain.
      pSurfaceCapabilities - a pointer to a VkSurfaceCapabilitiesKHR structure in which the capabilities are returned.

    • nvkGetPhysicalDeviceSurfaceFormatsKHR

      public static int nvkGetPhysicalDeviceSurfaceFormatsKHR(org.lwjgl.vulkan.VkPhysicalDevice physicalDevice, long surface, long pSurfaceFormatCount, long pSurfaceFormats)
      Unsafe version of: GetPhysicalDeviceSurfaceFormatsKHR
      Parameters:
      pSurfaceFormatCount - a pointer to an integer related to the number of format pairs available or queried, as described below.

    • vkGetPhysicalDeviceSurfaceFormatsKHR

      public static int vkGetPhysicalDeviceSurfaceFormatsKHR(org.lwjgl.vulkan.VkPhysicalDevice physicalDevice, long surface, IntBuffer pSurfaceFormatCount, @Nullable VkSurfaceFormatKHR.Buffer pSurfaceFormats)
      Query color formats supported by surface.
      C Specification

      To query the supported swapchain format-color space pairs for a surface, call:

      
 VkResult vkGetPhysicalDeviceSurfaceFormatsKHR(
     VkPhysicalDevice                            physicalDevice,
     VkSurfaceKHR                                surface,
     uint32_t*                                   pSurfaceFormatCount,
     VkSurfaceFormatKHR*                         pSurfaceFormats);
      Description

      If pSurfaceFormats is NULL, then the number of format pairs supported for the given surface is returned in pSurfaceFormatCount. Otherwise, pSurfaceFormatCount must point to a variable set by the application to the number of elements in the pSurfaceFormats array, and on return the variable is overwritten with the number of structures actually written to pSurfaceFormats. If the value of pSurfaceFormatCount is less than the number of format pairs supported, at most pSurfaceFormatCount structures will be written, and INCOMPLETE will be returned instead of SUCCESS, to indicate that not all the available format pairs were returned.

      The number of format pairs supported must be greater than or equal to 1. pSurfaceFormats must not contain an entry whose value for format is FORMAT_UNDEFINED.

      If pSurfaceFormats includes an entry whose value for colorSpace is COLOR_SPACE_SRGB_NONLINEAR_KHR and whose value for format is a UNORM (or SRGB) format and the corresponding SRGB (or UNORM) format is a color renderable format for IMAGE_TILING_OPTIMAL, then pSurfaceFormats must also contain an entry with the same value for colorSpace and format equal to the corresponding SRGB (or UNORM) format.

      If the VK_GOOGLE_surfaceless_query extension is enabled, the values returned in pSurfaceFormats will be identical for every valid surface created on this physical device, and so surface can be NULL_HANDLE.

      Valid Usage
      Valid Usage (Implicit)
      • physicalDevice must be a valid VkPhysicalDevice handle
      • If surface is not NULL_HANDLE, surface must be a valid VkSurfaceKHR handle
      • pSurfaceFormatCount must be a valid pointer to a uint32_t value
      • If the value referenced by pSurfaceFormatCount is not 0, and pSurfaceFormats is not NULL, pSurfaceFormats must be a valid pointer to an array of pSurfaceFormatCount VkSurfaceFormatKHR structures
      • Both of physicalDevice, and surface that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkInstance
      Return Codes
      On success, this command returns
      On failure, this command returns
      See Also

      VkSurfaceFormatKHR

      Parameters:
      physicalDevice - the physical device that will be associated with the swapchain to be created, as described for CreateSwapchainKHR.
      surface - the surface that will be associated with the swapchain.
      pSurfaceFormatCount - a pointer to an integer related to the number of format pairs available or queried, as described below.
      pSurfaceFormats - either NULL or a pointer to an array of VkSurfaceFormatKHR structures.

    • nvkGetPhysicalDeviceSurfacePresentModesKHR

      public static int nvkGetPhysicalDeviceSurfacePresentModesKHR(org.lwjgl.vulkan.VkPhysicalDevice physicalDevice, long surface, long pPresentModeCount, long pPresentModes)
      Unsafe version of: GetPhysicalDeviceSurfacePresentModesKHR
      Parameters:
      pPresentModeCount - a pointer to an integer related to the number of presentation modes available or queried, as described below.

    • vkGetPhysicalDeviceSurfacePresentModesKHR

      public static int vkGetPhysicalDeviceSurfacePresentModesKHR(org.lwjgl.vulkan.VkPhysicalDevice physicalDevice, long surface, IntBuffer pPresentModeCount, @Nullable IntBuffer pPresentModes)
      Query supported presentation modes.
      C Specification

      To query the supported presentation modes for a surface, call:

      
 VkResult vkGetPhysicalDeviceSurfacePresentModesKHR(
     VkPhysicalDevice                            physicalDevice,
     VkSurfaceKHR                                surface,
     uint32_t*                                   pPresentModeCount,
     VkPresentModeKHR*                           pPresentModes);
      Description

      If pPresentModes is NULL, then the number of presentation modes supported for the given surface is returned in pPresentModeCount. Otherwise, pPresentModeCount must point to a variable set by the application to the number of elements in the pPresentModes array, and on return the variable is overwritten with the number of values actually written to pPresentModes. If the value of pPresentModeCount is less than the number of presentation modes supported, at most pPresentModeCount values will be written, and INCOMPLETE will be returned instead of SUCCESS, to indicate that not all the available modes were returned.

      If the VK_GOOGLE_surfaceless_query extension is enabled and surface is NULL_HANDLE, the values returned in pPresentModes will only indicate support for PRESENT_MODE_FIFO_KHR, PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR, and PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR. To query support for any other present mode, a valid handle must be provided in surface.

      Valid Usage
      Valid Usage (Implicit)
      • physicalDevice must be a valid VkPhysicalDevice handle
      • If surface is not NULL_HANDLE, surface must be a valid VkSurfaceKHR handle
      • pPresentModeCount must be a valid pointer to a uint32_t value
      • If the value referenced by pPresentModeCount is not 0, and pPresentModes is not NULL, pPresentModes must be a valid pointer to an array of pPresentModeCount VkPresentModeKHR values
      • Both of physicalDevice, and surface that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkInstance
      Return Codes
      On success, this command returns
      On failure, this command returns
      Parameters:
      physicalDevice - the physical device that will be associated with the swapchain to be created, as described for CreateSwapchainKHR.
      surface - the surface that will be associated with the swapchain.
      pPresentModeCount - a pointer to an integer related to the number of presentation modes available or queried, as described below.
      pPresentModes - either NULL or a pointer to an array of VkPresentModeKHR values, indicating the supported presentation modes.

    • vkGetPhysicalDeviceSurfaceSupportKHR

      public static int vkGetPhysicalDeviceSurfaceSupportKHR(org.lwjgl.vulkan.VkPhysicalDevice physicalDevice, int queueFamilyIndex, long surface, int[] pSupported)
      Array version of: GetPhysicalDeviceSurfaceSupportKHR

    • vkGetPhysicalDeviceSurfaceFormatsKHR

      public static int vkGetPhysicalDeviceSurfaceFormatsKHR(org.lwjgl.vulkan.VkPhysicalDevice physicalDevice, long surface, int[] pSurfaceFormatCount, @Nullable VkSurfaceFormatKHR.Buffer pSurfaceFormats)
      Array version of: GetPhysicalDeviceSurfaceFormatsKHR

    • vkGetPhysicalDeviceSurfacePresentModesKHR

      public static int vkGetPhysicalDeviceSurfacePresentModesKHR(org.lwjgl.vulkan.VkPhysicalDevice physicalDevice, long surface, int[] pPresentModeCount, int @Nullable [] pPresentModes)
      Array version of: GetPhysicalDeviceSurfacePresentModesKHR