vkGetPhysicalDeviceDisplayPropertiesKHR - Query information about the available displays

Parameters

• 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 DisplayPropertiesKHR structures.

Description

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, 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 PhysicalDevice handle

• pPropertyCount must be a valid pointer to a uint32_t value
• If the value referenced by pPropertyCount is not 0, and pProperties is not NULL, pProperties must be a valid pointer to an array of pPropertyCount DisplayPropertiesKHR structures

Return Codes

Success

• SUCCESS
• INCOMPLETE

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

DisplayPropertiesKHR, PhysicalDevice

vkGetPhysicalDeviceDisplayPlanePropertiesKHR - Query the plane properties

Parameters

• 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 DisplayPlanePropertiesKHR structures.

Description

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.

Valid Usage (Implicit)

• physicalDevice must be a valid PhysicalDevice handle

• pPropertyCount must be a valid pointer to a uint32_t value
• If the value referenced by pPropertyCount is not 0, and pProperties is not NULL, pProperties must be a valid pointer to an array of pPropertyCount DisplayPlanePropertiesKHR structures

Return Codes

Success

• SUCCESS
• INCOMPLETE

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

DisplayPlanePropertiesKHR, PhysicalDevice

vkGetDisplayPlaneSupportedDisplaysKHR - Query the list of displays a plane supports

Parameters

• 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 displays available or queried, as described below.
• pDisplays is either NULL or a pointer to an array of DisplayKHR handles.

Description

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 handles actually written to pDisplays. If the value of pDisplayCount is less than the number of display planes for physicalDevice, at most pDisplayCount handles will be written. If pDisplayCount is smaller than the number of displays usable with the specified planeIndex for physicalDevice, INCOMPLETE will be returned instead of SUCCESS to indicate that not all the available values were returned.

Valid Usage

• planeIndex must be less than the number of display planes supported by the device as determined by calling getPhysicalDeviceDisplayPlanePropertiesKHR

Valid Usage (Implicit)

• physicalDevice must be a valid PhysicalDevice handle

• pDisplayCount must be a valid pointer to a uint32_t value
• If the value referenced by pDisplayCount is not 0, and pDisplays is not NULL, pDisplays must be a valid pointer to an array of pDisplayCount DisplayKHR handles

Return Codes

Success

• SUCCESS
• INCOMPLETE

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

DisplayKHR, PhysicalDevice

vkGetDisplayModePropertiesKHR - Query the set of mode properties supported by the display

Parameters

• 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 DisplayModePropertiesKHR structures.

Description

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, 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 PhysicalDevice handle

• display must be a valid DisplayKHR handle
• pPropertyCount must be a valid pointer to a uint32_t value
• If the value referenced by pPropertyCount is not 0, and pProperties is not NULL, pProperties must be a valid pointer to an array of pPropertyCount DisplayModePropertiesKHR structures
• display must have been created, allocated, or retrieved from physicalDevice

Return Codes

Success

• SUCCESS
• INCOMPLETE

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

DisplayKHR, DisplayModePropertiesKHR, PhysicalDevice

vkCreateDisplayModeKHR - Create a display mode

Parameters

• physicalDevice is the physical device associated with display.

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

Valid Usage (Implicit)

• physicalDevice must be a valid PhysicalDevice handle

• display must be a valid DisplayKHR handle
• pCreateInfo must be a valid pointer to a valid DisplayModeCreateInfoKHR structure
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure
• pMode must be a valid pointer to a DisplayModeKHR handle
• display must have been created, allocated, or retrieved from physicalDevice

Host Synchronization

• Host access to display must be externally synchronized

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_INITIALIZATION_FAILED

See Also

AllocationCallbacks, DisplayKHR, DisplayModeCreateInfoKHR, DisplayModeKHR, PhysicalDevice

vkGetDisplayPlaneCapabilitiesKHR - Query capabilities of a mode and plane combination

Parameters

• 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 DisplayPlaneCapabilitiesKHR structure in which the capabilities are returned.

Valid Usage (Implicit)

