1// Copyright 2017-2024 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-- 28:refpage: vkCreateHeadlessSurfaceEXT 29 30To create a headless sname:VkSurfaceKHR object, call: 31 32include::{generated}/api/protos/vkCreateHeadlessSurfaceEXT.adoc[] 33 34 * pname:instance is the instance to associate the surface with. 35 * pname:pCreateInfo is a pointer to a slink:VkHeadlessSurfaceCreateInfoEXT 36 structure containing parameters affecting the creation of the surface 37 object. 38 * pname:pAllocator is the allocator used for host memory allocated for the 39 surface object when there is no more specific allocator available (see 40 <<memory-allocation,Memory Allocation>>). 41 * pname:pSurface is a pointer to a sname:VkSurfaceKHR handle in which the 42 created surface object is returned. 43 44include::{generated}/validity/protos/vkCreateHeadlessSurfaceEXT.adoc[] 45-- 46 47[open,refpage='VkHeadlessSurfaceCreateInfoEXT',desc='Structure specifying parameters of a newly created headless surface object',type='structs'] 48-- 49The sname:VkHeadlessSurfaceCreateInfoEXT structure is defined as: 50 51include::{generated}/api/structs/VkHeadlessSurfaceCreateInfoEXT.adoc[] 52 53 * pname:sType is a elink:VkStructureType value identifying this structure. 54 * pname:pNext is `NULL` or a pointer to a structure extending this 55 structure. 56 * pname:flags is reserved for future use. 57 58include::{generated}/validity/structs/VkHeadlessSurfaceCreateInfoEXT.adoc[] 59-- 60 61For headless surfaces, pname:currentExtent is the reserved value 62[eq]#(0xFFFFFFFF, 0xFFFFFFFF)#. 63Whatever the application sets a swapchain's pname:imageExtent to will be the 64size of the surface, after the first image is presented. 65 66[open,refpage='VkHeadlessSurfaceCreateFlagsEXT',desc='Reserved for future use',type='flags'] 67-- 68include::{generated}/api/flags/VkHeadlessSurfaceCreateFlagsEXT.adoc[] 69 70tname:VkHeadlessSurfaceCreateFlagsEXT is a bitmask type for setting a mask, 71but is currently reserved for future use. 72-- 73