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(unit?: LengthMetricsUnit) 12 13**Widget capability**: This API can be used in ArkTS widgets since API version 9. 14 15**Atomic service API**: This API can be used in atomic services since API version 11. 16 17**System capability**: SystemCapability.ArkUI.ArkUI.Full 18 19**Parameters** 20 21| Name| Type| Mandatory| Description | 22| ------ | -------- | ---- | ------------------------------------- | 23| unit<sup>12+</sup> | [LengthMetricsUnit](../js-apis-arkui-graphics.md#lengthmetricsunit12) | No | Unit mode of the **Matrix2D** object. The value cannot be dynamically changed once set. The configuration method is the same as that of [CanvasRenderingContext2D](ts-canvasrenderingcontext2d.md#lengthmetricsunit12).<br>Default value: **DEFAULT**| 24 25## Attributes 26 27**Widget capability**: This API can be used in ArkTS widgets since API version 9. 28 29**Atomic service API**: This API can be used in atomic services since API version 11. 30 31**System capability**: SystemCapability.ArkUI.ArkUI.Full 32 33| Name| Type| Read Only| Optional | Description| 34| ----- | ----- | --------------- | ------ | ------------------------ | 35| scaleX | number | No| Yes| Horizontal scale factor. | 36| scaleY | number | No| Yes| Vertical scale factor. | 37| rotateX | number | No| Yes| Horizontal tilt coefficient. | 38| rotateY | number | No| Yes| Vertical tilt coefficient. | 39| translateX | number | No| Yes| Distance to translate on the x-axis.<br>Default unit: vp.| 40| translateY | number | No| Yes| Distance to translate on the y-axis.<br>Default unit: vp.| 41 42> **NOTE** 43> 44> You can use the [px2vp](ts-pixel-units.md#pixel-unit-conversion) API to convert the unit. 45 46**Example** 47 48```ts 49// xxx.ets 50@Entry 51@Component 52struct Parameter { 53 private settings: RenderingContextSettings = new RenderingContextSettings(true) 54 private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) 55 private matrix: Matrix2D = new Matrix2D() 56 57 build() { 58 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 59 Canvas(this.context) 60 .width('240vp') 61 .height('180vp') 62 .backgroundColor('#ffff00') 63 .onReady(() => { 64 this.context.fillRect(100, 20, 50, 50) 65 this.matrix.scaleX = 1 66 this.matrix.scaleY = 1 67 this.matrix.rotateX = -0.5 68 this.matrix.rotateY = 0.5 69 this.matrix.translateX = 10 70 this.matrix.translateY = 10 71 this.context.setTransform(this.matrix) 72 this.context.fillRect(100, 20, 50, 50) 73 }) 74 } 75 .width('100%') 76 .height('100%') 77 } 78} 79``` 80 81 82 83 84## Methods 85 86### identity 87 88identity(): Matrix2D 89 90Creates an identity matrix. 91 92**Widget capability**: This API can be used in ArkTS widgets since API version 9. 93 94**Atomic service API**: This API can be used in atomic services since API version 11. 95 96**System capability**: SystemCapability.ArkUI.ArkUI.Full 97 98**Return value** 99 100| Type | Description | 101| --------------------- | ---------- | 102| [Matrix2D](#matrix2d) | Identity matrix.| 103 104**Example** 105 106```ts 107// xxx.ets 108@Entry 109@Component 110struct Identity { 111 private settings: RenderingContextSettings = new RenderingContextSettings(true) 112 private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) 113 private matrix: Matrix2D = new Matrix2D() 114 115 build() { 116 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 117 Canvas(this.context) 118 .width('240vp') 119 .height('180vp') 120 .backgroundColor('#ffff00') 121 .onReady(() => { 122 this.context.fillRect(100, 20, 50, 50) 123 this.matrix = this.matrix.identity() 124 this.context.setTransform(this.matrix) 125 this.context.fillRect(100, 100, 50, 50) 126 }) 127 } 128 .width('100%') 129 .height('100%') 130 } 131} 132``` 133 134 135 136 137### invert 138 139invert(): Matrix2D 140 141Obtains an inverse of this matrix. 142 143**Widget capability**: This API can be used in ArkTS widgets since API version 9. 144 145**Atomic service API**: This API can be used in atomic services since API version 11. 146 147**System capability**: SystemCapability.ArkUI.ArkUI.Full 148 149**Return value** 150 151| Type | Description | 152| --------------------- | ------------ | 153| [Matrix2D](#matrix2d) | Inverse of the current matrix.| 154 155**Example** 156 157```ts 158// xxx.ets 159@Entry 160@Component 161struct Invert { 162 private settings: RenderingContextSettings = new RenderingContextSettings(true) 163 private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) 164 private matrix: Matrix2D = new Matrix2D() 165 166 build() { 167 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 168 Canvas(this.context) 169 .width('240vp') 170 .height('180vp') 171 .backgroundColor('#ffff00') 172 .onReady(() => { 173 this.context.fillRect(100, 110, 50, 50) 174 this.matrix.scaleX = 1 175 this.matrix.scaleY = 1 176 this.matrix.rotateX = -0.5 177 this.matrix.rotateY = 0.5 178 this.matrix.translateX = 10 179 this.matrix.translateY = 10 180 this.matrix.invert() 181 this.context.setTransform(this.matrix) 182 this.context.fillRect(100, 110, 50, 50) 183 }) 184 } 185 .width('100%') 186 .height('100%') 187 } 188} 189``` 190 191 192 193 194### multiply<sup>(deprecated) </sup> 195 196multiply(other?: Matrix2D): Matrix2D 197 198Multiplies this matrix by the target matrix. 199 200**Widget capability**: This API can be used in ArkTS widgets since API version 9. This API is an empty API. 201 202This API is deprecated since API version 10, and does not provide any actual rendering effects. Therefore, no examples are provided. 203 204**Parameters** 205 206| Name | Type | Mandatory| Description | 207| ----- | -------- | ---- | ---------- | 208| other | Matrix2D | No| Target matrix.<br>Default value: **null**| 209 210**Return value** 211 212| Type | Description | 213| --------------------- | -------------- | 214| [Matrix2D](#matrix2d) | Matrix of the multiplication result.| 215 216### rotate<sup>(deprecated) </sup> 217 218rotate(rx?: number, ry?: number): Matrix2D 219 220Performs a rotation operation on this matrix. 221 222**Widget capability**: This API can be used in ArkTS widgets since API version 9. This API is an empty API. 223 224This API is deprecated since API version 10. You are advised to use [rotate](#rotate10) instead. 225 226**Parameters** 227 228| Name| Type | Mandatory| Description | 229| ---- | ------ | ---- | -------------------------------- | 230| rx | number | No | Horizontal coordinate of the rotation point.<br>Default unit: vp.| 231| ry | number | No | Vertical coordinate of the rotation point.<br>Default unit: vp.| 232 233**Return value** 234 235| Type | Description | 236| --------------------- | -------------------- | 237| [Matrix2D](#matrix2d) | Matrix of the rotation result.| 238 239**Example** 240 241```ts 242// xxx.ets 243@Entry 244@Component 245struct Rotate { 246 private settings: RenderingContextSettings = new RenderingContextSettings(true) 247 private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) 248 private matrix: Matrix2D = new Matrix2D() 249 250 build() { 251 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 252 Canvas(this.context) 253 .width('240vp') 254 .height('180vp') 255 .backgroundColor('#ffff00') 256 .onReady(() => { 257 this.context.fillRect(50, 110, 50, 50) 258 this.matrix.scaleX = 1 259 this.matrix.scaleY = 1 260 this.matrix.rotateX = -0.5 261 this.matrix.rotateY = 0.5 262 this.matrix.translateX = 10 263 this.matrix.translateY = 10 264 this.matrix.rotate(5, 5) 265 this.context.setTransform(this.matrix) 266 this.context.fillRect(50, 110, 50, 50) 267 }) 268 } 269 .width('100%') 270 .height('100%') 271 } 272} 273``` 274 275 276 277 278### rotate<sup>10+</sup> 279 280rotate(degree: number, rx?: number, ry?: number): Matrix2D 281 282Performs a right multiplication rotation operation on this matrix, with the specified rotation point as the transform origin. 283 284**Widget capability**: This API can be used in ArkTS widgets since API version 10. 285 286**Atomic service API**: This API can be used in atomic services since API version 11. 287 288**System capability**: SystemCapability.ArkUI.ArkUI.Full 289 290**Parameters** 291 292| Name | Type | Mandatory| Description | 293| ------ | ------ | ---- | ------------------------------------------------------------ | 294| degree | number | Yes | Rotation angle. Positive angles represent clockwise rotation. You can convert the angle to radians using the following formula: degree * Math.PI/180.<br>Default unit: radian.| 295| rx | number | No | Horizontal coordinate of the rotation point.<br>Default unit: vp.<br>Default value: **0** | 296| ry | number | No | Vertical coordinate of the rotation point.<br>Default unit: vp.<br>Default value: **0** | 297 298**Return value** 299 300| Type | Description | 301| --------------------- | -------------------- | 302| [Matrix2D](#matrix2d) | Matrix of the rotation result.| 303 304**Example** 305 306```ts 307// xxx.ets 308@Entry 309@Component 310struct Rotate { 311 private settings: RenderingContextSettings = new RenderingContextSettings(true) 312 private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) 313 private matrix: Matrix2D = new Matrix2D() 314 315 build() { 316 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 317 Canvas(this.context) 318 .width('240vp') 319 .height('180vp') 320 .backgroundColor('#ffff00') 321 .onReady(() => { 322 this.context.fillRect(60, 80, 50, 50) 323 this.matrix.scaleX = 1 324 this.matrix.scaleY = 1 325 this.matrix.rotateX = -0.5 326 this.matrix.rotateY = 0.5 327 this.matrix.translateX = 10 328 this.matrix.translateY = 10 329 this.matrix.rotate(-60 * Math.PI / 180, 5, 5) 330 this.context.setTransform(this.matrix) 331 this.context.fillRect(60, 80, 50, 50) 332 }) 333 } 334 .width('100%') 335 .height('100%') 336 } 337} 338``` 339 340 341 342 343### translate 344 345translate(tx?: number, ty?: number): Matrix2D 346 347Performs a left multiplication translation operation on this matrix. 348 349**Widget capability**: This API can be used in ArkTS widgets since API version 9. 350 351**Atomic service API**: This API can be used in atomic services since API version 11. 352 353**System capability**: SystemCapability.ArkUI.ArkUI.Full 354 355**Parameters** 356 357| Name| Type | Mandatory| Description | 358| ---- | ------ | ---- | ---------------------------- | 359| tx | number | No | Distance to translate on the X axis.<br>Default unit: vp.<br>Default value: **0**| 360| ty | number | No | Distance to translate on the Y axis.<br>Default unit: vp.<br>Default value: **0**| 361 362**Return value** 363 364| Type | Description | 365| --------------------- | -------------------- | 366| [Matrix2D](#matrix2d) | Matrix of the translation result.| 367 368**Example** 369 370```ts 371// xxx.ets 372@Entry 373@Component 374struct Translate { 375 private settings: RenderingContextSettings = new RenderingContextSettings(true) 376 private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) 377 private matrix: Matrix2D = new Matrix2D() 378 379 build() { 380 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 381 Canvas(this.context) 382 .width('240vp') 383 .height('180vp') 384 .backgroundColor('#ffff00') 385 .onReady(() => { 386 this.context.fillRect(40, 20, 50, 50) 387 this.matrix.scaleX = 1 388 this.matrix.scaleY = 1 389 this.matrix.rotateX = 0 390 this.matrix.rotateY = 0 391 this.matrix.translateX = 0 392 this.matrix.translateY = 0 393 this.matrix.translate(100, 100) 394 this.context.setTransform(this.matrix) 395 this.context.fillRect(40, 20, 50, 50) 396 }) 397 } 398 .width('100%') 399 .height('100%') 400 } 401} 402``` 403 404 405 406 407### scale 408 409scale(sx?: number, sy?: number): Matrix2D 410 411Performs a right multiplication scaling operation on this matrix. 412 413**Widget capability**: This API can be used in ArkTS widgets since API version 9. 414 415**Atomic service API**: This API can be used in atomic services since API version 11. 416 417**System capability**: SystemCapability.ArkUI.ArkUI.Full 418 419**Parameters** 420 421| Parameter| Type | Mandatory| Description | 422| ---- | ------ | ---- | ------------------ | 423| sx | number | No | Horizontal scale factor.<br>Default value: **1.0**.| 424| sy | number | No | Vertical scale factor.<br>Default value: **1.0**.| 425 426**Return value** 427 428| Type | Description | 429| --------------------- | ------------------ | 430| [Matrix2D](#matrix2d) | Matrix of the scale result.| 431 432**Example** 433 434```ts 435// xxx.ets 436@Entry 437@Component 438struct Scale { 439 private settings: RenderingContextSettings = new RenderingContextSettings(true) 440 private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) 441 private matrix: Matrix2D = new Matrix2D() 442 443 build() { 444 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 445 Canvas(this.context) 446 .width('240vp') 447 .height('180vp') 448 .backgroundColor('#ffff00') 449 .onReady(() => { 450 this.context.fillRect(120, 70, 50, 50) 451 this.matrix.scaleX = 1 452 this.matrix.scaleY = 1 453 this.matrix.rotateX = -0.5 454 this.matrix.rotateY = 0.5 455 this.matrix.translateX = 10 456 this.matrix.translateY = 10 457 this.matrix.scale(0.5, 0.5) 458 this.context.setTransform(this.matrix) 459 this.context.fillRect(120, 70, 50, 50) 460 }) 461 } 462 .width('100%') 463 .height('100%') 464 } 465} 466``` 467 468 469
