Top Description Fields Constructors Methods
org.lwjgl.vulkan

public Class KHRSurface

extends Object
Class Inheritance
Imports
javax.annotation.*, java.nio.*, org.lwjgl.system.*
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/master/cube/cube.c).

VK_KHR_surface
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 Summary

Modifier and TypeField and Description
public static final int
VK_COLOR_SPACE_SRGB_NONLINEAR_KHR

VkColorSpaceKHR - Supported color space of the presentation engine Description

public static final int
VK_COLORSPACE_SRGB_NONLINEAR_KHR

VkColorSpaceKHR - Supported color space of the presentation engine Description

public static final int
VK_COMPOSITE_ALPHA_INHERIT_BIT_KHR

VkCompositeAlphaFlagBitsKHR - Alpha compositing modes supported on a device Description

These values are described as follows:

  • COMPOSITE_ALPHA_OPAQUE_BIT_KHR: The alpha component, if it exists, of the images is ignored in the compositing process. Instead, the image is treated as if it has a constant alpha of 1.0.
  • COMPOSITE_ALPHA_PRE_MULTIPLIED_BIT_KHR: The alpha component, if it exists, of the images is respected in the compositing process. The non-alpha components of the image are expected to already be multiplied by the alpha component by the application.
  • COMPOSITE_ALPHA_POST_MULTIPLIED_BIT_KHR: The alpha component, if it exists, of the images is respected in the compositing process. The non-alpha components of the image are not expected to already be multiplied by the alpha component by the application; instead, the compositor will multiply the non-alpha components of the image by the alpha component during compositing.
  • COMPOSITE_ALPHA_INHERIT_BIT_KHR: The way in which the presentation engine treats the alpha component in the images is unknown to the Vulkan API. Instead, the application is responsible for setting the composite alpha blending mode using native window system commands. If the application does not set the blending mode using native window system commands, then a platform-specific default will be used.
public static final int
VK_COMPOSITE_ALPHA_OPAQUE_BIT_KHR

VkCompositeAlphaFlagBitsKHR - Alpha compositing modes supported on a device Description

These values are described as follows:

  • COMPOSITE_ALPHA_OPAQUE_BIT_KHR: The alpha component, if it exists, of the images is ignored in the compositing process. Instead, the image is treated as if it has a constant alpha of 1.0.
  • COMPOSITE_ALPHA_PRE_MULTIPLIED_BIT_KHR: The alpha component, if it exists, of the images is respected in the compositing process. The non-alpha components of the image are expected to already be multiplied by the alpha component by the application.
  • COMPOSITE_ALPHA_POST_MULTIPLIED_BIT_KHR: The alpha component, if it exists, of the images is respected in the compositing process. The non-alpha components of the image are not expected to already be multiplied by the alpha component by the application; instead, the compositor will multiply the non-alpha components of the image by the alpha component during compositing.
  • COMPOSITE_ALPHA_INHERIT_BIT_KHR: The way in which the presentation engine treats the alpha component in the images is unknown to the Vulkan API. Instead, the application is responsible for setting the composite alpha blending mode using native window system commands. If the application does not set the blending mode using native window system commands, then a platform-specific default will be used.
public static final int
VK_COMPOSITE_ALPHA_POST_MULTIPLIED_BIT_KHR

VkCompositeAlphaFlagBitsKHR - Alpha compositing modes supported on a device Description

These values are described as follows:

  • COMPOSITE_ALPHA_OPAQUE_BIT_KHR: The alpha component, if it exists, of the images is ignored in the compositing process. Instead, the image is treated as if it has a constant alpha of 1.0.
  • COMPOSITE_ALPHA_PRE_MULTIPLIED_BIT_KHR: The alpha component, if it exists, of the images is respected in the compositing process. The non-alpha components of the image are expected to already be multiplied by the alpha component by the application.
  • COMPOSITE_ALPHA_POST_MULTIPLIED_BIT_KHR: The alpha component, if it exists, of the images is respected in the compositing process. The non-alpha components of the image are not expected to already be multiplied by the alpha component by the application; instead, the compositor will multiply the non-alpha components of the image by the alpha component during compositing.
  • COMPOSITE_ALPHA_INHERIT_BIT_KHR: The way in which the presentation engine treats the alpha component in the images is unknown to the Vulkan API. Instead, the application is responsible for setting the composite alpha blending mode using native window system commands. If the application does not set the blending mode using native window system commands, then a platform-specific default will be used.
