## 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_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, 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. If the parameters are not compatible with the specified display, the implementation must return `VK_ERROR_INITIALIZATION_FAILED`.

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 of `VkDisplayPlaneAlphaFlagBitsKHR` describing the supported alpha blending modes.
- `minSrcPosition` is the minimum source rectangle offset supported by this plane using the specified mode.
- `maxSrcPosition` is the maximum source rectangle offset supported by this plane using the specified mode. The `x` and `y` components of `maxSrcPosition` must each be greater than or equal to the `x` and `y` components of `minSrcPosition`, respectively.
- `minSrcExtent` is the minimum source rectangle size supported by this plane using the specified mode.
- `maxSrcExtent` is the maximum source rectangle 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

A complete display configuration includes a mode, one or more display planes and any parameters describing their behavior, and parameters describing some aspects of the images associated with those planes. Display surfaces describe the configuration of a single plane within a complete display configuration. To create a `VkSurfaceKHR` structure for a display surface, 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` 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 scanout 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.

| Note
Creating a display surface must not modify the state of the displays, planes, or other resources it names. For example, it must not apply the specified mode to be set on the associated display. Application of display configuration occurs as a side effect of presenting to a display surface.

Types of alpha blending supported by or used on a display are defined by the bitmask `VkDisplayPlaneAlphaFlagBitsKHR`, which contains the following values:

    typedef enum VkDisplayPlaneAlphaFlagBitsKHR {
        VK_DISPLAY_PLANE_ALPHA_OPAQUE_BIT_KHR = 0x00000001,
        VK_DISPLAY_PLANE_ALPHA_GLOBAL_BIT_KHR = 0x00000002,
        VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_BIT_KHR = 0x00000004,
        VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_PREMULTIPLIED_BIT_KHR = 0x00000008,
    } VkDisplayPlaneAlphaFlagBitsKHR;

These values are described as follows:

- `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.