29.3. Presenting Directly to Display Devices

In some environments applications can also present Vulkan rendering directly to display devices without using an intermediate windowing system. This can be useful for embedded applications, or implementing the rendering/presentation backend of a windowing system using Vulkan. The VK_EXT_KHR_display extension provides the functionality necessary to enumerate display devices and create VkSurface objects that target displays.

29.3.1. Display Enumeration

Various functions are provided for enumerating the available display devices present on a Vulkan physical device. To query information about the available displays, call:

VkResult vkGetPhysicalDeviceDisplayPropertiesKHR(
VkPhysicalDevice                            physicalDevice,
uint32_t*                                   pPropertyCount,
VkDisplayPropertiesKHR*                     pProperties);

• physicalDevice is a physical device.
• pPropertyCount is a pointer to an integer related to the number of display devices available or queried, as described below.
• pProperties is either NULL or a pointer to an array of VkDisplayPropertiesKHR structures.

If pProperties is NULL, then the number of display devices available for physicalDevice is returned in pPropertyCount. Otherwise, pPropertyCount must point to a variable set by the user to the number of elements in the pProperties array, and on return the variable is overwritten with the number of structures actually written to pProperties. If the value of pPropertyCount is less than the number of display devices for physicalDevice, at most pPropertyCount structures will be written. If pPropertyCount is smaller than the number of display devices available for physicalDevice, VK_INCOMPLETE will be returned instead of VK_SUCCESS to indicate that not all the available values were returned.

The VkDisplayPropertiesKHR structure is defined as:

typedef struct VkDisplayPropertiesKHR {
VkDisplayKHR                  display;
const char*                   displayName;
VkExtent2D                    physicalDimensions;
VkExtent2D                    physicalResolution;
VkSurfaceTransformFlagsKHR    supportedTransforms;
VkBool32                      planeReorderPossible;
VkBool32                      persistentContent;
} VkDisplayPropertiesKHR;

• display is a handle that is used to refer to the display described here. This handle will be valid for the lifetime of the Vulkan instance.
• displayName is a pointer to a NULL-terminated string containing the name of the display. Generally, this will be the name provided by the display’s EDID. It can be NULL if no suitable name is available.
• physicalDimensions describes the physical width and height of the visible portion of the display, in millimeters.
• physicalResolution describes the physical, native, or preferred resolution of the display.
Note For devices which have no natural value to return here, implementations should return the maximum resolution supported.
• supportedTransforms tells which transforms are supported by this display. This will contain one or more of the bits from VkSurfaceTransformFlagsKHR.
• planeReorderPossible tells whether the planes on this display can have their z order changed. If this is VK_TRUE, the application can re-arrange the planes on this display in any order relative to each other.
• persistentContent tells whether the display supports self-refresh/internal buffering. If this is true, the application can submit persistent present operations on swapchains created against this display.
Note Persistent presents may have higher latency, and may use less power when the screen content is updated infrequently, or when only a portion of the screen needs to be updated in most frames.

Display Planes

Images are presented to individual planes on a display. Devices must support at least one plane on each display. Planes can be stacked and blended to composite multiple images on one display. Devices may support only a fixed stacking order and fixed mapping between planes and displays, or they may allow arbitrary application specified stacking orders and mappings between planes and displays. To query the properties of device display planes, call:

VkResult vkGetPhysicalDeviceDisplayPlanePropertiesKHR(
VkPhysicalDevice                            physicalDevice,
uint32_t*                                   pPropertyCount,
VkDisplayPlanePropertiesKHR*                pProperties);

• physicalDevice is a physical device.
• pPropertyCount is a pointer to an integer related to the number of display planes available or queried, as described below.
• pProperties is either NULL or a pointer to an array of VkDisplayPlanePropertiesKHR structures.

