1# 画布操作及状态处理（C/C++） 2 3<!--Kit: ArkGraphics 2D--> 4<!--Subsystem: Graphics--> 5<!--Owner: @hangmengxin--> 6<!--Designer: @wangyanglan--> 7<!--Tester: @nobuggers--> 8<!--Adviser: @ge-yafang--> 9 10## 场景介绍 11 12创建或获取得到Canvas画布之后，可以基于画布进一步地进行图形操作和状态处理。画布操作属于可选操作，开发者可以根据场景需要进行。需要先进行画布操作，再进行后续绘制，只有这样画布操作才有效果。 13 14常见的画布操作如下： 15 16- 裁剪。 17 18- 矩阵变换，如平移、缩放、旋转等。 19 20- 状态保存与恢复。 21 22 23## 裁剪操作 24 25裁剪是图形处理中的常见操作，裁剪针对的是画布本身，可以用于限制绘图区域，只在指定的区域内容进行绘制。需要先进行裁剪操作，再进行绘制，才会有对应效果。 26 27当前支持的裁剪操作主要如下： 28 29- 裁剪矩形。 30 31- 裁剪圆角矩形。 32 33- 裁剪自定义路径。 34 35- 裁剪一个区域。 36 37 38### 接口说明 39 40裁剪操作常用接口如下表所示，详细的使用和参数说明请见[drawing_canvas.h](../reference/apis-arkgraphics2d/capi-drawing-canvas-h.md)。 41 42| 接口 | 描述 | 43| -------- | -------- | 44| void OH_Drawing_CanvasClipRect (OH_Drawing_Canvas \*, const OH_Drawing_Rect \*, OH_Drawing_CanvasClipOp clipOp, bool doAntiAlias) | 用于裁剪一个矩形。 | 45| void OH_Drawing_CanvasClipRoundRect (OH_Drawing_Canvas \*, const OH_Drawing_RoundRect \*, OH_Drawing_CanvasClipOp clipOp, bool doAntiAlias) | 用于裁剪一个圆角矩形。 | 46| void OH_Drawing_CanvasClipPath (OH_Drawing_Canvas \*, const OH_Drawing_Path \*, OH_Drawing_CanvasClipOp clipOp, bool doAntiAlias) | 用于裁剪一个自定义路径。 | 47| OH_Drawing_ErrorCode OH_Drawing_CanvasClipRegion (OH_Drawing_Canvas \*canvas, const OH_Drawing_Region \*region, OH_Drawing_CanvasClipOp clipOp) | 用于裁剪一个区域。 | 48 49 50### 开发示例 51 52此处以在画布上裁剪矩形为例给出示例和效果图，其他裁剪操作的逻辑基本相同，注意调用对应的接口并确保要裁剪的数据类型对应准确即可，此处不再一一展开。具体详细的使用和参数说明请见[drawing_canvas.h](../reference/apis-arkgraphics2d/capi-drawing-canvas-h.md)。 53 54使用OH_Drawing_CanvasClipRect接口裁剪矩形。有以下四个入参： 55- 第一个参数是画布Canvas，裁剪操作将在这个画布上进行。请确保已创建或获取得到画布Canvas，具体可见[画布的获取与绘制结果的显示（C/C++）](canvas-get-result-draw-c.md)。 56 57- 第二个参数是要裁剪的矩形区域。 58 59- 第三个参数是裁剪的操作类型，包括交集（INTERSECT）和差集（DIFFERENCE）。 60 61- 第四个参数表示是否需要进行抗锯齿处理。 62 63```c++ 64// 创建画刷对象 65OH_Drawing_Brush *brush = OH_Drawing_BrushCreate(); 66// 设置画刷填充颜色为蓝色 67OH_Drawing_BrushSetColor(brush, 0xff0000ff); 68// 在画布中设置画刷 69OH_Drawing_CanvasAttachBrush(canvas, brush); 70OH_Drawing_Rect *rect = OH_Drawing_RectCreate(400, 400, 1200, 1200); 71// 裁剪矩形区域 72OH_Drawing_CanvasClipRect(canvas, rect, OH_Drawing_CanvasClipOp::INTERSECT, true); 73OH_Drawing_Point *point = OH_Drawing_PointCreate(600, 600); 74// 绘制圆形 75OH_Drawing_CanvasDrawCircle(canvas, point, 600); 76// 去除画布中的画刷 77OH_Drawing_CanvasDetachBrush(canvas); 78// 销毁画刷对象并收回其占的内存 79OH_Drawing_BrushDestroy(brush); 80``` 81 82| 原始图 | 裁剪后的图 | 83| -------- | -------- | 84|  |  | 85 86 87## 矩阵变换操作 88 89矩阵变换也是常见的画布操作，是一种坐标系的转换，用于进行图形的变化。 90 91当前支持的矩阵变换主要如下： 92 93- 平移 94 95- 缩放 96 97- 旋转 98 99 100### 接口说明 101 102矩阵变换操作常用接口如下表所示，详细的使用和参数说明请见[drawing_matrix.h](../reference/apis-arkgraphics2d/capi-drawing-matrix-h.md)。 103 104| 接口 | 描述 | 105| -------- | -------- | 106| void OH_Drawing_CanvasTranslate (OH_Drawing_Canvas \*, float dx, float dy) | 用于平移画布一段距离。 | 107| void OH_Drawing_CanvasScale (OH_Drawing_Canvas \*, float sx, float sy) | 用于画布缩放。 | 108| void OH_Drawing_CanvasRotate (OH_Drawing_Canvas \*, float degrees, float px, float py) | 用于画布旋转一定的角度，正数表示顺时针旋转，负数反之。 | 109| void OH_Drawing_CanvasSkew (OH_Drawing_Canvas \*, float sx, float sy) | 用于画布倾斜变换。等同于将当前画布矩阵左乘（premultiply）倾斜变换矩阵，并应用到画布上。其中倾斜变换矩阵为：\|1 sx 0\| \|sy 1 0\| \|0 0 1\|。 | 110 111 112### 平移 113 114使用OH_Drawing_MatrixCreateTranslation()接口实现画布平移。接口接受2个参数，分别为水平方向和垂直方向的平移量，单位为px。 115 116简单示例和示意图如下所示： 117 118```c++ 119// 创建画刷对象 120OH_Drawing_Brush* brush = OH_Drawing_BrushCreate(); 121// 设置填充颜色 122OH_Drawing_BrushSetColor(brush, OH_Drawing_ColorSetArgb(0xFF, 0xFF, 0x00, 0x00)); 123// 设置画布中的画刷 124OH_Drawing_CanvasAttachBrush(canvas, brush); 125// 创建在水平和垂直方向分别平移300px的矩阵对象 126OH_Drawing_Matrix *matrix = OH_Drawing_MatrixCreateTranslation(300, 300); 127// 对Canvas进行矩阵变换 128OH_Drawing_CanvasConcatMatrix(canvas, matrix); 129// 绘制矩形 130OH_Drawing_Rect *rect = OH_Drawing_RectCreate(200, 300, 700, 600); 131OH_Drawing_CanvasDrawRect(canvas, rect); 132// 去除画布中的画刷 133OH_Drawing_CanvasDetachBrush(canvas); 134OH_Drawing_RectDestroy(rect); 135OH_Drawing_MatrixDestroy(matrix); 136``` 137 138| 原始图 | 平移后的效果图 | 139| -------- | -------- | 140|  |  | 141 142 143### 旋转 144 145使用OH_Drawing_MatrixCreateRotation()接口实现画布旋转，接口接受3个参数，分别为：旋转角度、旋转中心的x坐标和y坐标。 146 147简单示例和示意图如下所示： 148 149```c++ 150// 创建画刷对象 151OH_Drawing_Brush* brush = OH_Drawing_BrushCreate(); 152// 设置填充颜色 153OH_Drawing_BrushSetColor(brush, OH_Drawing_ColorSetArgb(0xFF, 0xFF, 0x00, 0x00)); 154// 设置画布中的画刷 155OH_Drawing_CanvasAttachBrush(canvas, brush); 156// 创建旋转的矩阵对象，三个参数分别是旋转角度和旋转中心坐标 157OH_Drawing_Matrix* matrix = OH_Drawing_MatrixCreateRotation(45, 200, 300); 158// 对Canvas进行矩阵变换 159OH_Drawing_CanvasConcatMatrix(canvas, matrix); 160// 绘制矩形 161OH_Drawing_Rect *rect = OH_Drawing_RectCreate(200, 300, 700, 600); 162OH_Drawing_CanvasDrawRect(canvas, rect); 163// 去除画布中的画刷 164OH_Drawing_CanvasDetachBrush(canvas); 165OH_Drawing_RectDestroy(rect); 166OH_Drawing_MatrixDestroy(matrix); 167``` 168 169| 原始图 | 旋转后的效果图 | 170| -------- | -------- | 171|  |  | 172 173 174### 缩放 175 176使用OH_Drawing_MatrixCreateScale()接口进行画布缩放，接口接受4个参数，分别为沿x轴和y轴的缩放因子、旋转中心的x轴和y轴坐标。 177 178简单示例和示意图如下所示： 179 180```c++ 181// 创建画刷对象 182OH_Drawing_Brush* brush = OH_Drawing_BrushCreate(); 183// 设置填充颜色 184OH_Drawing_BrushSetColor(brush, OH_Drawing_ColorSetArgb(0xFF, 0xFF, 0x00, 0x00)); 185// 设置画布中的画刷 186OH_Drawing_CanvasAttachBrush(canvas, brush); 187// 创建缩放的矩阵对象，4个参数分别是旋转中心坐标和水平垂直方向的缩放因子 188OH_Drawing_Matrix* matrix = OH_Drawing_MatrixCreateScale(2, 2, 200, 300); 189// 对Canvas进行矩阵变换 190OH_Drawing_CanvasConcatMatrix(canvas, matrix); 191// 绘制矩形 192OH_Drawing_Rect *rect = OH_Drawing_RectCreate(200, 300, 700, 600); 193OH_Drawing_CanvasDrawRect(canvas, rect); 194// 去除画布中的画刷 195OH_Drawing_CanvasDetachBrush(canvas); 196OH_Drawing_RectDestroy(rect); 197``` 198 199| 原始图 | 放大后的效果图 | 200| -------- | -------- | 201|  |  | 202 203 204## 画布状态保存与恢复 205 206保存操作用于保存当前画布的状态到一个栈顶，恢复操作用于恢复保存在栈顶的画布状态，恢复操作一旦执行，保存和恢复操作中间一系列平移、缩放、剪裁等操作都会被清除。 207 208 209### 接口说明 210 211画布状态保存与恢复使用的接口如下表所示，详细的使用和参数说明请见[drawing_canvas.h](../reference/apis-arkgraphics2d/capi-drawing-canvas-h.md)。 212 213| 接口 | 描述 | 214| -------- | -------- | 215| void OH_Drawing_CanvasSave (OH_Drawing_Canvas \*) | 用于保存当前画布的状态（画布矩阵）到一个栈顶。 | 216| void OH_Drawing_CanvasRestore (OH_Drawing_Canvas \*) | 用于恢复保存在栈顶的画布状态（画布矩阵）。 | 217| void OH_Drawing_CanvasRestoreToCount (OH_Drawing_Canvas \*, uint32_t saveCount) | 用于恢复到指定数量的画布状态（画布矩阵）。 | 218 219 220### 开发示例 221 222```c++ 223// 创建画笔对象 224OH_Drawing_Pen* pen = OH_Drawing_PenCreate(); 225// 设置画笔描边颜色 226OH_Drawing_PenSetColor(pen, OH_Drawing_ColorSetArgb(0xFF, 0xFF, 0x00, 0x00)); 227// 设置画笔线宽 228OH_Drawing_PenSetWidth(pen, 20); 229// 在画布中设置画笔 230OH_Drawing_CanvasAttachPen(canvas, pen); 231// 保存当前画布状态，当前是不存在放大等操作的，这个原始状态会被保存下来 232OH_Drawing_CanvasSave(canvas); 233OH_Drawing_Matrix *matrix = OH_Drawing_MatrixCreateScale(2, 2, 2, 2); 234// 放大画布 235OH_Drawing_CanvasConcatMatrix(canvas, matrix); 236OH_Drawing_Point* point = OH_Drawing_PointCreate(300, 300); 237// 绘制圆形，因为执行过放大操作，所以此时绘制的是大圆 238OH_Drawing_CanvasDrawCircle(canvas, point, 200); 239// 恢复操作，将恢复到没有放大的原始状态 240OH_Drawing_CanvasRestore(canvas); 241// 绘制圆形，因为已经恢复没有放大的原始状态，所以此时绘制的小圆 242OH_Drawing_CanvasDrawCircle(canvas, point, 200); 243// 去除画布中的画笔 244OH_Drawing_CanvasDetachPen(canvas); 245// 销毁画笔对象并收回其占的内存 246OH_Drawing_PenDestroy(pen); 247OH_Drawing_PointDestroy(point); 248OH_Drawing_MatrixDestroy(matrix); 249``` 250 251 252 253<!--RP1--> 254## 相关实例 255 256针对Drawing(C/C++)的开发，有以下相关实例可供参考： 257 258- [NDKGraphicsDraw (API14)](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/DocsSample/Drawing/NDKGraphicsDraw) 259<!--RP1End-->
