Skip to content

Commit 359abb1

Browse files
yashrajbhartiJosh-Cena
yashrajbharti
and
Josh-Cena
authored
Add DOMMatrix static method documentation (#41687)
* Add DOMMatrix static method documentation - Add documentation for DOMMatrix.fromFloat32Array() - Add documentation for DOMMatrix.fromFloat64Array() - Add documentation for DOMMatrix.fromMatrix() These static methods allow creating DOMMatrix objects from Float32Array, Float64Array, or existing matrix objects/objects with matrix properties. * fix semantics * Port over changes --------- Co-authored-by: Joshua Chen <sidachen2003@gmail.com>
1 parent e8ccddf commit 359abb1

File tree

6 files changed

+319
-19
lines changed

6 files changed

+319
-19
lines changed

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

Lines changed: 30 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -8,30 +8,43 @@ browser-compat: api.DOMMatrix.DOMMatrix
88

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

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

1513
## Syntax
1614

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

2221
### Parameters
2322

24-
- `init` {{optional_inline}}
25-
- : An array of numbers specifying the matrix you want to create, or a CSS transform string.
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.
2629

27-
In case an array of numbers is passed, the behavior depends on the length of the array:
28-
- for a 6-element array of components in the form `[a, b, c, d, e, f]`, a 2D matrix is created, initialized with the provided components.
29-
- for a 16-element array of components (in the column-major order) in the form `[m11, m12, m13, …, m42, m43, m44]`, a 3D 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("DOMMatrix.fromFloat32Array_static", "DOMMatrix.fromFloat32Array()")}} or {{domxref("DOMMatrix.fromFloat64Array_static", "DOMMatrix.fromFloat64Array()")}} instead.
33+
34+
### Return value
35+
36+
A new {{domxref("DOMMatrix")}} 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.
3044

3145
## Examples
3246

33-
This example creates a DOMMatrix to use as an argument for calling
34-
{{domxref("DOMPointReadOnly.matrixTransform()")}}.
47+
This example creates a DOMMatrix to use as an argument for calling {{domxref("DOMPointReadOnly.matrixTransform()")}}.
3548

