vkAcquireNextImageKHR unclear relationship between return codes and image acquisition

[Hawk777]

In the documentation for vkAcquireNextImageKHR, four return codes (VK_SUCCESS, VK_TIMEOUT, VK_NOT_READY, and VK_SUBOPTIMAL_KHR) are listed as “success”es, with a bunch of others being listed as “failure”s.

However, the immediately following paragraph states:

When successful, vkAcquireNextImageKHR acquires a presentable image from swapchain that an application can use, and sets pImageIndex to the index of that image within the swapchain.

Intuitively, this seems clearly wrong: an image should be acquired if the result is VK_SUCCESS or VK_SUBOPTIMAL_KHR, but not if the result is VK_TIMEOUT or VK_NOT_READY, even though those are considered “success” results.

The next paragraph states:

If timeout is zero, then vkAcquireNextImageKHR does not wait, and will either successfully acquire an image, or fail and return VK_NOT_READY if no image is available.

This seems poorly worded and potentially contradictory: if no image is immediately available, then vkAcquireNextImageKHR will fail and return… a success code?

[stonesthrow]

You are quite right of course and thank you for raising issue. I will fix the text that SUCCESS and SUBOPTIMAL will be successful with Image, the other two are failures with no image.

I'll try to get corrected text ASAP.

[Hawk777]

There might be a bigger problem than just vkAcquireNextImageKHR, actually. Section 3.8 has this to say:

Successful completion codes are returned when a command needs to communicate success or status information. All successful completion codes are non-negative values.

Run time error codes are returned when a command needs to communicate a failure that could only be detected at runtime. All runtime error codes are negative values.

But VK_TIMEOUT and VK_NOT_READY are positive numbers, and that obviously can’t be changed. So changing the writeup of just vkAcquireNextImageKHR would then make it inconsistent with the overall spec-wide definition of success and failure.

[stonesthrow]

A very good point, thank you. I might have to show this to the main Vulkan group for comment - try to avoid that inconsistency.

[oddhack]

This should be fixed in the 1.3.239 spec update.

[Hawk777]

Hm, it looks like only the first part was fixed. I’m looking at 1.3.240, and it still says “If timeout is zero, … fail and return VK_NOT_READY if no image is available” despite VK_NOT_READY being a success code not a failure code.

[oddhack]

@stonesthrow reopening per previous comment - should go back on the SI TSG agenda?

[stonesthrow]

Yes, keep open. There are codes that are not failures, like TIMEOUT and NOT_READY, that I'm not sure the latest update covered.

[stonesthrow]

Reopen for me to check language for non-errors