• physicalDevice must be a valid PhysicalDevice handle

• mode must be a valid DisplayModeKHR handle
• pCapabilities must be a valid pointer to a DisplayPlaneCapabilitiesKHR structure

Host Synchronization

• Host access to mode must be externally synchronized

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

DisplayModeKHR, DisplayPlaneCapabilitiesKHR, PhysicalDevice

vkCreateDisplayPlaneSurfaceKHR - Create a SurfaceKHR structure representing a display plane and mode

Parameters

• instance is the instance corresponding to the physical device the targeted display is on.

• pCreateInfo is a pointer to a DisplaySurfaceCreateInfoKHR 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 is a pointer to a SurfaceKHR handle in which the created surface is returned.

Valid Usage (Implicit)

• instance must be a valid Instance handle

• pCreateInfo must be a valid pointer to a valid DisplaySurfaceCreateInfoKHR structure
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure
• pSurface must be a valid pointer to a SurfaceKHR handle

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

AllocationCallbacks, DisplaySurfaceCreateInfoKHR, Instance, SurfaceKHR

VkDisplayPropertiesKHR - Structure describing an available display device

Description

Note

For devices which have no natural value to return here, implementations should return the maximum resolution supported.

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.

See Also

Bool32, DisplayKHR, DisplayProperties2KHR, Extent2D, SurfaceTransformFlagsKHR, getPhysicalDeviceDisplayPropertiesKHR

VkDisplayPlanePropertiesKHR - Structure describing display plane properties

See Also

DisplayKHR, DisplayPlaneProperties2KHR, getPhysicalDeviceDisplayPlanePropertiesKHR

VkDisplayModeParametersKHR - Structure describing display parameters associated with a display mode

Description

Note

For example, a 60Hz display mode would report a refreshRate of 60,000.

Valid Usage

• The width member of visibleRegion must be greater than 0

• The height member of visibleRegion must be greater than 0
• refreshRate must be greater than 0

See Also

DisplayModeCreateInfoKHR, DisplayModePropertiesKHR, Extent2D

VkDisplayModePropertiesKHR - Structure describing display mode properties

See Also

DisplayModeKHR, DisplayModeParametersKHR, DisplayModeProperties2KHR, getDisplayModePropertiesKHR

VkDisplayModeCreateInfoKHR - Structure specifying parameters of a newly created display mode object

Valid Usage (Implicit)

See Also

DisplayModeCreateFlagsKHR, DisplayModeParametersKHR, StructureType, createDisplayModeKHR

VkDisplayPlaneCapabilitiesKHR - Structure describing capabilities of a mode and plane combination

Description

The minimum and maximum position and extent fields describe the implementation 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 implementation’s individual fields. Not all combinations of values within the offset and extent ranges returned in DisplayPlaneCapabilitiesKHR are guaranteed to be supported. Presentation requests specifying unsupported combinations may fail.

See Also

DisplayPlaneAlphaFlagsKHR, DisplayPlaneCapabilities2KHR, Extent2D, Offset2D, getDisplayPlaneCapabilitiesKHR

VkDisplaySurfaceCreateInfoKHR - Structure specifying parameters of a newly created display plane surface object

Description

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.

Valid Usage

• planeIndex must be less than the number of display planes supported by the device as determined by calling getPhysicalDeviceDisplayPlanePropertiesKHR

• If the planeReorderPossible member of the DisplayPropertiesKHR structure returned by getPhysicalDeviceDisplayPropertiesKHR for the display corresponding to displayMode is TRUE then planeStackIndex must be less than the number of display planes supported by the device as determined by calling getPhysicalDeviceDisplayPlanePropertiesKHR; otherwise planeStackIndex must equal the currentStackIndex member of DisplayPlanePropertiesKHR returned by getPhysicalDeviceDisplayPlanePropertiesKHR for the display plane corresponding to displayMode
• If alphaMode is DISPLAY_PLANE_ALPHA_GLOBAL_BIT_KHR then globalAlpha must be between 0 and 1, inclusive
• alphaMode must be 0 or one of the bits present in the supportedAlpha member of DisplayPlaneCapabilitiesKHR returned by getDisplayPlaneCapabilitiesKHR for the display plane corresponding to displayMode
• The width and height members of imageExtent must be less than the maxImageDimensions2D member of PhysicalDeviceLimits

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_DISPLAY_SURFACE_CREATE_INFO_KHR