3649
```js
3750
const point = new DOMPoint(5, 4);
@@ -58,3 +71,9 @@ const transformedPoint = point.matrixTransform(matrix);
5871
## Browser compatibility
5972

6073
{{Compat}}
74+
75+
## See also
76+
77+
- {{domxref("DOMMatrix.fromFloat32Array_static", "DOMMatrix.fromFloat32Array()")}}
78+
- {{domxref("DOMMatrix.fromFloat64Array_static", "DOMMatrix.fromFloat64Array()")}}
79+
- {{domxref("DOMMatrix.fromMatrix_static", "DOMMatrix.fromMatrix()")}}

‎files/en-us/web/api/dommatrix/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: "DOMMatrix: fromFloat32Array() static method"
3+
short-title: fromFloat32Array()
4+
slug: Web/API/DOMMatrix/fromFloat32Array_static
5+
page-type: web-api-static-method
6+
browser-compat: api.DOMMatrix.fromFloat32Array_static
7+
---
8+
9+
{{APIRef("Geometry Interfaces")}}{{AvailableInWorkers}}
10+
11+
The **`fromFloat32Array()`** static method of the {{domxref("DOMMatrix")}} interface creates a new {{domxref("DOMMatrix")}} 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+
DOMMatrix.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("DOMMatrix")}} 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 = DOMMatrix.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 = DOMMatrix.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("DOMMatrix/DOMMatrix", "DOMMatrix()")}}
80+
- {{domxref("DOMMatrix.toFloat32Array()")}}
81+
- {{domxref("DOMMatrix.toFloat64Array()")}}
82+
- {{domxref("DOMMatrix.fromFloat64Array_static", "DOMMatrix.fromFloat64Array()")}}
83+
- {{domxref("DOMMatrix.fromMatrix_static", "DOMMatrix.fromMatrix()")}}

‎files/en-us/web/api/dommatrix/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: "DOMMatrix: fromFloat64Array() static method"
3+
short-title: fromFloat64Array()
4+
slug: Web/API/DOMMatrix/fromFloat64Array_static
5+
page-type: web-api-static-method
6+
browser-compat: api.DOMMatrix.fromFloat64Array_static
7+
---
8+
9+
{{APIRef("Geometry Interfaces")}}{{AvailableInWorkers}}
10+
11+
The **`fromFloat64Array()`** static method of the {{domxref("DOMMatrix")}} interface creates a new {{domxref("DOMMatrix")}} 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+
DOMMatrix.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("DOMMatrix")}} 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 = DOMMatrix.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 = DOMMatrix.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("DOMMatrix/DOMMatrix", "DOMMatrix()")}}
83+
- {{domxref("DOMMatrix.toFloat32Array()")}}
84+
- {{domxref("DOMMatrix.toFloat64Array()")}}
85+
- {{domxref("DOMMatrix.fromFloat32Array_static", "DOMMatrix.fromFloat32Array()")}}
86+
- {{domxref("DOMMatrix.fromMatrix_static", "DOMMatrix.fromMatrix()")}}

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

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
---
2+
title: "DOMMatrix: fromMatrix() static method"
3+
short-title: fromMatrix()
4+
slug: Web/API/DOMMatrix/fromMatrix_static
5+
page-type: web-api-static-method
6+
browser-compat: api.DOMMatrix.fromMatrix_static
7+
---
8+
9+
{{APIRef("Geometry Interfaces")}}{{AvailableInWorkers}}
10+
11+
The **`fromMatrix()`** static method of the {{domxref("DOMMatrix")}} interface creates a new {{domxref("DOMMatrix")}} object given an existing matrix or an object which provides the values for its properties.
12+
13+
## Syntax
14+
15+
```js-nolint
16+
DOMMatrix.fromMatrix()
17+
DOMMatrix.fromMatrix(other)
18+
```
19+
20+
### Parameters
21+
22+
- `other` {{optional_inline}}
23+
- : A {{domxref("DOMMatrix")}}, {{domxref("DOMMatrix")}}, 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("DOMMatrix")}} 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 `DOMMatrix` by providing matrix values in an object.
48+
49+
```js
50+
const matrix = DOMMatrix.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 `DOMMatrix` from an existing `DOMMatrix`.
70+
71+
```js
72+
const matrix1 = new DOMMatrix([1, 0, 0, 1, 100, 100]);
73+
const matrix2 = DOMMatrix.fromMatrix(matrix1);
74+
75+
console.log(matrix2.toString());
76+
// Output: matrix(1, 0, 0, 1, 100, 100)
77+
78+
// Now we can mutate it
79+
matrix2.translateSelf(50, 25);
80+
81+
console.log(matrix2.toString());
82+
// Output: matrix(1, 0, 0, 1, 150, 125)
83+
84+
console.log(matrix1.toString());
85+
// Output: matrix(1, 0, 0, 1, 100, 100)
86+
```
87+
88+
### Creating a default identity matrix
89+
90+
This example shows how calling `fromMatrix()` with no arguments creates an identity matrix.
91+
92+
```js
93+
const identityMatrix = DOMMatrix.fromMatrix();
94+
95+
console.log(identityMatrix.toString());
96+
// Output: matrix(1, 0, 0, 1, 0, 0)
97+
98+
console.log(identityMatrix.isIdentity);
99+
// Output: true
100+
```
101+
102+
## Specifications
103+
104+
{{Specifications}}
105+
106+
## Browser compatibility
107+
108+
{{Compat}}
109+
110+
## See also
111+
112+
- {{domxref("DOMMatrix.DOMMatrix", "DOMMatrix()")}} constructor
113+
- {{domxref("DOMMatrix.fromFloat32Array_static", "DOMMatrix.fromFloat32Array()")}}
114+
- {{domxref("DOMMatrix.fromFloat64Array_static", "DOMMatrix.fromFloat64Array()")}}

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

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -68,14 +68,12 @@ _This interface includes the following methods, as well as the methods it inheri
6868

6969
## Static methods
7070

71-
_This interface inherits methods from {{domxref("DOMMatrixReadOnly")}}._
72-
7371
- {{domxref("DOMMatrix.fromFloat32Array_static", "fromFloat32Array()")}}
74-
- : 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.
72+
- : Creates a new `DOMMatrix` object given a {{jsxref("Float32Array")}} of 6 or 16 single-precision (32-bit) floating-point values.
7573
- {{domxref("DOMMatrix.fromFloat64Array_static", "fromFloat64Array()")}}
76-
- : 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.
74+
- : Creates a new `DOMMatrix` object given a {{jsxref("Float64Array")}} of 6 or 16 double-precision (64-bit) floating-point values.
7775
- {{domxref("DOMMatrix.fromMatrix_static", "fromMatrix()")}}
78-
- : Creates a new mutable `DOMMatrix` object given an existing matrix or an object which provides the values for its properties.
76+
- : Creates a new `DOMMatrix` object given an existing matrix or an object which provides the values for its properties.
7977

8078
## Usage notes
8179

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,9 @@ The **`DOMMatrixReadOnly()`** constructor creates a new {{domxref("DOMMatrixRead
1313
## Syntax
1414

1515
```js-nolint
16-
DOMMatrixReadOnly()
17-
DOMMatrixReadOnly(initString)
18-
DOMMatrixReadOnly(initArray)
16+
new DOMMatrixReadOnly()
17+
new DOMMatrixReadOnly(initString)
18+
new DOMMatrixReadOnly(initArray)
1919
```
2020

2121
### Parameters

0 commit comments

Comments
 (0)