Editorial review: Document WebXR visibilitymaskchange event by chrisdavidmills · Pull Request #43975 · mdn/content

chrisdavidmills · 2026-04-30T13:54:32Z

Description

Chrome 144 adds support for the visibilitymaskchange event/XRVisibilityMaskChange event object; see https://chromestatus.com/feature/5073760055066624.

This PR adds documentation for:

The XRVisibilityMaskChange event object and all its members.
The visibilitymaskchange event
The XRView.index property.

Motivation

Additional details

Related issues and pull requests

github-actions · 2026-04-30T13:56:30Z

Preview URLs (11 pages)

Flaws (4)

Note! 8 documents with no flaws that don't need to be listed. 🎉

Found an unexpected or unresolvable flaw? Please report it here.

URL: /en-US/docs/Web/API/XRVisibilityMaskChangeEvent/indices
Title: XRVisibilityMaskChangeEvent: indices property
Flaw count: 1

macros:
- Macro domxref produces link /en-US/docs/Web/API/Uint32Array which is a redirect

URL: /en-US/docs/Web/API/XRVisibilityMaskChangeEvent/vertices
Title: XRVisibilityMaskChangeEvent: vertices property
Flaw count: 1

macros:
- Macro domxref produces link /en-US/docs/Web/API/Float32Array which is a redirect

URL: /en-US/docs/Web/API/XRVisibilityMaskChangeEvent/XRVisibilityMaskChangeEvent
Title: XRVisibilityMaskChangeEvent: XRVisibilityMaskChangeEvent() constructor
Flaw count: 2

macros:
- Macro domxref produces link /en-US/docs/Web/API/Uint32Array which is a redirect
- Macro domxref produces link /en-US/docs/Web/API/Float32Array which is a redirect

External URLs (2)

URL: /en-US/docs/Web/API/XRSession/visibilitymaskchange_event
Title: XRSession: visibilitymaskchange event

https://github.com/cabanier/three.js/blob/78a3227d95fc29e001d8cd139504c643987430c5/src/renderers/webxr/WebXRManager.js (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/XRVisibilityMaskChangeEvent
Title: XRVisibilityMaskChangeEvent

https://github.com/cabanier/three.js/blob/78a3227d95fc29e001d8cd139504c643987430c5/src/renderers/webxr/WebXRManager.js (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2026-05-01 08:21:34)

alcooper91 · 2026-04-30T16:21:31Z