• pNext must be NULL
• flags must be 0
• displayMode must be a valid DisplayModeKHR handle
• transform must be a valid SurfaceTransformFlagBitsKHR value
• alphaMode must be a valid DisplayPlaneAlphaFlagBitsKHR value

See Also

DisplayModeKHR, DisplayPlaneAlphaFlagBitsKHR, DisplaySurfaceCreateFlagsKHR, Extent2D, StructureType, SurfaceTransformFlagBitsKHR, createDisplayPlaneSurfaceKHR

VkDisplayModeCreateFlagsKHR - Reserved for future use

Description

DisplayModeCreateFlagsKHR is a bitmask type for setting a mask, but is currently reserved for future use.

See Also

DisplayModeCreateInfoKHR

VkDisplaySurfaceCreateFlagsKHR - Reserved for future use

Description

DisplaySurfaceCreateFlagsKHR is a bitmask type for setting a mask, but is currently reserved for future use.

See Also

DisplaySurfaceCreateInfoKHR

VkDisplayPlaneAlphaFlagBitsKHR - Alpha blending type

See Also

DisplayPlaneAlphaFlagsKHR, DisplaySurfaceCreateInfoKHR

VkDisplayKHR - Opaque handle to a display object

See Also

DisplayPlanePropertiesKHR, DisplayPropertiesKHR, acquireXlibDisplayEXT, createDisplayModeKHR, displayPowerControlEXT, getDisplayModeProperties2KHR, getDisplayModePropertiesKHR, getDisplayPlaneSupportedDisplaysKHR, getRandROutputDisplayEXT, registerDisplayEventEXT, releaseDisplayEXT

VkDisplayModeKHR - Opaque handle to a display mode object

See Also

DisplayModePropertiesKHR, DisplayPlaneInfo2KHR, DisplaySurfaceCreateInfoKHR, createDisplayModeKHR, getDisplayPlaneCapabilitiesKHR

VkSurfaceKHR - Opaque handle to a surface object

Description

The VK_KHR_surface extension declares the SurfaceKHR object, and provides a function for destroying SurfaceKHR objects. Separate platform-specific extensions each provide a function for creating a SurfaceKHR object for the respective platform. From the application’s perspective this is an opaque handle, just like the handles of other Vulkan objects.

See Also

PhysicalDeviceSurfaceInfo2KHR, SwapchainCreateInfoKHR, createAndroidSurfaceKHR, createDisplayPlaneSurfaceKHR, createHeadlessSurfaceEXT, createIOSSurfaceMVK, createImagePipeSurfaceFUCHSIA, createMacOSSurfaceMVK, createMetalSurfaceEXT, createStreamDescriptorSurfaceGGP, createViSurfaceNN, createWaylandSurfaceKHR, createWin32SurfaceKHR, createXcbSurfaceKHR, createXlibSurfaceKHR, destroySurfaceKHR, getDeviceGroupSurfacePresentModesKHR, getPhysicalDevicePresentRectanglesKHR, getPhysicalDeviceSurfaceCapabilities2EXT, getPhysicalDeviceSurfaceCapabilitiesKHR, getPhysicalDeviceSurfaceFormatsKHR, getPhysicalDeviceSurfacePresentModesKHR, getPhysicalDeviceSurfaceSupportKHR

VkSurfaceTransformFlagBitsKHR - presentation transforms supported on a device

See Also

CommandBufferInheritanceRenderPassTransformInfoQCOM, DisplaySurfaceCreateInfoKHR, RenderPassTransformBeginInfoQCOM, SurfaceCapabilities2EXT, SurfaceCapabilitiesKHR, SurfaceTransformFlagsKHR, SwapchainCreateInfoKHR