New page: DOMPointReadOnly.matrixTransform() (#37234)

* New page: DOMPointReadOnly.matrixTransform()

* New page: DOMPointReadOnly.matrixTransform()

* New page: DOMMatrixReadOnly.transformPoint()

* typo

* title

* Update files/en-us/web/api/dompointreadonly/matrixtransform/index.md

Co-authored-by: sideshowbarker <[email protected]>

---------

Co-authored-by: sideshowbarker <[email protected]>

files/en-us/web/api/dommatrixreadonly/transformpoint/index.md

@@ -0,0 +1,76 @@
+---
+title: "DOMMatrixReadOnly: transformPoint method"
+short-title: transformPoint
+slug: Web/API/DOMMatrixReadOnly/transformPoint
+page-type: web-api-instance-method
+browser-compat: api.DOMMatrixReadOnly.transformPoint
+---
+
+{{APIRef("Geometry Interfaces")}}{{AvailableInWorkers}}
+
+The **`transformPoint`** method of the
+{{domxref("DOMMatrixReadOnly")}} interface creates a new {{domxref("DOMPoint")}} object, transforming a specified point by the matrix. Neither the matrix nor the original point are altered.
+
+You can also create a new `DOMPoint` by applying a matrix to a point with the {{domxref("DOMPointReadOnly.matrixTransform()")}} method.
+
+## Syntax
+
+```js
+DOMMatrixReadOnly.transformPoint();
+DOMMatrixReadOnly.transformPoint(point);
+```
+
+### Parameters
+
+- `point`
+
+  - : A {{domxref("DOMPoint")}} or {{domxref("DOMPointReadOnly")}} instance, or an object containing up to four of the following properties:
+
+    - `x`
+      - : The `x`-coordinate of the point in space as a number. The default value is `0`.
+    - `y`
+      - : The `y`-coordinate of the point in space as a number. The default value is `0`.
+    - `z`
+      - : The `z`-coordinate, or depth coordinate, of the point in space as a number. The default value is `0`.; positive values are closer to the user and negative values retreat back into the screen.
+    - `w`
+      - : The `w` perspective value of the point, as a number. The default is `1`.
+
+### Return value
+
+A {{domxref("DOMPoint")}}.
+
+## Examples
+
+### 2D transform
+
+```js
+const matrix = new DOMMatrixReadOnly();
+const point = new DOMPointReadOnly(10, 20); // DOMPointReadOnly {x: 10, y: 20, z: 0, w: 1}
+let newPoint = matrix.transformPoint(point); // DOMPoint {x: 10, y: 20, z: 0, w: 1}
+```
+
+### 3D transform
+
+In this example, we apply a 3D point to a 3D matrix:
+
+```js
+// Matrix with translate(22, 37, 10) applied
+const matrix3D = new DOMMatrixReadOnly([
+  1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 22, 37, 10, 1,
+]);
+const point3D = new DOMPointReadOnly(5, 10, 3); // DOMPointReadOnly {x: 5, y: 10, z: 3, w: 1}
+const transformedPoint3D = point3D.matrixTransform(matrix3D); // DOMPoint {x: 27, y: 47, z: 13, w: 1}
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("DOMPointReadOnly.matrixTransform()")}}
+- CSS {{cssxref("transform-function/matrix", "matrix()")}} and {{cssxref("transform-function/matrix3d", "matrix3d()")}} functions

files/en-us/web/api/dompointreadonly/matrixtransform/index.md

@@ -0,0 +1,72 @@
+---
+title: "DOMPointReadOnly: matrixTransform()"
+short-title: matrixTransform()
+slug: Web/API/DOMPointReadOnly/matrixTransform
+page-type: web-api-static-method
+browser-compat: api.DOMPointReadOnly.matrixTransform
+---
+
+{{APIRef("Geometry Interfaces")}}{{AvailableInWorkers}}
+
+The static **`matrixTransform()`** method of the {{domxref("DOMPointReadOnly")}} interface applies a matrix transform specified as an object to the DOMPointReadOnly object, creating and returning a new `DOMPointReadOnly` object. Neither the matrix nor the point are altered.
+
+If the matrix passed as a parameter is 2D (the {{domxref("DOMMatrix.is_2d")}}is `true`) then this is a 2D transformation and the point's `z` coordinate will be `0` and point's `w` perspective will be `1`. Otherwise this is a 3D transformation.
+
+You can also create a new `DOMPoint` with a point and matrix with the {{domxref("DOMMatrixReadOnly.transformPoint()")}} method.
+
+## Syntax
+
+```js-nolint
+DOMPointReadOnly.matrixTransform( )
+DOMPointReadOnly.matrixTransform( matrix )
+```
+
+### Parameters
+
+- `matrix`
+
+  - : A {{domxref("DOMMatrix")}} or {{domxref("DOMMatrixReadOnly")}} object.
+
+### Return value
+
+A new {{domxref("DOMPoint")}} object.
+
+## Examples
+
+### 2D transform
+
+In this example, we apply a 2D matrix transform to a `DOMPointReadOnly`, creating a new `DOMPoint`:
+
+```js
+const originalPoint = new DOMPointReadOnly(10, 20); // DOMPointReadOnly {x: 10, y: 20, z: 0, w: 1}
+const matrix = new DOMMatrix([1, 0, 0, 1, 15, 30]);
+
+const transformedPoint = originalPoint.matrixTransform(matrix); // DOMPoint {x: 25, y: 50, z: 0, w: 1}
+
+console.log(transformedPoint.toJSON()); // output: {x: 25, y: 50, z: 0, w: 1}
+```
+
+### 3D transform
+
+In this example, we apply a 3D matrix transform to a `DOMPointReadOnly`:
+
+```js
+const point = new DOMPointReadOnly(5, 10); // DOMPointReadOnly {x: 5, y: 10, z: 0, w: 1}
+const matrix3D = new DOMMatrix().translate(0, 0, 10);
+const transformedPoint = point.matrixTransform(matrix3D); // DOMPoint {x: 5, y: 10, z: 10, w: 1}
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("DOMPoint")}}
+- {{domxref("DOMMatrix")}}
+- {{domxref("DOMMatrixReadOnly.transformPoint()")}}
+- CSS {{cssxref("transform-function/matrix", "matrix()")}} and {{cssxref("transform-function/matrix3d", "matrix3d()")}} functions