Basic Drawing Effects (C/C++)

Overview

You can set some basic effects, such as the fill color, anti-aliasing, stroke, and line connection style.

You can set the basic fill effect using a brush and set the basic stroke effect using a pen.

Fill Effect

You can set the basic fill color using a brush and use the brush to implement more complex drawing effects, such as the blend mode, shader effect, and filter effect. For details, see Complex Drawing Effects.

Available APIs

The following table lists the APIs for setting the drawing effect using a brush. For details, see drawing_brush.

API	Description
OH_Drawing_Brush* OH_Drawing_BrushCreate (void)	Creates a brush object.
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.
void OH_Drawing_BrushSetColor (OH_Drawing_Brush* , uint32_t color)	Sets the color for a brush. The color is used by the brush to fill in a shape.
void OH_Drawing_BrushSetAntiAlias (OH_Drawing_Brush* , bool)	Enables or disables anti-aliasing for a brush. Anti-aliasing makes the pixels around the shape edges semi-transparent, delivering a smoother effect.
void OH_Drawing_CanvasDetachBrush (OH_Drawing_Canvas*)	Removes the brush from the canvas. After the execution, the canvas does not use the previously set brush and restores to the default fill effect.
void OH_Drawing_BrushDestroy (OH_Drawing_Brush*)	Destroys a brush object and reclaims the memory occupied by the object.

How to Develop

1. Call OH_Drawing_BrushCreate() to create a brush object.

   // Create a brush object.
   OH_Drawing_Brush* brush = OH_Drawing_BrushCreate();
   

   sample_graphics.cpp

2. (Optional) Use the brush to set the basic drawing effect. You can select one or more of the following effects:

   • You can call OH_Drawing_BrushSetColor() to set the fill color.

     // Set the fill color to red.
     uint32_t color = 0xffff0000;
     OH_Drawing_BrushSetColor(brush, color);
     

     sample_graphics.cpp

     color is a 32-bit (ARGB) variable, for example, 0xffff0000.

   • You can call OH_Drawing_BrushSetAntiAlias() to enable the anti-aliasing effect to smooth the edges of the graphics.

     // Enable the anti-aliasing effect.
     OH_Drawing_BrushSetAntiAlias(brush, true);
     

     sample_graphics.cpp

3. Call OH_Drawing_CanvasAttachBrush() to set a brush for the canvas. This API takes two parameters: (1) Canvas object, which must be created or obtained. For details, see Obtaining a Canvas and Displaying Drawing Results (C/C++); (2) brush object to be set. The canvas uses the brush style and color to fill the shape.

   // Set the brush of the canvas.
   OH_Drawing_CanvasAttachBrush(canvas, brush);
   

   sample_graphics.cpp

4. Draw primitives as required. For details, see Drawing Primitives.

5. If no fill effect is required, you can use OH_Drawing_CanvasDetachBrush() to remove the brush. The input parameter is the Canvas object.

   // Remove the brush from the canvas.
   OH_Drawing_CanvasDetachBrush(canvas);
   

   sample_graphics.cpp

6. When the brush is no longer needed, destroy the brush object using OH_Drawing_BrushDestroy().

   // Destroy objects.
   OH_Drawing_BrushDestroy(brush);
   

   sample_graphics.cpp

Stroke Effect

You can set the basic stroke color using a pen and use the pen to implement more complex drawing effects, such as the blend mode, path effect, shader effect, and filter effect. For details, see Complex Drawing Effects.

Available APIs

The following table lists the APIs for setting the drawing effect using a pen. For details, see drawing_pen.

API	Description
OH_Drawing_Pen* OH_Drawing_PenCreate (void)	Creates a pen object.
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.
void OH_Drawing_PenSetColor (OH_Drawing_Pen* , uint32_t color)	Sets the color for a pen. The color is used by the pen to outline a shape.
void OH_Drawing_PenSetWidth (OH_Drawing_Pen* , float width)	Sets the width for a pen. The value 0 is treated as an unusually thin width. During drawing, the width of 0 is always drawn as 1 pixel wide, regardless of any scaling applied to the canvas. Negative values are also regarded as the value 0 during the drawing process.
void OH_Drawing_PenSetAntiAlias (OH_Drawing_Pen* , bool )	Enables or disables anti-aliasing for a pen. Anti-aliasing makes the pixels around the shape edges semi-transparent.
void OH_Drawing_PenSetCap (OH_Drawing_Pen* , OH_Drawing_PenLineCapStyle)	Sets the line cap style for a pen.
void OH_Drawing_PenSetJoin (OH_Drawing_Pen* , OH_Drawing_PenLineJoinStyle)	Sets the line join style for a pen.
void OH_Drawing_CanvasDetachPen (OH_Drawing_Canvas*)	Removes the brush from the canvas. After the execution, the canvas does not outline the shape and restores to the default fill effect.
void OH_Drawing_PenDestroy (OH_Drawing_Pen*)	Destroys a pen object and reclaims the memory occupied by the object.