public static final int
VK_COMPOSITE_ALPHA_PRE_MULTIPLIED_BIT_KHR

VkCompositeAlphaFlagBitsKHR - Alpha compositing modes supported on a device Description

These values are described as follows:

  • COMPOSITE_ALPHA_OPAQUE_BIT_KHR: The alpha component, if it exists, of the images is ignored in the compositing process. Instead, the image is treated as if it has a constant alpha of 1.0.
  • COMPOSITE_ALPHA_PRE_MULTIPLIED_BIT_KHR: The alpha component, if it exists, of the images is respected in the compositing process. The non-alpha components of the image are expected to already be multiplied by the alpha component by the application.
  • COMPOSITE_ALPHA_POST_MULTIPLIED_BIT_KHR: The alpha component, if it exists, of the images is respected in the compositing process. The non-alpha components of the image are not expected to already be multiplied by the alpha component by the application; instead, the compositor will multiply the non-alpha components of the image by the alpha component during compositing.
  • COMPOSITE_ALPHA_INHERIT_BIT_KHR: The way in which the presentation engine treats the alpha component in the images is unknown to the Vulkan API. Instead, the application is responsible for setting the composite alpha blending mode using native window system commands. If the application does not set the blending mode using native window system commands, then a platform-specific default will be used.
public static final int
VK_ERROR_NATIVE_WINDOW_IN_USE_KHR

Extends VkResult.

public static final int
VK_ERROR_SURFACE_LOST_KHR

Extends VkResult.

public static final String
VK_KHR_SURFACE_EXTENSION_NAME

The extension name.

public static final int
VK_KHR_SURFACE_SPEC_VERSION

The extension specification version.

public static final int
VK_OBJECT_TYPE_SURFACE_KHR

Extends VkObjectType.

public static final int
VK_PRESENT_MODE_FIFO_KHR

VkPresentModeKHR - Presentation mode supported for a surface Description

  • PRESENT_MODE_IMMEDIATE_KHR specifies that the presentation engine does not wait for a vertical blanking period to update the current image, meaning this mode may result in visible tearing. No internal queuing of presentation requests is needed, as the requests are applied immediately.
  • PRESENT_MODE_MAILBOX_KHR specifies that the presentation engine waits for the next vertical blanking period to update the current image. Tearing cannot be observed. An internal single-entry queue is used to hold pending presentation requests. If the queue is full when a new presentation request is received, the new request replaces the existing entry, and any images associated with the prior entry become available for reuse by the application. One request is removed from the queue and processed during each vertical blanking period in which the queue is non-empty.
  • PRESENT_MODE_FIFO_KHR specifies that the presentation engine waits for the next vertical blanking period to update the current image. Tearing cannot be observed. An internal queue is used to hold pending presentation requests. New requests are appended to the end of the queue, and one request is removed from the beginning of the queue and processed during each vertical blanking period in which the queue is non-empty. This is the only value of presentMode that is required to be supported.
  • PRESENT_MODE_FIFO_RELAXED_KHR specifies that the presentation engine generally waits for the next vertical blanking period to update the current image. If a vertical blanking period has already passed since the last update of the current image then the presentation engine does not wait for another vertical blanking period for the update, meaning this mode may result in visible tearing in this case. This mode is useful for reducing visual stutter with an application that will mostly present a new image before the next vertical blanking period, but may occasionally be late, and present a new image just after the next vertical blanking period. An internal queue is used to hold pending presentation requests. New requests are appended to the end of the queue, and one request is removed from the beginning of the queue and processed during or after each vertical blanking period in which the queue is non-empty.
  • PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR specifies that the presentation engine and application have concurrent access to a single image, which is referred to as a shared presentable image. The presentation engine is only required to update the current image after a new presentation request is received. Therefore the application must make a presentation request whenever an update is required. However, the presentation engine may update the current image at any point, meaning this mode may result in visible tearing.
  • PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR specifies that the presentation engine and application have concurrent access to a single image, which is referred to as a shared presentable image. The presentation engine periodically updates the current image on its regular refresh cycle. The application is only required to make one initial presentation request, after which the presentation engine must update the current image without any need for further presentation requests. The application can indicate the image contents have been updated by making a presentation request, but this does not guarantee the timing of when it will be updated. This mode may result in visible tearing if rendering to the image is not timed correctly.
public static final int
VK_PRESENT_MODE_FIFO_RELAXED_KHR

