harmony 鸿蒙drawing_canvas.h

2025-06-12
浏览 (4)

drawing_canvas.h

Overview

The drawing_canvas.h file declares the functions related to the canvas in the drawing module.

By default, the canvas has a black brush with anti-aliasing enabled and without any other style. This brush takes effect only when no brush or pen is proactively set in the canvas.

Canvases that are not set for recording will immediately draw the commands onto the bound bitmap, whereas canvases designated for recording will store the drawing commands for future replay.

File to include: <native_drawing/drawing_canvas.h>

Library: libnative_drawing.so

Since: 8

Related module: Drawing

Summary

Types

Name	Description
typedef enum OH_Drawing_SrcRectConstraint OH_Drawing_SrcRectConstraint	Defines an enum for the constraint types of the source rectangle.
typedef enum OH_Drawing_PointMode OH_Drawing_PointMode	Defines an enum for the modes of drawing multiple points. The modes include discrete points, line segments, and open polygons.
typedef enum OH_Drawing_VertexMode OH_Drawing_VertexMode	Defines an enum for the modes of interpreting the geometry of a given vertex.
typedef enum OH_Drawing_CanvasClipOp OH_Drawing_CanvasClipOp	Defines an enum for the canvas clipping modes.
typedef enum OH_Drawing_CanvasShadowFlags OH_Drawing_CanvasShadowFlags	Defines an enum for the canvas shadow flags.

Enums

Name	Description
OH_Drawing_SrcRectConstraint { STRICT_SRC_RECT_CONSTRAINT, FAST_SRC_RECT_CONSTRAINT }	Enumerates the constraint types of the source rectangle.
OH_Drawing_PointMode { POINT_MODE_POINTS, POINT_MODE_LINES, POINT_MODE_POLYGON }	Enumerates the modes of drawing multiple points. The modes include discrete points, line segments, and open polygons.
OH_Drawing_VertexMode { VERTEX_MODE_TRIANGLES, VERTEX_MODE_TRIANGLESSTRIP, VERTEX_MODE_TRIANGLEFAN }	Enumerates the modes of interpreting the geometry of a given vertex.
OH_Drawing_CanvasClipOp { DIFFERENCE, INTERSECT }	Enumerates the canvas clipping modes.
OH_Drawing_CanvasShadowFlags { SHADOW_FLAGS_NONE, SHADOW_FLAGS_TRANSPARENT_OCCLUDER, SHADOW_FLAGS_GEOMETRIC_ONLY, SHADOW_FLAGS_ALL }	Enumerates the canvas shadow flags.

Functions