How to Develop

1. Call OH_Drawing_PenCreate() to create a pen object.

   // Create a pen object.
   OH_Drawing_Pen* pen = OH_Drawing_PenCreate();
   

   sample_graphics.cpp

2. Call OH_Drawing_CanvasAttachPen() to set a pen for the canvas. This API takes two parameters: (1) Canvas object, which must be created or obtained. For details, see Obtaining a Canvas and Displaying Drawing Results (C/C++); (2) pen object to be set. The canvas uses the pen style and color to draw the outline.

   // Set the pen of the canvas.
   OH_Drawing_CanvasAttachPen(canvas, pen);
   

   sample_graphics.cpp

3. (Optional) Use the pen to set the stroke effect. You can select one or more of the following effects:

   • You can call OH_Drawing_PenSetColor() to set the pen color, which is used to outline a shape.

     // Set the pen color to red.
     uint32_t color = 0xffff0000;
     OH_Drawing_PenSetColor(pen, color);
     

     sample_graphics.cpp

     color is a 32-bit (ARGB) variable, for example, 0xffff0000.

   • You can call OH_Drawing_PenSetWidth() to set the pen width.

     // Set the pen width to 50 pixels.
     float width = 50.0;
     OH_Drawing_PenSetWidth(pen, width);
     

     sample_graphics.cpp

     width indicates the pixel value of the pen width.

   • You can call OH_Drawing_PenSetAntiAlias() to set anti-aliasing for the pen to make the drawing edge smoother.

     // Set anti-aliasing for the pen.
     OH_Drawing_PenSetAntiAlias(pen, true);
     

     sample_graphics.cpp

   • You can call OH_Drawing_PenSetCap() to set the pen cap style.

     // Set the pen cap style.
     OH_Drawing_PenSetCap(pen, OH_Drawing_PenLineCapStyle::LINE_ROUND_CAP);
     

     sample_graphics.cpp

     The options of OH_Drawing_PenLineCapStyle are as follows.

     Line Cap Style	Description	Effect
     LINE_FLAT_CAP	No cap style. Both ends of the line segment are cut off square.
     LINE_SQUARE_CAP	Square cap style. Both ends have a square, the height of which is half of the width of the line segment, with the same width.
     LINE_ROUND_CAP	Round cap style. Both ends have a semicircle centered, the diameter of which is the same as the width of the line segment.

   • You can call OH_Drawing_PenSetJoin() to set the pen join style.

     // Set the pen join style.
     OH_Drawing_PenSetJoin(pen, OH_Drawing_PenLineJoinStyle::LINE_BEVEL_JOIN);
     

     sample_graphics.cpp

     The options of OH_Drawing_PenLineJoinStyle are as follows.

     Line Join Style	Description	Effect
     LINE_MITER_JOIN	Miter join.
     LINE_ROUND_JOIN	Round join.
     LINE_BEVEL_JOIN	Beveled join.

4. Draw primitives as required. For details, see Drawing Primitives.

5. If no stroke effect is required, you can use OH_Drawing_CanvasDetachPen() to remove the brush. The input parameter is the Canvas object. Ensure that the canvas has been created or obtained. For details, see Obtaining a Canvas and Displaying Drawing Results (C/C++).

   // Remove the pen from the canvas.
   OH_Drawing_CanvasDetachPen(canvas);
   

   sample_graphics.cpp

6. When the pen is no longer needed for stroke, destroy the pen object using OH_Drawing_PenDestroy().

   // Destroy objects.
   OH_Drawing_PenDestroy(pen);
   

   sample_graphics.cpp

Samples

The following samples are provided to help you better understand how to use the Drawing APIs (C/C++) for development:

• NDKGraphicsDraw (API20)