1# Canvas Operations and State Processing (C/C++) 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 16 17## Cropping 18 19Cropping 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. 20 21Currently, the following tailoring operations are supported: 22 23- Crops a rectangle. 24 25- Crops a rounded rectangle. 26 27- Tailor the user-defined path. 28 29- Crops a region. 30 31 32### Available APIs 33 34The following table lists the common tailoring APIs. For details about the usage and parameters, see [drawing_canvas.h](../reference/apis-arkgraphics2d/drawing__canvas_8h.md). 35 36| Interface| Description| 37| -------- | -------- | 38| void OH_Drawing_CanvasClipRect (OH_Drawing_Canvas \*, const OH_Drawing_Rect \*, OH_Drawing_CanvasClipOp clipOp, bool doAntiAlias) | Clips a rectangle.| 39| void OH_Drawing_CanvasClipRoundRect (OH_Drawing_Canvas \*, const OH_Drawing_RoundRect \*, OH_Drawing_CanvasClipOp clipOp, bool doAntiAlias) | Clips a rounded rectangle.| 40| void OH_Drawing_CanvasClipPath (OH_Drawing_Canvas \*, const OH_Drawing_Path \*, OH_Drawing_CanvasClipOp clipOp, bool doAntiAlias) | Clips a path.| 41| OH_Drawing_ErrorCode OH_Drawing_CanvasClipRegion (OH_Drawing_Canvas \*canvas, const OH_Drawing_Region \*region, OH_Drawing_CanvasClipOp clipOp) | Clips a region.| 42 43 44### How to Develop 45 46The 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.h](../reference/apis-arkgraphics2d/drawing__canvas_8h.md). 47 48Crop a rectangle by calling OH_Drawing_CanvasClipRect. There are four input parameters: 49- The first parameter is the canvas. The cropping operation is performed on the canvas. Ensure that the canvas has been created or obtained. For details, see [Obtaining a Canvas and Displaying Drawing Results (C/C++)](canvas-get-result-draw-c.md). 50 51- The second parameter is the rectangular area to be cropped. 52 53- The third parameter is the cropping operation type, including INTERSECT and DIFFERENCE. 54 55- The fourth parameter indicates whether anti-aliasing is required. 56 57```c++ 58// Create a brush object. 59OH_Drawing_Brush *brush = OH_Drawing_BrushCreate(); 60// Set the brush fill color to blue. 61OH_Drawing_BrushSetColor(brush, 0xff0000ff); 62// Set the brush in the canvas. 63OH_Drawing_CanvasAttachBrush(canvas, brush); 64OH_Drawing_Rect *rect = OH_Drawing_RectCreate(400, 400, 1200, 1200); 65// Crop a rectangular area. 66OH_Drawing_CanvasClipRect(canvas, rect, OH_Drawing_CanvasClipOp::INTERSECT, true); 67OH_Drawing_Point *point = OH_Drawing_PointCreate(600, 600); 68// Draw a circle on the canvas. 69OH_Drawing_CanvasDrawCircle(canvas, point, 600); 70// Remove the brush from the canvas. 71OH_Drawing_CanvasDetachBrush(canvas); 72// Destroy the brush object and reclaim the memory occupied by the brush object. 73OH_Drawing_BrushDestroy(brush); 74``` 75 76| Original image| Image after cropping| 77| -------- | -------- | 78|  |  | 79 80 81## Matrix Transformation 82 83Matrix transformation is also a common canvas operation, is a coordinate system transformation, and is used to change a graph. 84 85Currently, the following matrix transformations are supported: 86 87- Translation 88 89- Scaling 90 91- Rotation 92 93 94### Available APIs 95 96The following table lists the common APIs for matrix transformation. For details about the usage and parameters, see [drawing_matrix.h](../reference/apis-arkgraphics2d/drawing__matrix_8h.md). 97 98| Interface| Description| 99| -------- | -------- | 100| void OH_Drawing_CanvasTranslate (OH_Drawing_Canvas \*, float dx, float dy) | Translates a canvas by a given distance.| 101| void OH_Drawing_CanvasScale (OH_Drawing_Canvas \*, float sx, float sy) | Scales a canvas.| 102| void OH_Drawing_CanvasRotate (OH_Drawing_Canvas \*, float degrees, float px, float py) | Rotates a canvas by a given angle. A positive value indicates a clockwise rotation, and a negative value indicates a counterclockwise rotation.| 103| void OH_Drawing_CanvasSkew (OH_Drawing_Canvas \*, float sx, float sy) | Skews a canvas. This function premultiplies the current canvas matrix by a skew transformation matrix and applies the resulting matrix to the canvas. The skew transformation matrix is as follows: \|1 sx 0\| \|sy 1 0\| \|0 0 1\|.| 104 105 106### Translation 107 108Use the OH_Drawing_MatrixCreateTranslation() API to translate the canvas. The interface accepts two parameters, that is, the horizontal translation amount and vertical translation amount. The unit is pixel. 109 110The following figure shows a simple example. 111 112```c++ 113// Create a brush object. 114OH_Drawing_Brush* brush = OH_Drawing_BrushCreate(); 115// Fill color to be superimposed on the image. 116OH_Drawing_BrushSetColor(brush, OH_Drawing_ColorSetArgb(0xFF, 0xFF, 0x00, 0x00)); 117// Set the brush in the canvas. 118OH_Drawing_CanvasAttachBrush(canvas, brush); 119// Create a matrix object that is translated by 300 px in the horizontal and vertical directions. 120OH_Drawing_Matrix *matrix = OH_Drawing_MatrixCreateTranslation(300, 300); 121// Perform matrix transformation on Canvas. 122OH_Drawing_CanvasConcatMatrix(canvas, matrix); 123// Draw a rectangle. 124OH_Drawing_Rect *rect = OH_Drawing_RectCreate(200, 300, 700, 600); 125OH_Drawing_CanvasDrawRect(canvas, rect); 126// Remove the brush from the canvas. 127OH_Drawing_CanvasDetachBrush(canvas); 128OH_Drawing_RectDestroy(rect); 129OH_Drawing_MatrixDestroy(matrix); 130``` 131 132| Original image| Effect after translation| 133| -------- | -------- | 134|  |  | 135 136 137### Rotation 138 139Call the OH_Drawing_MatrixCreateRotation() 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 141The following figure shows a simple example. 142 143```c++ 144// Create a brush object. 145OH_Drawing_Brush* brush = OH_Drawing_BrushCreate(); 146Fill color to be superimposed on the image. 147OH_Drawing_BrushSetColor(brush, OH_Drawing_ColorSetArgb(0xFF, 0xFF, 0x00, 0x00)); 148// Set the brush in the canvas. 149OH_Drawing_CanvasAttachBrush(canvas, brush); 150// Create a rotation matrix object. The three parameters are the rotation angle and rotation center coordinates. 151OH_Drawing_Matrix* matrix = OH_Drawing_MatrixCreateRotation(45, 200, 300); 152// Perform matrix transformation on Canvas. 153OH_Drawing_CanvasConcatMatrix(canvas, matrix); 154// Draw a rectangle. 155OH_Drawing_Rect *rect = OH_Drawing_RectCreate(200, 300, 700, 600); 156OH_Drawing_CanvasDrawRect(canvas, rect); 157// Remove the brush from the canvas. 158OH_Drawing_CanvasDetachBrush(canvas); 159OH_Drawing_RectDestroy(rect); 160OH_Drawing_MatrixDestroy(matrix); 161``` 162 163| Original image| Rotated effect| 164| -------- | -------- | 165|  |  | 166 167 168### Scaling 169 170Use the OH_Drawing_MatrixCreateScale() API to scale the canvas. The API accepts four parameters: scaling factor along the x-axis and y-axis, and the x-axis and y-axis coordinates of the rotation center. 171 172The following figure shows a simple example. 173 174```c++ 175// Create a brush object. 176OH_Drawing_Brush* brush = OH_Drawing_BrushCreate(); 177Fill color to be superimposed on the image. 178OH_Drawing_BrushSetColor(brush, OH_Drawing_ColorSetArgb(0xFF, 0xFF, 0x00, 0x00)); 179// Set the brush in the canvas. 180OH_Drawing_CanvasAttachBrush(canvas, brush); 181// Create a scaling matrix object. The four parameters are the rotation center coordinates and horizontal and vertical scaling factors. 182OH_Drawing_Matrix* matrix = OH_Drawing_MatrixCreateScale(2, 2, 200, 300); 183// Perform matrix transformation on Canvas. 184OH_Drawing_CanvasConcatMatrix(canvas, matrix); 185// Draw a rectangle. 186OH_Drawing_Rect *rect = OH_Drawing_RectCreate(200, 300, 700, 600); 187OH_Drawing_CanvasDrawRect(canvas, rect); 188// Remove the brush from the canvas. 189OH_Drawing_CanvasDetachBrush(canvas); 190OH_Drawing_RectDestroy(rect); 191``` 192 193| Original image| Zoomed-in effect| 194| -------- | -------- | 195|  |  | 196 197 198## Saving and Restoring the Canvas State 199 200The 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. 201 202 203### Available APIs 204 205The following table lists the APIs for saving and restoring the canvas status. For details about the usage and parameters, see [drawing_canvas.h](../reference/apis-arkgraphics2d/drawing__canvas_8h.md). 206 207| Interface| Description| 208| -------- | -------- | 209| void OH_Drawing_CanvasSave (OH_Drawing_Canvas \*) | Saves the current canvas status (canvas matrix) to the top of the stack.| 210| void OH_Drawing_CanvasRestore (OH_Drawing_Canvas \*) | Restores the canvas status (canvas matrix) saved on the top of the stack.| 211| void OH_Drawing_CanvasRestoreToCount (OH_Drawing_Canvas \*, uint32_t saveCount) | Restores to a given number of canvas statuses (canvas matrices).| 212 213 214### How to Develop 215 216```c++ 217// Create a pen object. 218OH_Drawing_Pen* pen = OH_Drawing_PenCreate(); 219// Set the stroke color. 220OH_Drawing_PenSetColor(pen, OH_Drawing_ColorSetArgb(0xFF, 0xFF, 0x00, 0x00)); 221// Set the line width of the pen. 222OH_Drawing_PenSetWidth(pen, 20); 223// Set the pen in the canvas. 224OH_Drawing_CanvasAttachPen(canvas, pen); 225// Save the current canvas status. Currently, operations such as zoom-in are not performed. The original status is saved. 226OH_Drawing_CanvasSave(canvas); 227OH_Drawing_Matrix *matrix = OH_Drawing_MatrixCreateScale(2, 2, 2, 2); 228// Zoom In 229OH_Drawing_CanvasConcatMatrix(canvas, matrix); 230OH_Drawing_Point* point = OH_Drawing_PointCreate(300, 300); 231// Draw a circle. Because the zoom-in operation has been performed, a large circle is drawn. 232OH_Drawing_CanvasDrawCircle(canvas, point, 200); 233// Restore the image to the original state without zooming in. 234OH_Drawing_CanvasRestore(canvas); 235// Draw a circle. The circle is drawn because it has been restored to the original state without being zoomed in. 236OH_Drawing_CanvasDrawCircle(canvas, point, 200); 237// Remove the pen from the canvas. 238OH_Drawing_CanvasDetachPen(canvas); 239// Destroy the pen object and reclaim the memory occupied by the object. 240OH_Drawing_PenDestroy(pen); 241OH_Drawing_PointDestroy(point); 242OH_Drawing_MatrixDestroy(matrix); 243``` 244 245 246
