0
代码
代码
Issues
Pull Requests
讨论
Wiki
分析
0
GGiteeupdate
edbd3174创建于 2025年2月25日历史提交

drawing_canvas.h

概述

文件中定义了与画布相关的功能函数。

画布自带一个黑色，开启抗锯齿，不具备其他任何样式的默认画刷，当且仅当画布中主动设置的画刷和画笔都不存在时生效。

非录制类型画布会将绘制指令直接绘制到绑定的位图中，录制类型画布会将绘制指令录制下来用于后续的回放。

引用文件：<native_drawing/drawing_canvas.h>

库： libnative_drawing.so

起始版本： 8

相关模块：Drawing

汇总

类型定义

名称 描述
typedef enum OH_Drawing_SrcRectConstraint OH_Drawing_SrcRectConstraint 源矩形区域约束类型枚举。
typedef enum OH_Drawing_PointMode OH_Drawing_PointMode 绘制多个点的方式枚举，方式分为离散点、直线或开放多边形。
typedef enum OH_Drawing_VertexMode OH_Drawing_VertexMode 用于指定如何解释给定顶点的几何形状的枚举类型。
typedef enum OH_Drawing_CanvasClipOp OH_Drawing_CanvasClipOp 画布裁剪方式的枚举集合。
typedef enum OH_Drawing_CanvasShadowFlags OH_Drawing_CanvasShadowFlags 阴影标志枚举。

枚举

名称 描述
OH_Drawing_SrcRectConstraint { STRICT_SRC_RECT_CONSTRAINT, FAST_SRC_RECT_CONSTRAINT } 源矩形区域约束类型枚举。
OH_Drawing_PointMode { POINT_MODE_POINTS, POINT_MODE_LINES, POINT_MODE_POLYGON } 绘制多个点的方式枚举，方式分为离散点、直线或开放多边形。
OH_Drawing_VertexMode { VERTEX_MODE_TRIANGLES, VERTEX_MODE_TRIANGLESSTRIP, VERTEX_MODE_TRIANGLEFAN } 用于指定如何解释给定顶点的几何形状的枚举类型。
OH_Drawing_CanvasClipOp { DIFFERENCE, INTERSECT } 画布裁剪方式的枚举集合。
OH_Drawing_CanvasShadowFlags { SHADOW_FLAGS_NONE, SHADOW_FLAGS_TRANSPARENT_OCCLUDER, SHADOW_FLAGS_GEOMETRIC_ONLY, SHADOW_FLAGS_ALL } 阴影标志枚举。

函数

