Editorial review: Document WebXR visibilitymaskchange event #43975

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

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:53:20Z

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

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

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-11T00:11:57Z

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:10:37Z

As per the template, though it feels a bit pointless

Suggested change

### Basic usage

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

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

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

Suggested change

### Basic usage

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

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:16:41Z

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

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

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

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:30:38Z

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

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

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

-Original file line number
+Diff line change
@@ Expand Up / @@ -83,6 +83,8 @@ _The following events are delivered to `XRSession` objects._ @@
       - : An event of type {{domxref("XRInputSourceEvent")}} which is sent to the `XRSession` when the user initially squeezes a squeezable controller. This may be, for example, a trigger which is used to represent grabbing objects, or might represent actual squeezing when wearing a haptic glove. Also available through the `onsqueezestart` event handler property.
     - {{domxref("XRSession.visibilitychange_event", "visibilitychange")}} {{Experimental_Inline}}
       - : An {{domxref("XRSessionEvent")}} which is sent to the session when its visibility state as indicated by the {{domxref("XRSession.visibilityState", "visibilityState")}} changes. Also available through the `onvisibilitychange` event handler property.
+    - {{domxref("XRSession.visibilitymaskchange_event", "visibilitymaskchange")}} {{Experimental_Inline}}
+      - : An {{domxref("XRVisibilityMaskChangeEvent")}} which is sent to the session when the portion of the {{domxref("XRView")}} visible to the user changes, enabling performance improvements by allowing the browser to draw only the visible part of the updated view. Also available through the `onvisibilitymaskchange` event handler property.
     ## Example
@@ Expand Down @@

