• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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