-
Notifications
You must be signed in to change notification settings - Fork 454
/
wsi.txt
609 lines (516 loc) · 29.8 KB
/
wsi.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
== WSI Swapchain
A sname:VkSwapchainKHR object (a.k.a. swapchain) provides the ability to
present rendering results to a surface. A swapchain is an abstraction for an
array of presentable images that are associated with a surface. The
swapchain images are represented by sname:VkImage objects created by the
platform. One image (which can: be an array image for
multiview/stereoscopic-3D surfaces) is displayed at a time, but multiple
images can: be queued for presentation. An application renders to the image,
and then queues the image for presentation to the surface. A native window
cannot: be associated with more than one swapchain at a time. Further,
swapchains cannot: be created for native windows that have a non-Vulkan
graphics API surface associated with them.
The presentation engine is an abstraction for the platform's compositor or
hardware/software display engine.
[NOTE]
.Note
====
The presentation engine may: be synchronous or asynchronous with respect to
the application and/or logical device.
Some implementations may: use the device's graphics queue or dedicated
presentation hardware to perform presentation.
====
The presentable images of a swapchain are owned by the presentation engine.
An application can: acquire use of a presentable image from the presentation
engine. Use of a presentable image must: occur only after the image is
returned by fname:vkAcquireNextImageKHR, and before it is presented by
fname:vkQueuePresentKHR. This includes transitioning the image layout and
rendering commands.
An application can: acquire use of a presentable image with
fname:vkAcquireNextImageKHR. After acquiring a presentable image and before
modifying it, the application must: use a synchronization primitive to
ensure that the presentation engine has finished reading from the image. The
application can: then transition the image's layout, queue rendering
commands to it, etc. Finally, the application presents the image with
fname:vkQueuePresentKHR, which releases the acquisition of the image.
The presentation engine controls the order in which presentable images are
acquired for use by the application.
[NOTE]
.Note
====
This allows the platform to handle situations which require out-of-order
return of images after presentation. At the same time, it allows the
application to generate command buffers referencing all of the images in the
swapchain at initialization time, rather than in its main loop.
====
How this all works is described below.
// refBegin vkCreateSwapchainKHR - Create a swapchain
To create a swapchain, call:
include::../../api/protos/vkCreateSwapchainKHR.txt[]
* pname:device is the device to create the swapchain for.
* pname:pCreateInfo is a pointer to an instance of the
slink:VkSwapchainCreateInfoKHR structure specifying the parameters of
the created swapchain.
* pname:pAllocator is the allocator used for host memory allocated for the
swapchain object when there is no more specific allocator available (see
<<memory-allocation,Memory Allocation>>).
* pname:pSwapchain is a pointer to a sname:VkSwapchainKHR handle in which
the created swapchain object will be returned.
include::../../validity/protos/vkCreateSwapchainKHR.txt[]
// refBegin VkSwapchainCreateInfoKHR - Structure specifying parameters of a newly created swapchain object
The sname:VkSwapchainCreateInfoKHR structure is defined as:
include::../../api/structs/VkSwapchainCreateInfoKHR.txt[]
* pname:sType is the type of this structure and must: be
ename:VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:flags is reserved for future use, and must: be zero.
* pname:surface is the surface that the swapchain will present images to.
* pname:minImageCount is the minimum number of presentable images that the
application needs. The platform will either create the swapchain with at
least that many images, or will fail to create the swapchain.
* pname:imageFormat is a slink:VkFormat that is valid for
swapchains on the specified surface.
* pname:imageColorSpace is a slink:VkColorSpaceKHR that is valid for
swapchains on the specified surface.
* pname:imageExtent is the size (in pixels) of the swapchain. Behavior is
platform-dependent when the image extent does not match the surface's
pname:currentExtent as returned by
fname:vkGetPhysicalDeviceSurfaceCapabilitiesKHR.
* pname:imageArrayLayers is the number of views in a multiview/stereo
surface. For non-stereoscopic-3D applications, this value is 1.
* pname:imageUsage is a bitfield of elink:VkImageUsageFlagBits, indicating
how the application will use the swapchain's presentable images.
* pname:imageSharingMode is the sharing mode used for the images of the
swapchain.
* pname:queueFamilyIndexCount is the number of queue families having
access to the images of the swapchain in case pname:imageSharingMode is
ename:VK_SHARING_MODE_CONCURRENT.
* pname:pQueueFamilyIndices is an array of queue family indices having
access to the images of the swapchain in case pname:imageSharingMode is
ename:VK_SHARING_MODE_CONCURRENT.
* pname:preTransform is a bitfield of elink:VkSurfaceTransformFlagBitsKHR,
describing the transform, relative to the presentation engine's
natural orientation, applied to the image content prior to presentation.
If it does not match the pname:currentTransform value returned by
fname:vkGetPhysicalDeviceSurfaceCapabilitiesKHR, the presentation engine
will transform the image content as part of the presentation operation.
* pname:compositeAlpha is a bitfield of elink:VkCompositeAlphaFlagBitsKHR,
indicating the alpha compositing mode to use when this surface
is composited together with other surfaces on certain window systems.
* pname:presentMode is the presentation mode the swapchain will use. A
swapchain's present mode determines how incoming present requests will
be processed and queued internally.
* pname:clipped indicates whether the Vulkan implementation is allowed
to discard rendering operations that affect regions of the surface which
aren't visible.
** If set to ename:VK_TRUE, the presentable images associated with the
swapchain may: not own all of their pixels. Pixels in the presentable
images that correspond to regions of the target surface obscured by
another window on the desktop or subject to some other clipping
mechanism will have undefined content when read back. Pixel shaders
maynot: execute for these pixels, and thus any side affects they would
have had will not occur.
** If set to ename:VK_FALSE, presentable images associated with the
swapchain will own all the pixels they contain.
Setting this value to ename:VK_TRUE does not guarantee any clipping
will occur, but allows more optimal presentation methods to be used on
some platforms.
[NOTE]
.Note
====
Applications should: set this value to
ename:VK_TRUE if they do not expect to read back the content of presentable
images before presenting them or after reacquiring them and if their
pixel shaders do not have any side effects that require them to run for
all pixels in the presentable image.
====
* pname:oldSwapchain, if not code:VK_NULL_HANDLE, specifies the
swapchain that will be
replaced by the new swapchain being created. The new swapchain will: be
a descendant of pname:oldSwapchain. Further, any descendants of the
new swapchain will also be descendants of pname:oldSwapchain. Upon
calling
fname:vkCreateSwapchainKHR with a pname:oldSwapchain that is
not code:VK_NULL_HANDLE, any
images not acquired by the application may: be freed by the
implementation, which may: occur even if creation of the new swapchain
fails. The application must: destroy the old swapchain to free all
memory associated with the old swapchain. The application must: wait for
the completion of any outstanding rendering to images it currently has
acquired at the time the swapchain is destroyed. The application can:
continue to present any images it acquired and has not yet presented
using the old swapchain, as long as it has not entered a state that
causes it to return ename:VK_ERROR_OUT_OF_DATE_KHR. However, the
application cannot: acquire any more images from the old swapchain
regardless of whether or not creation of the new swapchain succeeds.
include::../../validity/structs/VkSwapchainCreateInfoKHR.txt[]
As mentioned above, if fname:vkCreateSwapchainKHR succeeds, it will return a
handle to a swapchain that contains an array of at least pname:minImageCount
presentable images.
While acquired by the application, swapchain images can: be used in any way
that equivalent non-swapchain images can: be used. A swapchain image is
equivalent to a non-swapchain image created with the following
sname:VkImageCreateInfo parameters:
[options="header"]
|====
|sname:VkImageCreateInfo Field|Value
|pname:flags |`0`
|pname:imageType |`VK_IMAGE_TYPE_2D`
|pname:format |`pCreateInfo->imageFormat`
|pname:extent |`{pCreateInfo->imageExtent.width, pCreateInfo->imageExtent.height, 1}`
|pname:mipLevels |`1`
|pname:arrayLayers |`pCreateInfo->imageArrayLayers`
|pname:samples |`VK_SAMPLE_COUNT_1_BIT`
|pname:tiling |`VK_IMAGE_TILING_OPTIMAL`
|pname:usage |`pCreateInfo->imageUsage`
|pname:sharingMode |`pCreateInfo->imageSharingMode`
|pname:queueFamilyIndexCount |`pCreateInfo->queueFamilyIndexCount`
|pname:pQueueFamilyIndices |`pCreateInfo->pQueueFamilyIndices`
|pname:initialLayout |`VK_IMAGE_LAYOUT_UNDEFINED`
|====
The sname:VkSurfaceKHR associated with a swapchain mustnot: be destroyed
until after the swapchain is destroyed.
Like core functions, several WSI fuctions, including
fname:vkCreateSwapchainKHR return ename:VK_ERROR_DEVICE_LOST if the logical
device was lost. See <<devsandqueues-lost-device,Lost Device>>. As with most
core objects, sname:VkSwapchainKHR is a child of the device and is affected
by the lost state; it must: be destroyed before destroying the
sname:VkDevice. However, sname:VkSurfaceKHR is not a child of any
sname:VkDevice and is not otherwise affected by the lost device. After
successfully recreating a sname:VkDevice, the same sname:VkSurfaceKHR can:
be used to create a new sname:VkSwapchainKHR, provided the previous one was
destroyed.
[NOTE]
.Note
====
As mentioned in <<devsandqueues-lost-device,Lost Device>>, after a lost
device event, the sname:VkPhysicalDevice may: also be lost. If other
sname:VkPhysicalDevice are available, they can: be used together with the
same sname:VkSurfaceKHR to create the new sname:VkSwapchainKHR, however the
application must: query the surface capabilities again, because they may:
differ on a per-physical device basis.
====
// refBegin vkDestroySwapchainKHR - Destroy a swapchain object
To destroy a swapchain object call:
include::../../api/protos/vkDestroySwapchainKHR.txt[]
* pname:device is the sname:VkDevice assocated with pname:swapchain.
* pname:swapchain is the swapchain to destroy.
* pname:pAllocator is the allocator used for host memory allocated for the
swapchain object when there is no more specific allocator available (see
<<memory-allocation,Memory Allocation>>).
pname:swapchain and all associated sname:VkImage handles are destroyed, and
must: not be acquired or used any more by the application. The memory of
each sname:VkImage will only be freed after that image is no longer used by
the platform. For example, if one image of the swapchain is being displayed
in a window, the memory for that image may: not be freed until the window is
destroyed, or another swapchain is created for the window. Destroying the
swapchain does not invalidate the parent sname:VkSurfaceKHR, and a new
swapchain can: be created with it.
include::../VK_KHR_display_swapchain/destroy_swapchain_interactions.txt[]
include::../../validity/protos/vkDestroySwapchainKHR.txt[]
include::../VK_KHR_display_swapchain/create_shared_swapchains.txt[]
// refBegin vkGetSwapchainImagesKHR - Obtain the array of presentable images associated with a swapchain
To obtain the array of presentable images associated with a swapchain,
call:
include::../../api/protos/vkGetSwapchainImagesKHR.txt[]
* pname:device is the device associated with pname:swapchain.
* pname:swapchain is the swapchain to query.
* pname:pSwapchainImageCount is a pointer to an integer related to the
number of swapchain images available or queried, as described below.
* pname:pSwapchainImages is either `NULL` or a pointer to an array
of sname:VkImage handles.
If pname:pSwapchainImages is `NULL`, then the number of presentable images
for pname:swapchain is returned in pname:pSwapchainImageCount. Otherwise,
pname:pSwapchainImageCount must: point to a variable set by the user to the
number of elements in the pname:pSwapchainImages array, and on return the
variable is overwritten with the number of structures actually written to
pname:pSwapchainImages. If the value of pname:pSwapchainImageCount is less
than the number of presentable images for pname:swapchain, at most
pname:pSwapchainImageCount structures will be written.
If pname:pSwapchainImageCount is smaller than the number of presentable
images for pname:swapchain, ename:VK_INCOMPLETE will be returned instead of
ename:VK_SUCCESS to indicate that not all the available values were
returned.
include::../../validity/protos/vkGetSwapchainImagesKHR.txt[]
[NOTE]
.Note
====
By knowing all presentable images used in the swapchain, the application
can: create command buffers that reference these images prior to entering
its main rendering loop.
====
The implementation will have already allocated and bound the memory backing
the sname:VkImages returned by fname:vkGetSwapchainImagesKHR. The memory for
each image will not alias with the memory for other images or with any
sname:VkDeviceMemory object. As such, performing any operation affecting the
binding of memory to a presentable image results in undefined behavior. All
presentable images are initially in the ename:VK_IMAGE_LAYOUT_UNDEFINED
layout, thus before using presentable images, the application must:
transition them to a valid layout for the intended use.
Further, the lifetime of presentable images is controlled by the
implementation so destroying a presentable image with flink:vkDestroyImage
results in undefined behavior. See flink:vkDestroySwapchainKHR for further
details on the lifetime of presentable images.
// refBegin vkAcquireNextImageKHR - Retrieve the index of the next available presentable image
To acquire an available presentable image to use, and retrieve the
index of that image, call:
include::../../api/protos/vkAcquireNextImageKHR.txt[]
* pname:device is the device assocated with pname:swapchain.
* pname:swapchain is the swapchain from which an image is being acquired.
* pname:timeout indicates how long the function waits, in nanoseconds, if
no image is available.
* pname:semaphore is code:VK_NULL_HANDLE or a semaphore to signal.
* pname:fence is code:VK_NULL_HANDLE or a fence to signal.
* pname:pImageIndex is a pointer to a basetype:uint32_t that is set to the
index of the next image to use (i.e. an index into the array of images
returned by fname:vkGetSwapchainImagesKHR).
include::../../validity/protos/vkAcquireNextImageKHR.txt[]
When successful, fname:vkAcquireNextImageKHR acquires a presentable image
that the application can: use, and sets pname:pImageIndex to the index of
that image. The presentation engine may: not have finished reading from the
image at the time it is acquired, so the application must: use
pname:semaphore and/or pname:fence to ensure that the image layout and
contents are not modified until the presentation engine reads have
completed.
As mentioned above, the presentation engine controls the order in which
presentable images are made available to the application. This allows the
platform to handle special situations. The order in which images are
acquired is implementation-dependent. Images may: be acquired in a
seemingly random order that is not a simple round-robin.
If a swapchain has enough presentable images, applications can: acquire
multiple images without an intervening fname:vkQueuePresentKHR.
Applications can: present images in a different order than the order in
which they were acquired.
If pname:timeout is 0, fname:vkAcquireNextImageKHR will not block, but will
either succeed or return VK_NOT_READY. If pname:timeout is `UINT64_MAX`, the
function will not return until an image is acquired from the presentation
engine. Other values for pname:timeout will cause the function to return
when an image becomes available, or when the specified number of nanoseconds
have passed (in which case it will return VK_TIMEOUT). An error can: also
cause fname:vkAcquireNextImageKHR to return early.
[NOTE]
.Note
====
As mentioned above, the presentation engine may: be asynchronous with
respect to the application and/or logical device.
fname:vkAcquireNextImageKHR may: return as soon as it can: identify which
image will be acquired, and can: guarantee that pname:semaphore and
pname:fence will be signaled by the presentation engine; and may: not
successfully return sooner. The application uses pname:timeout to specify
how long fname:vkAcquireNextImageKHR waits for an image to become acquired.
====
Applications cannot: rely on fname:vkAcquireNextImageKHR blocking in order
to meter their rendering speed. Various factors can: interrupt
fname:vkAcquireNextImageKHR from blocking.
[NOTE]
.Note
====
For example, if an error occurs, fname:vkAcquireNextImageKHR may: return
even though no image is available. As another example, some presentation
engines are able to enqueue an unbounded number of presentation and acquire
next image operations such that fname:vkAcquireNextImageKHR never needs to
wait for completion of outstanding present operations before returning.
====
The availability of presentable images is influenced by factors such as the
implementation of the presentation engine, the ename:VkPresentModeKHR being
used, the number of images in the swapchain, the number of images that the
application has acquired at any given time, and the performance of the
application. The value of
sname:VkSurfaceCapabilitiesKHR::pname:minImageCount indicates how many
images must: be in the swapchain in order for fname:vkAcquireNextImageKHR to
acquire an image if the application currently has no acquired images.
Let _n_ be the total number of images in the swapchain, _m_ be the value of
sname:VkSurfaceCapabilitiesKHR::pname:minImageCount, and _a_ be the number
of presentable images that the application has currently acquired
(i.e. images acquired with fname:vkAcquireNextImageKHR, but not yet
presented with fname:vkQueuePresentKHR). fname:vkAcquireNextImageKHR can:
always succeed if latexmath:[$a \leq n - m$] at the time fname:vkAcquireNextImageKHR is
called.
fname:vkAcquireNextImageKHR shouldnot: be called if latexmath:[$a > n - m$]
with a pname:timeout of code:UINT64_MAX; in such a case,
fname:vkAcquireNextImageKHR may: block indefinitely.
[NOTE]
.Note
====
For example, if the pname:minImageCount member of
sname:VkSurfaceCapabilitiesKHR is 2, and the application creates a swapchain
with 2 presentable images, the application can: acquire one image, and
must: present it before trying to acquire another image.
If we modify this example so that the application wishes to acquire up to 3
presentable images simultaneously, it must: request a minimum image count of
4 when creating the swapchain.
====
If pname:semaphore is not code:VK_NULL_HANDLE, the semaphore must: be
unsignaled and not have any uncompleted signal or wait operations pending.
It will become signaled when the application can: use the image. Queue
operations that access the image contents must: wait until the semaphore
signals; typically applications should: include the semaphore in the
pname:pWaitSemaphores list for the queue submission that transitions the
image away from the ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR layout. Use of the
semaphore allows rendering operations to be recorded and submitted before
the presentation engine has completed its use of the image.
If pname:fence is not equal to code:VK_NULL_HANDLE, the fence must: be
unsignaled and not have any uncompleted signal operations pending. It will
become signaled when the application can: use the image. Applications can:
use this to meter their frame generation work to match the presentation
rate.
pname:semaphore and pname:fence must: not both be equal to
code:VK_NULL_HANDLE. An application must: wait until either the
pname:semaphore or pname:fence is signaled before using the presentable
image.
pname:semaphore and pname:fence may: already be signaled when
fname:vkAcquireNextImageKHR returns, if the image is being acquired for the
first time, or if the presentable image is immediately ready for use.
A successful call to fname:vkAcquireNextImageKHR counts as a signal
operation on pname:semaphore for the purposes of queue forward-progress
requirements. The semaphore is guaranteed to signal, so a wait operation
can: be queued for the semaphore without risk of deadlock.
The fname:vkCmdWaitEvents or fname:vkCmdPipelineBarrier used to transition
the image away from ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR layout must: have
pname:dstStageMask and pname:dstAccessMask parameters set based on the next
use of the image. The pname:srcAccessMask must: include
ename:VK_ACCESS_MEMORY_READ_BIT to ensure that all prior reads by the
presentation engine are complete before the image layout transition occurs.
The application must: use <<synchronization-implicit-ordering,implicit
ordering guarantees>> and
<<synchronization-execution-and-memory-dependencies,execution dependencies>>
to prevent the image transition from occurring before the semaphore passed
to fname:vkAcquireNextImageKHR has signaled.
[NOTE]
.Note
====
When the swapchain image will be written by some stage latexmath:[$S$], the
recommended idiom for ensuring the semaphore signals before the transition
occurs is:
* The batch that contains the transition includes the image-acquire
semaphore in the list of semaphores to wait for, with a wait stage mask
that includes latexmath:[$S$].
* The pipeline barrier that performs the transition includes
latexmath:[$S$] in both the pname:srcStageMask and pname:dstStageMask.
This causes the pipeline barrer to wait at latexmath:[$S$] until the
semaphore signals before performing the transition and memory barrier, while
allowing earlier pipeline stages of subsequent commands to proceed.
====
After a successful return, the image indicated by pname:pImageIndex will
still be in the ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR layout if it was
previously presented, or in the ename:VK_IMAGE_LAYOUT_UNDEFINED layout if
this is the first time it has been acquired.
The possible return values for fname:vkAcquireNextImageKHR() depend on the
pname:timeout provided:
* ename:VK_SUCCESS is returned if an image became available.
* ename:VK_ERROR_SURFACE_LOST_KHR if the surface becomes no longer
available.
* ename:VK_NOT_READY is returned if pname:timeout is zero and no image was
available.
* ename:VK_TIMEOUT is returned if pname:timeout is greater than zero and
less than `UINT64_MAX`, and no image became available within the time
allowed.
* ename:VK_SUBOPTIMAL_KHR is returned if an image became available, and
the swapchain no longer matches the surface properties exactly, but can:
still be used to present to the surface successfully.
[NOTE]
.Note
====
This may: happen, for example, if the platform surface has been resized but
the platform is able to scale the presented images to the new size to
produce valid surface updates. It is up to applications to decide whether
they prefer to continue using the current swapchain indefinitely or
temporarily in this state, or to re-create the swapchain to better match the
platform surface properties.
====
* ename:VK_ERROR_OUT_OF_DATE_KHR is returned if the surface has changed in
such a way that it is no longer compatible with the swapchain, and
further presentation requests using the swapchain will fail.
Applications must: query the new surface properties and recreate their
swapchain if they wish to continue presenting to the surface.
If the native surface and presented image sizes no longer match,
presentation maynot: succeed. If presentation does succeed, parts of the
native surface may: be undefined, parts of the presented image may: have
been clipped before presentation, and/or the image may: have been scaled
(uniformly or not uniformly) before presentation. It is the application's
responsibility to detect surface size changes and react appropriately. If
presentation does not succeed because of a mismatch in the surface and
presented image sizes, a ename:VK_ERROR_OUT_OF_DATE_KHR error will be
returned.
Before an application can: present an image, the image's layout must: be
transitioned to the ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR layout. The
fname:vkCmdWaitEvents or fname:vkCmdPipelineBarrier that perform the
transition must: have pname:srcStageMask and pname:srcAccessMask parameters
set based on the preceding use of the image. The pname:dstAccessMask must:
include ename:VK_ACCESS_MEMORY_READ_BIT indicating all prior accesses
indicated in pname:srcAccessMask from stages in pname:srcStageMask are to be
made available to reads by the presentation engine. Any value of
pname:dstStageMask is valid, but should: be set to
ename:VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT to avoid delaying subsequent
commands that don't access the image.
// refBegin vkQueuePresentKHR - Queue an image for presentation
After queueing all rendering commands and transitioning the image to the
correct layout, to queue an image for presentation, call:
include::../../api/protos/vkQueuePresentKHR.txt[]
* pname:queue is a queue that is capable of presentation to the target
surface's platform on the same device as the image's swapchain.
* pname:pPresentInfo is a pointer to an instance of the
slink:VkPresentInfoKHR structure specifying the parameters of the
presentation.
include::../../validity/protos/vkQueuePresentKHR.txt[]
// refBegin VkPresentInfoKHR - Structure describing parameters of a queue presentation
The sname:VkPresentInfoKHR structure is defined as:
include::../../api/structs/VkPresentInfoKHR.txt[]
* pname:sType is the type of this structure and must: be
ename:VK_STRUCTURE_TYPE_PRESENT_INFO_KHR.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:waitSemaphoreCount is the number of semaphores to wait for before
issuing the present request. The number may: be zero.
* pname:pWaitSemaphores, if not code:VK_NULL_HANDLE, is an array of
sname:VkSemaphore
objects with pname:waitSemaphoreCount entries, and specifies the
semaphores to wait for before issuing the present request.
* pname:swapchainCount is the number of swapchains being presented to
by this command.
* pname:pSwapchains is an array of sname:VkSwapchainKHR objects with
pname:swapchainCount entries. A given swapchain mustnot: appear in this
list more than once.
* pname:pImageIndices is an array of indices into the array of each
swapchain's presentable images, with pname:swapchainCount entries. Each
entry in this array identifies the image to present on the corresponding
entry in the pname:pSwapchains array.
* pname:pResults is an array of ename:VkResult typed elements with
pname:swapchainCount entries. Applications that don't need per-swapchain
results can: use `NULL` for pname:pResults. If non-`NULL`, each entry in
pname:pResults will be set to the ename:VkResult for presenting the
swapchain corresponding to the same index in pname:pSwapchains.
include::../../validity/structs/VkPresentInfoKHR.txt[]
include::../VK_KHR_display_swapchain/display_swapchain_present.txt[]
fname:vkQueuePresentKHR, releases the acquisition of the images referenced
by pname:imageIndices. A presented images must: not be used again before it
has been reacquired using fname:vkAcquireNextImageKHR.
The processing of the presentation happens in issue order with other queue
operations, but semaphores have to be used to ensure that prior rendering
and other commands in the specified queue complete before the presentation
begins. The presentation command itself does not delay processing of
subsequent commands on the queue, however, presentation requests sent to a
particular queue are always performed in order. Exact presentation timing is
controled by the semantics of the presentation engine and native platform in
use.
include::../VK_KHR_display_swapchain/queue_present_interactions.txt[]
The result codes ename:VK_ERROR_OUT_OF_DATE_KHR and ename:VK_SUBOPTIMAL_KHR
have the same meaning when returned by fname:vkQueuePresentKHR as they do
when returned by fname:vkAcquireNextImageKHR(). If multiple swapchains are
presented, the result code is determined applying the following rules in
order:
* If the device is lost, ename:VK_ERROR_DEVICE_LOST is returned.
* If any of the target surfaces are no longer available the error
ename:VK_ERROR_SURFACE_LOST_KHR is returned.
* If any of the presents would have a result of
ename:VK_ERROR_OUT_OF_DATE_KHR if issued separately then
ename:VK_ERROR_OUT_OF_DATE_KHR is returned.
* If any of the presents would have a result of ename:VK_SUBOPTIMAL_KHR if
issued separately then ename:VK_SUBOPTIMAL_KHR is returned.
* Otherwise ename:VK_SUCCESS is returned.
Presentation is a read-only operation that will not affect the content of
the presentable images. Upon reacquiring the image and transitioning it away
from the ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR layout, the contents will be
the same as they were prior to transitioning the image to the present source
layout and presenting it. However, if a mechanism other than Vulkan is
used to modify the platform window associated with the swapchain, the
content of all presentable images in the swapchain becomes undefined.