Name	Description
OH_Drawing_Canvas * OH_Drawing_CanvasCreate (void)	Creates an OH_Drawing_Canvas object.
void OH_Drawing_CanvasDestroy (OH_Drawing_Canvas *)	Destroys an OH_Drawing_Canvas object and reclaims the memory occupied by the object.
void OH_Drawing_CanvasBind (OH_Drawing_Canvas , OH_Drawing_Bitmap )	Binds a bitmap to a canvas so that the content drawn on the canvas is output to the bitmap. (This process is called CPU rendering.) A canvas bound to a bitmap is a non-recording canvas.
void OH_Drawing_CanvasAttachPen (OH_Drawing_Canvas , const OH_Drawing_Pen )	Attaches a pen to a canvas so that the canvas can use the style and color of the pen to outline a shape. If the pen effect changes after this function is called, you must call the function again to use the new effect in the subsequent drawing.
void OH_Drawing_CanvasDetachPen (OH_Drawing_Canvas *)	Detaches the pen from a canvas so that the canvas can no longer use the style and color of the pen to outline a shape.
void OH_Drawing_CanvasAttachBrush (OH_Drawing_Canvas , const OH_Drawing_Brush )	Attaches a brush to a canvas so that the canvas can use the style and color of the brush to fill in a shape. If the brush effect changes after this function is called, you must call the function again to use the new effect in the subsequent drawing.
void OH_Drawing_CanvasDetachBrush (OH_Drawing_Canvas *)	Detaches the brush from a canvas so that the canvas can no longer use the previously set brush to fill in a shape.
void OH_Drawing_CanvasSave (OH_Drawing_Canvas *)	Saves the current canvas status (canvas matrix) to the top of the stack. This function must be used in pair with OH_Drawing_CanvasRestore.
void OH_Drawing_CanvasSaveLayer (OH_Drawing_Canvas , const OH_Drawing_Rect , const OH_Drawing_Brush *)	Saves the matrix and cropping region, and allocates a bitmap for subsequent drawing. If you call OH_Drawing_CanvasRestore, changes made to the matrix and clipping region are discarded, and the bitmap is drawn.
void OH_Drawing_CanvasRestore (OH_Drawing_Canvas *)	Restores the canvas status (canvas matrix) saved on the top of the stack.
uint32_t OH_Drawing_CanvasGetSaveCount (OH_Drawing_Canvas *)	Obtains the number of canvas statuses (canvas matrices) saved in the stack.
void OH_Drawing_CanvasRestoreToCount (OH_Drawing_Canvas *, uint32_t saveCount)	Restores to a given number of canvas statuses (canvas matrices).
void OH_Drawing_CanvasDrawLine (OH_Drawing_Canvas *, float x1, float y1, float x2, float y2)	Draws a line segment.
void OH_Drawing_CanvasDrawPath (OH_Drawing_Canvas , const OH_Drawing_Path )	Draws a 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 *)	Draws a portion of a pixel map onto a specified area of the canvas.
void OH_Drawing_CanvasDrawBackground (OH_Drawing_Canvas , const OH_Drawing_Brush )	Draws a background filled with a brush.
void OH_Drawing_CanvasDrawRegion (OH_Drawing_Canvas , const OH_Drawing_Region )	Draws a region.
OH_Drawing_ErrorCode OH_Drawing_CanvasDrawPoint (OH_Drawing_Canvas canvas, const OH_Drawing_Point2D point)	Draws a point.
void OH_Drawing_CanvasDrawPoints (OH_Drawing_Canvas , OH_Drawing_PointMode mode, uint32_t count, const OH_Drawing_Point2D )	Draws multiple points. You can draw a single point, a line segment, or an open polygon.
void OH_Drawing_CanvasDrawBitmap (OH_Drawing_Canvas , const OH_Drawing_Bitmap , float left, float top)	Draws a bitmap. A bitmap, also referred to as a dot matrix image, a pixel map image, or a grid image, includes single points called pixels (image elements).
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 *)	Draws a portion of a bitmap onto a specified area of the canvas.
void OH_Drawing_CanvasSetMatrix (OH_Drawing_Canvas , OH_Drawing_Matrix )	Sets the matrix status for a canvas.
void OH_Drawing_CanvasResetMatrix (OH_Drawing_Canvas *)	Resets the matrix of a canvas to an identity matrix.
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)	Draws a portion of an image onto a specified area of the canvas. The area selected by the source rectangle is scaled and translated to the destination rectangle.
void OH_Drawing_CanvasDrawImageRect (OH_Drawing_Canvas , OH_Drawing_Image , OH_Drawing_Rect dst, OH_Drawing_SamplingOptions )	Draws an image onto a specified area of the canvas.
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)	Draws a triangular grid described by a vertex array.
bool OH_Drawing_CanvasReadPixels (OH_Drawing_Canvas , OH_Drawing_Image_Info , void *dstPixels, uint32_t dstRowBytes, int32_t srcX, int32_t srcY)	Copies pixel data from a canvas to a specified address. This function cannot be used for recorded canvases.
bool OH_Drawing_CanvasReadPixelsToBitmap (OH_Drawing_Canvas , OH_Drawing_Bitmap , int32_t srcX, int32_t srcY)	Copies pixel data from a canvas to an image. This function cannot be used for recorded canvases.
OH_Drawing_ErrorCode OH_Drawing_CanvasIsClipEmpty (OH_Drawing_Canvas canvas, bool isClipEmpty)	Checks whether the region that can be drawn is empty after cropping.
OH_Drawing_ErrorCode OH_Drawing_CanvasGetImageInfo (OH_Drawing_Canvas canvas, OH_Drawing_Image_Info imageInfo)	Obtains the image information of a canvas.
void OH_Drawing_CanvasDrawRect (OH_Drawing_Canvas , const OH_Drawing_Rect )	Draws a rectangle.
void OH_Drawing_CanvasDrawCircle (OH_Drawing_Canvas , const OH_Drawing_Point , float radius)	Draws a circle.
OH_Drawing_ErrorCode OH_Drawing_CanvasDrawColor (OH_Drawing_Canvas *canvas, uint32_t color, OH_Drawing_BlendMode blendMode)	Fills the entire canvas with the specified color and blend mode.
void OH_Drawing_CanvasDrawOval (OH_Drawing_Canvas , const OH_Drawing_Rect )	Draws an oval.
void OH_Drawing_CanvasDrawArc (OH_Drawing_Canvas , const OH_Drawing_Rect , float startAngle, float sweepAngle)	Draws an arc. If the absolute value of the sweep angle exceeds 360 degrees, an ellipse is drawn.
OH_Drawing_ErrorCode OH_Drawing_CanvasDrawArcWithCenter (OH_Drawing_Canvas canvas, const OH_Drawing_Rect rect, float startAngle, float sweepAngle, bool useCenter)	Draws an arc. It enables you to define the starting angle, the sweep angle, and whether the arc’s endpoints should connect to its center.
void OH_Drawing_CanvasDrawRoundRect (OH_Drawing_Canvas , const OH_Drawing_RoundRect )	Draws a rounded rectangle.
OH_Drawing_ErrorCode OH_Drawing_CanvasDrawNestedRoundRect (OH_Drawing_Canvas canvas, const OH_Drawing_RoundRect outer, const OH_Drawing_RoundRect *inner)	Draws two nested rounded rectangles. The outer rectangle boundary must contain the inner rectangle boundary. Otherwise, there is no drawing effect.
OH_Drawing_ErrorCode OH_Drawing_CanvasDrawSingleCharacter (OH_Drawing_Canvas canvas, const char str, const OH_Drawing_Font *font, float x, float y)	Draws a single character. If the typeface of the current font does not support the character to draw, the system typeface is used to draw the character.
void OH_Drawing_CanvasDrawTextBlob (OH_Drawing_Canvas , const OH_Drawing_TextBlob , float x, float y)	Draws a TextBlob. If the typeface used to construct OH_Drawing_TextBlob does not support a character, that character will not be drawn.
enum OH_Drawing_CanvasShadowFlags { SHADOW_FLAGS_NONE, SHADOW_FLAGS_TRANSPARENT_OCCLUDER, SHADOW_FLAGS_GEOMETRIC_ONLY, SHADOW_FLAGS_ALL }	Enumerates the canvas shadow flags.
typedef enum OH_Drawing_CanvasShadowFlags OH_Drawing_CanvasShadowFlags	Defines an enum for the canvas shadow flags.
void OH_Drawing_CanvasClipRect (OH_Drawing_Canvas , const OH_Drawing_Rect , OH_Drawing_CanvasClipOp clipOp, bool doAntiAlias)	Clips a rectangle.
void OH_Drawing_CanvasClipRoundRect (OH_Drawing_Canvas , const OH_Drawing_RoundRect , OH_Drawing_CanvasClipOp clipOp, bool doAntiAlias)	Clips a rounded rectangle.
void OH_Drawing_CanvasClipPath (OH_Drawing_Canvas , const OH_Drawing_Path , OH_Drawing_CanvasClipOp clipOp, bool doAntiAlias)	Clips a path.
OH_Drawing_ErrorCode OH_Drawing_CanvasClipRegion (OH_Drawing_Canvas canvas, const OH_Drawing_Region region, OH_Drawing_CanvasClipOp clipOp)	Clips a rectangle.
void OH_Drawing_CanvasRotate (OH_Drawing_Canvas *, float degrees, float px, float py)	Rotates a canvas by a given angle. A positive number indicates a clockwise rotation, and a negative number indicates a counterclockwise rotation.
void OH_Drawing_CanvasTranslate (OH_Drawing_Canvas *, float dx, float dy)	Translates a canvas by a given distance.
void OH_Drawing_CanvasScale (OH_Drawing_Canvas *, float sx, float sy)	Scales a canvas.
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\|
void OH_Drawing_CanvasClear (OH_Drawing_Canvas *, uint32_t color)	Clears a canvas by using a given color.
int32_t OH_Drawing_CanvasGetWidth (OH_Drawing_Canvas *)	Obtains the canvas width.
int32_t OH_Drawing_CanvasGetHeight (OH_Drawing_Canvas *)	Obtains the canvas height.
void OH_Drawing_CanvasGetLocalClipBounds (OH_Drawing_Canvas , OH_Drawing_Rect )	Obtains the bounds of the cropping region of a canvas. This function cannot be used for recorded canvases.
void OH_Drawing_CanvasGetTotalMatrix (OH_Drawing_Canvas , OH_Drawing_Matrix )	Obtains the 3x3 matrix of a canvas.
void OH_Drawing_CanvasConcatMatrix (OH_Drawing_Canvas , OH_Drawing_Matrix )	Preconcats the existing matrix with the passed-in matrix. The drawing operation triggered before this function is called is not affected.
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)	Draws an offset spot shadow and uses a given path to outline the ambient shadow.
OH_Drawing_ErrorCode OH_Drawing_CanvasDrawRecordCmd (OH_Drawing_Canvas canvas, OH_Drawing_RecordCmd recordCmd)	Draws an OH_Drawing_RecordCmd object.
OH_Drawing_ErrorCode OH_Drawing_CanvasQuickRejectPath (OH_Drawing_Canvas canvas, const OH_Drawing_Path path, bool *quickReject)	Checks whether the path is not intersecting with the canvas area. The canvas area includes its boundaries.
OH_Drawing_ErrorCode OH_Drawing_CanvasQuickRejectRect (OH_Drawing_Canvas canvas, const OH_Drawing_Rect rect, bool *quickReject)	Checks whether the rectangle is not intersecting with the canvas area. The canvas area includes its boundaries.
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)	Splits a PixelMap into nine sections using two horizontal and two vertical lines: four edge sections, four corner sections, and a central section. If the four corner sections are smaller than the target rectangle, they will be drawn in the target rectangle without scaling. Otherwise, they will be scaled to fit the target rectangle. Any remaining space will be filled by stretching or compressing the other five sections to cover the entire target rectangle.