1// Copyright 2017-2022 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[[headless]] 6=== Presenting to headless surfaces 7 8Vulkan rendering can be presented to a headless surface, where the 9presentation operation is a no-op producing no externally-visible result. 10 11[NOTE] 12.Note 13==== 14Because there is no real presentation target, the headless presentation 15engine may be extended to impose an arbitrary or customisable set of 16restrictions and features. 17This makes it a useful portable test target for applications targeting a 18wide range of presentation engines where the actual target presentation 19engines might be scarce, unavailable or otherwise undesirable or 20inconvenient to use for general Vulkan application development. 21 22The usual surface query mechanisms must be used to determine the actual 23restrictions and features of the implementation. 24==== 25 26[open,refpage='vkCreateHeadlessSurfaceEXT',desc='Create a headless slink:VkSurfaceKHR object',type='protos'] 27-- 28To create a headless sname:VkSurfaceKHR object, call: 29 30include::{generated}/api/protos/vkCreateHeadlessSurfaceEXT.adoc[] 31 32 * pname:instance is the instance to associate the surface with. 33 * pname:pCreateInfo is a pointer to a slink:VkHeadlessSurfaceCreateInfoEXT 34 structure containing parameters affecting the creation of the surface 35 object. 36 * pname:pAllocator is the allocator used for host memory allocated for the 37 surface object when there is no more specific allocator available (see 38 <<memory-allocation,Memory Allocation>>). 39 * pname:pSurface is a pointer to a sname:VkSurfaceKHR handle in which the 40 created surface object is returned. 41 42include::{generated}/validity/protos/vkCreateHeadlessSurfaceEXT.adoc[] 43-- 44 45[open,refpage='VkHeadlessSurfaceCreateInfoEXT',desc='Structure specifying parameters of a newly created headless surface object',type='structs'] 46-- 47The sname:VkHeadlessSurfaceCreateInfoEXT structure is defined as: 48 49include::{generated}/api/structs/VkHeadlessSurfaceCreateInfoEXT.adoc[] 50 51 * pname:sType is the type of this structure. 52 * pname:pNext is `NULL` or a pointer to a structure extending this 53 structure. 54 * pname:flags is reserved for future use. 55 56include::{generated}/validity/structs/VkHeadlessSurfaceCreateInfoEXT.adoc[] 57-- 58 59For headless surfaces, pname:currentExtent is the reserved value 60[eq]#(0xFFFFFFFF, 0xFFFFFFFF)#. 61Whatever the application sets a swapchain's pname:imageExtent to will be the 62size of the surface, after the first image is presented. 63 64[open,refpage='VkHeadlessSurfaceCreateFlagsEXT',desc='Reserved for future use',type='flags'] 65-- 66include::{generated}/api/flags/VkHeadlessSurfaceCreateFlagsEXT.adoc[] 67 68tname:VkHeadlessSurfaceCreateFlagsEXT is a bitmask type for setting a mask, 69but is currently reserved for future use. 70-- 71