If pProperties is NULL, then the number of display planes available for physicalDevice is returned in pPropertyCount. Otherwise, pPropertyCount must point to a variable set by the user to the number of elements in the pProperties array, and on return the variable is overwritten with the number of structures actually written to pProperties. If the value of pPropertyCount is less than the number of display planes for physicalDevice, at most pPropertyCount structures will be written.

The VkDisplayPlanePropertiesKHR structure is defined as:

typedef struct VkDisplayPlanePropertiesKHR {
VkDisplayKHR    currentDisplay;
uint32_t        currentStackIndex;
} VkDisplayPlanePropertiesKHR;

• currentDisplay is the handle of the display the plane is currently associated with. If the plane is not currently attached to any displays, this will be VK_NULL_HANDLE.
• currentStackIndex is the current z-order of the plane. This will be between 0 and the value returned by vkGetPhysicalDeviceDisplayPlanePropertiesKHR() in pPropertyCount.

To determine which displays a plane is usable with, call

VkResult vkGetDisplayPlaneSupportedDisplaysKHR(
VkPhysicalDevice                            physicalDevice,
uint32_t                                    planeIndex,
uint32_t*                                   pDisplayCount,
VkDisplayKHR*                               pDisplays);

• physicalDevice is a physical device.
• planeIndex is the plane which the application wishes to use, and must be in the range $[0, \mathit{physical device plane count}-1]$ .
• pDisplayCount is a pointer to an integer related to the number of display planes available or queried, as described below.
• pDisplays is either NULL or a pointer to an array of VkDisplayKHR structures.

If pDisplays is NULL, then the number of displays usable with the specified planeIndex for physicalDevice is returned in pDisplayCount. Otherwise, pDisplayCount must point to a variable set by the user to the number of elements in the pDisplays array, and on return the variable is overwritten with the number of structures actually written to pDisplays. If the value of pDisplayCount is less than the number of display planes for physicalDevice, at most pDisplayCount structures will be written. If pDisplayCount is smaller than the number of displays usable with the specified planeIndex for physicalDevice, VK_INCOMPLETE will be returned instead of VK_SUCCESS to indicate that not all the available values were returned.

Additional properties of displays are queried using specialized query functions.

Display Modes

Each display has one or more supported modes associated with it by default. These built-in modes are queried by calling:

VkResult vkGetDisplayModePropertiesKHR(
VkPhysicalDevice                            physicalDevice,
VkDisplayKHR                                display,
uint32_t*                                   pPropertyCount,
VkDisplayModePropertiesKHR*                 pProperties);

• physicalDevice is the physical device associated with display.
• display is the display to query.
• pPropertyCount is a pointer to an integer related to the number of display modes available or queried, as described below.
• pProperties is either NULL or a pointer to an array of VkDisplayModePropertiesKHR structures.

If pProperties is NULL, then the number of display modes available on the specified display for physicalDevice is returned in pPropertyCount. Otherwise, pPropertyCount must point to a variable set by the user to the number of elements in the pProperties array, and on return the variable is overwritten with the number of structures actually written to pProperties. If the value of pPropertyCount is less than the number of display modes for physicalDevice, at most pPropertyCount structures will be written. If pPropertyCount is smaller than the number of display modes available on the specified display for physicalDevice, VK_INCOMPLETE will be returned instead of VK_SUCCESS to indicate that not all the available values were returned.

The VkDisplayModePropertiesKHR structure is defined as:

typedef struct VkDisplayModePropertiesKHR {
VkDisplayModeKHR              displayMode;
VkDisplayModeParametersKHR    parameters;
} VkDisplayModePropertiesKHR;

• displayMode is a handle to the display mode described in this structure. This handle will be valid for the lifetime of the Vulkan instance.
• parameters is a VkDisplayModeParametersKHR structure describing the display parameters associated with displayMode.

The VkDisplayModeParametersKHR structure is defined as:

typedef struct VkDisplayModeParametersKHR {
VkExtent2D    visibleRegion;
uint32_t      refreshRate;
} VkDisplayModeParametersKHR;

