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