| // Copyright 2017-2021 The Khronos Group, Inc. |
| // |
| // SPDX-License-Identifier: CC-BY-4.0 |
| |
| [[headless,headless]] |
| |
| === Presenting to headless surfaces |
| |
| Vulkan rendering can be presented to a headless surface, where the |
| presentation operation is a no-op producing no externally-visible result. |
| |
| [NOTE] |
| .Note |
| ==== |
| Because there is no real presentation target, the headless presentation |
| engine may be extended to impose an arbitrary or customisable set of |
| restrictions and features. |
| This makes it a useful portable test target for applications targeting a |
| wide range of presentation engines where the actual target presentation |
| engines might be scarce, unavailable or otherwise undesirable or |
| inconvenient to use for general Vulkan application development. |
| |
| The usual surface query mechanisms must be used to determine the actual |
| restrictions and features of the implementation. |
| ==== |
| |
| [open,refpage='vkCreateHeadlessSurfaceEXT',desc='Create a headless slink:VkSurfaceKHR object',type='protos'] |
| -- |
| To create a headless sname:VkSurfaceKHR object, call: |
| |
| include::{generated}/api/protos/vkCreateHeadlessSurfaceEXT.txt[] |
| |
| * pname:instance is the instance to associate the surface with. |
| * pname:pCreateInfo is a pointer to a slink:VkHeadlessSurfaceCreateInfoEXT |
| structure containing parameters affecting the creation of the surface |
| object. |
| * 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 is a pointer to a sname:VkSurfaceKHR handle in which the |
| created surface object is returned. |
| |
| include::{generated}/validity/protos/vkCreateHeadlessSurfaceEXT.txt[] |
| -- |
| |
| [open,refpage='VkHeadlessSurfaceCreateInfoEXT',desc='Structure specifying parameters of a newly created headless surface object',type='structs'] |
| -- |
| The sname:VkHeadlessSurfaceCreateInfoEXT structure is defined as: |
| |
| include::{generated}/api/structs/VkHeadlessSurfaceCreateInfoEXT.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:flags is reserved for future use. |
| |
| include::{generated}/validity/structs/VkHeadlessSurfaceCreateInfoEXT.txt[] |
| -- |
| |
| For headless surfaces, pname:currentExtent is the reserved value |
| [eq]#(0xFFFFFFFF, 0xFFFFFFFF)#. |
| Whatever the application sets a swapchain's pname:imageExtent to will be the |
| size of the surface, after the first image is presented. |
| |
| [open,refpage='VkHeadlessSurfaceCreateFlagsEXT',desc='Reserved for future use',type='flags'] |
| -- |
| include::{generated}/api/flags/VkHeadlessSurfaceCreateFlagsEXT.txt[] |
| |
| tname:VkHeadlessSurfaceCreateFlagsEXT is a bitmask type for setting a mask, |
| but is currently reserved for future use. |
| -- |