• visibleRegion is the 2D extents of the visible region.
• refreshRate is a uint32_t that is the number of times the display is refreshed each second multiplied by 1000.
Note For example, a 60Hz display mode would report a refreshRate of 60,000.

Additional modes may also be created by calling:

VkResult vkCreateDisplayModeKHR(
VkPhysicalDevice                            physicalDevice,
VkDisplayKHR                                display,
const VkDisplayModeCreateInfoKHR*           pCreateInfo,
const VkAllocationCallbacks*                pAllocator,
VkDisplayModeKHR*                           pMode);

• physicalDevice is the physical device associated with display.
• display is the display to create an additional mode for.
• pCreateInfo is a VkDisplayModeCreateInfoKHR structure describing the new mode to create.
• pAllocator is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation).
• pMode returns the handle of the mode created.

The VkDisplayModeCreateInfoKHR structure is defined as:

typedef struct VkDisplayModeCreateInfoKHR {
VkStructureType                sType;
const void*                    pNext;
VkDisplayModeCreateFlagsKHR    flags;
VkDisplayModeParametersKHR     parameters;
} VkDisplayModeCreateInfoKHR;

• sType is the type of this structure and must be VK_STRUCTURE_TYPE_DISPLAY_MODE_CREATE_INFO_KHR.
• pNext is NULL or a pointer to an extension-specific structure.
• flags is reserved for future use, and must be zero.
• parameters is a VkDisplayModeParametersKHR structure describing the display parameters to use in creating the new mode.

Applications that wish to present directly to a display must select which layer, or "plane" of the display they wish to target, and a mode to use with the display. Each display supports at least one plane. The capabilities of a given mode and plane combination are determined by calling:

VkResult vkGetDisplayPlaneCapabilitiesKHR(
VkPhysicalDevice                            physicalDevice,
VkDisplayModeKHR                            mode,
uint32_t                                    planeIndex,
VkDisplayPlaneCapabilitiesKHR*              pCapabilities);

• physicalDevice is the physical device associated with display
• mode is the display mode the application intends to program when using the specified plane. Note this parameter also implicitly specifies a display.
• planeIndex is the plane which the application intends to use with the display, and is less than the number of display planes supported by the device.
• pCapabilities is a pointer to a VkDisplayPlaneCapabilitiesKHR structure in which the capabilities are returned.

The VkDisplayPlaneCapabilitiesKHR structure is defined as:

typedef struct VkDisplayPlaneCapabilitiesKHR {
VkDisplayPlaneAlphaFlagsKHR    supportedAlpha;
VkOffset2D                     minSrcPosition;
VkOffset2D                     maxSrcPosition;
VkExtent2D                     minSrcExtent;
VkExtent2D                     maxSrcExtent;
VkOffset2D                     minDstPosition;
VkOffset2D                     maxDstPosition;
VkExtent2D                     minDstExtent;
VkExtent2D                     maxDstExtent;
} VkDisplayPlaneCapabilitiesKHR;

• supportedAlpha is a bitmask describing the supported alpha blending modes. Possible values of supportedAlpha are arbitrary combinations of the following values:

• VK_DISPLAY_PLANE_ALPHA_OPAQUE_BIT_KHR: The source image will be treated as opaque.
• VK_DISPLAY_PLANE_ALPHA_GLOBAL_BIT_KHR: A global alpha value must be specified that will be applied to all pixels in the source image.
• VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_BIT_KHR: The alpha value will be determined by the alpha channel of the source image’s pixels. If the source format contains no alpha values, no blending will be applied. The source alpha values are not premultiplied into the source image’s other color channels.
• VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_PREMULTIPLIED_BIT_KHR: This is equivalent to VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_BIT_KHR except the source alpha values are assumed to be premultiplied into the source image’s other color channels.
• minSrcPosition is the minimum source rect offset supported by this plane using the specified mode.
• maxSrcPosition is the maximum source rect offset supported by this plane using the specified mode. The x and y offets must be >= 0.
• maxSrcPosition is the maximum source rect offset supported by this plane using the specified mode. The x and y offsets must be >= minSrcPosition.
• minSrcExtent is the minimum source rect size supported by this plane using the specified mode.
• maxSrcExtent is the maximum source rect size supported by this plane using the specified mode.
• minDstPosition, maxDstPosition, minDstExtent, maxDstExtent all have similar semantics to their corresponding "Src" equivalents, but apply to the output region within the mode rather than the input region within the source image. Unlike the "Src" offsets, minDstPosition and maxDstPosition may contain negative values.

