KhronosGroup / KhronosGroup/OpenXR-Docs

How to correctly implement/interpret xrReleaseSwapchainImage specification?

Open
#177 4 comments 0 reactions 0 assignees View on GitHub
clarification synced to gitlab
Dominant language
Python
Stars
181
Forks
74
PR merge metrics
No merged PRs in 30d

Description

From the current OpenXR spec (https://registry.khronos.org/OpenXR/specs/1.1-khr/html/xrspec.html), **bold face is mine**:

`xrReleaseSwapchainImage` (excerpt):
* **Once an application is done submitting commands that reference the swapchain image**, the application must release the swapchain image.
* [xrEndFrame](https://registry.khronos.org/OpenXR/specs/1.1-khr/html/xrspec.html#xrEndFrame) **will use the most recently released swapchain image**. In each frame submitted to the compositor, only one image index from each swapchain will be used.

From `xrReleaseSwapchainImage` spec. it is not clear whether the client calls `xrReleaseSwapchainImage` right after submitting all commands to the command queue (but possibly not having the image rendered by GPU yet), or client must synchronize on GPU work before calling the function.

1. If it is a client responsibility then the rest is fine
2. If however it is a runtime responsibility then **the most recently released swapchain image** may not be ready for the compositor (yet) at the time it gets to it by following `xEndFrame` call, so it may need to
* use the "old" image still for compositing the frame - which could introduce all sorts of different inconsistencies in what is composited.
* reproject the "old state" from the previous `xEndFrame` call, but this may unnecessary block some images, which may have been already replaced by newer ones by the client, and lose the images which has been finished.

Having the compositor waiting for the image to be released by GPU may lead to lost vsync.

So the common sense would suggest that the synchronization would be the responsibility of the client app, but after having look at `hello_xr` demo I did not find any such mechanism. So what is the right approach for the runtime?

Another unclarity is related to `xrEndFrame` and the possibility for client **to not call `xrReleaseSwapchainImage`** before.

From OpenXR spec. - `Frame Submission` (excerpt):
An application may call [xrEndFrame](https://registry.khronos.org/OpenXR/specs/1.1-khr/html/xrspec.html#xrEndFrame) without having called [xrReleaseSwapchainImage](https://registry.khronos.org/OpenXR/specs/1.1-khr/html/xrspec.html#xrReleaseSwapchainImage) since the previous call to [xrEndFrame](https://registry.khronos.org/OpenXR/specs/1.1-khr/html/xrspec.html#xrEndFrame) for any swapchain passed to [xrEndFrame](https://registry.khronos.org/OpenXR/specs/1.1-khr/html/xrspec.html#xrEndFrame).

What is the right approach for the runtime then?
1. Should it implicitly call `xrReleaseSwapchainImage` on each image which has been "waited" on?
2. Should it ignore the image from the views?
3. Should it take **the most recently released swapchain image** (i.e. some older image from the swapchain, which was released already)?

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the linked OpenXR 1.1 specification sections for xrReleaseSwapchainImage and Frame Submission, then compare their wording with the hello_xr demo. Clarify the runtime and application responsibilities for GPU completion, omitted releases, and xrEndFrame behavior; done means the specification answers the listed cases unambiguously.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.