VkPresentModeKHR - Presentation mode supported for a surface Description

  • PRESENT_MODE_IMMEDIATE_KHR specifies that the presentation engine does not wait for a vertical blanking period to update the current image, meaning this mode may result in visible tearing. No internal queuing of presentation requests is needed, as the requests are applied immediately.
  • PRESENT_MODE_MAILBOX_KHR specifies that the presentation engine waits for the next vertical blanking period to update the current image. Tearing cannot be observed. An internal single-entry queue is used to hold pending presentation requests. If the queue is full when a new presentation request is received, the new request replaces the existing entry, and any images associated with the prior entry become available for reuse by the application. One request is removed from the queue and processed during each vertical blanking period in which the queue is non-empty.
  • PRESENT_MODE_FIFO_KHR specifies that the presentation engine waits for the next vertical blanking period to update the current image. Tearing cannot be observed. An internal queue is used to hold pending presentation requests. New requests are appended to the end of the queue, and one request is removed from the beginning of the queue and processed during each vertical blanking period in which the queue is non-empty. This is the only value of presentMode that is required to be supported.
  • PRESENT_MODE_FIFO_RELAXED_KHR specifies that the presentation engine generally waits for the next vertical blanking period to update the current image. If a vertical blanking period has already passed since the last update of the current image then the presentation engine does not wait for another vertical blanking period for the update, meaning this mode may result in visible tearing in this case. This mode is useful for reducing visual stutter with an application that will mostly present a new image before the next vertical blanking period, but may occasionally be late, and present a new image just after the next vertical blanking period. An internal queue is used to hold pending presentation requests. New requests are appended to the end of the queue, and one request is removed from the beginning of the queue and processed during or after each vertical blanking period in which the queue is non-empty.
  • PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR specifies that the presentation engine and application have concurrent access to a single image, which is referred to as a shared presentable image. The presentation engine is only required to update the current image after a new presentation request is received. Therefore the application must make a presentation request whenever an update is required. However, the presentation engine may update the current image at any point, meaning this mode may result in visible tearing.
  • PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR specifies that the presentation engine and application have concurrent access to a single image, which is referred to as a shared presentable image. The presentation engine periodically updates the current image on its regular refresh cycle. The application is only required to make one initial presentation request, after which the presentation engine must update the current image without any need for further presentation requests. The application can indicate the image contents have been updated by making a presentation request, but this does not guarantee the timing of when it will be updated. This mode may result in visible tearing if rendering to the image is not timed correctly.
public static final int
VK_PRESENT_MODE_IMMEDIATE_KHR

VkPresentModeKHR - Presentation mode supported for a surface Description

  • PRESENT_MODE_IMMEDIATE_KHR specifies that the presentation engine does not wait for a vertical blanking period to update the current image, meaning this mode may result in visible tearing. No internal queuing of presentation requests is needed, as the requests are applied immediately.
  • PRESENT_MODE_MAILBOX_KHR specifies that the presentation engine waits for the next vertical blanking period to update the current image. Tearing cannot be observed. An internal single-entry queue is used to hold pending presentation requests. If the queue is full when a new presentation request is received, the new request replaces the existing entry, and any images associated with the prior entry become available for reuse by the application. One request is removed from the queue and processed during each vertical blanking period in which the queue is non-empty.
  • PRESENT_MODE_FIFO_KHR specifies that the presentation engine waits for the next vertical blanking period to update the current image. Tearing cannot be observed. An internal queue is used to hold pending presentation requests. New requests are appended to the end of the queue, and one request is removed from the beginning of the queue and processed during each vertical blanking period in which the queue is non-empty. This is the only value of presentMode that is required to be supported.
  • PRESENT_MODE_FIFO_RELAXED_KHR specifies that the presentation engine generally waits for the next vertical blanking period to update the current image. If a vertical blanking period has already passed since the last update of the current image then the presentation engine does not wait for another vertical blanking period for the update, meaning this mode may result in visible tearing in this case. This mode is useful for reducing visual stutter with an application that will mostly present a new image before the next vertical blanking period, but may occasionally be late, and present a new image just after the next vertical blanking period. An internal queue is used to hold pending presentation requests. New requests are appended to the end of the queue, and one request is removed from the beginning of the queue and processed during or after each vertical blanking period in which the queue is non-empty.
  • PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR specifies that the presentation engine and application have concurrent access to a single image, which is referred to as a shared presentable image. The presentation engine is only required to update the current image after a new presentation request is received. Therefore the application must make a presentation request whenever an update is required. However, the presentation engine may update the current image at any point, meaning this mode may result in visible tearing.
  • PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR specifies that the presentation engine and application have concurrent access to a single image, which is referred to as a shared presentable image. The presentation engine periodically updates the current image on its regular refresh cycle. The application is only required to make one initial presentation request, after which the presentation engine must update the current image without any need for further presentation requests. The application can indicate the image contents have been updated by making a presentation request, but this does not guarantee the timing of when it will be updated. This mode may result in visible tearing if rendering to the image is not timed correctly.
