1// Copyright 2018-2023 The Khronos Group Inc.
2//
3// SPDX-License-Identifier: CC-BY-4.0
4
5=== Alternate Methods to Signal Fences
6
7Besides submitting a fence to a queue as part of a
8<<devsandqueues-submission, queue submission>> command, a fence may: also be
9signaled when a particular event occurs on a device or display.
10
11[open,refpage='vkRegisterDeviceEventEXT',desc='Signal a fence when a device event occurs',type='protos']
12--
13:refpage: vkRegisterDeviceEventEXT
14
15To create a fence that will be signaled when an event occurs on a device,
16call:
17
18include::{generated}/api/protos/vkRegisterDeviceEventEXT.adoc[]
19
20  * pname:device is a logical device on which the event may: occur.
21  * pname:pDeviceEventInfo is a pointer to a slink:VkDeviceEventInfoEXT
22    structure describing the event of interest to the application.
23  * pname:pAllocator controls host memory allocation as described in the
24    <<memory-allocation, Memory Allocation>> chapter.
25  * pname:pFence is a pointer to a handle in which the resulting fence
26    object is returned.
27
28include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[]
29
30include::{generated}/validity/protos/vkRegisterDeviceEventEXT.adoc[]
31--
32
33[open,refpage='VkDeviceEventInfoEXT',desc='Describe a device event to create',type='structs']
34--
35The sname:VkDeviceEventInfoEXT structure is defined as:
36
37include::{generated}/api/structs/VkDeviceEventInfoEXT.adoc[]
38
39  * pname:sType is a elink:VkStructureType value identifying this structure.
40  * pname:pNext is `NULL` or a pointer to a structure extending this
41    structure.
42  * pname:device is a elink:VkDeviceEventTypeEXT value specifying when the
43    fence will be signaled.
44
45include::{generated}/validity/structs/VkDeviceEventInfoEXT.adoc[]
46--
47
48[open,refpage='VkDeviceEventTypeEXT',desc='Events that can occur on a device object',type='enums']
49--
50Possible values of slink:VkDeviceEventInfoEXT::pname:device, specifying when
51a fence will be signaled, are:
52
53include::{generated}/api/enums/VkDeviceEventTypeEXT.adoc[]
54
55  * ename:VK_DEVICE_EVENT_TYPE_DISPLAY_HOTPLUG_EXT specifies that the fence
56    is signaled when a display is plugged into or unplugged from the
57    specified device.
58    Applications can: use this notification to determine when they need to
59    re-enumerate the available displays on a device.
60--
61
62[open,refpage='vkRegisterDisplayEventEXT',desc='Signal a fence when a display event occurs',type='protos']
63--
64:refpage: vkRegisterDisplayEventEXT
65
66To create a fence that will be signaled when an event occurs on a
67slink:VkDisplayKHR object, call:
68
69include::{generated}/api/protos/vkRegisterDisplayEventEXT.adoc[]
70
71  * pname:device is a logical device associated with pname:display
72  * pname:display is the display on which the event may: occur.
73  * pname:pDisplayEventInfo is a pointer to a slink:VkDisplayEventInfoEXT
74    structure describing the event of interest to the application.
75  * pname:pAllocator controls host memory allocation as described in the
76    <<memory-allocation, Memory Allocation>> chapter.
77  * pname:pFence is a pointer to a handle in which the resulting fence
78    object is returned.
79
80include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[]
81
82include::{generated}/validity/protos/vkRegisterDisplayEventEXT.adoc[]
83--
84
85[open,refpage='VkDisplayEventInfoEXT',desc='Describe a display event to create',type='structs']
86--
87The sname:VkDisplayEventInfoEXT structure is defined as:
88
89include::{generated}/api/structs/VkDisplayEventInfoEXT.adoc[]
90
91  * pname:sType is a elink:VkStructureType value identifying this structure.
92  * pname:pNext is `NULL` or a pointer to a structure extending this
93    structure.
94  * pname:displayEvent is a elink:VkDisplayEventTypeEXT specifying when the
95    fence will be signaled.
96
97include::{generated}/validity/structs/VkDisplayEventInfoEXT.adoc[]
98--
99
100[open,refpage='VkDisplayEventTypeEXT',desc='Events that can occur on a display object',type='enums']
101--
102Possible values of slink:VkDisplayEventInfoEXT::pname:displayEvent,
103specifying when a fence will be signaled, are:
104
105include::{generated}/api/enums/VkDisplayEventTypeEXT.adoc[]
106
107  * ename:VK_DISPLAY_EVENT_TYPE_FIRST_PIXEL_OUT_EXT specifies that the fence
108    is signaled when the first pixel of the next display refresh cycle
109    leaves the display engine for the display.
110--
111