1# Canvas Operations and State Processing (ArkTS) 2 3 4## When to Use 5 6After the canvas is created or obtained, a graphics operation and state processing may be further performed based on the canvas. Canvas operations are optional. You can perform these operations based on the scenario requirements. You need to perform operations on the canvas before drawing the canvas. Only in this way can the canvas operations take effect. 7 8Common canvas operations are as follows: 9 10- Cropping 11 12- Matrix transformation, such as translation, scaling, and rotation. 13 14- Status saving and restoration 15 16For details about canvas operations and API parameters, see [drawing.Canvas](../reference/apis-arkgraphics2d/js-apis-graphics-drawing.md#canvas). 17 18 19## Cropping 20 21Cropping is a common operation in graphics processing. Cropping is performed on the canvas itself and can be used to limit the drawing area and draw only the specified area. You need to perform the cropping operation and then draw the image to obtain the corresponding effect. 22 23Currently, the following tailoring operations are supported: 24 25- Crops a rectangle. 26 27- Crops a rounded rectangle. 28 29- Tailor the user-defined path. 30 31- Crops a region. 32 33 34### Available APIs 35 36The following table lists the common tailoring APIs. For details about the usage and parameters, see [drawing.Canvas](../reference/apis-arkgraphics2d/js-apis-graphics-drawing.md#canvas). 37 38 39| Interface| Description| 40| -------- | -------- | 41| clipRect(rect: common2D.Rect, clipOp?: ClipOp, doAntiAlias?: boolean): void | Clips a rectangle.| 42| clipRoundRect(roundRect: RoundRect, clipOp?: ClipOp, doAntiAlias?: boolean): void | Clips a rounded rectangle.| 43| clipPath(path: Path, clipOp?: ClipOp, doAntiAlias?: boolean): void | Clips a path.| 44| clipRegion(region: Region, clipOp?: ClipOp): void | Clips a region.| 45 46 47### How to Develop 48 49The following describes how to crop a rectangle on the canvas. The logic of other cropping operations is similar. Call the corresponding APIs and ensure that the data type to be cropped is correct. For details about the usage and parameters, see [drawing.Canvas](../reference/apis-arkgraphics2d/js-apis-graphics-drawing.md#canvas). 50 51Call clipRect() to crop a rectangle. There are three input parameters: 52 53 54- rect is the rectangular area to be cropped. 55 56- clipOp indicates the clipping mode, including INTERSECT and DIFFERENCE. For details, see [ClipOp](../reference/apis-arkgraphics2d/js-apis-graphics-drawing.md#clipop12). 57 58- doAntiAlias indicates whether anti-aliasing is required. If the value is true, the anti-aliasing function is enabled, and the edge pixels of the image are blurred semi-transparently when the image is drawn. If the value is false, the anti-aliasing function is disabled. 59 60 61```ts 62// Create a brush. 63let brush = new drawing.Brush(); 64// Set the color to blue. 65brush.setColor(0xFF, 0x00, 0x00, 0xFF); 66// Set the brush filling effect. 67canvas.attachBrush(brush); 68// Create a rectangle object. 69let rect: common2D.Rect = { left: 200, top: 200, right: 600, bottom: 600 }; 70// Crop a rectangular area. 71canvas.clipRect(rect); 72// Draw a circle on the canvas. 73canvas.drawCircle(300, 300, 300); 74// Remove the padding effect. 75canvas.detachBrush(); 76``` 77 78 79| Original image| Image after cropping| 80| -------- | -------- | 81|  |  | 82 83 84## Matrix Transformation 85 86Matrix transformation is also a common canvas operation, is a coordinate system transformation, and is used to change a graph. 87 88Currently, the following matrix transformations are supported: 89 90- Translation 91 92- Scaling 93 94- Rotation 95 96 97### Available APIs 98 99The following table lists the common APIs for matrix transformation. For details about the usage and parameters, see [drawing.Canvas](../reference/apis-arkgraphics2d/js-apis-graphics-drawing.md#canvas). 100 101| Interface| Description| 102| -------- | -------- | 103| translate(dx: number, dy: number): void | Translates a canvas by a given distance.| 104| scale(sx: number, sy: number): void | Scales a canvas.| 105| rotate(degrees: number, sx: number, sy: number): void | Rotates a canvas by a given angle. A positive value indicates a clockwise rotation, and a negative value indicates a counterclockwise rotation.| 106| skew(sx: number, sy: number) : void | Skews a canvas in both the horizontal and vertical directions.| 107 108 109### Translation 110 111Use the translate() API to translate the canvas. The interface accepts two parameters, that is, the horizontal translation amount and vertical translation amount. The unit is pixel. 112 113The following figure shows a simple example. 114 115 116```ts 117// Create a brush. 118let brush = new drawing.Brush(); 119// Set the color to red. 120brush.setColor(0xFF, 0xFF, 0x00, 0x00); 121// Set the brush filling effect. 122canvas.attachBrush(brush); 123// Perform the pan operation. 124canvas.translate(300, 300); 125// Draw a rectangle. 126canvas.drawRect({ left: 200, top: 200, right: 600, bottom: 600 }); 127// Remove the padding effect. 128canvas.detachBrush(); 129``` 130 131 132| Original image| Effect after translation| 133| -------- | -------- | 134|  |  | 135 136 137### Rotation 138 139Use the rotate() API to rotate the canvas. The API accepts three parameters: rotation angle, X coordinate of the rotation center, and Y coordinate of the rotation center. 140 141 142The following figure shows a simple example. 143 144 145```ts 146// Create a brush. 147let brush = new drawing.Brush(); 148// Set the color to red. 149brush.setColor(0xFF, 0xFF, 0x00, 0x00); 150// Set the brush filling effect. 151canvas.attachBrush(brush); 152// Rotate the image clockwise by 45 degrees. 153canvas.rotate(45, 200, 200); 154// Draw a rectangle. 155canvas.drawRect({ left: 200, top: 200, right: 600, bottom: 600 }); 156// Remove the padding effect. 157canvas.detachBrush(); 158``` 159 160 161| Original image| Rotated effect| 162| -------- | -------- | 163|  |  | 164 165 166### Scaling 167 168Use the scale() API to scale the canvas. The API accepts two parameters: scaling factor along the x-axis and scaling factor along the y-axis. 169 170 171The following figure shows a simple example. 172 173 174```ts 175// Create a brush. 176let brush = new drawing.Brush(); 177// Set the color to red. 178brush.setColor({ alpha: 0xFF, red: 0xFF, green: 0x00, blue: 0x00 }); 179// Set the brush filling effect. 180canvas.attachBrush(brush); 181// Perform the zoom-in operation. 182canvas.scale(2, 2); 183// Draw a rectangle. 184canvas.drawRect({ left: 200, top: 200, right: 600, bottom: 600 }); 185// Remove the padding effect. 186canvas.detachBrush(); 187``` 188 189 190| Original image| Effect after resizing| 191| -------- | -------- | 192|  |  | 193 194 195## Saving and Restoring the Canvas State 196 197 198The save operation is used to save the current canvas status to the top of a stack. The restore operation is used to restore the canvas status saved at the top of the stack. Once the restore operation is performed, a series of operations such as translation, scaling, and cropping between the save and restore operations are cleared. 199 200 201### Available APIs 202 203The following table lists the APIs for saving and restoring the canvas status. For details about the usage and parameters, see [canvas](../reference/apis-arkgraphics2d/js-apis-graphics-drawing.md#canvas). 204 205| Interface| Description| 206| -------- | -------- | 207| save(): void; | Saves the current canvas status (canvas matrix) to the top of the stack.| 208| restore(): void; | Restores the canvas status (canvas matrix) saved on the top of the stack.| 209| restoreToCount(count: number): void; | Restores to a given number of canvas statuses (canvas matrices).| 210 211The following figure shows a simple example. 212 213 214```ts 215// Create a pen. 216let pen = new drawing.Pen(); 217// Set the color to red. 218pen.setColor({ alpha: 0xFF, red: 0xFF, green: 0x00, blue: 0x00 }); 219// Set the stroke width to 20 px. 220pen.setStrokeWidth(20); 221// Set the stroke effect. 222canvas.attachPen(pen); 223// Save operation. Currently, no zoom-in operation is performed. The original status is saved. 224canvas.save(); 225// Zoom in twice on the x-axis and y-axis respectively. 226canvas.scale(2, 2); 227// Draw a circle. Because the zoom-in operation has been performed, a large circle is drawn. 228canvas.drawCircle(300, 300, 200); 229// Restore to the original state without zooming in. 230canvas.restore(); 231// Draw a circle. Because the circle has been restored to the original state without being zoomed in, a small circle is drawn. 232canvas.drawCircle(300, 300, 200); 233// Remove the stroke effect. 234canvas.detachPen(); 235``` 236 237 238 239
