// 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.
--