Package org.lwjgl.vulkan

Class KHRSurface

  • public class KHRSurface
extends java.lang.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/master/cube/cube.c).

    Name String
    VK_KHR_surface
    Extension Type
    Instance extension
    Registered Extension Number
    1
    Revision
    25
    Extension and Version Dependencies
    • Requires Vulkan 1.0
    Contact
    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
    • Jason Ekstrand, Intel

    • Method Detail

      • nvkDestroySurfaceKHR

        public static void nvkDestroySurfaceKHR​(VkInstance instance,
                                        long surface,
                                        long pAllocator)
        Unsafe version of: DestroySurfaceKHR

      • vkDestroySurfaceKHR

        public static void vkDestroySurfaceKHR​(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).

      • vkGetPhysicalDeviceSurfaceSupportKHR

        public static int vkGetPhysicalDeviceSurfaceSupportKHR​(VkPhysicalDevice physicalDevice,
                                                       int queueFamilyIndex,
                                                       long surface,
                                                       java.nio.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
        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, which is set to TRUE to indicate support, and FALSE otherwise.

      • vkGetPhysicalDeviceSurfaceCapabilitiesKHR

        public static int vkGetPhysicalDeviceSurfaceCapabilitiesKHR​(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 (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 an instance of the VkSurfaceCapabilitiesKHR structure in which the capabilities are returned.

      • nvkGetPhysicalDeviceSurfaceFormatsKHR

        public static int nvkGetPhysicalDeviceSurfaceFormatsKHR​(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​(VkPhysicalDevice physicalDevice,
                                                       long surface,
                                                       java.nio.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. The number of format pairs supported will be greater than or equal to 1. Otherwise, pSurfaceFormatCount must point to a variable set by the user 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. If pSurfaceFormatCount is smaller than the number of format pairs supported for the given surface, INCOMPLETE will be returned instead of SUCCESS to indicate that not all the available values were returned.

        Valid Usage (Implicit)
        • physicalDevice must be a valid VkPhysicalDevice 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 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​(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​(VkPhysicalDevice physicalDevice,
                                                            long surface,
                                                            java.nio.IntBuffer pPresentModeCount,
                                                            @Nullable
                                                            java.nio.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 user 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. If pPresentModeCount is smaller than the number of presentation modes supported for the given surface, INCOMPLETE will be returned instead of SUCCESS to indicate that not all the available values were returned.

        Valid Usage (Implicit)
        • physicalDevice must be a valid VkPhysicalDevice 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 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.