Some more suspicious swapchain rfc keyword usage by stonesthrow · Pull Request #1680 · KhronosGroup/Vulkan-Docs

stonesthrow · 2021-11-08T22:51:38Z

Closes #1586

Change "should be interpreted as follows" to " indicates the following"

"may" change to "must"

chapters/VK_KHR_shared_presentable_image/wsi.txt

chapters/VK_KHR_swapchain/wsi.txt

…RFC-keyword-usage

llandwerlin-intel · 2022-01-19T17:16:38Z

Looks good.

linyaa-kiwi · 2022-01-19T17:16:47Z

lgtm

cubanismo · 2022-01-19T17:19:45Z

chapters/VK_EXT_display_control/swapchain_counters.txt


 If a counter is not available because the swapchain is out of date, the
-implementation may: return ename:VK_ERROR_OUT_OF_DATE_KHR.
+implementation must: return ename:VK_ERROR_OUT_OF_DATE_KHR.


When we drafted the OUT_OF_DATE language, some IHVs were uncomfortable with requiring errors in states that are defined as OUT_OF_DATE, and carry on as if things are fine instead. This language is fine with me, but other driver vendors may still object to such requirements.

OK. Good history. The issue by is KrO0ze identifying non-exact language. Do we know who objected? see if they reaffirm stance or not.

Lot of code relies on mustiness of this. So if you preserve "may", it needs some serious acompanying note explaining what exactly that implies as well as what is the correct way to deal with swapchain state.

I can imagine though the failure could be allowed to be deferred. E.g. acquire pretends success, and then it fails at present. Still needs to be copiously noted in spec if that can happen and explicitly how far the driver can push that leeway.

@cubanismo - lets see if we can craft some text that will work here.

Not sure if resolved per @cubanismo comment, but I certainly am happy with "must"...

Discussed in working group today: No objection to proceeding with "must:"

chapters/VK_KHR_shared_presentable_image/wsi.txt

krOoze · 2022-01-20T21:33:27Z

chapters/VK_KHR_swapchain/wsi.txt

 image from the new swapchain is ready to be presented.
-As usual, flink:vkQueuePresentKHR may: fail if pname:oldSwapchain has
+flink:vkQueuePresentKHR must: fail if pname:oldSwapchain has
 entered a state that causes ename:VK_ERROR_OUT_OF_DATE_KHR to be returned.


This does not fix the full extent of the complaint in the original Issue.

The problem is also the sentence is tautological. If VK_ERROR_OUT_OF_DATE_KHR was returned, then by definition it did fail (no may or must about it).

I think the intention of the sentence is the following (and so should the wording match that)

Retired oldSwapchain may: still become unusable as much as non-retired swapchain. When that happens, it is treated identically by vkQueuePresentKHR; the command must return VK_ERROR_OUT_OF_DATE_KHR.

krOoze · 2022-01-20T21:36:25Z

chapters/VK_KHR_swapchain/wsi.txt

@@ -258,7 +258,7 @@ flink:vkQueuePresentKHR any images it had already acquired from
 pname:oldSwapchain.
 E.g., an application may present an image from the old swapchain before an


It is "just" a note, though I would still avoid unmarkupped RFC terminology. Should be "can:".

Change to read better

Try a little better wording

…RFC-keyword-usage

krOoze · 2022-07-07T22:19:32Z

chapters/VK_EXT_display_control/swapchain_counters.txt


 If a counter is not available because the swapchain is out of date, the
-implementation may: return ename:VK_ERROR_OUT_OF_DATE_KHR.
+implementation must: return ename:VK_ERROR_OUT_OF_DATE_KHR.


Not sure if resolved per @cubanismo comment, but I certainly am happy with "must"...

krOoze · 2022-07-07T22:26:55Z

chapters/VK_KHR_swapchain/wsi.txt

-image from the new swapchain is ready to be presented.
-As usual, flink:vkQueuePresentKHR may: fail if pname:oldSwapchain has
-entered a state that causes ename:VK_ERROR_OUT_OF_DATE_KHR to be returned.
+pname:oldSwapchain. flink:vkQueuePresentKHR must: return ename:VK_ERROR_OUT_OF_DATE_KHR.


This seems wrong, and contrary to the original text.

Agreed. This should probably stay as-is. Was there concern about the informal nature of the language used here or something? It seems fine for the context (A note, not normative content). Arguably all the normative terms (must:, can:, etc.) should be removed from the note, but I think there are several other examples of those leaking into spec notes.

The intent is that when a non-out-of-date swapchain is retired, applications are allowed to continue presenting its images if they were already acquired. This enables smooth transitions from retired->new swapchains. If implementations can not implement that, they are of course allowed to return OUT_OF_DATE when applications attempt it. CTS now contains coverage for this usage.

…RFC-keyword-usage

linyaa-kiwi · 2022-11-30T16:33:49Z

@stonesthrow Is this MR still alive? It appears that everything is resolved except one comment by krooze.

oddhack · 2023-04-13T09:14:51Z

@stonesthrow Is this MR still alive? It appears that everything is resolved except one comment by krooze.

@stonesthrow pinging on this PR again - would be nice to get it off the queue.

stonesthrow · 2023-04-27T14:24:00Z

