Define when changes to session state are applied. #439
Conversation
Makes the frame lifetime more explicit and explains what session data is captured and when.
explainer.md
Outdated
| @@ -251,6 +255,10 @@ function drawScene(view) { | |||
| } | |||
| ``` | |||
|
|
|||
| ### Frame lifetime | |||
There was a problem hiding this comment.
Derp. Was considering breaking off into it's own section then reconsidered. Guess I left a piece behind.
explainer.md
Outdated
| @@ -197,10 +197,14 @@ If the system's underlying XR device changes (signaled by the `devicechange` eve | |||
|
|
|||
| The WebXR Device API provides information about the current frame to be rendered via the `XRFrame` object which developers must examine each iteration of the render loop. From this object the frame's `XRViewerPose` can be queried, which contains the information about all the views which must be rendered in order for the scene to display correctly on the XR device. | |||
|
|
|||
| `XRWebGLLayer` objects are not updated automatically. To present new frames, developers must use `XRSession`'s `requestAnimationFrame()` method. When the callback function is run, it is passed both a timestamp and an `XRFrame` containing fresh rendering data that must be used to draw into the `XRWebGLLayer`s `framebuffer` during the callback. | |||
| `XRWebGLLayer` objects are not updated automatically. To present new frames, developers must use `XRSession`'s `requestAnimationFrame()` method. The first time `requestAnimationFrame()` is called for a session a new `XRFrame` is created internally. Subsequent calls to `requestAnimationFrame()` will all use the same `XRFrame` until the frame callbacks are run. At that point the next `requestAnimationFrame()` call will create a new `XRFrame` and the cycle repeats. | |||
There was a problem hiding this comment.
Might be less confusing (and prescriptive) to say something more like...
A new
XRFrameis created for each batch ofrequestAnimationFrame()callbacks.
There was a problem hiding this comment.
Worked on the wording a bit more, and used the phrasing you suggested in particular. Let me know how it reads to you now.
explainer.md
Outdated
|
|
||
| `XRFrame` objects act as snapshots of the state of the XR device and all associated inputs. The state may represent historical data, current sensor readings, or a future projection. Due to it's time-sensitive nature, an `XRFrame` is only valid during the execution of the callback that it is passed into, and once control is returned to the browser any active `XRFrame` objects are marked as inactive. Calling any method of an inactive `XRFrame` will throw a [`NotAllowedError`](https://heycam.github.io/webidl/#notallowederror). | ||
| A new `XRFrame` is created for each batch of `requestAnimationFrame()` callbacks. `XRFrame` objects act as snapshots of the state of the XR device and all associated inputs. The state may represent historical data, current sensor readings, or a future projection. Due to it's time-sensitive nature, an `XRFrame` is only valid during the execution of the callback that it is passed into, and once control is returned to the browser any active `XRFrame` objects are marked as inactive. Calling any method of an inactive `XRFrame` will throw a [`NotAllowedError`](https://heycam.github.io/webidl/#notallowederror). |
There was a problem hiding this comment.
The first sentence here implies that XRFrames are basically created only for rAF callbacks, while another key source is input event callbacks. This is key context for the third sentence, which talks about "historical data", as the rAF XRFrame instances will all be about a future-predicted photon time.
There was a problem hiding this comment.
Good catch. Updated that line to say:
A new
XRFrameis created for each batch ofrequestAnimationFrame()callbacks or for certain events that are associated with tracking data.
|
Thanks for the feedback @thetuvix! At this point since it doesn't seem like there's any further feedback I'll go ahead and merge this change in when @NellWaliczek clears her review bit. |
explainer.md
Outdated
| `XRFrame` objects act as snapshots of the state of the XR device and all associated inputs. The state may represent historical data, current sensor readings, or a future projection. Due to it's time-sensitive nature, an `XRFrame` is only valid during the execution of the callback that it is passed into, and once control is returned to the browser any active `XRFrame` objects are marked as inactive. Calling any method of an inactive `XRFrame` will throw a [`NotAllowedError`](https://heycam.github.io/webidl/#notallowederror). | ||
| A new `XRFrame` is created for each batch of `requestAnimationFrame()` callbacks or for certain events that are associated with tracking data. `XRFrame` objects act as snapshots of the state of the XR device and all associated inputs. The state may represent historical data, current sensor readings, or a future projection. Due to it's time-sensitive nature, an `XRFrame` is only valid during the execution of the callback that it is passed into, and once control is returned to the browser any active `XRFrame` objects are marked as inactive. Calling any method of an inactive `XRFrame` will throw a [`NotAllowedError`](https://heycam.github.io/webidl/#notallowederror). | ||
|
|
||
| The `XRFrame` also makes a copy of the `XRSession`'s "render state", such as `depthNear/Far` values and the `baseLayer`, at the time the first `requestAnimationFrame()` call in the current batch was made. This captured render state is what will be used when the frame is being composited by the XR hardware. Any subsequent changes the developer makes to the session's render state will not be applied until the the next `XRFrame` is created. |
There was a problem hiding this comment.
This captured render state is what will be used when the frame is being composited by the XR hardware.
This may accidentally be implying that the developer isn't directly impact by these changes, so it might be worth calling out that, for example, depthNear/Far changes will impact the projection matrices.
There was a problem hiding this comment.
Good call. Updated to say:
This captured render state is what will be used when computing view information like projection matrices and when the frame is being composited by the XR hardware.
Makes the frame lifetime more explicit and explains what session data is captured and when. This is not something that's had an explicit issue created for it, but it has come up repeatedly as we've discussed various mutable bits of session state. Will become even more important as we add more mutable state to the session in the future.
Also contemplating a related change to make the state that changes on a per-frame basis more explicit, but that'll be a followup to this.