-Original file line number
+Diff line change
@@ -0,0 +1,94 @@
+    ---
+    title: "XRSession: visibilitymaskchange event"
+    short-title: visibilitymaskchange
+    slug: Web/API/XRSession/visibilitymaskchange_event
+    page-type: web-api-event
+    status:
+      - experimental
+    browser-compat: api.XRSession.visibilitymaskchange_event
+    ---
+    {{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.
+    ## Syntax
+    Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property.
+    ```js-nolint
+    addEventListener("visibilitymaskchange", (event) => { })
+    onvisibilitymaskchange = (event) => { }
+    ```
+    ## Event type
+    An {{domxref("XRVisibilityMaskChangeEvent")}}. Inherits from {{domxref("Event")}}.
+    {{InheritanceDiagram("XRVisibilityMaskChangeEvent")}}
+    ## Event properties
+    _In addition to the properties listed below, properties from the parent interface, {{domxref("Event")}}, are available._
+    - {{domxref("XRVisibilityMaskChangeEvent.eye", "eye")}} {{ReadOnlyInline}}
+      - : The eye the mask applies to.
+    - {{domxref("XRVisibilityMaskChangeEvent.index", "index")}} {{ReadOnlyInline}}
+      - : The index of the current {{domxref("XRView")}} in the {{domxref("XRViewerPose.views")}} array.
+    - {{domxref("XRVisibilityMaskChangeEvent.indices", "indices")}} {{ReadOnlyInline}}
+      - : An array of indices specifying the vertices in the `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.
+    - {{domxref("XRVisibilityMaskChangeEvent.session", "session")}} {{ReadOnlyInline}}
+      - : 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.
+    ## Examples
+    ### Three.js example
+    This snippet shows how `visibilitymaskchange` might be used to draw only the visible portion of the `XRView` in a Three.js application. The new view must be drawn using the {{domxref("XRView.projectionMatrix")}} of the relevant `XRView` and a default {{domxref("XRRigidTransform")}}.
+    ```js
+    session.addEventListener("visibilitymaskchange", onVisibilityMaskChange);
+    function onVisibilityMaskChange(event) {
+      const geometry = new BufferGeometry();
+      geometry.setIndex(new BufferAttribute(event.indices, 1));
+      const vertices = new Float32Array((event.vertices.length / 2) * 3);
+      let x = 0,
+        y = 0;
+      while (x < event.vertices.length) {
+        vertices[y++] = event.vertices[x++];
+        vertices[y++] = event.vertices[x++];
+        vertices[y++] = -1;
+      }
+      geometry.setAttribute("position", new BufferAttribute(vertices, 3));
+      const mask = event.eye === "left" ? leftEyeMask : rightEyeMask;
+      const matrix = cameras[event.eye === "left" ? 0 : 1].projectionMatrix;
+      mask.geometry = geometry;
+      mask.material = new ShaderMaterial({
+        vertexShader: _visibility_mask_vertex,
+        fragmentShader: _visibility_mask_fragment,
+        uniforms: {
+          clipMatrix: { value: matrix },
+        },
+      });
+      maskScene = new Scene();
+      maskScene.add(leftEyeMask);
+      maskScene.add(rightEyeMask);
+    }
+    ```
+    The code snippet is taken from [this fork of WebXRManager.js](https://github.com/cabanier/three.js/blob/78a3227d95fc29e001d8cd139504c643987430c5/src/renderers/webxr/WebXRManager.js).
+    ## Specifications
+    {{Specifications}}
+    ## Browser compatibility
+    {{Compat}}

-Original file line number
+Diff line change
@@ Expand Up @@
       - : Which of the two eyes (`left`) or (`right`) for which this `XRView` represents the perspective. This value is used to ensure that any content which is pre-rendered for presenting to a specific eye is distributed or positioned correctly. The value can also be `none` if the `XRView` is presenting monoscopic data (such as a 2D image, a fullscreen view of text, or a close-up view of something that doesn't need to appear in 3D).
     - {{domxref("XRView.isFirstPersonObserver", "isFirstPersonObserver")}} {{ReadOnlyInline}} {{Experimental_Inline}}
       - : Returns a boolean indicating if the `XRView` is a first-person observer view.
+    - {{domxref("XRView.index", "index")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+      - : Returns a number specifying the index of the current `XRView` in the {{domxref("XRViewerPose.views")}} array.
     - {{domxref("XRView.projectionMatrix", "projectionMatrix")}} {{ReadOnlyInline}} {{Experimental_Inline}}
       - : The projection matrix that will transform the scene to appear correctly given the point-of-view indicated by `eye`. This matrix should be used directly in order to avoid presentation distortions that may lead to potentially serious user discomfort.
     - {{domxref("XRView.recommendedViewportScale", "recommendedViewportScale")}} {{ReadOnlyInline}} {{Experimental_Inline}}
@@ Expand Down @@

-Original file line number
+Diff line change
@@ -0,0 +1,88 @@
+    ---
+    title: XRVisibilityMaskChangeEvent
+    slug: Web/API/XRVisibilityMaskChangeEvent
+    page-type: web-api-interface
+    browser-compat: api.XRVisibilityMaskChangeEvent
+    ---
+    {{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.
+    An `XRVisibilityMaskChangeEvent` object is made available as the event object of a {{domxref("XRSession.visibilitymaskchange_event", "visibilitymaskchange")}} event, fired when the portion of the view displayed to the user changes.
+    {{InheritanceDiagram}}
+    ## Constructor
+    - {{domxref("XRVisibilityMaskChangeEvent.XRVisibilityMaskChangeEvent", "XRVisibilityMaskChangeEvent()")}}
+      - : Creates and returns a new `XRVisibilityMaskChangeEvent` object.
+    ## Instance properties
+    _In addition to properties inherited from its parent interface, {{domxref("Event")}}, `XRVisibilityMaskChangeEvent` provides the following:_
+    - {{domxref("XRVisibilityMaskChangeEvent.eye", "eye")}} {{ReadOnlyInline}}
+      - : The eye the mask applies to.
+    - {{domxref("XRVisibilityMaskChangeEvent.index", "index")}} {{ReadOnlyInline}}
+      - : The index of the current {{domxref("XRView")}} in the {{domxref("XRViewerPose.views")}} array.
+    - {{domxref("XRVisibilityMaskChangeEvent.indices", "indices")}} {{ReadOnlyInline}}
+      - : An array of indices specifying the vertices in the [`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.
+    - {{domxref("XRVisibilityMaskChangeEvent.session", "session")}} {{ReadOnlyInline}}
+      - : The {{domxref("XRSession")}} to which the event belongs.
+    - {{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.
+    ## Instance methods
+    _While `XRSessionEvent` defines no methods, it inherits methods from its parent interface, {{domxref("Event")}}._
+    ## Examples
+    ### Three.js example
+    This snippet shows how `visibilitymaskchange` might be used to draw only the visible portion of the `XRView` in a Three.js application. The new view must be drawn using the {{domxref("XRView.projectionMatrix")}} of the relevant `XRView` and a default {{domxref("XRRigidTransform")}}.
+    ```js
+    session.addEventListener("visibilitymaskchange", onVisibilityMaskChange);
+    function onVisibilityMaskChange(event) {
+      const geometry = new BufferGeometry();
+      geometry.setIndex(new BufferAttribute(event.indices, 1));
+      const vertices = new Float32Array((event.vertices.length / 2) * 3);
+      let x = 0,
+        y = 0;
+      while (x < event.vertices.length) {
+        vertices[y++] = event.vertices[x++];
+        vertices[y++] = event.vertices[x++];
+        vertices[y++] = -1;
+      }
+      geometry.setAttribute("position", new BufferAttribute(vertices, 3));
+      const mask = event.eye === "left" ? leftEyeMask : rightEyeMask;
+      const matrix = cameras[event.eye === "left" ? 0 : 1].projectionMatrix;
+      mask.geometry = geometry;
+      mask.material = new ShaderMaterial({
+        vertexShader: _visibility_mask_vertex,
+        fragmentShader: _visibility_mask_fragment,
+        uniforms: {
+          clipMatrix: { value: matrix },
+        },
+      });
+      maskScene = new Scene();
+      maskScene.add(leftEyeMask);
+      maskScene.add(rightEyeMask);
+    }
+    ```
+    The code snippet is taken from [this fork of WebXRManager.js](https://github.com/cabanier/three.js/blob/78a3227d95fc29e001d8cd139504c643987430c5/src/renderers/webxr/WebXRManager.js).
+    ## Specifications
+    {{Specifications}}
+    ## Browser compatibility
+    {{Compat}}

Editorial review: Document WebXR visibilitymaskchange event #43975

Are you sure you want to change the base?

Uh oh!

Editorial review: Document WebXR visibilitymaskchange event #43975

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing

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!

Uh oh!

Uh oh!