名称 描述
OH_Drawing_Canvas * OH_Drawing_CanvasCreate (void) 用于创建一个画布对象。
void OH_Drawing_CanvasDestroy (OH_Drawing_Canvas *) 用于销毁画布对象并回收该对象占有的内存。
void OH_Drawing_CanvasBind (OH_Drawing_Canvas *, OH_Drawing_Bitmap *) 用于将一个位图对象绑定到画布中，使得画布绘制的内容输出到位图中（即CPU渲染）。绑定位图对象后的画布为非录制类型画布。
void OH_Drawing_CanvasAttachPen (OH_Drawing_Canvas *, const OH_Drawing_Pen *) 用于设置画笔给画布，画布将会使用设置画笔的样式和颜色去绘制图形形状的轮廓。执行该方法后，若画笔的效果发生改变并且开发者希望该变化生效于接下来的绘制动作，需要再次执行该方法以确保变化生效。
void OH_Drawing_CanvasDetachPen (OH_Drawing_Canvas *) 用于去除掉画布中的画笔，使用后画布将不去绘制图形形状的轮廓。
void OH_Drawing_CanvasAttachBrush (OH_Drawing_Canvas *, const OH_Drawing_Brush *) 用于设置画刷给画布，画布将会使用设置的画刷样式和颜色去填充绘制的图形形状。执行该方法后，若画刷的效果发生改变并且开发者希望该变化生效于接下来的绘制动作，需要再次执行该方法以确保变化生效。
void OH_Drawing_CanvasDetachBrush (OH_Drawing_Canvas *) 用于去除掉画布中的画刷，使用后画布将不使用此前设置的画刷去填充图形形状。
void OH_Drawing_CanvasSave (OH_Drawing_Canvas *) 用于保存当前画布的状态（画布矩阵）到一个栈顶。需要与恢复接口OH_Drawing_CanvasRestore配合使用。
void OH_Drawing_CanvasSaveLayer (OH_Drawing_Canvas *, const OH_Drawing_Rect *, const OH_Drawing_Brush *) 保存矩阵和裁剪区域，为后续绘制分配位图。调用恢复接口。 OH_Drawing_CanvasRestore将放弃对矩阵和剪切区域所做的更改，并绘制位图。
void OH_Drawing_CanvasRestore (OH_Drawing_Canvas *) 用于恢复保存在栈顶的画布状态（画布矩阵）。
uint32_t OH_Drawing_CanvasGetSaveCount (OH_Drawing_Canvas *) 用于获取栈中保存的画布状态（画布矩阵）的数量。
void OH_Drawing_CanvasRestoreToCount (OH_Drawing_Canvas *, uint32_t saveCount) 用于恢复到指定数量的画布状态（画布矩阵）。
void OH_Drawing_CanvasDrawLine (OH_Drawing_Canvas *, float x1, float y1, float x2, float y2) 用于画一条直线段。
void OH_Drawing_CanvasDrawPath (OH_Drawing_Canvas *, const OH_Drawing_Path *) 用于画一个自定义路径。
void OH_Drawing_CanvasDrawPixelMapRect (OH_Drawing_Canvas *, OH_Drawing_PixelMap *, const OH_Drawing_Rect *src, const OH_Drawing_Rect *dst, const OH_Drawing_SamplingOptions *) 用于将像素图的指定区域绘制到画布的指定区域。
void OH_Drawing_CanvasDrawBackground (OH_Drawing_Canvas *, const OH_Drawing_Brush *) 用于画一个背景，此背景以画刷填充。
void OH_Drawing_CanvasDrawRegion (OH_Drawing_Canvas *, const OH_Drawing_Region *) 用于画一块区域。
OH_Drawing_ErrorCode OH_Drawing_CanvasDrawPoint (OH_Drawing_Canvas *canvas, const OH_Drawing_Point2D *point) 用于画一个点。
void OH_Drawing_CanvasDrawPoints (OH_Drawing_Canvas *, OH_Drawing_PointMode mode, uint32_t count, const OH_Drawing_Point2D *) 用于画多个点，绘制方式分为绘制单独的点、绘制成线段或绘制成开放多边形。
void OH_Drawing_CanvasDrawBitmap (OH_Drawing_Canvas *, const OH_Drawing_Bitmap *, float left, float top) 用于画一个位图，位图又称为点阵图像、像素图或栅格图像，是由像素（图片元素）的单个点组成。
void OH_Drawing_CanvasDrawBitmapRect (OH_Drawing_Canvas *, const OH_Drawing_Bitmap *, const OH_Drawing_Rect *src, const OH_Drawing_Rect *dst, const OH_Drawing_SamplingOptions *) 将位图的指定区域绘制到画布的指定区域。
void OH_Drawing_CanvasSetMatrix (OH_Drawing_Canvas *, OH_Drawing_Matrix *) 设置画布的矩阵状态。
void OH_Drawing_CanvasResetMatrix (OH_Drawing_Canvas *) 重置当前画布的矩阵为单位矩阵。
void OH_Drawing_CanvasDrawImageRectWithSrc (OH_Drawing_Canvas *, const OH_Drawing_Image *, const OH_Drawing_Rect *src, const OH_Drawing_Rect *dst, const OH_Drawing_SamplingOptions *, OH_Drawing_SrcRectConstraint) 将图片绘制到画布的指定区域上，源矩形选定的区域会缩放平移到目标矩形。
void OH_Drawing_CanvasDrawImageRect (OH_Drawing_Canvas *, OH_Drawing_Image *, OH_Drawing_Rect *dst, OH_Drawing_SamplingOptions *) 将图片绘制到画布的指定区域上。
void OH_Drawing_CanvasDrawVertices (OH_Drawing_Canvas *, OH_Drawing_VertexMode vertexMmode, int32_t vertexCount, const OH_Drawing_Point2D *positions, const OH_Drawing_Point2D *texs, const uint32_t *colors, int32_t indexCount, const uint16_t *indices, OH_Drawing_BlendMode mode) 用于画顶点数组描述的三角网格。
bool OH_Drawing_CanvasReadPixels (OH_Drawing_Canvas *, OH_Drawing_Image_Info *, void *dstPixels, uint32_t dstRowBytes, int32_t srcX, int32_t srcY) 从画布中拷贝像素数据到指定地址。该接口不可用于录制类型画布。
bool OH_Drawing_CanvasReadPixelsToBitmap (OH_Drawing_Canvas *, OH_Drawing_Bitmap *, int32_t srcX, int32_t srcY) 从画布拷贝像素数据到位图中。该接口不可用于录制类型画布。
OH_Drawing_ErrorCode OH_Drawing_CanvasIsClipEmpty (OH_Drawing_Canvas *canvas, bool *isClipEmpty) 用于判断裁剪后可绘制区域是否为空。
OH_Drawing_ErrorCode OH_Drawing_CanvasGetImageInfo (OH_Drawing_Canvas *canvas, OH_Drawing_Image_Info *imageInfo) 用于获取画布的图像信息。
void OH_Drawing_CanvasDrawRect (OH_Drawing_Canvas *, const OH_Drawing_Rect *) 用于画一个矩形。
void OH_Drawing_CanvasDrawCircle (OH_Drawing_Canvas *, const OH_Drawing_Point *, float radius) 用于画一个圆形。
OH_Drawing_ErrorCode OH_Drawing_CanvasDrawColor (OH_Drawing_Canvas *canvas, uint32_t color, OH_Drawing_BlendMode blendMode) 用于使用指定的颜色及混合模式来填充整个画布。
void OH_Drawing_CanvasDrawOval (OH_Drawing_Canvas *, const OH_Drawing_Rect *) 用于画一个椭圆。
void OH_Drawing_CanvasDrawArc (OH_Drawing_Canvas *, const OH_Drawing_Rect *, float startAngle, float sweepAngle) 用于画一个弧。当扫描角度的绝对值大于360度时，本接口绘制的是一个椭圆。
OH_Drawing_ErrorCode OH_Drawing_CanvasDrawArcWithCenter (OH_Drawing_Canvas *canvas, const OH_Drawing_Rect *rect, float startAngle, float sweepAngle, bool useCenter) 绘制一段圆弧。该方法允许指定圆弧的起始角度、扫描角度以及圆弧的起点和终点是否连接圆弧的中心点。
void OH_Drawing_CanvasDrawRoundRect (OH_Drawing_Canvas *, const OH_Drawing_RoundRect *) 用于画一个圆角矩形。
OH_Drawing_ErrorCode OH_Drawing_CanvasDrawNestedRoundRect (OH_Drawing_Canvas *canvas, const OH_Drawing_RoundRect *outer, const OH_Drawing_RoundRect *inner) 绘制两个嵌套的圆角矩形，外部矩形边界必须包含内部矩形边界，否则无绘制效果。
OH_Drawing_ErrorCode OH_Drawing_CanvasDrawSingleCharacter (OH_Drawing_Canvas *canvas, const char *str, const OH_Drawing_Font *font, float x, float y) 用于绘制单个字符。当前字型中的字体不支持待绘制字符时，退化到使用系统字体绘制字符。
void OH_Drawing_CanvasDrawTextBlob (OH_Drawing_Canvas *, const OH_Drawing_TextBlob *, float x, float y) 用于画一段文字。若构造OH_Drawing_TextBlob的字体不支持待绘制字符，则该部分字符无法绘制。
enum OH_Drawing_CanvasShadowFlags { SHADOW_FLAGS_NONE, SHADOW_FLAGS_TRANSPARENT_OCCLUDER, SHADOW_FLAGS_GEOMETRIC_ONLY, SHADOW_FLAGS_ALL } 阴影标志枚举。
typedef enum OH_Drawing_CanvasShadowFlags OH_Drawing_CanvasShadowFlags 阴影标志枚举。
void OH_Drawing_CanvasClipRect (OH_Drawing_Canvas *, const OH_Drawing_Rect *, OH_Drawing_CanvasClipOp clipOp, bool doAntiAlias) 用于裁剪一个矩形。
void OH_Drawing_CanvasClipRoundRect (OH_Drawing_Canvas *, const OH_Drawing_RoundRect *, OH_Drawing_CanvasClipOp clipOp, bool doAntiAlias) 用于裁剪一个圆角矩形。
void OH_Drawing_CanvasClipPath (OH_Drawing_Canvas *, const OH_Drawing_Path *, OH_Drawing_CanvasClipOp clipOp, bool doAntiAlias) 用于裁剪一个自定义路径。
OH_Drawing_ErrorCode OH_Drawing_CanvasClipRegion (OH_Drawing_Canvas *canvas, const OH_Drawing_Region *region, OH_Drawing_CanvasClipOp clipOp) 用于裁剪一个区域。
void OH_Drawing_CanvasRotate (OH_Drawing_Canvas *, float degrees, float px, float py) 用于画布旋转一定的角度，正数表示顺时针旋转，负数反之。
void OH_Drawing_CanvasTranslate (OH_Drawing_Canvas *, float dx, float dy) 用于平移画布一段距离。
void OH_Drawing_CanvasScale (OH_Drawing_Canvas *, float sx, float sy) 用于画布缩放。
void OH_Drawing_CanvasSkew (OH_Drawing_Canvas *, float sx, float sy) 用于画布倾斜变换。等同于将当前画布矩阵左乘（premultiply）倾斜变换矩阵，并应用到画布上。其中倾斜变换矩阵为： |1 sx 0| |sy 1 0| |0 0 1|。
void OH_Drawing_CanvasClear (OH_Drawing_Canvas *, uint32_t color) 用于使用指定颜色去清空画布。
int32_t OH_Drawing_CanvasGetWidth (OH_Drawing_Canvas *) 获取画布宽度。
int32_t OH_Drawing_CanvasGetHeight (OH_Drawing_Canvas *) 获取画布高度。
void OH_Drawing_CanvasGetLocalClipBounds (OH_Drawing_Canvas *, OH_Drawing_Rect *) 获取画布裁剪区域的边界。该接口不可用于录制类型画布。
void OH_Drawing_CanvasGetTotalMatrix (OH_Drawing_Canvas *, OH_Drawing_Matrix *) 获取画布3x3矩阵。
void OH_Drawing_CanvasConcatMatrix (OH_Drawing_Canvas *, OH_Drawing_Matrix *) 画布现有矩阵左乘以传入矩阵，不影响该接口之前的绘制操作。
void OH_Drawing_CanvasDrawShadow (OH_Drawing_Canvas *, OH_Drawing_Path *, OH_Drawing_Point3D planeParams, OH_Drawing_Point3D devLightPos, float lightRadius, uint32_t ambientColor, uint32_t spotColor, OH_Drawing_CanvasShadowFlags flag) 绘制射灯类型阴影，使用路径描述环境光阴影的轮廓。
OH_Drawing_ErrorCode OH_Drawing_CanvasDrawRecordCmd (OH_Drawing_Canvas *canvas, OH_Drawing_RecordCmd *recordCmd) 用于绘制录制指令对象。
OH_Drawing_ErrorCode OH_Drawing_CanvasQuickRejectPath (OH_Drawing_Canvas *canvas, const OH_Drawing_Path *path, bool *quickReject) 判断路径与画布区域是否不相交。画布区域包含边界。
OH_Drawing_ErrorCode OH_Drawing_CanvasQuickRejectRect (OH_Drawing_Canvas *canvas, const OH_Drawing_Rect *rect, bool *quickReject) 判断矩形和画布区域是否不相交。画布区域包含边界。
OH_Drawing_ErrorCode OH_Drawing_CanvasDrawPixelMapNine (OH_Drawing_Canvas *canvas, OH_Drawing_PixelMap *pixelMap, const OH_Drawing_Rect *center, const OH_Drawing_Rect *dst, OH_Drawing_FilterMode mode) 通过绘制两条水平线和两条垂直线将像素图分割成9个部分：四个边，四个角和中心。 若角落的4个区域尺寸不超过目标矩形，则会在不缩放的情况下被绘制在目标矩形，反之则会按比例缩放绘制在目标矩形。 如果还有剩余空间，剩下的5个区域会通过拉伸或压缩来绘制，以便能够完全覆盖目标矩形。