The minimum and maximum position and extent fields describe the hardware limits, if any, as they apply to the specified display mode and plane. Vendors may support displaying a subset of a swapchain’s presentable images on the specified display plane. This is expressed by returning minSrcPosition, maxSrcPosition, minSrcExtent, and maxSrcExtent values that indicate a range of possible positions and sizes may be used to specify the region within the presentable images that source pixels will be read from when creating a swapchain on the specified display mode and plane.

Vendors may also support mapping the presentable images' content to a subset or superset of the visible region in the specified display mode. This is expressed by returning minDstPosition, maxDstPosition, minDstExtent and maxDstExtent values that indicate a range of possible positions and sizes may be used to describe the region within the display mode that the source pixels will be mapped to.

Other vendors may support only a 1-1 mapping between pixels in the presentable images and the display mode. This may be indicated by returning (0,0) for minSrcPosition, maxSrcPosition, minDstPosition, and maxDstPosition, and (display mode width, display mode height) for minSrcExtent, maxSrcExtent, minDstExtent, and maxDstExtent.

These values indicate the limits of the hardware’s individual fields. Not all combinations of values within the offset and extent ranges returned in VkDisplayPlaneCapabilitiesKHR are guaranteed to be supported. Vendors may still fail presentation requests that specify unsupported combinations.

29.3.2. Display Surfaces

To create a VkSurfaceKHR structure representing a display plane and mode, call

VkResult vkCreateDisplayPlaneSurfaceKHR(
VkInstance                                  instance,
const VkDisplaySurfaceCreateInfoKHR*        pCreateInfo,
const VkAllocationCallbacks*                pAllocator,
VkSurfaceKHR*                               pSurface);

• instance is the instance corresponding to the physical device the targeted display is on.
• pCreateInfo:pCreateInfo is a pointer to an instance of the VkDisplaySurfaceCreateInfoKHR structure specifying which mode, plane, and other parameters to use, as described below.
• pAllocator is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation).
• pSurface points to a VkSurfaceKHR handle in which the created surface is returned.

The VkDisplaySurfaceCreateInfoKHR structure is defined as:

typedef struct VkDisplaySurfaceCreateInfoKHR {
VkStructureType                   sType;
const void*                       pNext;
VkDisplaySurfaceCreateFlagsKHR    flags;
VkDisplayModeKHR                  displayMode;
uint32_t                          planeIndex;
uint32_t                          planeStackIndex;
VkSurfaceTransformFlagBitsKHR     transform;
float                             globalAlpha;
VkDisplayPlaneAlphaFlagBitsKHR    alphaMode;
VkExtent2D                        imageExtent;
} VkDisplaySurfaceCreateInfoKHR;

• sType is the type of this structure and must be VK_STRUCTURE_TYPE_DISPLAY_SURFACE_CREATE_INFO_KHR.
• pNext is NULL or a pointer to an extension-specific structure.
• flags is reserved for future use, and must be zero.
• displayMode is the mode to use when displaying this surface.
• planeIndex is the plane on which this surface appears.
• planeStackIndex is the z-order of the plane.
• transform is the transform to apply to the images as part of the scannout operation.
• globalAlpha is the global alpha value. This value is ignored if alphaMode is not VK_DISPLAY_PLANE_ALPHA_GLOBAL_BIT_KHR.
• alphaMode is the type of alpha blending to use.
• imageSize The size of the presentable images to use with the surface.