| // Copyright (c) 2014-2018 Khronos Group. This work is licensed under a |
| // Creative Commons Attribution 4.0 International License; see |
| // http://creativecommons.org/licenses/by/4.0/ |
| |
| [[display,display]] |
| |
| == 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 sname:VkSurfaceKHR objects that target |
| displays. |
| |
| |
| === Display Enumeration |
| |
| [open,refpage='VkDisplayKHR',desc='Opaque handle to a display object',type='handles'] |
| -- |
| |
| Displays are represented by sname:VkDisplayKHR handles: |
| |
| include::../../api/handles/VkDisplayKHR.txt[] |
| |
| -- |
| |
| [open,refpage='vkGetPhysicalDeviceDisplayPropertiesKHR',desc='Query information about the available displays',type='protos'] |
| -- |
| |
| Various functions are provided for enumerating the available display devices |
| present on a Vulkan physical device. |
| To query information about the available displays, call: |
| |
| include::../../api/protos/vkGetPhysicalDeviceDisplayPropertiesKHR.txt[] |
| |
| * pname:physicalDevice is a physical device. |
| * pname:pPropertyCount is a pointer to an integer related to the number of |
| display devices available or queried, as described below. |
| * pname:pProperties is either `NULL` or a pointer to an array of |
| sname:VkDisplayPropertiesKHR structures. |
| |
| If pname:pProperties is `NULL`, then the number of display devices available |
| for pname:physicalDevice is returned in pname:pPropertyCount. |
| Otherwise, pname:pPropertyCount must: point to a variable set by the user to |
| the number of elements in the pname:pProperties array, and on return the |
| variable is overwritten with the number of structures actually written to |
| pname:pProperties. |
| If the value of pname:pPropertyCount is less than the number of display |
| devices for pname:physicalDevice, at most pname:pPropertyCount structures |
| will be written. |
| If pname:pPropertyCount is smaller than the number of display devices |
| available for pname:physicalDevice, ename:VK_INCOMPLETE will be returned |
| instead of ename:VK_SUCCESS to indicate that not all the available values |
| were returned. |
| |
| include::../../validity/protos/vkGetPhysicalDeviceDisplayPropertiesKHR.txt[] |
| -- |
| |
| [open,refpage='VkDisplayPropertiesKHR',desc='Structure describing an available display device',type='structs'] |
| -- |
| |
| The sname:VkDisplayPropertiesKHR structure is defined as: |
| |
| include::../../api/structs/VkDisplayPropertiesKHR.txt[] |
| |
| * pname: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. |
| * pname: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. |
| If not `NULL`, the memory it points to must: remain accessible as long |
| as pname:display is valid. |
| * pname:physicalDimensions describes the physical width and height of the |
| visible portion of the display, in millimeters. |
| * pname:physicalResolution describes the physical, native, or preferred |
| resolution of the display. |
| |
| [NOTE] |
| .Note |
| ==== |
| For devices which have no natural value to return here, implementations |
| should: return the maximum resolution supported. |
| ==== |
| |
| * pname:supportedTransforms tells which transforms are supported by this |
| display. |
| This will contain one or more of the bits from |
| sname:VkSurfaceTransformFlagsKHR. |
| * pname:planeReorderPossible tells whether the planes on this display can: |
| have their z order changed. |
| If this is ename:VK_TRUE, the application can: re-arrange the planes on |
| this display in any order relative to each other. |
| * pname: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] |
| .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. |
| ==== |
| |
| include::../../validity/structs/VkDisplayPropertiesKHR.txt[] |
| -- |
| |
| ifdef::VK_KHR_get_display_properties2[] |
| |
| [open,refpage='vkGetPhysicalDeviceDisplayProperties2KHR',desc='Query information about the available displays',type='protos'] |
| -- |
| |
| To query information about the available displays, call: |
| |
| include::../../api/protos/vkGetPhysicalDeviceDisplayProperties2KHR.txt[] |
| |
| * pname:physicalDevice is a physical device. |
| * pname:pPropertyCount is a pointer to an integer related to the number of |
| display devices available or queried, as described below. |
| * pname:pProperties is either `NULL` or a pointer to an array of |
| sname:VkDisplayProperties2KHR structures. |
| |
| fname:vkGetPhysicalDeviceDisplayProperties2KHR behaves similarly to |
| flink:vkGetPhysicalDeviceDisplayPropertiesKHR, with the ability to return |
| extended information via chained output structures. |
| |
| include::../../validity/protos/vkGetPhysicalDeviceDisplayProperties2KHR.txt[] |
| -- |
| |
| [open,refpage='VkDisplayProperties2KHR',desc='Structure describing an available display device',type='structs'] |
| -- |
| |
| The sname:VkDisplayProperties2KHR structure is defined as: |
| |
| include::../../api/structs/VkDisplayProperties2KHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to an extension-specific structure. |
| * pname:displayProperties is an instance of the |
| slink:VkDisplayPropertiesKHR structure. |
| |
| include::../../validity/structs/VkDisplayProperties2KHR.txt[] |
| -- |
| |
| endif::VK_KHR_get_display_properties2[] |
| |
| ifdef::VK_EXT_direct_mode_display[] |
| include::../VK_EXT_direct_mode_display/acquire_release_displays.txt[] |
| endif::VK_EXT_direct_mode_display[] |
| |
| |
| ==== Display Planes |
| |
| [open,refpage='vkGetPhysicalDeviceDisplayPlanePropertiesKHR',desc='Query the plane properties',type='protos'] |
| -- |
| |
| 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: |
| |
| include::../../api/protos/vkGetPhysicalDeviceDisplayPlanePropertiesKHR.txt[] |
| |
| * pname:physicalDevice is a physical device. |
| * pname:pPropertyCount is a pointer to an integer related to the number of |
| display planes available or queried, as described below. |
| * pname:pProperties is either `NULL` or a pointer to an array of |
| sname:VkDisplayPlanePropertiesKHR structures. |
| |
| If pname:pProperties is `NULL`, then the number of display planes available |
| for pname:physicalDevice is returned in pname:pPropertyCount. |
| Otherwise, pname:pPropertyCount must: point to a variable set by the user to |
| the number of elements in the pname:pProperties array, and on return the |
| variable is overwritten with the number of structures actually written to |
| pname:pProperties. |
| If the value of pname:pPropertyCount is less than the number of display |
| planes for pname:physicalDevice, at most pname:pPropertyCount structures |
| will be written. |
| |
| include::../../validity/protos/vkGetPhysicalDeviceDisplayPlanePropertiesKHR.txt[] |
| -- |
| |
| [open,refpage='VkDisplayPlanePropertiesKHR',desc='Structure describing display plane properties',type='structs'] |
| -- |
| |
| The sname:VkDisplayPlanePropertiesKHR structure is defined as: |
| |
| include::../../api/structs/VkDisplayPlanePropertiesKHR.txt[] |
| |
| * pname: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 |
| sname:VK_NULL_HANDLE. |
| * pname:currentStackIndex is the current z-order of the plane. |
| This will be between 0 and the value returned by |
| fname:vkGetPhysicalDeviceDisplayPlanePropertiesKHR in |
| pname:pPropertyCount. |
| |
| include::../../validity/structs/VkDisplayPlanePropertiesKHR.txt[] |
| -- |
| |
| ifdef::VK_KHR_get_display_properties2[] |
| |
| [open,refpage='vkGetPhysicalDeviceDisplayPlaneProperties2KHR',desc='Query information about the available display planes.',type='protos'] |
| -- |
| |
| To query the properties of a device's display planes, call: |
| |
| include::../../api/protos/vkGetPhysicalDeviceDisplayPlaneProperties2KHR.txt[] |
| |
| * pname:physicalDevice is a physical device. |
| * pname:pPropertyCount is a pointer to an integer related to the number of |
| display planes available or queried, as described below. |
| * pname:pProperties is either `NULL` or a pointer to an array of |
| sname:VkDisplayPlaneProperties2KHR structures. |
| |
| fname:vkGetPhysicalDeviceDisplayPlaneProperties2KHR behaves similarly to |
| flink:vkGetPhysicalDeviceDisplayPlanePropertiesKHR, with the ability to |
| return extended information via chained output structures. |
| |
| include::../../validity/protos/vkGetPhysicalDeviceDisplayPlaneProperties2KHR.txt[] |
| -- |
| |
| [open,refpage='VkDisplayPlaneProperties2KHR',desc='Structure describing an available display plane',type='structs'] |
| -- |
| |
| The sname:VkDisplayPlaneProperties2KHR structure is defined as: |
| |
| include::../../api/structs/VkDisplayPlaneProperties2KHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to an extension-specific structure. |
| * pname:displayPlaneProperties is an instance of the |
| slink:VkDisplayPlanePropertiesKHR structure. |
| |
| include::../../validity/structs/VkDisplayPlaneProperties2KHR.txt[] |
| -- |
| |
| endif::VK_KHR_get_display_properties2[] |
| |
| [open,refpage='vkGetDisplayPlaneSupportedDisplaysKHR',desc='Query the list of displays a plane supports',type='protos'] |
| -- |
| |
| To determine which displays a plane is usable with, call |
| |
| include::../../api/protos/vkGetDisplayPlaneSupportedDisplaysKHR.txt[] |
| |
| * pname:physicalDevice is a physical device. |
| * pname:planeIndex is the plane which the application wishes to use, and |
| must: be in the range [eq]#[0, physical device plane count - 1]#. |
| * pname:pDisplayCount is a pointer to an integer related to the number of |
| displays available or queried, as described below. |
| * pname:pDisplays is either `NULL` or a pointer to an array of |
| sname:VkDisplayKHR handles. |
| |
| If pname:pDisplays is `NULL`, then the number of displays usable with the |
| specified pname:planeIndex for pname:physicalDevice is returned in |
| pname:pDisplayCount. |
| Otherwise, pname:pDisplayCount must: point to a variable set by the user to |
| the number of elements in the pname:pDisplays array, and on return the |
| variable is overwritten with the number of handles actually written to |
| pname:pDisplays. |
| If the value of pname:pDisplayCount is less than the number of display |
| planes for pname:physicalDevice, at most pname:pDisplayCount handles will be |
| written. |
| If pname:pDisplayCount is smaller than the number of displays usable with |
| the specified pname:planeIndex for pname:physicalDevice, ename:VK_INCOMPLETE |
| will be returned instead of ename:VK_SUCCESS to indicate that not all the |
| available values were returned. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkGetDisplayPlaneSupportedDisplaysKHR-planeIndex-01249]] |
| pname:planeIndex must: be less than the number of display planes |
| supported by the device as determined by calling |
| fname:vkGetPhysicalDeviceDisplayPlanePropertiesKHR |
| **** |
| |
| include::../../validity/protos/vkGetDisplayPlaneSupportedDisplaysKHR.txt[] |
| -- |
| |
| Additional properties of displays are queried using specialized query |
| functions. |
| |
| |
| ==== Display Modes |
| |
| [open,refpage='VkDisplayModeKHR',desc='Opaque handle to a display mode object',type='handles'] |
| -- |
| |
| Display modes are represented by sname:VkDisplayModeKHR handles: |
| |
| include::../../api/handles/VkDisplayModeKHR.txt[] |
| |
| -- |
| |
| [open,refpage='vkGetDisplayModePropertiesKHR',desc='Query the set of mode properties supported by the display',type='protos'] |
| -- |
| |
| Each display has one or more supported modes associated with it by default. |
| These built-in modes are queried by calling: |
| |
| include::../../api/protos/vkGetDisplayModePropertiesKHR.txt[] |
| |
| * pname:physicalDevice is the physical device associated with |
| pname:display. |
| * pname:display is the display to query. |
| * pname:pPropertyCount is a pointer to an integer related to the number of |
| display modes available or queried, as described below. |
| * pname:pProperties is either `NULL` or a pointer to an array of |
| sname:VkDisplayModePropertiesKHR structures. |
| |
| If pname:pProperties is `NULL`, then the number of display modes available |
| on the specified pname:display for pname:physicalDevice is returned in |
| pname:pPropertyCount. |
| Otherwise, pname:pPropertyCount must: point to a variable set by the user to |
| the number of elements in the pname:pProperties array, and on return the |
| variable is overwritten with the number of structures actually written to |
| pname:pProperties. |
| If the value of pname:pPropertyCount is less than the number of display |
| modes for pname:physicalDevice, at most pname:pPropertyCount structures will |
| be written. |
| If pname:pPropertyCount is smaller than the number of display modes |
| available on the specified pname:display for pname:physicalDevice, |
| ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS to indicate |
| that not all the available values were returned. |
| |
| include::../../validity/protos/vkGetDisplayModePropertiesKHR.txt[] |
| -- |
| |
| [open,refpage='VkDisplayModePropertiesKHR',desc='Structure describing display mode properties',type='structs'] |
| -- |
| |
| The sname:VkDisplayModePropertiesKHR structure is defined as: |
| |
| include::../../api/structs/VkDisplayModePropertiesKHR.txt[] |
| |
| * pname:displayMode is a handle to the display mode described in this |
| structure. |
| This handle will be valid for the lifetime of the Vulkan instance. |
| * pname:parameters is a slink:VkDisplayModeParametersKHR structure |
| describing the display parameters associated with pname:displayMode. |
| |
| include::../../validity/structs/VkDisplayModePropertiesKHR.txt[] |
| -- |
| |
| ifdef::VK_KHR_get_display_properties2[] |
| |
| [open,refpage='vkGetDisplayModeProperties2KHR',desc='Query information about the available display modes.',type='protos'] |
| -- |
| |
| To query the properties of a device's built-in display modes, call: |
| |
| include::../../api/protos/vkGetDisplayModeProperties2KHR.txt[] |
| |
| * pname:physicalDevice is the physical device associated with |
| pname:display. |
| * pname:display is the display to query. |
| * pname:pPropertyCount is a pointer to an integer related to the number of |
| display modes available or queried, as described below. |
| * pname:pProperties is either `NULL` or a pointer to an array of |
| sname:VkDisplayModeProperties2KHR structures. |
| |
| fname:vkGetDisplayModeProperties2KHR behaves similarly to |
| flink:vkGetDisplayModePropertiesKHR, with the ability to return extended |
| information via chained output structures. |
| |
| include::../../validity/protos/vkGetDisplayModeProperties2KHR.txt[] |
| -- |
| |
| [open,refpage='VkDisplayModeProperties2KHR',desc='Structure describing an available display mode',type='structs'] |
| -- |
| |
| The sname:VkDisplayModeProperties2KHR structure is defined as: |
| |
| include::../../api/structs/VkDisplayModeProperties2KHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to an extension-specific structure. |
| * pname:displayModeProperties is an instance of the |
| slink:VkDisplayModePropertiesKHR structure. |
| |
| include::../../validity/structs/VkDisplayModeProperties2KHR.txt[] |
| -- |
| |
| endif::VK_KHR_get_display_properties2[] |
| |
| [open,refpage='VkDisplayModeParametersKHR',desc='Structure describing display parameters associated with a display mode',type='structs'] |
| -- |
| |
| The sname:VkDisplayModeParametersKHR structure is defined as: |
| |
| include::../../api/structs/VkDisplayModeParametersKHR.txt[] |
| |
| * pname:visibleRegion is the 2D extents of the visible region. |
| * pname:refreshRate is a code:uint32_t that is the number of times the |
| display is refreshed each second multiplied by 1000. |
| |
| [NOTE] |
| .Note |
| ==== |
| For example, a 60Hz display mode would report a pname:refreshRate of 60,000. |
| ==== |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkDisplayModeParametersKHR-width-01990]] |
| The pname:width member of pname:visibleRegion must: be greater than `0` |
| * [[VUID-VkDisplayModeParametersKHR-height-01991]] |
| The pname:height member of pname:visibleRegion must: be greater than `0` |
| * [[VUID-VkDisplayModeParametersKHR-refreshRate-01992]] |
| pname:refreshRate must: be greater than `0` |
| **** |
| |
| include::../../validity/structs/VkDisplayModeParametersKHR.txt[] |
| -- |
| |
| [open,refpage='vkCreateDisplayModeKHR',desc='Create a display mode',type='protos'] |
| -- |
| |
| Additional modes may: also be created by calling: |
| |
| include::../../api/protos/vkCreateDisplayModeKHR.txt[] |
| |
| * pname:physicalDevice is the physical device associated with |
| pname:display. |
| * pname:display is the display to create an additional mode for. |
| * pname:pCreateInfo is a slink:VkDisplayModeCreateInfoKHR structure |
| describing the new mode to create. |
| * pname: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,Memory Allocation>>). |
| * pname:pMode returns the handle of the mode created. |
| |
| include::../../validity/protos/vkCreateDisplayModeKHR.txt[] |
| -- |
| |
| [open,refpage='VkDisplayModeCreateInfoKHR',desc='Structure specifying parameters of a newly created display mode object',type='structs'] |
| -- |
| |
| The sname:VkDisplayModeCreateInfoKHR structure is defined as: |
| |
| include::../../api/structs/VkDisplayModeCreateInfoKHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to an extension-specific structure. |
| * pname:flags is reserved for future use, and must: be zero. |
| * pname:parameters is a slink: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 ename:VK_ERROR_INITIALIZATION_FAILED. |
| |
| include::../../validity/structs/VkDisplayModeCreateInfoKHR.txt[] |
| -- |
| |
| [open,refpage='vkGetDisplayPlaneCapabilitiesKHR',desc='Query capabilities of a mode and plane combination',type='protos'] |
| -- |
| |
| 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: |
| |
| include::../../api/protos/vkGetDisplayPlaneCapabilitiesKHR.txt[] |
| |
| * pname:physicalDevice is the physical device associated with |
| pname:display |
| * pname:mode is the display mode the application intends to program when |
| using the specified plane. |
| Note this parameter also implicitly specifies a display. |
| * pname: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. |
| * pname:pCapabilities is a pointer to a |
| slink:VkDisplayPlaneCapabilitiesKHR structure in which the capabilities |
| are returned. |
| |
| include::../../validity/protos/vkGetDisplayPlaneCapabilitiesKHR.txt[] |
| -- |
| |
| [open,refpage='VkDisplayPlaneCapabilitiesKHR',desc='Structure describing capabilities of a mode and plane combination',type='structs'] |
| -- |
| |
| The sname:VkDisplayPlaneCapabilitiesKHR structure is defined as: |
| |
| include::../../api/structs/VkDisplayPlaneCapabilitiesKHR.txt[] |
| |
| * pname:supportedAlpha is a bitmask of |
| elink:VkDisplayPlaneAlphaFlagBitsKHR describing the supported alpha |
| blending modes. |
| * pname:minSrcPosition is the minimum source rectangle offset supported by |
| this plane using the specified mode. |
| * pname:maxSrcPosition is the maximum source rectangle offset supported by |
| this plane using the specified mode. |
| The pname:x and pname:y components of pname:maxSrcPosition must: each be |
| greater than or equal to the pname:x and pname:y components of |
| pname:minSrcPosition, respectively. |
| * pname:minSrcExtent is the minimum source rectangle size supported by |
| this plane using the specified mode. |
| * pname:maxSrcExtent is the maximum source rectangle size supported by |
| this plane using the specified mode. |
| * pname:minDstPosition, pname:maxDstPosition, pname:minDstExtent, |
| pname:maxDstExtent all have similar semantics to their corresponding |
| ptext:*Src* equivalents, but apply to the output region within the mode |
| rather than the input region within the source image. |
| Unlike the ptext:*Src* offsets, pname:minDstPosition and |
| pname:maxDstPosition may: contain negative values. |
| |
| 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 pname:minSrcPosition, pname:maxSrcPosition, |
| pname:minSrcExtent, and pname: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 pname:minDstPosition, pname:maxDstPosition, |
| pname:minDstExtent and pname: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 [eq]#(0,0)# for pname:minSrcPosition, |
| pname:maxSrcPosition, pname:minDstPosition, and pname:maxDstPosition, and |
| (display mode width, display mode height) for pname:minSrcExtent, |
| pname:maxSrcExtent, pname:minDstExtent, and pname: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 sname:VkDisplayPlaneCapabilitiesKHR are guaranteed to be supported. |
| Vendors may: still fail presentation requests that specify unsupported |
| combinations. |
| |
| include::../../validity/structs/VkDisplayPlaneCapabilitiesKHR.txt[] |
| -- |
| |
| ifdef::VK_KHR_get_display_properties2[] |
| |
| [open,refpage='vkGetDisplayPlaneCapabilities2KHR',desc='Query capabilities of a mode and plane combination',type='protos'] |
| -- |
| |
| To query the capabilities of a given mode and plane combination, call: |
| |
| include::../../api/protos/vkGetDisplayPlaneCapabilities2KHR.txt[] |
| |
| * pname:physicalDevice is the physical device associated with |
| pname:pDisplayPlaneInfo. |
| * pname:pDisplayPlaneInfo is a pointer to an instance of the |
| slink:VkDisplayPlaneInfo2KHR structure describing the plane and mode. |
| * pname:pCapabilities is a pointer to a |
| slink:VkDisplayPlaneCapabilities2KHR structure in which the capabilities |
| are returned. |
| |
| fname:vkGetDisplayPlaneCapabilities2KHR behaves similarly to |
| flink:vkGetDisplayPlaneCapabilitiesKHR, with the ability to specify extended |
| inputs via chained input structures, and to return extended information via |
| chained output structures. |
| |
| include::../../validity/protos/vkGetDisplayPlaneCapabilities2KHR.txt[] |
| -- |
| |
| [open,refpage='VkDisplayPlaneInfo2KHR',desc='Structure defining the intended configuration of a display plane',type='structs'] |
| -- |
| |
| The sname:VkDisplayPlaneInfo2KHR structure is defined as: |
| |
| include::../../api/structs/VkDisplayPlaneInfo2KHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to an extension-specific structure. |
| * pname:mode is the display mode the application intends to program when |
| using the specified plane. |
| |
| [NOTE] |
| .Note |
| ==== |
| This parameter also implicitly specifies a display. |
| ==== |
| |
| * pname:planeIndex is the plane which the application intends to use with |
| the display. |
| |
| The members of sname:VkDisplayPlaneInfo2KHR correspond to the arguments to |
| flink:vkGetDisplayPlaneCapabilitiesKHR, with pname:sType and pname:pNext |
| added for extensibility. |
| |
| include::../../validity/structs/VkDisplayPlaneInfo2KHR.txt[] |
| -- |
| |
| [open,refpage='VkDisplayPlaneCapabilities2KHR',desc='Structure describing the capabilities of a mode and plane combination',type='structs'] |
| -- |
| |
| The sname:VkDisplayPlaneCapabilities2KHR structure is defined as: |
| |
| include::../../api/structs/VkDisplayPlaneCapabilities2KHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to an extension-specific structure. |
| * pname:capabilities is an instance of the |
| slink:VkDisplayPlaneCapabilitiesKHR structure. |
| |
| include::../../validity/structs/VkDisplayPlaneCapabilities2KHR.txt[] |
| -- |
| |
| endif::VK_KHR_get_display_properties2[] |
| |
| ifdef::VK_EXT_display_control[] |
| include::../VK_EXT_display_control/display_control.txt[] |
| endif::VK_EXT_display_control[] |
| |
| [[wsi-display-surfaces]] |
| === Display Surfaces |
| |
| [open,refpage='vkCreateDisplayPlaneSurfaceKHR',desc='Create a slink:VkSurfaceKHR structure representing a display plane and mode',type='protos'] |
| -- |
| |
| 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 sname:VkSurfaceKHR structure for a display surface, call: |
| |
| include::../../api/protos/vkCreateDisplayPlaneSurfaceKHR.txt[] |
| |
| * pname:instance is the instance corresponding to the physical device the |
| targeted display is on. |
| * pname:pCreateInfo is a pointer to an instance of the |
| slink:VkDisplaySurfaceCreateInfoKHR structure specifying which mode, |
| plane, and other parameters to use, as described below. |
| * pname:pAllocator is the allocator used for host memory allocated for the |
| surface object when there is no more specific allocator available (see |
| <<memory-allocation,Memory Allocation>>). |
| * pname:pSurface points to a slink:VkSurfaceKHR handle in which the |
| created surface is returned. |
| |
| include::../../validity/protos/vkCreateDisplayPlaneSurfaceKHR.txt[] |
| -- |
| |
| [open,refpage='VkDisplaySurfaceCreateInfoKHR',desc='Structure specifying parameters of a newly created display plane surface object',type='structs'] |
| -- |
| |
| The sname:VkDisplaySurfaceCreateInfoKHR structure is defined as: |
| |
| include::../../api/structs/VkDisplaySurfaceCreateInfoKHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to an extension-specific structure. |
| * pname:flags is reserved for future use, and must: be zero. |
| * pname:displayMode is a slink:VkDisplayModeKHR handle specifying the mode |
| to use when displaying this surface. |
| * pname:planeIndex is the plane on which this surface appears. |
| * pname:planeStackIndex is the z-order of the plane. |
| * pname:transform is a elink:VkSurfaceTransformFlagBitsKHR value |
| specifying the transformation to apply to images as part of the scanout |
| operation. |
| * pname:globalAlpha is the global alpha value. |
| This value is ignored if pname:alphaMode is not |
| ename:VK_DISPLAY_PLANE_ALPHA_GLOBAL_BIT_KHR. |
| * pname:alphaMode is a elink:VkDisplayPlaneAlphaFlagBitsKHR value |
| specifying the type of alpha blending to use. |
| * pname:imageExtent The size of the presentable images to use with the |
| surface. |
| |
| [NOTE] |
| .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 |
| **** |
| * [[VUID-VkDisplaySurfaceCreateInfoKHR-planeIndex-01252]] |
| pname:planeIndex must: be less than the number of display planes |
| supported by the device as determined by calling |
| fname:vkGetPhysicalDeviceDisplayPlanePropertiesKHR |
| * [[VUID-VkDisplaySurfaceCreateInfoKHR-planeReorderPossible-01253]] |
| If the pname:planeReorderPossible member of the |
| sname:VkDisplayPropertiesKHR structure returned by |
| fname:vkGetPhysicalDeviceDisplayPropertiesKHR for the display |
| corresponding to pname:displayMode is ename:VK_TRUE then |
| pname:planeStackIndex must: be less than the number of display planes |
| supported by the device as determined by calling |
| fname:vkGetPhysicalDeviceDisplayPlanePropertiesKHR; otherwise |
| pname:planeStackIndex must: equal the pname:currentStackIndex member of |
| sname:VkDisplayPlanePropertiesKHR returned by |
| fname:vkGetPhysicalDeviceDisplayPlanePropertiesKHR for the display plane |
| corresponding to pname:displayMode |
| * [[VUID-VkDisplaySurfaceCreateInfoKHR-alphaMode-01254]] |
| If pname:alphaMode is ename:VK_DISPLAY_PLANE_ALPHA_GLOBAL_BIT_KHR then |
| pname:globalAlpha must: be between `0` and `1`, inclusive |
| * [[VUID-VkDisplaySurfaceCreateInfoKHR-alphaMode-01255]] |
| pname:alphaMode must: be `0` or one of the bits present in the |
| pname:supportedAlpha member of sname:VkDisplayPlaneCapabilitiesKHR |
| returned by fname:vkGetDisplayPlaneCapabilitiesKHR for the display plane |
| corresponding to pname:displayMode |
| * [[VUID-VkDisplaySurfaceCreateInfoKHR-width-01256]] |
| The pname:width and pname:height members of pname:imageExtent must: be |
| less than the pname:maxImageDimensions2D member of |
| sname:VkPhysicalDeviceLimits |
| **** |
| |
| include::../../validity/structs/VkDisplaySurfaceCreateInfoKHR.txt[] |
| -- |
| |
| [open,refpage='VkDisplayPlaneAlphaFlagBitsKHR',desc='Alpha blending type',type='enums'] |
| -- |
| |
| Possible values of slink:VkDisplaySurfaceCreateInfoKHR::pname:alphaMode, |
| specifying the type of alpha blending to use on a display, are: |
| |
| include::../../api/enums/VkDisplayPlaneAlphaFlagBitsKHR.txt[] |
| |
| * ename:VK_DISPLAY_PLANE_ALPHA_OPAQUE_BIT_KHR specifies that the source |
| image will be treated as opaque. |
| * ename:VK_DISPLAY_PLANE_ALPHA_GLOBAL_BIT_KHR specifies that a global |
| alpha value must: be specified that will be applied to all pixels in the |
| source image. |
| * ename:VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_BIT_KHR specifies that 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. |
| * ename:VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_PREMULTIPLIED_BIT_KHR is |
| equivalent to ename: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. |
| |
| -- |
| |
| [open,refpage='VkDisplayPlaneAlphaFlagsKHR',desc='Bitmask of VkDisplayPlaneAlphaFlagBitsKHR',type='enums'] |
| -- |
| include::../../api/flags/VkDisplayPlaneAlphaFlagsKHR.txt[] |
| |
| sname:VkDisplayPlaneAlphaFlagsKHR is a bitmask type for setting a mask of |
| zero or more slink:VkDisplayPlaneAlphaFlagBitsKHR. |
| -- |