@oddhack Sorry, I just haven't had any bandwidth to look into this again. At this time I am swamped.
Maybe its close to complete. It was either this or another issue that the underlying text of the spec got a big change and so I was thinking this needed to re-investigated to be sure it changes were needed and correct.

cubanismo

@stonesthrow Did you still want to proceed with this PR? If so, please address the feedback.

cubanismo · 2025-12-03T18:10:39Z

chapters/VK_EXT_display_control/swapchain_counters.txt


 If a counter is not available because the swapchain is out of date, the
-implementation may: return ename:VK_ERROR_OUT_OF_DATE_KHR.
+implementation must: return ename:VK_ERROR_OUT_OF_DATE_KHR.


Discussed in working group today: No objection to proceeding with "must:"

cubanismo · 2025-12-03T18:16:11Z

chapters/VK_KHR_swapchain/wsi.txt

-image from the new swapchain is ready to be presented.
-As usual, flink:vkQueuePresentKHR may: fail if pname:oldSwapchain has
-entered a state that causes ename:VK_ERROR_OUT_OF_DATE_KHR to be returned.
+pname:oldSwapchain. flink:vkQueuePresentKHR must: return ename:VK_ERROR_OUT_OF_DATE_KHR.


Agreed. This should probably stay as-is. Was there concern about the informal nature of the language used here or something? It seems fine for the context (A note, not normative content). Arguably all the normative terms (must:, can:, etc.) should be removed from the note, but I think there are several other examples of those leaking into spec notes.

The intent is that when a non-out-of-date swapchain is retired, applications are allowed to continue presenting its images if they were already acquired. This enables smooth transitions from retired->new swapchains. If implementations can not implement that, they are of course allowed to return OUT_OF_DATE when applications attempt it. CTS now contains coverage for this usage.

stonesthrow added 3 commits November 8, 2021 15:42

Update wsi.txt

0329fb3

Change "should be interpreted as follows" to " indicates the following"

Update swapchain_counters.txt

5c24ec7

"may" change to "must"

Update wsi.txt

41150d5

"may" change to "must"

stonesthrow added the System Integration label Nov 8, 2021

stonesthrow added this to the Needs Approval milestone Nov 8, 2021

oddhack reviewed Nov 9, 2021

View reviewed changes

chapters/VK_KHR_shared_presentable_image/wsi.txt Outdated Show resolved Hide resolved

oddhack reviewed Nov 9, 2021

View reviewed changes

chapters/VK_KHR_swapchain/wsi.txt Outdated Show resolved Hide resolved

stonesthrow added 3 commits December 6, 2021 14:56

vkGetSwapchainStatusKHR codes

e36c231

Removed as-usual text

f12c413

Merge branch 'KhronosGroup:main' into Some-more-suspicious-swapchain-…

32416d0

…RFC-keyword-usage

cubanismo reviewed Jan 19, 2022

View reviewed changes

krOoze suggested changes Jan 20, 2022

View reviewed changes

stonesthrow added 3 commits February 4, 2022 16:19

Change Status code line

6cdf707

Change to read better

Reword return from retired oldSwapchain on vkQueuePresent

b64bd1f

Try a little better wording

Merge branch 'KhronosGroup:main' into Some-more-suspicious-swapchain-…

af04900

…RFC-keyword-usage

krOoze reviewed Jul 7, 2022

View reviewed changes

Merge branch 'KhronosGroup:main' into Some-more-suspicious-swapchain-…

ceb4ba8

…RFC-keyword-usage

cubanismo reviewed Dec 3, 2025

View reviewed changes

		@@ -258,7 +258,7 @@ flink:vkQueuePresentKHR any images it had already acquired from
		pname:oldSwapchain.
		E.g., an application may present an image from the old swapchain before an

Conversation

stonesthrow commented Nov 8, 2021

Uh oh!

Uh oh!

Uh oh!

llandwerlin-intel commented Jan 19, 2022

Uh oh!

linyaa-kiwi commented Jan 19, 2022

Uh oh!

cubanismo Jan 19, 2022

Choose a reason for hiding this comment

Uh oh!

stonesthrow Jan 20, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

krOoze Jan 20, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stonesthrow Feb 4, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

krOoze Jul 7, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubanismo Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

krOoze Jan 20, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stonesthrow Feb 4, 2022

Choose a reason for hiding this comment

Uh oh!

krOoze Jan 20, 2022

Choose a reason for hiding this comment

Uh oh!

krOoze Jul 7, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

krOoze Jul 7, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubanismo Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

linyaa-kiwi commented Nov 30, 2022

Uh oh!

oddhack commented Apr 13, 2023

Uh oh!

stonesthrow commented Apr 27, 2023

Uh oh!

cubanismo left a comment

Choose a reason for hiding this comment

Uh oh!

cubanismo Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

cubanismo Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

stonesthrow Jan 20, 2022 •

edited

Loading

krOoze Jan 20, 2022 •

edited

Loading

stonesthrow Feb 4, 2022 •

edited

Loading

krOoze Jul 7, 2022 •

edited

Loading

krOoze Jan 20, 2022 •

edited

Loading

krOoze Jul 7, 2022 •

edited

Loading

krOoze Jul 7, 2022 •

edited

Loading