+
+```js
+xrSession.addEventListener("visibilitymaskchange", (e) => {
+  if (userSessionEnded) {


NIT: This is a little confusing, I thought it was tracking some variable that the session had already ended at first glance/read through. maybe userRequestsSessionEnd and clear it in the block as well?

That's a fair comment. I've updated the variable name throughout to userRequestsSessionEnd in my next commit.

alcooper91 · 2026-04-30T16:22:32Z

+
+{{APIRef("WebXR Device API")}}{{SecureContext_Header}}
+
+The read-only **`vertices`** property of the {{domxref("XRVisibilityMaskChangeEvent")}} interface is an array of coordinates representing the vertices required to draw the entire scene displayed in the {{domxref("XRView")}}. If this array is empty, the whole region of the `XRView` will be drawn.


Maybe also reference here that it's intended to be referenced into by the indices property.

Sure, makes sense. I've added the following in a new paragraph:

The {{domxref("XRVisibilityMaskChangeEvent.indices", "indices")}} array specifies the indices of the vertices array that should be drawn to display the currently visible part of the scene displayed in the XRView.

More detail required than that to allow readers to understand what is going on

If these are floats, then they are numbers, not "points" so my guess in https://github.com/mdn/content/pull/43975/changes#r3215903956 is completely wrong. But the comment is valid - a reader should be able to work out how this works.

alcooper91

LGTM

hamishwillee · 2026-05-11T00:10:37Z

+A number.
+
+## Examples
+


As per the template, though it feels a bit pointless

Suggested change

### Basic usage

hamishwillee · 2026-05-11T00:11:57Z

+
+{{APIRef("WebXR Device API")}}{{SecureContext_Header}}
+
+The read-only **`index`** property of the {{domxref("XRView")}} interface indicates the index of the current `XRView` in the {{domxref("XRViewerPose.views")}} array.


For all these it is this form

Suggested change

The read-only **`index`** property of the {{domxref("XRView")}} interface indicates the index of the current `XRView` in the {{domxref("XRViewerPose.views")}} array.

The **`index`** read-only property of the {{domxref("XRView")}} interface indicates the index of the current `XRView` in the {{domxref("XRViewerPose.views")}} array.

https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/API_property_subpage_template

hamishwillee · 2026-05-11T00:12:29Z

+
+{{APIRef("WebXR Device API")}}{{SecureContext_Header}}
+
+The read-only **`eye`** property of the {{domxref("XRVisibilityMaskChangeEvent")}} interface indicates the eye the mask applies to.


For all

Suggested change

The read-only **`eye`** property of the {{domxref("XRVisibilityMaskChangeEvent")}} interface indicates the eye the mask applies to.

The **`eye`** read-only property of the {{domxref("XRVisibilityMaskChangeEvent")}} interface indicates the eye the mask applies to.

hamishwillee · 2026-05-11T01:15:46Z

+An emumerated value indicating which eye the mask applies to, which can be one of:
+
+- `left`
+  - : The {{domxref("XRView")}} represents the point-of-view of the viewer's left eye.
+- `right`
+  - : The view represents the viewer's right eye.
+- `none`
+  - : The `XRView` describes a monoscopic view, or the view otherwise doesn't represent a particular eye's point-of-view.


There is a bunch of stuff that confuses me here. How does {{domxref("XRView")}} map to eye? Mentioning a view below feels like he wrong place - if there is a relationship then push it into the intro above or in the intro sentence here.
This bit should look like

Suggested change

An emumerated value indicating which eye the mask applies to, which can be one of:

- `left`

- : The {{domxref("XRView")}} represents the point-of-view of the viewer's left eye.

- `right`

- : The view represents the viewer's right eye.

- `none`

- : The `XRView` describes a monoscopic view, or the view otherwise doesn't represent a particular eye's point-of-view.

An emumerated value indicating which eye the mask applies to from the viewer's perspective.

This can be one of:

- `left`

- : The viewer's left eye.

- `right`

- : The viewer's right eye.

- `none`

- : A monoscopic view, or the view otherwise doesn't represent a particular eye's point-of-view.

hamishwillee · 2026-05-11T01:16:07Z

+  - : The `XRView` describes a monoscopic view, or the view otherwise doesn't represent a particular eye's point-of-view.
+
+## Examples
+


Suggested change

### Basic usage

hamishwillee · 2026-05-11T01:16:41Z

+
+{{APIRef("WebXR Device API")}}{{SecureContext_Header}}
+
+The read-only **`index`** property of the {{domxref("XRVisibilityMaskChangeEvent")}} interface indicates the index of the current {{domxref("XRView")}} in the {{domxref("XRViewerPose.views")}} array.


Suggested change

The read-only **`index`** property of the {{domxref("XRVisibilityMaskChangeEvent")}} interface indicates the index of the current {{domxref("XRView")}} in the {{domxref("XRViewerPose.views")}} array.

The **`index`** read-only property of the {{domxref("XRVisibilityMaskChangeEvent")}} interface indicates the index of the current {{domxref("XRView")}} in the {{domxref("XRViewerPose.views")}} array.

A sentence on how many views there might be in that array, and why the index matters might be useful.

It's always a balance how much to say in reference - ie. how much context you should need to provide. I don't feel like I have enough to do anything useful with this page.

hamishwillee · 2026-05-11T01:17:18Z

+
+{{APIRef("WebXR Device API")}}{{SecureContext_Header}}
+
+The read-only **`indices`** property of the {{domxref("XRVisibilityMaskChangeEvent")}} interface is an array of indices specifying the vertices in the {{domxref("XRVisibilityMaskChangeEvent.vertices", "vertices")}} array that should be drawn to display the currently visible part of the scene displayed in the `XRView`. If this array is empty, the whole region of the `XRView` will be drawn.


Suggested change

The read-only **`indices`** property of the {{domxref("XRVisibilityMaskChangeEvent")}} interface is an array of indices specifying the vertices in the {{domxref("XRVisibilityMaskChangeEvent.vertices", "vertices")}} array that should be drawn to display the currently visible part of the scene displayed in the `XRView`. If this array is empty, the whole region of the `XRView` will be drawn.

The **`indices`** read-only property of the {{domxref("XRVisibilityMaskChangeEvent")}} interface is an array of indices specifying the vertices in the {{domxref("XRVisibilityMaskChangeEvent.vertices", "vertices")}} array that should be drawn to display the currently visible part of the scene displayed in the `XRView`. If this array is empty, the whole region of the `XRView` will be drawn.

hamishwillee · 2026-05-11T01:26:45Z

+
+{{APIRef("WebXR Device API")}}{{SecureContext_Header}}
+
+The read-only **`indices`** property of the {{domxref("XRVisibilityMaskChangeEvent")}} interface is an array of indices specifying the vertices in the {{domxref("XRVisibilityMaskChangeEvent.vertices", "vertices")}} array that should be drawn to display the currently visible part of the scene displayed in the `XRView`. If this array is empty, the whole region of the `XRView` will be drawn.


This isn't enough information to understand how indices and vertices work.

A vertix is a co-ordinate. You can define a polygonal region using more than three vertices (some care is required in definitions because if you assume vertices are somehow ordered, it is possible to cross over your path and define odd geometries.

Anyway, from this I'd guess that the verticies defines an array of points. This might have many more points than in the mask, so you have a indicies array that specifies the numbers in the vertices array that define the actual mask. That might be completely wrong, but whatever the truth is it needs to be said somewhere.

Other things I'd like to know - is the masked area the inner polygon defined by your vertices or the external area? Does the set of vertices defined here change with the event - I presume so?

hamishwillee · 2026-05-11T01:28:49Z

+
+{{APIRef("WebXR Device API")}}{{SecureContext_Header}}
+
+The read-only **`session`** property of the {{domxref("XRVisibilityMaskChangeEvent")}} interface indicates the {{domxref("XRSession")}} to which the event belongs.


Suggested change

The read-only **`session`** property of the {{domxref("XRVisibilityMaskChangeEvent")}} interface indicates the {{domxref("XRSession")}} to which the event belongs.

The **`session`** read-only property of the {{domxref("XRVisibilityMaskChangeEvent")}} interface indicates the {{domxref("XRSession")}} to which the event belongs.

hamishwillee · 2026-05-11T01:29:57Z

+An {{domxref("XRSession")}} object indicating which WebXR session the event belongs to.
+
+## Examples
+


Level three heading is in template. This is kind of the "default" but if you can find something more meaningful that is good.

Suggested change

### Basic usage

hamishwillee · 2026-05-11T01:30:38Z

+{{APIRef("WebXR Device API")}}{{SecureContext_Header}}
+
+The read-only **`session`** property of the {{domxref("XRVisibilityMaskChangeEvent")}} interface indicates the {{domxref("XRSession")}} to which the event belongs.
+


What's a session? Is there a sentence we could add to explain the relevance?

hamishwillee · 2026-05-11T01:34:23Z

+The WebXR Device API's
+**`XRVisibilityMaskChangeEvent()`** constructor creates and returns a new
+{{domxref("XRVisibilityMaskChangeEvent")}} object.


The https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/API_constructor_subpage_template template isn't very clear yet, but a more "standard format" would be to

not have odd line breaks

Do something like

Suggested change

The WebXR Device API's

**`XRVisibilityMaskChangeEvent()`** constructor creates and returns a new

{{domxref("XRVisibilityMaskChangeEvent")}} object.

The **`XRVisibilityMaskChangeEvent()`** constructor creates and returns a new {{domxref("XRVisibilityMaskChangeEvent")}} object.

hamishwillee · 2026-05-11T01:46:02Z

+
+{{APIRef("WebXR Device API")}}{{SecureContext_Header}}
+
+The **`XRVisibilityMaskChangeEvent`** of the [WebXR Device API](/en-US/docs/Web/API/WebXR_Device_API) describes the portion of an {{domxref("XRView")}} visible to the user (that is, the portion not hidden by the mask) after the view has changed. This enables performance improvements by allowing the browser to draw only the visible part of the updated view.


This enables performance improvements by allowing the browser to draw only the visible part of the updated view.

Er, users get events - browsers generate them. So I can see that a browser can enable performance improvements, but it isn't clear what the user is supposed to do with this event and why it is relevant.

hamishwillee · 2026-05-11T01:48:26Z

+
+{{APIRef("WebXR Device API")}}{{SeeCompatTable}}{{SecureContext_Header}}
+
+The **`visibilitymaskchange`** event is sent to an {{domxref("XRSession")}} when the portion of an {{domxref("XRView")}} visible to the user changes — that is, the portion not hidden by the mask. This enables performance improvements by allowing the browser to draw only the visible part of the updated view. The required information to draw the update is contained in the {{domxref("XRVisibilityMaskChangeEvent")}} event object.


See https://github.com/mdn/content/pull/43975/changes#r3215941539 - it isn't clear to me how this works, since events are handled by user code, but it talks about browser behaviour.

The required information to draw the update is contained in the {{domxref("XRVisibilityMaskChangeEvent")}} event object.

As I understand it the event is-a XRVisibilityMaskChangeEvent - this is an odd way to say that. Am I missing something?

hamishwillee · 2026-05-11T01:51:55Z

+  - : The {{domxref("XRSession")}} to which the event refers.
+- {{domxref("XRVisibilityMaskChangeEvent.vertices", "vertices")}} {{ReadOnlyInline}}
+  - : An array of coordinates representing the vertices required to draw the entire scene displayed in the `XRView`. If this array is empty, the whole region of the `XRView` will be drawn.
+


And what also not in the template, but is always appreciated is a section "Events" that lists the actual events fired from this type.

I'm doing something similar in https://github.com/mdn/content/pull/44047/changes#diff-3b2cb04c1d5d238054f6807ab130a07a1f1bb8ca392b0a092c0073354f523f94

hamishwillee · 2026-05-11T01:53:20Z

+
+{{InheritanceDiagram("XRVisibilityMaskChangeEvent")}}
+
+## Event properties


I think I need to update the template. An event is just an interface. This should be instance properties.

Document visibilitymaskchange event

3e05507

chrisdavidmills requested a review from a team as a code owner April 30, 2026 13:54

chrisdavidmills requested review from hamishwillee and removed request for a team April 30, 2026 13:54

github-actions Bot added the Content:WebAPI Web API docs label Apr 30, 2026

chrisdavidmills changed the title ~~Document visibilitymaskchange event~~ Technical review: Document WebXR visibilitymaskchange event Apr 30, 2026

github-actions Bot added the size/m [PR only] 51-500 LoC changed label Apr 30, 2026

alcooper91 reviewed Apr 30, 2026

View reviewed changes

chrisdavidmills mentioned this pull request May 1, 2026

Any plans to add demos for the visibilitymaskchange event? immersive-web/webxr-samples#240

Open

Fixes for tech review comments

3507c1c

chrisdavidmills changed the title ~~Technical review: Document WebXR visibilitymaskchange event~~ Editorial review: Document WebXR visibilitymaskchange event May 1, 2026

hamishwillee reviewed May 11, 2026

View reviewed changes


		{{APIRef("WebXR Device API")}}{{SecureContext_Header}}

		The read-only `vertices` property of the {{domxref("XRVisibilityMaskChangeEvent")}} interface is an array of coordinates representing the vertices required to draw the entire scene displayed in the {{domxref("XRView")}}. If this array is empty, the whole region of the `XRView` will be drawn.


		{{APIRef("WebXR Device API")}}{{SecureContext_Header}}

		The read-only `index` property of the {{domxref("XRView")}} interface indicates the index of the current `XRView` in the {{domxref("XRViewerPose.views")}} array.

	The read-only `index` property of the {{domxref("XRView")}} interface indicates the index of the current `XRView` in the {{domxref("XRViewerPose.views")}} array.
	The `index` read-only property of the {{domxref("XRView")}} interface indicates the index of the current `XRView` in the {{domxref("XRViewerPose.views")}} array.


		{{APIRef("WebXR Device API")}}{{SecureContext_Header}}

		The read-only `eye` property of the {{domxref("XRVisibilityMaskChangeEvent")}} interface indicates the eye the mask applies to.

	The read-only `eye` property of the {{domxref("XRVisibilityMaskChangeEvent")}} interface indicates the eye the mask applies to.
	The `eye` read-only property of the {{domxref("XRVisibilityMaskChangeEvent")}} interface indicates the eye the mask applies to.

-An emumerated value indicating which eye the mask applies to, which can be one of:
-- `left`
-  - : The {{domxref("XRView")}} represents the point-of-view of the viewer's left eye.
-- `right`
-  - : The view represents the viewer's right eye.
-- `none`
-  - : The `XRView` describes a monoscopic view, or the view otherwise doesn't represent a particular eye's point-of-view.
+An emumerated value indicating which eye the mask applies to from the viewer's perspective.
+This can be one of:
+- `left`
+  - : The viewer's left eye.
+- `right`
+  - : The viewer's right eye.
+- `none`
+  - : A monoscopic view, or the view otherwise doesn't represent a particular eye's point-of-view.

		- : The `XRView` describes a monoscopic view, or the view otherwise doesn't represent a particular eye's point-of-view.

		## Examples


		{{APIRef("WebXR Device API")}}{{SecureContext_Header}}

		The read-only `indices` property of the {{domxref("XRVisibilityMaskChangeEvent")}} interface is an array of indices specifying the vertices in the {{domxref("XRVisibilityMaskChangeEvent.vertices", "vertices")}} array that should be drawn to display the currently visible part of the scene displayed in the `XRView`. If this array is empty, the whole region of the `XRView` will be drawn.

	The read-only `indices` property of the {{domxref("XRVisibilityMaskChangeEvent")}} interface is an array of indices specifying the vertices in the {{domxref("XRVisibilityMaskChangeEvent.vertices", "vertices")}} array that should be drawn to display the currently visible part of the scene displayed in the `XRView`. If this array is empty, the whole region of the `XRView` will be drawn.
	The `indices` read-only property of the {{domxref("XRVisibilityMaskChangeEvent")}} interface is an array of indices specifying the vertices in the {{domxref("XRVisibilityMaskChangeEvent.vertices", "vertices")}} array that should be drawn to display the currently visible part of the scene displayed in the `XRView`. If this array is empty, the whole region of the `XRView` will be drawn.


		{{APIRef("WebXR Device API")}}{{SecureContext_Header}}

		The read-only `session` property of the {{domxref("XRVisibilityMaskChangeEvent")}} interface indicates the {{domxref("XRSession")}} to which the event belongs.

	The read-only `session` property of the {{domxref("XRVisibilityMaskChangeEvent")}} interface indicates the {{domxref("XRSession")}} to which the event belongs.
	The `session` read-only property of the {{domxref("XRVisibilityMaskChangeEvent")}} interface indicates the {{domxref("XRSession")}} to which the event belongs.

		An {{domxref("XRSession")}} object indicating which WebXR session the event belongs to.

		## Examples


		{{APIRef("WebXR Device API")}}{{SecureContext_Header}}

		The `XRVisibilityMaskChangeEvent` of the [WebXR Device API](/en-US/docs/Web/API/WebXR_Device_API) describes the portion of an {{domxref("XRView")}} visible to the user (that is, the portion not hidden by the mask) after the view has changed. This enables performance improvements by allowing the browser to draw only the visible part of the updated view.


		{{APIRef("WebXR Device API")}}{{SeeCompatTable}}{{SecureContext_Header}}

		The `visibilitymaskchange` event is sent to an {{domxref("XRSession")}} when the portion of an {{domxref("XRView")}} visible to the user changes — that is, the portion not hidden by the mask. This enables performance improvements by allowing the browser to draw only the visible part of the updated view. The required information to draw the update is contained in the {{domxref("XRVisibilityMaskChangeEvent")}} event object.


		{{InheritanceDiagram("XRVisibilityMaskChangeEvent")}}

		## Event properties

Conversation

chrisdavidmills commented Apr 30, 2026

Description

Motivation

Additional details

Related issues and pull requests

Uh oh!

github-actions Bot commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hamishwillee May 11, 2026 • 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!

alcooper91 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

github-actions Bot commented Apr 30, 2026 •

edited

Loading

hamishwillee May 11, 2026 •

edited

Loading