public static final int
VK_PRESENT_MODE_MAILBOX_KHR

VkPresentModeKHR - Presentation mode supported for a surface Description

  • PRESENT_MODE_IMMEDIATE_KHR specifies that the presentation engine does not wait for a vertical blanking period to update the current image, meaning this mode may result in visible tearing. No internal queuing of presentation requests is needed, as the requests are applied immediately.
  • PRESENT_MODE_MAILBOX_KHR specifies that the presentation engine waits for the next vertical blanking period to update the current image. Tearing cannot be observed. An internal single-entry queue is used to hold pending presentation requests. If the queue is full when a new presentation request is received, the new request replaces the existing entry, and any images associated with the prior entry become available for reuse by the application. One request is removed from the queue and processed during each vertical blanking period in which the queue is non-empty.
  • PRESENT_MODE_FIFO_KHR specifies that the presentation engine waits for the next vertical blanking period to update the current image. Tearing cannot be observed. An internal queue is used to hold pending presentation requests. New requests are appended to the end of the queue, and one request is removed from the beginning of the queue and processed during each vertical blanking period in which the queue is non-empty. This is the only value of presentMode that is required to be supported.
  • PRESENT_MODE_FIFO_RELAXED_KHR specifies that the presentation engine generally waits for the next vertical blanking period to update the current image. If a vertical blanking period has already passed since the last update of the current image then the presentation engine does not wait for another vertical blanking period for the update, meaning this mode may result in visible tearing in this case. This mode is useful for reducing visual stutter with an application that will mostly present a new image before the next vertical blanking period, but may occasionally be late, and present a new image just after the next vertical blanking period. An internal queue is used to hold pending presentation requests. New requests are appended to the end of the queue, and one request is removed from the beginning of the queue and processed during or after each vertical blanking period in which the queue is non-empty.
  • PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR specifies that the presentation engine and application have concurrent access to a single image, which is referred to as a shared presentable image. The presentation engine is only required to update the current image after a new presentation request is received. Therefore the application must make a presentation request whenever an update is required. However, the presentation engine may update the current image at any point, meaning this mode may result in visible tearing.
  • PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR specifies that the presentation engine and application have concurrent access to a single image, which is referred to as a shared presentable image. The presentation engine periodically updates the current image on its regular refresh cycle. The application is only required to make one initial presentation request, after which the presentation engine must update the current image without any need for further presentation requests. The application can indicate the image contents have been updated by making a presentation request, but this does not guarantee the timing of when it will be updated. This mode may result in visible tearing if rendering to the image is not timed correctly.
public static final int
VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_BIT_KHR

VkSurfaceTransformFlagBitsKHR - Presentation transforms supported on a device Description

public static final int
VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_180_BIT_KHR

VkSurfaceTransformFlagBitsKHR - Presentation transforms supported on a device Description

public static final int
VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_270_BIT_KHR

VkSurfaceTransformFlagBitsKHR - Presentation transforms supported on a device Description

public static final int
VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_90_BIT_KHR

VkSurfaceTransformFlagBitsKHR - Presentation transforms supported on a device Description

public static final int
VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR

VkSurfaceTransformFlagBitsKHR - Presentation transforms supported on a device Description

public static final int
VK_SURFACE_TRANSFORM_INHERIT_BIT_KHR

VkSurfaceTransformFlagBitsKHR - Presentation transforms supported on a device Description

public static final int
VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR

VkSurfaceTransformFlagBitsKHR - Presentation transforms supported on a device Description

public static final int
VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR

VkSurfaceTransformFlagBitsKHR - Presentation transforms supported on a device Description

public static final int
VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR

VkSurfaceTransformFlagBitsKHR - Presentation transforms supported on a device Description

Constructor Summary

