Skip to content

Commit e8ccddf

Browse files
yashrajbhartiJosh-Cena
yashrajbharti
and
Josh-Cena
authored
Add DOMMatrixReadOnly static method documentation (#41686)
* Add DOMMatrixReadOnly static method documentation - Add documentation for DOMMatrixReadOnly.fromFloat32Array() - Add documentation for DOMMatrixReadOnly.fromFloat64Array() - Add documentation for DOMMatrixReadOnly.fromMatrix() These static methods allow creating DOMMatrix objects from Float32Array, Float64Array, or existing matrix objects/objects with matrix properties. * Switch to non mutable wording * More fixes * Update files/en-us/web/api/dommatrixreadonly/dommatrixreadonly/index.md --------- Co-authored-by: Joshua Chen <sidachen2003@gmail.com>
1 parent 0e8ed36 commit e8ccddf

File tree

8 files changed

+328
-17
lines changed

8 files changed

+328
-17
lines changed

‎files/en-us/web/api/dommatrix/invertself/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ browser-compat: api.DOMMatrix.invertSelf
88

99
{{APIRef("Geometry Interfaces")}}{{AvailableInWorkers}}
1010

11-
The **`invertSelf()`** method of the {{domxref("DOMMatrix")}} interface inverts the original matrix. If the matrix cannot be inverted, the new matrix's components are all set to `NaN` and its {{domxref("DOMMatrixReadonly.is2D", "is2D")}} property is set to `false`.
11+
The **`invertSelf()`** method of the {{domxref("DOMMatrix")}} interface inverts the original matrix. If the matrix cannot be inverted, the new matrix's components are all set to `NaN` and its {{domxref("DOMMatrixReadOnly.is2D", "is2D")}} property is set to `false`.
1212

1313
To invert a matrix without mutating it, see {{domxref("DOMMatrixReadOnly.inverse()")}}
1414

‎files/en-us/web/api/dommatrix/rotateaxisangleself/index.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,9 +25,9 @@ rotateAxisAngleSelf(rotX, rotY, rotZ, angle)
2525
### Parameters
2626

2727
- `rotX`
28-
- : A number; the x-coordinate of the vector denoting the axis of rotation. If non-zero, {{domxref("DOMMatrixReadonly.is2D", "is2D")}} is false.
28+
- : A number; the x-coordinate of the vector denoting the axis of rotation. If non-zero, {{domxref("DOMMatrixReadOnly.is2D", "is2D")}} is false.
2929
- `rotY` {{optional_inline}}
30-
- : A number; the y-coordinate of the vector denoting the axis of rotation. If undefined, the `rotX` value is used. If non-zero, {{domxref("DOMMatrixReadonly.is2D", "is2D")}} is false.
30+
- : A number; the y-coordinate of the vector denoting the axis of rotation. If undefined, the `rotX` value is used. If non-zero, {{domxref("DOMMatrixReadOnly.is2D", "is2D")}} is false.
3131
- `rotZ` {{optional_inline}}
3232
- : A number; the z-coordinate of the vector denoting the axis of rotation. If undefined, the `rotX` value is used.
3333
- `angle` {{optional_inline}}

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

Lines changed: 47 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -8,26 +8,57 @@ browser-compat: api.DOMMatrixReadOnly.DOMMatrixReadOnly
88

99
{{APIRef("Geometry Interfaces")}}{{AvailableInWorkers}}
1010

11-
The **`DOMMatrixReadOnly`** constructor creates a new
12-
{{domxref("DOMMatrixReadOnly")}} object which represents 4x4 matrices, suitable for 2D
13-
and 3D operations.
11+
The **`DOMMatrixReadOnly()`** constructor creates a new {{domxref("DOMMatrixReadOnly")}} object which represents a 4x4 matrix, suitable for 2D and 3D operations.
1412

1513
## Syntax
1614

1715
```js-nolint
1816
DOMMatrixReadOnly()
19-
DOMMatrixReadOnly(init)
17+
DOMMatrixReadOnly(initString)
18+
DOMMatrixReadOnly(initArray)
2019
```
2120

2221
### Parameters
2322

24-
- `init` {{optional_inline}}
25-
- : Either a string containing a sequence of numbers or an array of numbers
26-
specifying the matrix you want to create.
23+
- `initString` {{optional_inline}}
24+
- : A string representing a 2D or 3D matrix in CSS {{cssxref("transform-function/matrix", "matrix()")}} or {{cssxref("transform-function/matrix3d", "matrix3d()")}} format.
25+
- `initArray` {{optional_inline}}
26+
- : An array containing either 6 or 16 numbers in column-major order. Other array lengths throw a {{jsxref("TypeError")}}.
27+
- A 6-element array is interpreted as the matrix components `[m11, m12, m21, m22, m41, m42]`, creating a 2D matrix.
28+
- A 16-element array is interpreted as the matrix components `[m11, m12, m13, m14, m21, m22, m23, m24, m31, m32, m33, m34, m41, m42, m43, m44]`, creating a 3D matrix.
2729

28-
In case an array of numbers is passed, the behavior depends on the length of the array:
29-
- for a 6-element array of components in the form `[a, b, c, d, e, f]`, a 2D read-only matrix is created, initialized with the provided components.
30-
- for a 16-element array of components (in the column-major order) in the form `[m11, m12, m13, …, m42, m43, m44]`, a 3D read-only matrix is created, initialized with the provided components.
30+
If this argument is omitted, an identity matrix is created, i.e., equivalent to `[1, 0, 0, 1, 0, 0]`.
31+
32+
If this argument is provided as a {{jsxref("Float32Array")}} or {{jsxref("Float64Array")}}, consider using the more performant static methods {{domxref("DOMMatrixReadOnly.fromFloat32Array_static", "DOMMatrixReadOnly.fromFloat32Array()")}} or {{domxref("DOMMatrixReadOnly.fromFloat64Array_static", "DOMMatrixReadOnly.fromFloat64Array()")}} instead.
33+
34+
### Return value
35+
36+
A new {{domxref("DOMMatrixReadOnly")}} object.
37+
38+
### Exceptions
39+
40+
- {{jsxref("TypeError")}}
41+
- : Thrown if the argument is not a string or an array with a length other than 6 or 16.
42+
- {{jsxref("SyntaxError")}}
43+
- : Thrown if the string argument is not in a valid CSS {{cssxref("transform-function/matrix", "matrix()")}} or {{cssxref("transform-function/matrix3d", "matrix3d()")}} format.
44+
45+
## Examples
46+
47+
### Creating a DOMMatrixReadOnly from a string
48+
49+
```js
50+
const matrixFromString = new DOMMatrixReadOnly("matrix(1, 0, 0, 1, 10, 20)");
51+
console.log(matrixFromString.toJSON());
52+
// Output: {a: 1, b: 0, c: 0, d: 1, e: 10, f: 20}
53+
```
54+
55+
### Creating a DOMMatrixReadOnly from an array
56+
57+
```js
58+
const matrixFromArray = new DOMMatrixReadOnly([1, 0, 0, 1, 10, 20]);
59+
console.log(matrixFromArray.toJSON());
60+
// Output: {a: 1, b: 0, c: 0, d: 1, e: 10, f: 20}
61+
```
3162

3263
## Specifications
3364

@@ -36,3 +67,9 @@ DOMMatrixReadOnly(init)
3667
## Browser compatibility
3768

3869
{{Compat}}
70+
71+
## See also
72+
73+
- {{domxref("DOMMatrixReadOnly.fromFloat32Array_static", "DOMMatrixReadOnly.fromFloat32Array()")}}
74+
- {{domxref("DOMMatrixReadOnly.fromFloat64Array_static", "DOMMatrixReadOnly.fromFloat64Array()")}}
75+
- {{domxref("DOMMatrixReadOnly.fromMatrix_static", "DOMMatrixReadOnly.fromMatrix()")}}

‎files/en-us/web/api/dommatrixreadonly/fromfloat32array_static/index.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
title: "DOMMatrixReadOnly: fromFloat32Array() static method"
3+
short-title: fromFloat32Array()
4+
slug: Web/API/DOMMatrixReadOnly/fromFloat32Array_static
5+
page-type: web-api-static-method
6+
browser-compat: api.DOMMatrixReadOnly.fromFloat32Array_static
7+
---
8+
9+
{{APIRef("Geometry Interfaces")}}{{AvailableInWorkers}}
10+
11+
The **`fromFloat32Array()`** static method of the {{domxref("DOMMatrixReadOnly")}} interface creates a new {{domxref("DOMMatrixReadOnly")}} object given an array of single-precision (32-bit) floating-point values.
12+
13+
If the array has 6 values, the result is a 2D matrix; if the array has 16 values, the result is a 3D matrix. Otherwise, a {{jsxref("TypeError")}} exception is thrown.
14+
15+
## Syntax
16+
17+
```js-nolint
18+
DOMMatrixReadOnly.fromFloat32Array(array)
19+
```
20+
21+
### Parameters
22+
23+
- `array`
24+
- : A {{jsxref("Float32Array")}} with 6 or 16 elements in column-major order.
25+
26+
### Return value
27+
28+
A {{domxref("DOMMatrixReadOnly")}} object.
29+
30+
### Exceptions
31+
32+
- {{jsxref("TypeError")}}
33+
- : Thrown if the length of the `array` parameter is not 6 or 16.
34+
35+
## Examples
36+
37+
### Creating a 2D matrix from a Float32Array
38+
39+
This example creates a 2D matrix from a 6-element `Float32Array`.
40+
41+
```js
42+
const float32Array = new Float32Array([1, 0, 0, 1, 10, 20]);
43+
const matrix2D = DOMMatrixReadOnly.fromFloat32Array(float32Array);
44+
45+
console.log(matrix2D.toString());
46+
// Output: matrix(1, 0, 0, 1, 10, 20)
47+
48+
console.log(matrix2D.is2D);
49+
// Output: true
50+
```
51+
52+
### Creating a 3D matrix from a Float32Array
53+
54+
This example creates a 3D matrix from a 16-element `Float32Array`.
55+
56+
```js
57+
const float32Array = new Float32Array([
58+
1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 10, 20, 30, 1,
59+
]);
60+
const matrix3D = DOMMatrixReadOnly.fromFloat32Array(float32Array);
61+
62+
console.log(matrix3D.is2D);
63+
// Output: false
64+
65+
console.log(matrix3D.m41, matrix3D.m42, matrix3D.m43);
66+
// Output: 10 20 30
67+
```
68+
69+
## Specifications
70+
71+
{{Specifications}}
72+
73+
## Browser compatibility
74+
75+
{{Compat}}
76+
77+
## See also
78+
79+
- {{domxref("DOMMatrixReadOnly/DOMMatrixReadOnly", "DOMMatrixReadOnly()")}}
80+
- {{domxref("DOMMatrixReadOnly.toFloat32Array()")}}
81+
- {{domxref("DOMMatrixReadOnly.toFloat64Array()")}}
82+
- {{domxref("DOMMatrixReadOnly.fromFloat64Array_static", "DOMMatrixReadOnly.fromFloat64Array()")}}
83+
- {{domxref("DOMMatrixReadOnly.fromMatrix_static", "DOMMatrixReadOnly.fromMatrix()")}}

‎files/en-us/web/api/dommatrixreadonly/fromfloat64array_static/index.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
---
2+
title: "DOMMatrixReadOnly: fromFloat64Array() static method"
3+
short-title: fromFloat64Array()
4+
slug: Web/API/DOMMatrixReadOnly/fromFloat64Array_static
5+
page-type: web-api-static-method
6+
browser-compat: api.DOMMatrixReadOnly.fromFloat64Array_static
7+
---
8+
9+
{{APIRef("Geometry Interfaces")}}{{AvailableInWorkers}}
10+
11+
The **`fromFloat64Array()`** static method of the {{domxref("DOMMatrixReadOnly")}} interface creates a new {{domxref("DOMMatrixReadOnly")}} object given an array of double-precision (64-bit) floating-point values.
12+
13+
If the array has 6 values, the result is a 2D matrix; if the array has 16 values, the result is a 3D matrix. Otherwise, a {{jsxref("TypeError")}} exception is thrown.
14+
15+
## Syntax
16+
17+
```js-nolint
18+
DOMMatrixReadOnly.fromFloat64Array(array)
19+
```
20+
21+
### Parameters
22+
23+
- `array`
24+
- : A {{jsxref("Float64Array")}} with 6 or 16 elements in column-major order.
25+
26+
### Return value
27+
28+
A {{domxref("DOMMatrixReadOnly")}} object.
29+
30+
### Exceptions
31+
32+
- {{jsxref("TypeError")}}
33+
- : Thrown if the length of the `array` parameter is not 6 or 16.
34+
35+
## Examples
36+
37+
### Creating a 2D matrix from a Float64Array
38+
39+
This example creates a 2D matrix from a 6-element `Float64Array`.
40+
41+
```js
42+
const float64Array = new Float64Array([1, 0, 0, 1, 10, 20]);
43+
const matrix2D = DOMMatrixReadOnly.fromFloat64Array(float64Array);
44+
45+
console.log(matrix2D.toString());
46+
// Output: matrix(1, 0, 0, 1, 10, 20)
47+
48+
console.log(matrix2D.is2D);
49+
// Output: true
50+
51+
console.log(matrix2D.e, matrix2D.f);
52+
// Output: 10 20
53+
```
54+
55+
### Creating a 3D matrix from a Float64Array
56+
57+
This example creates a 3D matrix from a 16-element `Float64Array`.
58+
59+
```js
60+
const float64Array = new Float64Array([
61+
1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 10, 20, 30, 1,
62+
]);
63+
const matrix3D = DOMMatrixReadOnly.fromFloat64Array(float64Array);
64+
65+
console.log(matrix3D.is2D);
66+
// Output: false
67+
68+
console.log(matrix3D.m41, matrix3D.m42, matrix3D.m43);
69+
// Output: 10 20 30
70+
```
71+
72+
## Specifications
73+
74+
{{Specifications}}
75+
76+
## Browser compatibility
77+
78+
{{Compat}}
79+
80+
## See also
81+
82+
- {{domxref("DOMMatrixReadOnly/DOMMatrixReadOnly", "DOMMatrixReadOnly()")}}
83+
- {{domxref("DOMMatrixReadOnly.toFloat32Array()")}}
84+
- {{domxref("DOMMatrixReadOnly.toFloat64Array()")}}
85+
- {{domxref("DOMMatrixReadOnly.fromFloat32Array_static", "DOMMatrixReadOnly.fromFloat32Array()")}}
86+
- {{domxref("DOMMatrixReadOnly.fromMatrix_static", "DOMMatrixReadOnly.fromMatrix()")}}

‎files/en-us/web/api/dommatrixreadonly/frommatrix_static/index.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
---
2+
title: "DOMMatrixReadOnly: fromMatrix() static method"
3+
short-title: fromMatrix()
4+
slug: Web/API/DOMMatrixReadOnly/fromMatrix_static
5+
page-type: web-api-static-method
6+
browser-compat: api.DOMMatrixReadOnly.fromMatrix_static
7+
---
8+
9+
{{APIRef("Geometry Interfaces")}}{{AvailableInWorkers}}
10+
11+
The **`fromMatrix()`** static method of the {{domxref("DOMMatrixReadOnly")}} interface creates a new {{domxref("DOMMatrixReadOnly")}} object given an existing matrix or an object which provides the values for its properties.
12+
13+
## Syntax
14+
15+
```js-nolint
16+
DOMMatrixReadOnly.fromMatrix()
17+
DOMMatrixReadOnly.fromMatrix(other)
18+
```
19+
20+
### Parameters
21+
22+
- `other` {{optional_inline}}
23+
- : A {{domxref("DOMMatrix")}}, {{domxref("DOMMatrixReadOnly")}}, or an object with the same properties. All properties default to `0`. The properties are:
24+
- `is2D`
25+
- : A boolean. `true` if the matrix should be created as a 2D matrix. Defaults to `false` if at least one of `m13`, `m14`, `m23`, `m24`, `m31`, `m32`, `m34`, or `m43` is non-zero, or at least one of `m33` or `m44` is not 1; otherwise, defaults to `true`.
26+
- `m11`, `m12`, `m13`, `m14`, `m21`, `m22`, `m23`, `m24`, `m31`, `m32`, `m33`, `m34`, `m41`, `m42`, `m43`, `m44`
27+
- : Numbers representing each component of a 4×4 matrix, where `m11` through `m14` are the first column, `m21` through `m24` are the second column, and so forth. `m11`, `m22`, `m33`, and `m44` default to `1`, and all other components default to `0`.
28+
29+
If `is2D` is explicitly set to `true`, `m13`, `m14`, `m23`, `m24`, `m31`, `m32`, `m34`, or `m43` must either be omitted or set to `0`, and `m33` and `m44` must either be omitted or set to `1`.
30+
31+
- `a`, `b`, `c`, `d`, `e`, `f`
32+
- : Aliases for `m11`, `m12`, `m21`, `m22`, `m41`, and `m42`, respectively, for convenience when initializing 2D matrices. If these aliases are provided with the `m` counterparts, their values must be equal.
33+
34+
### Return value
35+
36+
A {{domxref("DOMMatrixReadOnly")}} object.
37+
38+
### Exceptions
39+
40+
- {{jsxref("TypeError")}}
41+
- : Thrown if the provided object's properties are inconsistent (for example, if both `a` and `m11` are provided but have different values).
42+
43+
## Examples
44+
45+
### Creating a matrix from an object
46+
47+
This example creates a `DOMMatrixReadOnly` by providing matrix values in an object.
48+
49+
```js
50+
const matrix = DOMMatrixReadOnly.fromMatrix({
51+
a: 1,
52+
b: 0,
53+
c: 0,
54+
d: 1,
55+
e: 50,
56+
f: 50,
57+
is2D: true,
58+
});
59+
60+
console.log(matrix.toString());
61+
// Output: matrix(1, 0, 0, 1, 50, 50)
62+
63+
console.log(matrix.is2D);
64+
// Output: true
65+
```
66+
67+
### Creating a matrix from an existing matrix
68+
69+
This example creates a new `DOMMatrixReadOnly` from an existing `DOMMatrixReadOnly`.
70+
71+
```js
72+
const matrix1 = new DOMMatrixReadOnly([1, 0, 0, 1, 100, 100]);
73+
const matrix2 = DOMMatrixReadOnly.fromMatrix(matrix1);
74+
75+
console.log(matrix2.toString());
76+
// Output: matrix(1, 0, 0, 1, 100, 100)
77+
```
78+
79+
### Creating a default identity matrix
80+
81+
This example shows how calling `fromMatrix()` with no arguments creates an identity matrix.
82+
83+
```js
84+
const identityMatrix = DOMMatrixReadOnly.fromMatrix();
85+
86+
console.log(identityMatrix.toString());
87+
// Output: matrix(1, 0, 0, 1, 0, 0)
88+
89+
console.log(identityMatrix.isIdentity);
90+
// Output: true
91+
```
92+
93+
## Specifications
94+
95+
{{Specifications}}
96+
97+
## Browser compatibility
98+
99+
{{Compat}}
100+
101+
## See also
102+
103+
- {{domxref("DOMMatrixReadOnly.DOMMatrixReadOnly", "DOMMatrixReadOnly()")}} constructor
104+
- {{domxref("DOMMatrixReadOnly.fromFloat32Array_static", "DOMMatrixReadOnly.fromFloat32Array()")}}
105+
- {{domxref("DOMMatrixReadOnly.fromFloat64Array_static", "DOMMatrixReadOnly.fromFloat64Array()")}}

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -82,11 +82,11 @@ _This interface doesn't inherit any methods. None of the following methods alter
8282
## Static methods
8383

8484
- {{domxref("DOMMatrixReadOnly.fromFloat32Array_static", "fromFloat32Array()")}}
85-
- : Creates a new mutable `DOMMatrix` object given an array of single-precision (32-bit) floating-point values. If the array has six values, the result is a 2D matrix; if the array has 16 values, the result is a 3D matrix. Otherwise, a {{jsxref("TypeError")}} exception is thrown.
85+
- : Creates a new `DOMMatrixReadOnly` object given a {{jsxref("Float32Array")}} of 6 or 16 single-precision (32-bit) floating-point values.
8686
- {{domxref("DOMMatrixReadOnly.fromFloat64Array_static", "fromFloat64Array()")}}
87-
- : Creates a new mutable `DOMMatrix` object given an array of double-precision (64-bit) floating-point values. If the array has six values, the result is a 2D matrix; if the array has 16 values, the result is a 3D matrix. Otherwise, a {{jsxref("TypeError")}} exception is thrown.
87+
- : Creates a new `DOMMatrixReadOnly` object given a {{jsxref("Float64Array")}} of 6 or 16 double-precision (64-bit) floating-point values.
8888
- {{domxref("DOMMatrixReadOnly.fromMatrix_static", "fromMatrix()")}}
89-
- : Creates a new mutable `DOMMatrix` object given an existing matrix or an object which provides the values for its properties. If no matrix is specified, the matrix is initialized with every element set to `0` _except_ the bottom-right corner and the element immediately above and to its left: `m33` and `m34`. These have the default value of `1`.
89+
- : Creates a new `DOMMatrixReadOnly` object given an existing matrix or an object which provides the values for its properties.
9090

9191
## Specifications
9292

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ browser-compat: api.DOMPointReadOnly.matrixTransform
1010

1111
The **`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.
1212

13-
If the matrix passed as a parameter is 2D (the {{domxref("DOMMatrixReadonly.is2D", "is2D")}} 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.
13+
If the matrix passed as a parameter is 2D (the {{domxref("DOMMatrixReadOnly.is2D", "is2D")}} 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.
1414

1515
You can also create a new `DOMPoint` with a point and matrix with the {{domxref("DOMMatrixReadOnly.transformPoint()")}} method.
1616

0 commit comments

Comments
 (0)