forked from mdn/content
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Document WebXR layer init & XRCompositionLayer (mdn#8948)
* Document WebXR layer init & XRCompositionLayer * Apply suggestions from code review Co-authored-by: Joe Medley <[email protected]> Co-authored-by: Joe Medley <[email protected]>
- Loading branch information
Showing
9 changed files
with
395 additions
and
0 deletions.
There are no files selected for viewing
43 changes: 43 additions & 0 deletions
43
files/en-us/web/api/xrcompositionlayer/blendtexturesourcealpha/index.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,43 @@ | ||
| --- | ||
| title: XRCompositionLayer.blendTextureSourceAlpha | ||
| slug: Web/API/XRCompositionLayer/blendTextureSourceAlpha | ||
| tags: | ||
| - API | ||
| - Property | ||
| - Reference | ||
| - VR | ||
| - WebXR | ||
| - WebXR API | ||
| - WebXR Device API | ||
| - XR | ||
| browser-compat: api.XRCompositionLayer.blendTextureSourceAlpha | ||
| --- | ||
| {{APIRef("WebXR Device API")}} | ||
|
|
||
| The **`blendTextureSourceAlpha`** property of the {{domxref("XRCompositionLayer")}} interface is a boolean enabling the layer's texture {{Glossary("Alpha", "alpha channel")}}. | ||
|
|
||
| ## Value | ||
|
|
||
| A boolean. `true` enables the alpha channel, `false` disables it. | ||
|
|
||
| ## Examples | ||
|
|
||
| ### Setting a layer's texture alpha channel | ||
|
|
||
| The following code snippet toggles a layer to opaque and back. | ||
|
|
||
| ```js | ||
| myLayer.blendTextureSourceAlpha = !myLayer.blendTextureSourceAlpha; | ||
| ``` | ||
|
|
||
| ## Specifications | ||
|
|
||
| {{Specifications}} | ||
|
|
||
| ## Browser compatibility | ||
|
|
||
| {{Compat}} | ||
|
|
||
| ## See also | ||
|
|
||
| - {{Glossary("Alpha", "Alpha channel")}} |
48 changes: 48 additions & 0 deletions
48
files/en-us/web/api/xrcompositionlayer/chromaticaberrationcorrection/index.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,48 @@ | ||
| --- | ||
| title: XRCompositionLayer.chromaticAberrationCorrection | ||
| slug: Web/API/XRCompositionLayer/chromaticAberrationCorrection | ||
| tags: | ||
| - API | ||
| - Property | ||
| - Reference | ||
| - VR | ||
| - WebXR | ||
| - WebXR API | ||
| - WebXR Device API | ||
| - XR | ||
| browser-compat: api.XRCompositionLayer.chromaticAberrationCorrection | ||
| --- | ||
| {{APIRef("WebXR Device API")}} | ||
|
|
||
| The **`chromaticAberrationCorrection`** property of the {{domxref("XRCompositionLayer")}} interface is a boolean enabling the layer's optical chromatic aberration correction. | ||
|
|
||
| Chromatic aberration ("color fringing") is an imperfection wherein a lens fails to focus all wavelengths of colors at the same point. This effect results in a seven-colored rainbow. To remove these imperfections a process called chromatic aberration correction is needed. For more information, read [Chromatic aberration](https://en.wikipedia.org/wiki/Chromatic_aberration) on Wikipedia. | ||
|
|
||
| ## Value | ||
|
|
||
| A boolean. `true` enables chromatic aberration correction for the layer; `false` disables it. | ||
| If the device doesn't support this feature, `chromaticAberrationCorrection` is {{jsxref("null")}} and setting it will not do anything. | ||
|
|
||
| If `chromaticAberrationCorrection` was changed, it will take effect in the next frame. | ||
|
|
||
| ## Examples | ||
|
|
||
| ### Setting a layer's chromatic aberration correction | ||
|
|
||
| The following code snippet enables the layer's chromatic aberration correction. | ||
|
|
||
| ```js | ||
| myLayer.chromaticAberrationCorrection = true; | ||
| ``` | ||
|
|
||
| ## Specifications | ||
|
|
||
| {{Specifications}} | ||
|
|
||
| ## Browser compatibility | ||
|
|
||
| {{Compat}} | ||
|
|
||
| ## See also | ||
|
|
||
| - [Chromatic aberration](https://en.wikipedia.org/wiki/Chromatic_aberration) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,48 @@ | ||
| --- | ||
| title: XRCompositionLayer.destroy() | ||
| slug: Web/API/XRCompositionLayer/destroy | ||
| tags: | ||
| - API | ||
| - Method | ||
| - Reference | ||
| - AR | ||
| - VR | ||
| - XR | ||
| - WebXR | ||
| browser-compat: api.XRCompositionLayer.destroy | ||
| --- | ||
| {{APIRef("WebXR Device API")}} | ||
|
|
||
| The **`destroy()`** method of the {{domxref("XRCompositionLayer")}} interface deletes the references to the underlying graphics library for the layer. It also sets the color textures and depth stencil texture arrays to an empty array. | ||
|
|
||
| ## Syntax | ||
|
|
||
| ```js | ||
| destroy() | ||
| ``` | ||
|
|
||
| ### Parameters | ||
|
|
||
| None. | ||
|
|
||
| ### Return value | ||
|
|
||
| Returns {{jsxref("undefined")}}. | ||
|
|
||
| ## Examples | ||
|
|
||
| ### Deleting a layer | ||
|
|
||
| Call `destroy()` to delete a layer. | ||
|
|
||
| ```js | ||
| myLayer.destroy(); | ||
| ``` | ||
|
|
||
| ## Specifications | ||
|
|
||
| {{Specifications}} | ||
|
|
||
| ## Browser compatibility | ||
|
|
||
| {{Compat}} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,67 @@ | ||
| --- | ||
| title: XRCompositionLayer | ||
| slug: Web/API/XRCompositionLayer | ||
| tags: | ||
| - API | ||
| - AR | ||
| - Augmented Reality | ||
| - Interface | ||
| - Reference | ||
| - VR | ||
| - Virtual Reality | ||
| - WebXR | ||
| - WebXR Device API | ||
| - XR | ||
| - XRCompositionLayer | ||
| browser-compat: api.XRCompositionLayer | ||
| --- | ||
| {{securecontext_header}}{{APIRef("WebXR Device API")}} | ||
|
|
||
| The **`XRCompositionLayer`** interface of the [WebXR Device API](/en-US/docs/Web/API/WebXR_Device_API) is a base class that defines a set of common properties and behaviors for WebXR layer types. It is not constructable on its own. | ||
|
|
||
| Several layer types inherit from `XRCompositionLayer`: | ||
| - {{domxref("XREquirectLayer")}} | ||
| - {{domxref("XRCubeLayer")}} | ||
| - {{domxref("XRCylinderLayer")}} | ||
| - {{domxref("XRProjectionLayer")}} | ||
| - {{domxref("XRQuadLayer")}} | ||
|
|
||
| `XRCompositionLayer` itself inherits from the general {{domxref("XRLayer")}} class (which inherits from {{domxref("EventTarget")}}). | ||
|
|
||
| ## Properties | ||
|
|
||
| - {{domxref("XRCompositionLayer.blendTextureSourceAlpha")}} | ||
| - : A boolean enabling the layer's texture alpha channel. | ||
| - {{domxref("XRCompositionLayer.chromaticAberrationCorrection")}} | ||
| - : A boolean enabling optical chromatic aberration correction for the layer if the device supports it, {{jsxref("null")}} otherwise. | ||
| - {{domxref("XRCompositionLayer.layout")}} {{ReadOnlyInline}} | ||
| - : The layout type of the layer. | ||
| - {{domxref("XRCompositionLayer.mipLevels")}} {{ReadOnlyInline}} | ||
| - : The number of mip levels in the color and texture data for the layer. | ||
| - {{domxref("XRCompositionLayer.needsRedraw")}} {{ReadOnlyInline}} | ||
| - : A boolean signaling that the layer should be rerendered in the next frame. | ||
|
|
||
| ## Methods | ||
|
|
||
| *Inherits methods from its parent, {{domxref("EventTarget")}}*. | ||
|
|
||
| - {{domxref("XRCompositionLayer.destroy()")}} | ||
| - : Deletes the underlying layer attachments. | ||
|
|
||
| ## Specifications | ||
|
|
||
| {{Specifications}} | ||
|
|
||
| ## Browser compatibility | ||
|
|
||
| {{Compat}} | ||
|
|
||
| ## See also | ||
|
|
||
| - {{domxref("XRLayer")}} | ||
| - {{domxref("EventTarget")}} | ||
| - {{domxref("XREquirectLayer")}} | ||
| - {{domxref("XRCubeLayer")}} | ||
| - {{domxref("XRCylinderLayer")}} | ||
| - {{domxref("XRProjectionLayer")}} | ||
| - {{domxref("XRQuadLayer")}} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,72 @@ | ||
| --- | ||
| title: XRCompositionLayer.layout | ||
| slug: Web/API/XRCompositionLayer/layout | ||
| tags: | ||
| - API | ||
| - Property | ||
| - Reference | ||
| - VR | ||
| - WebXR | ||
| - WebXR API | ||
| - WebXR Device API | ||
| - XR | ||
|
|
||
| browser-compat: api.XRCompositionLayer.layout | ||
| --- | ||
| {{APIRef("WebXR Device API")}} | ||
|
|
||
| The read-only **`layout`** property of the {{domxref("XRCompositionLayer")}} interface is the layout type of the layer. | ||
|
|
||
| To specify the layout type of a layer, use one of the layer creation methods and their `layout` option: | ||
|
|
||
| - {{domxref("XRWebGLBinding.createQuadLayer()")}} | ||
| - {{domxref("XRWebGLBinding.createCylinderLayer()")}} | ||
| - {{domxref("XRWebGLBinding.createEquirectLayer()")}} | ||
| - {{domxref("XRWebGLBinding.createCubeLayer()")}} | ||
|
|
||
| ## Value | ||
|
|
||
| A string. Possible values: | ||
|
|
||
| - `default` | ||
| - : The layer accommodates all views of the session. | ||
| - `mono` | ||
| - : A single {{domxref("XRSubImage")}} is allocated and presented to both eyes. | ||
| - `stereo` | ||
| - : The user agent decides how it allocates the {{domxref("XRSubImage")}} (one or two) and the layout (top/bottom or left/right). | ||
| - `stereo-left-right` | ||
| - : A single {{domxref("XRSubImage")}} is allocated. Left eye gets the left area of the texture, right eye the right. | ||
| - `stereo-top-bottom` | ||
| - : A single {{domxref("XRSubImage")}} is allocated. Left eye gets the top area of the texture, right eye the bottom. | ||
|
|
||
| ## Examples | ||
|
|
||
| ### Setting and getting a layer's layout | ||
|
|
||
| To specify a layer's layout, use a layer creation method (like {{domxref("XRWebGLBinding.createQuadLayer()")}}) and its `layout` option. To retrieve the type of layer layout, use the `layout` property: | ||
|
|
||
| ```js | ||
| const layer = xrGlBinding.createQuadLayer({ | ||
| pixelWidth: 1024, | ||
| pixelHeight: 768, | ||
| layout: "stereo" | ||
| }); | ||
|
|
||
| layer.layout; // "stereo" | ||
| ``` | ||
|
|
||
| ## Specifications | ||
|
|
||
| {{Specifications}} | ||
|
|
||
| ## Browser compatibility | ||
|
|
||
| {{Compat}} | ||
|
|
||
| ## See also | ||
|
|
||
| - {{domxref("XRSubImage")}} | ||
| - {{domxref("XRWebGLBinding.createQuadLayer()")}} | ||
| - {{domxref("XRWebGLBinding.createCylinderLayer()")}} | ||
| - {{domxref("XRWebGLBinding.createEquirectLayer()")}} | ||
| - {{domxref("XRWebGLBinding.createCubeLayer()")}} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,56 @@ | ||
| --- | ||
| title: XRCompositionLayer.mipLevels | ||
| slug: Web/API/XRCompositionLayer/mipLevels | ||
| tags: | ||
| - API | ||
| - Property | ||
| - Reference | ||
| - VR | ||
| - WebXR | ||
| - WebXR API | ||
| - WebXR Device API | ||
| - XR | ||
| browser-compat: api.XRCompositionLayer.mipLevels | ||
| --- | ||
| {{APIRef("WebXR Device API")}} | ||
|
|
||
| The read-only **`mipLevels`** property of the {{domxref("XRCompositionLayer")}} interface is a layer's number of mip levels in the color and texture data. | ||
|
|
||
| The desired number of mip levels can be specified when creating layers. However, if the user agent can't create the requested number, it can create less. Use `mipLevels` to determine the actual number of mip levels for a layer. | ||
|
|
||
| ## Value | ||
|
|
||
| A number equal or smaller to the requested mip levels when a layer has been created. | ||
|
|
||
| ## Examples | ||
|
|
||
| ### Getting a layer's mip levels | ||
|
|
||
| The `mipLevels` property indicates the actual number of mip levels that have been created. In this example, the desired number of 5 mip levels that had been requested for an {{domxref("XRQuadLayer")}} could be full-filled. | ||
|
|
||
| ```js | ||
| let xrGLBinding = new XRWebGLBinding(session, gl); | ||
| let quadLayer = xrGLBinding.createQuadLayer({ | ||
| space: refSpace, | ||
| viewPixelHeight: layerHeight, | ||
| viewPixelWidth: layerWidth, | ||
| width: 1.0, | ||
| height: 1.0, | ||
| mipLevels: 5, | ||
| transform : new XRRigidTransform({ /* ... */}), | ||
| }); | ||
|
|
||
| quadLayer.mipLevels; // 5 | ||
| ``` | ||
|
|
||
| ## Specifications | ||
|
|
||
| {{Specifications}} | ||
|
|
||
| ## Browser compatibility | ||
|
|
||
| {{Compat}} | ||
|
|
||
| ## See also | ||
|
|
||
| - [Mipmap](https://en.wikipedia.org/wiki/Mipmap) on Wikipedia |
57 changes: 57 additions & 0 deletions
57
files/en-us/web/api/xrcompositionlayer/needsredraw/index.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,57 @@ | ||
| --- | ||
| title: XRCompositionLayer.needsRedraw | ||
| slug: Web/API/XRCompositionLayer/needsRedraw | ||
| tags: | ||
| - API | ||
| - Property | ||
| - Reference | ||
| - VR | ||
| - WebXR | ||
| - WebXR API | ||
| - WebXR Device API | ||
| - XR | ||
| browser-compat: api.XRCompositionLayer.needsRedraw | ||
| --- | ||
| {{APIRef("WebXR Device API")}} | ||
|
|
||
| The read-only **`needsRedraw`** property of the {{domxref("XRCompositionLayer")}} interface is a boolean signaling that the layer should be rerendered in the next frame. | ||
|
|
||
| The need for redrawing can occur when the underlying resources of a layer are lost due to textures that might have been freed by the compositor under the hood. This might happen when the device falls asleep or when the browser switches context (to an operating system dialog or similar) and then comes back. | ||
|
|
||
| Redrawing is not a problem for layers which are updated with every frame. However, for layers updated infrequently, or for static layers (where you can only draw once after creation or after a `redraw` event), the layer's content might be lost and need to be redrawn. If the layer's resources are lost, the `needsRedraw` property will be `true` and a `redraw` event is fired on the layer. | ||
|
|
||
| ## Value | ||
|
|
||
| A boolean. `true` indicates a rerendering is needed in the next frame, `false` indicates no re-rendering is needed. | ||
|
|
||
| ## Examples | ||
|
|
||
| ### Redrawing layers | ||
|
|
||
| Use the `needsRedrawing` property to check if a layer needs to be redrawn and then redraw it. | ||
|
|
||
| ```js | ||
| function onXRFrame(time, frame) { | ||
|
|
||
| /* ... */ | ||
|
|
||
| if (quadLayer.needsRedraw) { | ||
| // redraw the layer | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Specifications | ||
|
|
||
| {{Specifications}} | ||
|
|
||
| ## Browser compatibility | ||
|
|
||
| {{Compat}} | ||
|
|
||
| ## See also | ||
|
|
||
| - {{domxref("XREquirectLayer")}}: {{domxref("XREquirectLayer.redraw_event", "redraw")}} event | ||
| - {{domxref("XRCubeLayer")}}: {{domxref("XRCubeLayer.redraw_event", "redraw")}} event | ||
| - {{domxref("XRCylinderLayer")}}: {{domxref("XRCylinderLayer.redraw_event", "redraw")}} event | ||
| - {{domxref("XRQuadLayer")}}: {{domxref("XRQuadLayer.redraw_event", "redraw")}} event |
Oops, something went wrong.