• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Matrix2D
2
3**Matrix2D** allows you to perform matrix transformation, such as scaling, rotating, and translating.
4
5>  **NOTE**
6>
7> The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
8
9## APIs
10
11Matrix2D()
12
13Since API version 9, this API is supported in ArkTS widgets.
14
15## Attributes
16
17| Name                     | Type  | Description                                                        |
18| ------------------------- | ------ | ------------------------------------------------------------ |
19| [scaleX](#scalex)         | number | Horizontal scale factor. Since API version 9, this API is supported in ArkTS widgets.|
20| [scaleY](#scaley)         | number | Vertical scale factor. Since API version 9, this API is supported in ArkTS widgets.|
21| [rotateX](#rotatex)       | number | Horizontal tilt coefficient. Since API version 9, this API is supported in ArkTS widgets.|
22| [rotateY](#rotatey)       | number | Vertical tilt coefficient. Since API version 9, this API is supported in ArkTS widgets.|
23| [translateX](#translatex) | number | Horizontal translation distance, in vp. Since API version 9, this API is supported in ArkTS widgets.|
24| [translateY](#translatey) | number | Vertical translation distance, in vp. Since API version 9, this API is supported in ArkTS widgets.|
25
26>  **NOTE**
27>
28>  You can use the [px2vp](ts-pixel-units.md#pixel-unit-conversion) API to convert the unit.
29
30### scaleX
31
32```ts
33// xxx.ets
34@Entry
35@Component
36struct Matrix2DScaleX {
37  @State message: string = 'Matrix2D ScaleX'
38
39  printMatrix(title: string, matrix: Matrix2D) {
40    console.log(title)
41    console.log("Matrix [scaleX = " + matrix.scaleX + ", scaleY = " + matrix.scaleY +
42                ", rotateX = " + matrix.rotateX + ", rotateY = " + matrix.rotateY +
43                ", translateX = " + matrix.translateX + ", translateY = " + matrix.translateY + "]")
44  }
45  build() {
46    Row() {
47      Column() {
48        Text(this.message)
49          .fontSize(20)
50          .fontWeight(FontWeight.Bold)
51        Button("Set scaleX")
52          .onClick(() => {
53            let matrix : Matrix2D = new Matrix2D()
54            matrix.scaleX = 1
55            this.printMatrix(this.message, matrix)
56          })
57      }
58      .width('100%')
59    }
60    .height('100%')
61  }
62}
63```
64
65### scaleY
66
67```ts
68// xxx.ets
69@Entry
70@Component
71struct Matrix2DScaleY {
72  @State message: string = 'Matrix2D ScaleY'
73
74  printMatrix(title: string, matrix: Matrix2D) {
75    console.log(title)
76    console.log("Matrix [scaleX = " + matrix.scaleX + ", scaleY = " + matrix.scaleY +
77                ", rotateX = " + matrix.rotateX + ", rotateY = " + matrix.rotateY +
78                ", translateX = " + matrix.translateX + ", translateY = " + matrix.translateY + "]")
79  }
80  build() {
81    Row() {
82      Column() {
83        Text(this.message)
84          .fontSize(20)
85          .fontWeight(FontWeight.Bold)
86        Button("Set scaleY")
87          .onClick(() => {
88            let matrix : Matrix2D = new Matrix2D()
89            matrix.scaleY = 1
90            this.printMatrix(this.message, matrix)
91          })
92      }
93      .width('100%')
94    }
95    .height('100%')
96  }
97}
98```
99
100### rotateX
101
102```ts
103// xxx.ets
104@Entry
105@Component
106struct Matrix2DRotateX {
107  @State message: string = 'Matrix2D RotateX'
108
109  printMatrix(title: string, matrix: Matrix2D) {
110    console.log(title)
111    console.log("Matrix [scaleX = " + matrix.scaleX + ", scaleY = " + matrix.scaleY +
112                ", rotateX = " + matrix.rotateX + ", rotateY = " + matrix.rotateY +
113                ", translateX = " + matrix.translateX + ", translateY = " + matrix.translateY + "]")
114  }
115  build() {
116    Row() {
117      Column() {
118        Text(this.message)
119          .fontSize(20)
120          .fontWeight(FontWeight.Bold)
121        Button("Set rotateX")
122          .onClick(() => {
123            let matrix : Matrix2D = new Matrix2D()
124            matrix.rotateX = Math.sin(45 / Math.PI)
125            this.printMatrix(this.message, matrix)
126          })
127      }
128      .width('100%')
129    }
130    .height('100%')
131  }
132}
133```
134
135### rotateY
136
137```ts
138// xxx.ets
139@Entry
140@Component
141struct Matrix2DRotateY {
142  @State message: string = 'Matrix2D RotateY'
143
144  printMatrix(title: string, matrix: Matrix2D) {
145    console.log(title)
146    console.log("Matrix [scaleX = " + matrix.scaleX + ", scaleY = " + matrix.scaleY +
147                ", rotateX = " + matrix.rotateX + ", rotateY = " + matrix.rotateY +
148                ", translateX = " + matrix.translateX + ", translateY = " + matrix.translateY + "]")
149  }
150  build() {
151    Row() {
152      Column() {
153        Text(this.message)
154          .fontSize(20)
155          .fontWeight(FontWeight.Bold)
156        Button("Set rotateY")
157          .onClick(() => {
158            let matrix : Matrix2D = new Matrix2D()
159            matrix.rotateY = Math.cos(45 / Math.PI)
160            this.printMatrix(this.message, matrix)
161          })
162      }
163      .width('100%')
164    }
165    .height('100%')
166  }
167}
168```
169
170### translateX
171
172```ts
173// xxx.ets
174@Entry
175@Component
176struct Matrix2DTranslateX {
177  @State message: string = 'Matrix2D TranslateX'
178
179  printMatrix(title: string, matrix: Matrix2D) {
180    console.log(title)
181    console.log("Matrix [scaleX = " + matrix.scaleX + ", scaleY = " + matrix.scaleY +
182                ", rotateX = " + matrix.rotateX + ", rotateY = " + matrix.rotateY +
183                ", translateX = " + matrix.translateX + ", translateY = " + matrix.translateY + "]")
184  }
185  build() {
186    Row() {
187      Column() {
188        Text(this.message)
189          .fontSize(20)
190          .fontWeight(FontWeight.Bold)
191        Button("Set translateX")
192          .onClick(() => {
193            let matrix : Matrix2D = new Matrix2D()
194            matrix.translateX = 10
195            this.printMatrix(this.message, matrix)
196          })
197      }
198      .width('100%')
199    }
200    .height('100%')
201  }
202}
203```
204
205### translateY
206
207```ts
208// xxx.ets
209@Entry
210@Component
211struct Matrix2DTranslateY {
212  @State message: string = 'Matrix2D TranslateY'
213
214  printMatrix(title: string, matrix: Matrix2D) {
215    console.log(title)
216    console.log("Matrix [scaleX = " + matrix.scaleX + ", scaleY = " + matrix.scaleY +
217                ", rotateX = " + matrix.rotateX + ", rotateY = " + matrix.rotateY +
218                ", translateX = " + matrix.translateX + ", translateY = " + matrix.translateY + "]")
219  }
220  build() {
221    Row() {
222      Column() {
223        Text(this.message)
224          .fontSize(20)
225          .fontWeight(FontWeight.Bold)
226        Button("Set translateY")
227          .onClick(() => {
228            let matrix : Matrix2D = new Matrix2D()
229            matrix.translateY = 10
230            this.printMatrix(this.message, matrix)
231          })
232      }
233      .width('100%')
234    }
235    .height('100%')
236  }
237}
238```
239
240## Methods
241
242### identity
243
244identity(): Matrix2D
245
246Creates an identity matrix.
247
248Since API version 9, this API is supported in ArkTS widgets.
249
250**Return value**
251
252| Type                 | Description      |
253| --------------------- | ---------- |
254| [Matrix2D](#matrix2d) | Identity matrix.|
255
256**Example**
257
258```ts
259// xxx.ets
260@Entry
261@Component
262struct Matrix2DIdentity {
263  @State message: string = 'Matrix2D Identity'
264
265  printMatrix(title: string, matrix: Matrix2D) {
266    console.log(title)
267    console.log("Matrix [scaleX = " + matrix.scaleX + ", scaleY = " + matrix.scaleY +
268                ", rotateX = " + matrix.rotateX + ", rotateY = " + matrix.rotateY +
269                ", translateX = " + matrix.translateX + ", translateY = " + matrix.translateY + "]")
270  }
271  build() {
272    Row() {
273      Column() {
274        Text(this.message)
275          .fontSize(20)
276          .fontWeight(FontWeight.Bold)
277        Button("matrix identity")
278          .onClick(() => {
279            let matrix : Matrix2D = new Matrix2D()
280            matrix = matrix.identity()
281            this.printMatrix(this.message, matrix)
282          })
283      }
284      .width('100%')
285    }
286    .height('100%')
287  }
288}
289```
290
291### invert
292
293invert(): Matrix2D
294
295Obtains an inverse of this matrix.
296
297Since API version 9, this API is supported in ArkTS widgets.
298
299**Return value**
300
301| Type                 | Description        |
302| --------------------- | ------------ |
303| [Matrix2D](#matrix2d) | Inverse of the current matrix.|
304
305**Example**
306
307```ts
308// xxx.ets
309@Entry
310@Component
311struct Matrix2DInvert {
312  @State message: string = 'Matrix2D Invert'
313
314  printMatrix(title: string, matrix: Matrix2D) {
315    console.log(title)
316    console.log("Matrix [scaleX = " + matrix.scaleX + ", scaleY = " + matrix.scaleY +
317                ", rotateX = " + matrix.rotateX + ", rotateY = " + matrix.rotateY +
318                ", translateX = " + matrix.translateX + ", translateY = " + matrix.translateY + "]")
319  }
320  build() {
321    Row() {
322      Column() {
323        Text(this.message)
324          .fontSize(20)
325          .fontWeight(FontWeight.Bold)
326        Button("matrix invert")
327          .onClick(() => {
328            let matrix : Matrix2D = new Matrix2D()
329            matrix.scaleX = 2
330            matrix.scaleY = 1
331            matrix.rotateX = 0
332            matrix.rotateY = 0
333            matrix.translateX = 10
334            matrix.translateY = 20
335            matrix.invert()
336            this.printMatrix(this.message, matrix)
337          })
338      }
339      .width('100%')
340    }
341    .height('100%')
342  }
343}
344```
345
346### multiply<sup>(deprecated) </sup>
347
348multiply(other?: Matrix2D): Matrix2D
349
350Multiplies this matrix by the target matrix.
351
352Since API version 9, this API is supported in ArkTS widgets. This API is a null API.
353
354This API is deprecated since API version 10.
355
356**Parameters**
357
358| Parameter | Type    | Mandatory| Default Value| Description      |
359| ----- | -------- | ---- | ------ | ---------- |
360| other | Matrix2D | No  | null   | Target matrix.|
361
362**Return value**
363
364| Type                 | Description          |
365| --------------------- | -------------- |
366| [Matrix2D](#matrix2d) | Matrix of the multiplication result.|
367
368**Example**
369
370```ts
371// xxx.ets
372@Entry
373@Component
374struct Matrix2DMultiply {
375  @State message: string = 'Matrix2D Multiply'
376
377  printMatrix(title: string, matrix: Matrix2D) {
378    console.log(title)
379    console.log("Matrix [scaleX = " + matrix.scaleX + ", scaleY = " + matrix.scaleY +
380                ", rotateX = " + matrix.rotateX + ", rotateY = " + matrix.rotateY +
381                ", translateX = " + matrix.translateX + ", translateY = " + matrix.translateY + "]")
382  }
383  build() {
384    Row() {
385      Column() {
386        Text(this.message)
387          .fontSize(20)
388          .fontWeight(FontWeight.Bold)
389        Button("matrix multiply")
390          .onClick(() => {
391            let matrix : Matrix2D = new Matrix2D()
392            matrix.scaleX = 1
393            matrix.scaleY = 1
394            matrix.rotateX = 0
395            matrix.rotateY = 0
396            matrix.translateX = 0
397            matrix.translateY = 0
398            let other: Matrix2D = new Matrix2D()
399            other.scaleX = 2
400            other.scaleY = 2
401            other.rotateX = 0
402            other.rotateY = 0
403            other.translateX = 10
404            other.translateY = 10
405            other.multiply(other)
406            this.printMatrix(this.message, matrix)
407          })
408      }
409      .width('100%')
410    }
411    .height('100%')
412  }
413}
414```
415
416### rotate<sup>(deprecated) </sup>
417
418rotate(rx?: number, ry?: number): Matrix2D
419
420Performs a rotation operation on this matrix.
421
422Since API version 9, this API is supported in ArkTS widgets. This API is a null API.
423
424This API is deprecated since API version 10. You are advised to use [rotate](#rotate10) instead.
425
426**Parameters**
427
428| Parameter| Type  | Mandatory| Default Value| Description                            |
429| ---- | ------ | ---- | ------ | -------------------------------- |
430| rx   | number | No  | 0      | Horizontal coordinate (in vp) of the rotation point.|
431| ry   | number | No  | 0      | Vertical coordinate (in vp) of the rotation point.|
432
433**Return value**
434
435| Type                 | Description                |
436| --------------------- | -------------------- |
437| [Matrix2D](#matrix2d) | Matrix of the rotation result.|
438
439**Example**
440
441```ts
442// xxx.ets
443@Entry
444@Component
445struct Matrix2DRotate {
446  @State message: string = 'Matrix2D Rotate'
447
448  printMatrix(title: string, matrix: Matrix2D) {
449    console.log(title)
450    console.log("Matrix [scaleX = " + matrix.scaleX + ", scaleY = " + matrix.scaleY +
451                ", rotateX = " + matrix.rotateX + ", rotateY = " + matrix.rotateY +
452                ", translateX = " + matrix.translateX + ", translateY = " + matrix.translateY + "]")
453  }
454  build() {
455    Row() {
456      Column() {
457        Text(this.message)
458          .fontSize(20)
459          .fontWeight(FontWeight.Bold)
460        Button("matrix rotate")
461          .onClick(() => {
462            let matrix : Matrix2D = new Matrix2D()
463            matrix.scaleX = 1
464            matrix.scaleY = 1
465            matrix.rotateX = 0
466            matrix.rotateY = 0
467            matrix.translateX = 0
468            matrix.translateY = 0
469            matrix.rotate(10, 10)
470            this.printMatrix(this.message, matrix)
471          })
472      }
473      .width('100%')
474    }
475    .height('100%')
476  }
477}
478```
479
480### rotate<sup>10+</sup>
481
482rotate(degree: number, rx?: number, ry?: number): Matrix2D
483
484Performs a right multiplication rotation operation on this matrix, with the specified rotation point as the transform origin.
485
486Since API version 10, this API is supported in ArkTS widgets.
487
488**Parameters**
489
490| Parameter  | Type  | Mandatory| Default Value| Description                                                        |
491| ------ | ------ | ---- | ------ | ------------------------------------------------------------ |
492| degree | number | Yes  | 0      | Rotation angle, in radians. A positive angle denotes a clockwise rotation. You can use **Math.PI& / 180** to convert the angle to a radian value.|
493| rx     | number | No  | 0      | Horizontal coordinate (in vp) of the rotation point.                            |
494| ry     | number | No  | 0      | Vertical coordinate (in vp) of the rotation point.                            |
495
496**Return value**
497
498| Type                 | Description                |
499| --------------------- | -------------------- |
500| [Matrix2D](#matrix2d) | Matrix of the rotation result.|
501
502**Example**
503
504```ts
505// xxx.ets
506@Entry
507@Component
508struct Matrix2DRotate {
509  @State message: string = 'Matrix2D Rotate'
510
511  printMatrix(title: string, matrix: Matrix2D) {
512    console.log(title)
513    console.log("Matrix [scaleX = " + matrix.scaleX + ", scaleY = " + matrix.scaleY +
514                ", rotateX = " + matrix.rotateX + ", rotateY = " + matrix.rotateY +
515                ", translateX = " + matrix.translateX + ", translateY = " + matrix.translateY + "]")
516  }
517  build() {
518    Row() {
519      Column() {
520        Text(this.message)
521          .fontSize(20)
522          .fontWeight(FontWeight.Bold)
523        Button("matrix rotate")
524          .onClick(() => {
525            let matrix : Matrix2D = new Matrix2D()
526            matrix.scaleX = 1
527            matrix.scaleY = 1
528            matrix.rotateX = 0
529            matrix.rotateY = 0
530            matrix.translateX = 0
531            matrix.translateY = 0
532            matrix.rotate(90 / Math.PI, 10, 10)
533            this.printMatrix(this.message, matrix)
534          })
535      }
536      .width('100%')
537    }
538    .height('100%')
539  }
540}
541```
542
543### translate
544
545translate(tx?: number, ty?: number): Matrix2D
546
547Performs a left multiplication translation operation on this matrix.
548
549Since API version 9, this API is supported in ArkTS widgets.
550
551**Parameters**
552
553| Parameter| Type  | Mandatory| Default Value| Description                        |
554| ---- | ------ | ---- | ------ | ---------------------------- |
555| tx   | number | No  | 0      | Horizontal translation distance, in vp.|
556| ty   | number | No  | 0      | Vertical translation distance, in vp.|
557
558**Return value**
559
560| Type                 | Description                |
561| --------------------- | -------------------- |
562| [Matrix2D](#matrix2d) | Matrix of the translation result.|
563
564**Example**
565
566```ts
567// xxx.ets
568@Entry
569@Component
570struct Matrix2DTranslate {
571  @State message: string = 'Matrix2D Translate'
572
573  printMatrix(title: string, matrix: Matrix2D) {
574    console.log(title)
575    console.log("Matrix [scaleX = " + matrix.scaleX + ", scaleY = " + matrix.scaleY +
576                ", rotateX = " + matrix.rotateX + ", rotateY = " + matrix.rotateY +
577                ", translateX = " + matrix.translateX + ", translateY = " + matrix.translateY + "]")
578  }
579  build() {
580    Row() {
581      Column() {
582        Text(this.message)
583          .fontSize(20)
584          .fontWeight(FontWeight.Bold)
585        Button("matrix translate")
586          .onClick(() => {
587            let matrix : Matrix2D = new Matrix2D()
588            matrix.scaleX = 1
589            matrix.scaleY = 1
590            matrix.rotateX = 0
591            matrix.rotateY = 0
592            matrix.translateX = 0
593            matrix.translateY = 0
594            matrix.translate(100, 100)
595            this.printMatrix(this.message, matrix)
596          })
597      }
598      .width('100%')
599    }
600    .height('100%')
601  }
602}
603```
604
605### scale
606
607scale(sx?: number, sy?: number): Matrix2D
608
609Performs a right multiplication scaling operation on this matrix.
610
611Since API version 9, this API is supported in ArkTS widgets.
612
613**Parameters**
614
615| Parameter| Type  | Mandatory| Default Value| Description              |
616| ---- | ------ | ---- | ------ | ------------------ |
617| sx   | number | No  | 1      | Horizontal scale factor.|
618| sy   | number | No  | 1      | Vertical scale factor.|
619
620**Return value**
621
622| Type                 | Description              |
623| --------------------- | ------------------ |
624| [Matrix2D](#matrix2d) | Matrix of the scale result.|
625
626**Example**
627
628```ts
629// xxx.ets
630@Entry
631@Component
632struct Matrix2DScale {
633  @State message: string = 'Matrix2D Scale'
634
635  printMatrix(title: string, matrix: Matrix2D) {
636    console.log(title)
637    console.log("Matrix [scaleX = " + matrix.scaleX + ", scaleY = " + matrix.scaleY +
638                ", rotateX = " + matrix.rotateX + ", rotateY = " + matrix.rotateY +
639                ", translateX = " + matrix.translateX + ", translateY = " + matrix.translateY + "]")
640  }
641  build() {
642    Row() {
643      Column() {
644        Text(this.message)
645          .fontSize(20)
646          .fontWeight(FontWeight.Bold)
647        Button("matrix scale")
648          .onClick(() => {
649            let matrix : Matrix2D = new Matrix2D()
650            matrix.scaleX = 1
651            matrix.scaleY = 1
652            matrix.rotateX = 0
653            matrix.rotateY = 0
654            matrix.translateX = 0
655            matrix.translateY = 0
656            matrix.scale(0.5, 0.5)
657            this.printMatrix(this.message, matrix)
658          })
659      }
660      .width('100%')
661    }
662    .height('100%')
663  }
664}
665```
666