AccessConstructor and Description
protected
KHRSurface()

Method Summary

Modifier and TypeMethod and Description
public static void
nvkDestroySurfaceKHR(VkInstance instance, long surface, long pAllocator)

Unsafe version of: DestroySurfaceKHR

public static int
nvkGetPhysicalDeviceSurfaceCapabilitiesKHR(VkPhysicalDevice physicalDevice, long surface, long pSurfaceCapabilities)

Unsafe version of: GetPhysicalDeviceSurfaceCapabilitiesKHR

public static int
nvkGetPhysicalDeviceSurfaceFormatsKHR(VkPhysicalDevice physicalDevice, long surface, long
a pointer to an integer related to the number of format pairs available or queried, as described below.
pSurfaceFormatCount, long pSurfaceFormats)

Unsafe version of: GetPhysicalDeviceSurfaceFormatsKHR

public static int
nvkGetPhysicalDeviceSurfacePresentModesKHR(VkPhysicalDevice physicalDevice, long surface, long
a pointer to an integer related to the number of presentation modes available or queried, as described below.
pPresentModeCount, long pPresentModes)

Unsafe version of: GetPhysicalDeviceSurfacePresentModesKHR

public static int
nvkGetPhysicalDeviceSurfaceSupportKHR(VkPhysicalDevice physicalDevice, int queueFamilyIndex, long surface, long pSupported)

Unsafe version of: GetPhysicalDeviceSurfaceSupportKHR

public static void
vkDestroySurfaceKHR(VkInstance
the instance used to create the surface.
instance, long
the surface to destroy.
surface, VkAllocationCallbacks
the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation).
pAllocator)

Destroy a VkSurfaceKHR object.

public static int
vkGetPhysicalDeviceSurfaceCapabilitiesKHR(VkPhysicalDevice
the physical device that will be associated with the swapchain to be created, as described for CreateSwapchainKHR.
physicalDevice, long
the surface that will be associated with the swapchain.
surface, VkSurfaceCapabilitiesKHR
a pointer to a VkSurfaceCapabilitiesKHR structure in which the capabilities are returned.
pSurfaceCapabilities)

Query surface capabilities.

public static int
vkGetPhysicalDeviceSurfaceFormatsKHR(VkPhysicalDevice
the physical device that will be associated with the swapchain to be created, as described for CreateSwapchainKHR.
physicalDevice, long
the surface that will be associated with the swapchain.
surface, IntBuffer
a pointer to an integer related to the number of format pairs available or queried, as described below.
pSurfaceFormatCount, VkSurfaceFormatKHR.Buffer
either NULL or a pointer to an array of VkSurfaceFormatKHR structures.
pSurfaceFormats)

Query color formats supported by surface.

public static int
vkGetPhysicalDeviceSurfaceFormatsKHR(VkPhysicalDevice physicalDevice, long surface, int[] pSurfaceFormatCount, VkSurfaceFormatKHR.Buffer pSurfaceFormats)

Array version of: GetPhysicalDeviceSurfaceFormatsKHR

public static int
vkGetPhysicalDeviceSurfacePresentModesKHR(VkPhysicalDevice
the physical device that will be associated with the swapchain to be created, as described for CreateSwapchainKHR.
physicalDevice, long
the surface that will be associated with the swapchain.
surface, IntBuffer
a pointer to an integer related to the number of presentation modes available or queried, as described below.
pPresentModeCount, IntBuffer
either NULL or a pointer to an array of VkPresentModeKHR values, indicating the supported presentation modes.
pPresentModes)

Query supported presentation modes.

public static int
vkGetPhysicalDeviceSurfacePresentModesKHR(VkPhysicalDevice physicalDevice, long surface, int[] pPresentModeCount, int[] pPresentModes)

Array version of: GetPhysicalDeviceSurfacePresentModesKHR

public static int
vkGetPhysicalDeviceSurfaceSupportKHR(VkPhysicalDevice
the physical device.
physicalDevice, int
the queue family.
queueFamilyIndex, long
the surface.
surface, IntBuffer
a pointer to a VkBool32, which is set to TRUE to indicate support, and FALSE otherwise.
pSupported)

Query if presentation is supported.

public static int
vkGetPhysicalDeviceSurfaceSupportKHR(VkPhysicalDevice physicalDevice, int queueFamilyIndex, long surface, int[] pSupported)

Array version of: GetPhysicalDeviceSurfaceSupportKHR

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait