diff --git a/zh-cn/graphic/graphic_2d/native_drawing/drawing_brush.h b/zh-cn/graphic/graphic_2d/native_drawing/drawing_brush.h
index 1619d8df9..4859b5d27 100644
--- a/zh-cn/graphic/graphic_2d/native_drawing/drawing_brush.h
+++ b/zh-cn/graphic/graphic_2d/native_drawing/drawing_brush.h
@@ -25,7 +25,8 @@
/**
* @file drawing_brush.h
*
- * @brief This file declares the functions related to the brush in the drawing module.
+ * @brief 文件中定义了与画刷相关的功能函数。
+ *
本模块为单线程模型策略，需要调用方自行管理线程安全和上下文状态的切换。
*
* @kit ArkGraphics2D
* @library libnative_drawing.so
@@ -52,28 +53,34 @@ extern "C" {
typedef struct OH_NativeColorSpaceManager OH_NativeColorSpaceManager;
/**
- * @brief 用于创建一个画刷对象。
+ * @brief 用于创建一个画刷对象。调用本接口创建的画刷对象，
+ * 在使用完毕后必须调用{@link OH_Drawing_BrushDestroy}销毁并回收内存，否则会导致内存泄漏。
*
- * @return 函数会返回一个指针，指针指向创建的画刷对象。
+ * @return 函数会返回一个指针，指针指向创建的画刷对象。如果返回NULL，表示创建失败；可能的原因是可用内存不足。
* @since 8
* @version 1.0
*/
OH_Drawing_Brush* OH_Drawing_BrushCreate(void);
/**
- * @brief 创建一个画刷对象副本{@link OH_Drawing_Brush}，用于拷贝一个已有画刷对象。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * brush为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ * @brief 拷贝一个已有画刷对象，创建其画刷对象副本{@link OH_Drawing_Brush}。调用本接口创建的画刷对象，
+ * 在使用完毕后必须调用{@link OH_Drawing_BrushDestroy}销毁并回收内存，
+ * 否则会导致内存泄漏。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
brush为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param brush 指向画刷对象的指针。
- * @return 函数会返回一个指针，指针指向创建的画刷对象副本{@link OH_Drawing_Brush}。如果对象返回NULL，表示创建失败；可能的原因是可用内存为空，或者是brush为NULL。
+ * @return 函数会返回一个指针，指针指向创建的画刷对象副本{@link OH_Drawing_Brush}。如果返回NULL，表示创建失败；
+ * 可能的原因是可用内存不足，或者是brush为NULL。
* @since 12
* @version 1.0
*/
OH_Drawing_Brush* OH_Drawing_BrushCopy(OH_Drawing_Brush* brush);
/**
- * @brief 用于销毁画刷对象并回收该对象占有的内存。
+ * @brief 用于销毁画刷对象并回收该对象占用的内存。
+ * 应与{@link OH_Drawing_BrushCreate}或{@link OH_Drawing_BrushCopy}配对使用，对已创建或拷贝得到的画刷对象进行释放，
+ * 避免内存泄漏。
*
* @param brush 指向画刷对象的指针。
* @since 8
@@ -83,8 +90,8 @@ void OH_Drawing_BrushDestroy(OH_Drawing_Brush* brush);
/**
* @brief 用于获取画刷是否设置抗锯齿属性，如果为真则说明画刷会启用抗锯齿功能，在绘制图形时会对图形的边缘像素进行半透明的模糊处理。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * brush为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
brush为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param brush 指向画刷对象的指针。
* @return 函数返回画刷对象是否设置抗锯齿属性，返回真则设置了抗锯齿，返回假则没有设置抗锯齿。
@@ -95,8 +102,8 @@ bool OH_Drawing_BrushIsAntiAlias(const OH_Drawing_Brush* brush);
/**
* @brief 用于设置画刷的抗锯齿属性，设置为真则画刷在绘制图形时会对图形的边缘像素进行半透明的模糊处理。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * brush为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
brush为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param brush 指向画刷对象的指针。
* @param antiAlias 真为抗锯齿，假则不做抗锯齿处理。
@@ -107,11 +114,11 @@ void OH_Drawing_BrushSetAntiAlias(OH_Drawing_Brush* brush, bool antiAlias);
/**
* @brief 用于获取画刷的颜色属性，颜色属性描述了画刷填充图形时使用的颜色，用一个32位（ARGB）的变量表示。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * brush为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
brush为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param brush 指向画刷对象的指针。
- * @return 函数返回一个描述颜色的32位（ARGB）变量。
+ * @return 函数返回一个描述颜色的32位（ARGB）变量，各颜色通道取值范围为[0, 255]。
* @since 8
* @version 1.0
*/
@@ -119,23 +126,26 @@ uint32_t OH_Drawing_BrushGetColor(const OH_Drawing_Brush* brush);
/**
* @brief 用于设置画刷的颜色属性，颜色属性描述了画刷填充图形时使用的颜色，用一个32位（ARGB）的变量表示。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * brush为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ * 当需要色彩空间管理或高精度颜色表示时，建议优先使用{@link OH_Drawing_BrushSetColor4f}。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
brush为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param brush 指向画刷对象的指针。
- * @param color 描述颜色的32位（ARGB）变量。
+ * @param color 描述颜色的32位（ARGB）变量，各颜色通道取值范围为[0, 255]。
* @since 8
* @version 1.0
*/
void OH_Drawing_BrushSetColor(OH_Drawing_Brush* brush, uint32_t color);
/**
- * @brief 获取画刷的透明度值。画刷在填充形状时透明通道会使用该值。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * brush为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ * @brief 用于获取画刷的透明度值。画刷在填充形状时透明通道会使用该值。
+ * 当画刷颜色通过{@link OH_Drawing_BrushSetColor4f}设置时，建议使用
+ * {@link OH_Drawing_BrushGetAlphaFloat}获取透明度以避免精度丢失。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
brush为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
- * @param brush 表示指向画刷对象的指针。
- * @return 返回一个8位变量，用于表示透明度值。
+ * @param brush 指向画刷对象的指针。
+ * @return 返回一个8位无符号整数，用于表示透明度值，取值范围为[0, 255]，0表示完全透明，255表示完全不透明。
* @since 11
* @version 1.0
*/
@@ -143,30 +153,33 @@ uint8_t OH_Drawing_BrushGetAlpha(const OH_Drawing_Brush* brush);
/**
* @brief 为画刷设置透明度值。画刷在填充形状时透明通道会使用该值。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * brush为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
brush为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param brush 指向画刷对象的指针。
- * @param alpha 表示要设置的透明度值，是一个8位变量。
+ * @param alpha 表示要设置的透明度值，取值范围为[0, 255]的8位无符号整数，0表示完全透明，255表示完全不透明。
* @since 11
* @version 1.0
*/
void OH_Drawing_BrushSetAlpha(OH_Drawing_Brush* brush, uint8_t alpha);
/**
- * @brief 设置画刷的颜色。颜色将被画刷用来填充形状。
- * 颜色采用浮点数表示的ARGB格式，色彩空间由{@link OH_NativeColorSpaceManager}指定。
- * 如果colorSpaceManager为nullptr，使用SRGB（基于IEC 61966-2.1：1999的标准红绿蓝色彩空间）色彩空间作为默认值。
+ * @brief 设置画刷的颜色。画刷使用该颜色填充形状。
+ *
与{@link OH_Drawing_BrushSetColor}相比，本接口使用浮点数表示ARGB分量，精度更高，
+ * 并支持通过colorSpaceManager指定色彩空间；当需要色彩空间管理或高精度颜色表示时，
+ * 优先使用本接口。
+ *
颜色采用浮点数表示的ARGB格式，色彩空间由{@link OH_NativeColorSpaceManager}指定。
+ *
如果colorSpaceManager为NULL，使用sRGB（基于IEC 61966-2.1:1999的标准红绿蓝色彩空间）色彩空间作为默认值。
*
* @param brush 表示指向{@link OH_Drawing_Brush}对象的指针。
- * @param a 表示颜色中的透明度值，用0.0 ~ 1.0之间的浮点数表示，大于1.0时，取1.0，小于0.0时，取0.0。
- * @param r 表示颜色中的红色分量，用0.0 ~ 1.0之间的浮点数表示，大于1.0时，取1.0，小于0.0时，取0.0。
- * @param g 表示颜色中的绿色分量，用0.0 ~ 1.0之间的浮点数表示，大于1.0时，取1.0，小于0.0时，取0.0。
- * @param b 表示颜色中的蓝色分量，用0.0 ~ 1.0之间的浮点数表示，大于1.0时，取1.0，小于0.0时，取0.0。
+ * @param a 表示颜色中的透明度值，用[0.0, 1.0]之间的浮点数表示，大于1.0时，取1.0，小于0.0时，取0.0。
+ * @param r 表示颜色中的红色分量，用[0.0, 1.0]之间的浮点数表示，大于1.0时，取1.0，小于0.0时，取0.0。
+ * @param g 表示颜色中的绿色分量，用[0.0, 1.0]之间的浮点数表示，大于1.0时，取1.0，小于0.0时，取0.0。
+ * @param b 表示颜色中的蓝色分量，用[0.0, 1.0]之间的浮点数表示，大于1.0时，取1.0，小于0.0时，取0.0。
* @param colorSpaceManager 表示指向{@link OH_NativeColorSpaceManager}对象的指针。
* @return 函数返回执行结果。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数brush为NULL。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数brush为NULL。
* @since 20
* @version 1.0
*/
@@ -174,52 +187,60 @@ OH_Drawing_ErrorCode OH_Drawing_BrushSetColor4f(OH_Drawing_Brush* brush, float a
OH_NativeColorSpaceManager* colorSpaceManager);
/**
- * @brief 获取画刷颜色的透明度值。
+ * @brief 用于获取画刷颜色的透明度值，以浮点数形式表示。与{@link OH_Drawing_BrushGetAlpha}相比，
+ * 本接口返回浮点数表示的透明度，精度更高；当画刷颜色通过
+ * {@link OH_Drawing_BrushSetColor4f}设置时，应使用本接口获取透明度以避免精度丢失。
*
* @param brush 表示指向{@link OH_Drawing_Brush}对象的指针。
- * @param a 表示颜色的透明度，范围为0.0 ~ 1.0的浮点数。
+ * @param a 表示指向浮点数的指针，用于接收画刷颜色的透明度值，取值范围为[0.0, 1.0]。调用前需确保指针指向有效内存。
* @return 函数返回执行结果。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数brush或a为NULL。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数brush或a为NULL。
* @since 20
* @version 1.0
*/
OH_Drawing_ErrorCode OH_Drawing_BrushGetAlphaFloat(const OH_Drawing_Brush* brush, float* a);
/**
- * @brief 获取画刷颜色的红色分量。
+ * @brief 用于获取画刷颜色的红色分量，以浮点数形式表示。与{@link OH_Drawing_BrushGetColor}相比，
+ * 本接口以浮点数返回颜色分量，精度更高；当画刷颜色通过
+ * {@link OH_Drawing_BrushSetColor4f}设置时，应使用本接口获取红色分量以避免精度丢失。
*
* @param brush 表示指向{@link OH_Drawing_Brush}对象的指针。
- * @param r 表示颜色中的红色分量，范围为0.0 ~ 1.0的浮点数。
+ * @param r 表示指向浮点数的指针，用于接收画刷颜色的红色分量值，取值范围为[0.0, 1.0]。调用前需确保指针指向有效内存。
* @return 函数返回执行结果。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数brush或r为NULL。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数brush或r为NULL。
* @since 20
* @version 1.0
*/
OH_Drawing_ErrorCode OH_Drawing_BrushGetRedFloat(const OH_Drawing_Brush* brush, float* r);
/**
- * @brief 获取画刷颜色的绿色分量。
+ * @brief 用于获取画刷颜色的绿色分量，以浮点数形式表示。与{@link OH_Drawing_BrushGetColor}相比，
+ * 本接口以浮点数返回颜色分量，精度更高；当画刷颜色通过
+ * {@link OH_Drawing_BrushSetColor4f}设置时，应使用本接口获取绿色分量以避免精度丢失。
*
* @param brush 表示指向{@link OH_Drawing_Brush}对象的指针。
- * @param g 表示颜色中的绿色分量，范围为0.0 ~ 1.0的浮点数。
+ * @param g 表示指向浮点数的指针，用于接收画刷颜色的绿色分量值，取值范围为[0.0, 1.0]。调用前需确保指针指向有效内存。
* @return 函数返回执行结果。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数brush或g为NULL。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数brush或g为NULL。
* @since 20
* @version 1.0
*/
OH_Drawing_ErrorCode OH_Drawing_BrushGetGreenFloat(const OH_Drawing_Brush* brush, float* g);
/**
- * @brief 获取画刷颜色的蓝色分量。
+ * @brief 用于获取画刷颜色的蓝色分量，以浮点数形式表示。与{@link OH_Drawing_BrushGetColor}相比，
+ * 本接口以浮点数返回颜色分量，精度更高；当画刷颜色通过
+ * {@link OH_Drawing_BrushSetColor4f}设置时，应使用本接口获取蓝色分量以避免精度丢失。
*
* @param brush 表示指向{@link OH_Drawing_Brush}对象的指针。
- * @param b 表示颜色中的蓝色分量，范围为0.0 ~ 1.0的浮点数。
+ * @param b 表示指向浮点数的指针，用于接收画刷颜色的蓝色分量值，取值范围为[0.0, 1.0]。调用前需确保指针指向有效内存。
* @return 函数返回执行结果。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数brush或b为NULL。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数brush或b为NULL。
* @since 20
* @version 1.0
*/
@@ -227,8 +248,8 @@ OH_Drawing_ErrorCode OH_Drawing_BrushGetBlueFloat(const OH_Drawing_Brush* brush,
/**
* @brief 为画刷设置着色器效果。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * brush为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
brush为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param brush 指向画刷对象的指针。
* @param shaderEffect 表示指向着色器对象的指针，为NULL表示清空画刷的着色器效果。
@@ -239,8 +260,8 @@ void OH_Drawing_BrushSetShaderEffect(OH_Drawing_Brush* brush, OH_Drawing_ShaderE
/**
* @brief 为画刷设置阴影层，设置的阴影层效果当前仅在绘制文字时生效。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * brush为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
brush为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param brush 指向画刷对象的指针。
* @param shadowLayer 表示指向阴影层的指针，为NULL表示清空画刷的阴影层效果。
@@ -251,8 +272,8 @@ void OH_Drawing_BrushSetShadowLayer(OH_Drawing_Brush* brush, OH_Drawing_ShadowLa
/**
* @brief 为画刷设置滤波器{@link OH_Drawing_Filter}。滤波器是一个容器，可以承载蒙版滤波器和颜色滤波器。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * brush为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
brush为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param brush 指向画刷对象的指针。
* @param filter 表示指向滤波器对象的指针，为NULL表示清空画刷滤波器。
@@ -263,24 +284,26 @@ void OH_Drawing_BrushSetFilter(OH_Drawing_Brush* brush, OH_Drawing_Filter* filte
/**
* @brief 从画刷获取滤波器{@link OH_Drawing_Filter}。滤波器是一个容器，可以承载蒙版滤波器和颜色滤波器。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * brush、filter任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
brush、filter任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param brush 指向画刷对象{@link OH_Drawing_Brush}的指针。
- * @param filter 表示指向滤波器对象{@link OH_Drawing_Filter}的指针。
+ * @param filter 表示指向滤波器对象{@link OH_Drawing_Filter}的指针，用于接收从画刷中获取的滤波器。调用前需分配好内存，
+ * 由函数写入结果。
* @since 12
* @version 1.0
*/
void OH_Drawing_BrushGetFilter(OH_Drawing_Brush* brush, OH_Drawing_Filter* filter);
/**
- * @brief 为画刷设置一个混合器，该混合器实现了指定的混合模式枚举。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * brush为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER；
- * blendMode不在枚举范围内时返回OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE。
+ * @brief 为画刷设置混合模式，通过指定的混合模式枚举决定画刷在绘制时源像素与目标像素的合成方式。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
brush为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER；
+ *
blendMode不在枚举范围内时返回OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE。
*
* @param brush 指向画刷对象{@link OH_Drawing_Brush}的指针。
- * @param blendMode 混合模式枚举类型{@link OH_Drawing_BlendMode}。
+ * @param blendMode 要设置的混合模式，用于指定画刷在绘制时源像素与目标像素的混合方式。
+ * 枚举类型{@link OH_Drawing_BlendMode}。
* @since 12
* @version 1.0
*/
@@ -288,8 +311,8 @@ void OH_Drawing_BrushSetBlendMode(OH_Drawing_Brush* brush, OH_Drawing_BlendMode
/**
* @brief 将画刷重置至初始状态，清空所有已设置的属性。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * brush为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
brush为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param brush 指向画刷对象{@link OH_Drawing_Brush}的指针。
* @since 12
diff --git a/zh-cn/graphic/graphic_2d/native_drawing/drawing_canvas.h b/zh-cn/graphic/graphic_2d/native_drawing/drawing_canvas.h
index b571ffc59..f1984ce63 100644
--- a/zh-cn/graphic/graphic_2d/native_drawing/drawing_canvas.h
+++ b/zh-cn/graphic/graphic_2d/native_drawing/drawing_canvas.h
@@ -25,9 +25,12 @@
/**
* @file drawing_canvas.h
*
- * @brief This 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.
+ * @brief 文件中定义了画布（Canvas）的创建、绑定、绘制、变换、裁剪及状态管理等功能函数。
+ * 画布是ArkGraphics 2D中用于2D图形渲染的核心组件，支持绘制形状、路径、图像、像素图和文字，并提供画布变换（旋转、平移、
+ * 缩放、倾斜）、裁剪、矩阵操作等能力。
+ *
画布自带一个默认画刷，画刷为黑色、开启抗锯齿、不具备其他任何样式，
+ * 当且仅当画布中主动设置的画刷和画笔都不存在时生效。
+ *
本模块为单线程模型策略，需要调用方自行管理线程安全和上下文状态的切换。
*
* @kit ArkGraphics2D
* @library libnative_drawing.so
@@ -65,9 +68,12 @@ typedef enum {
} OH_Drawing_SrcRectConstraint;
/**
- * @brief 用于创建一个画布对象。
+ * @brief 用于创建一个画布对象。画布自带一个默认画刷，画刷为黑色、开启抗锯齿、不具备其他任何样式，
+ * 当且仅当画布中主动设置的画刷和画笔都不存在时生效。创建的画布对象在使用完毕后，必须调用
+ * {@link OH_Drawing_CanvasDestroy}销毁画布对象并释放资源，否则会导致内存泄漏。
*
- * @return 函数会返回一个指针，指针指向创建的画布对象。
+ * @return 函数会返回一个指针，指针指向创建的画布对象{@link OH_Drawing_Canvas}，如果为NULL，则创建失败，
+ * 原因可能是可用内存不足。
* @since 8
* @version 1.0
*/
@@ -75,9 +81,11 @@ OH_Drawing_Canvas* OH_Drawing_CanvasCreate(void);
/**
* @brief 用于将一个像素图对象绑定到画布中，使得画布绘制的内容输出到像素图中（即CPU渲染）。绑定像素图对象后的画布为非录制类型画布。
- * 像素图对象应该在销毁画布对象之后调用{@link OH_Drawing_PixelMapDissolve}解除绑定。
+ *
像素图对象应该在调用{@link OH_Drawing_CanvasDestroy}销毁画布对象之后，
+ * 再调用{@link OH_Drawing_PixelMapDissolve}解除绑定。
*
* @param pixelMap 指向像素图{@link OH_Drawing_PixelMap}的指针。
+ * 像素图对象应该在销毁画布对象之后调用{@link OH_Drawing_PixelMapDissolve}解除绑定。
* @return 函数会返回一个指针，指针指向创建的画布对象{@link OH_Drawing_Canvas}，如果对象返回为NULL，则创建失败，原因可能是可用内存不足或者像素图对象为空。
* @since 20
* @version 1.0
@@ -85,7 +93,7 @@ OH_Drawing_Canvas* OH_Drawing_CanvasCreate(void);
OH_Drawing_Canvas* OH_Drawing_CanvasCreateWithPixelMap(OH_Drawing_PixelMap* pixelMap);
/**
- * @brief 用于销毁画布对象并回收该对象占有的内存。
+ * @brief 用于销毁画布对象并回收该对象占用的内存。
*
* @param canvas 指向画布对象的指针。
* @since 8
@@ -95,8 +103,8 @@ void OH_Drawing_CanvasDestroy(OH_Drawing_Canvas* canvas);
/**
* @brief 用于将一个位图对象绑定到画布中，使得画布绘制的内容输出到位图中（即CPU渲染）。绑定位图对象后的画布为非录制类型画布。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas、bitmap任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas、bitmap任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象的指针。
* @param bitmap 指向位图对象的指针。
@@ -106,9 +114,10 @@ void OH_Drawing_CanvasDestroy(OH_Drawing_Canvas* canvas);
void OH_Drawing_CanvasBind(OH_Drawing_Canvas* canvas, OH_Drawing_Bitmap* bitmap);
/**
- * @brief 用于设置画笔给画布，画布将会使用设置画笔的样式和颜色去绘制图形形状的轮廓。执行该方法后，若画笔的效果发生改变并且开发者希望该变化生效于接下来的绘制动作，需要再次执行该方法以确保变化生效。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas、pen任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ * @brief 用于为画布设置画笔，画布将使用该画笔的样式和颜色绘制图形形状的轮廓。执行该方法后，
+ * 若画笔的效果发生改变并且开发者希望该变化生效于接下来的绘制动作，需要再次执行该方法以确保变化生效。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas、pen任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象的指针。
* @param pen 指向画笔对象的指针。
@@ -118,9 +127,9 @@ void OH_Drawing_CanvasBind(OH_Drawing_Canvas* canvas, OH_Drawing_Bitmap* bitmap)
void OH_Drawing_CanvasAttachPen(OH_Drawing_Canvas* canvas, const OH_Drawing_Pen* pen);
/**
- * @brief 用于去除掉画布中的画笔，使用后画布将不去绘制图形形状的轮廓。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ * @brief 用于去除画布中的画笔，使用后画布将不绘制图形形状的轮廓。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象的指针。
* @since 8
@@ -129,9 +138,10 @@ void OH_Drawing_CanvasAttachPen(OH_Drawing_Canvas* canvas, const OH_Drawing_Pen*
void OH_Drawing_CanvasDetachPen(OH_Drawing_Canvas* canvas);
/**
- * @brief 用于设置画刷给画布，画布将会使用设置的画刷样式和颜色去填充绘制的图形形状。执行该方法后，若画刷的效果发生改变并且开发者希望该变化生效于接下来的绘制动作，需要再次执行该方法以确保变化生效。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas、brush任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ * @brief 用于为画布设置画刷，画布将使用该画刷的样式和颜色填充绘制的图形形状。执行该方法后，
+ * 若画刷的效果发生改变并且开发者希望该变化生效于接下来的绘制动作，需要再次执行该方法以确保变化生效。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas、brush任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象的指针。
* @param brush 指向画刷对象的指针。
@@ -141,9 +151,9 @@ void OH_Drawing_CanvasDetachPen(OH_Drawing_Canvas* canvas);
void OH_Drawing_CanvasAttachBrush(OH_Drawing_Canvas* canvas, const OH_Drawing_Brush* brush);
/**
- * @brief 用于去除掉画布中的画刷，使用后画布将不使用此前设置的画刷去填充图形形状。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ * @brief 用于去除画布中的画刷，使用后画布将不使用此前设置的画刷填充图形形状。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象的指针。
* @since 8
@@ -153,8 +163,8 @@ void OH_Drawing_CanvasDetachBrush(OH_Drawing_Canvas* canvas);
/**
* @brief 用于保存当前画布的状态（画布矩阵）到一个栈顶。需要与恢复接口{@link OH_Drawing_CanvasRestore}配合使用。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象的指针。
* @since 8
@@ -163,10 +173,10 @@ void OH_Drawing_CanvasDetachBrush(OH_Drawing_Canvas* canvas);
void OH_Drawing_CanvasSave(OH_Drawing_Canvas* canvas);
/**
- * @brief 保存矩阵和裁剪区域，为后续绘制分配位图。调用恢复接口。
- * {@link OH_Drawing_CanvasRestore}将放弃对矩阵和剪切区域所做的更改，并绘制位图。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ * @brief 保存矩阵和裁剪区域，为后续绘制分配位图。调用恢复接口{@link OH_Drawing_CanvasRestore}后，
+ * 将舍弃对矩阵和裁剪区域所做的更改，并绘制位图。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象{@link OH_Drawing_Canvas}的指针。
* @param rect 指向矩形对象{@link OH_Drawing_Rect}的指针，用于限制图层大小，为NULL表示无限制。
@@ -178,8 +188,8 @@ void OH_Drawing_CanvasSaveLayer(OH_Drawing_Canvas* canvas, const OH_Drawing_Rect
/**
* @brief 用于恢复保存在栈顶的画布状态（画布矩阵）。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象的指针。
* @since 8
@@ -189,8 +199,8 @@ void OH_Drawing_CanvasRestore(OH_Drawing_Canvas* canvas);
/**
* @brief 用于获取栈中保存的画布状态（画布矩阵）的数量。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象的指针。
* @return 函数会返回一个32位的值描述画布状态（画布矩阵）的数量，画布初始状态数量为1。
@@ -201,8 +211,8 @@ uint32_t OH_Drawing_CanvasGetSaveCount(OH_Drawing_Canvas* canvas);
/**
* @brief 用于恢复到指定数量的画布状态（画布矩阵）。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象的指针。
* @param saveCount 要恢复的画布状态深度。小于等于1时，恢复为初始状态；大于已保存的画布状态数量时，不执行任何操作。
@@ -213,14 +223,14 @@ void OH_Drawing_CanvasRestoreToCount(OH_Drawing_Canvas* canvas, uint32_t saveCou
/**
* @brief 用于画一条直线段。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象的指针。
- * @param x1 线段起始点的横坐标。
- * @param y1 线段起始点的纵坐标。
- * @param x2 线段结束点的横坐标。
- * @param y2 线段结束点的纵坐标。
+ * @param x1 线段起始点的横坐标，单位为物理像素px。
+ * @param y1 线段起始点的纵坐标，单位为物理像素px。
+ * @param x2 线段结束点的横坐标，单位为物理像素px。
+ * @param y2 线段结束点的纵坐标，单位为物理像素px。
* @since 8
* @version 1.0
*/
@@ -228,8 +238,8 @@ void OH_Drawing_CanvasDrawLine(OH_Drawing_Canvas* canvas, float x1, float y1, fl
/**
* @brief 用于画一个自定义路径。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas、path任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas、path任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象的指针。
* @param path 指向路径对象的指针。
@@ -239,21 +249,22 @@ void OH_Drawing_CanvasDrawLine(OH_Drawing_Canvas* canvas, float x1, float y1, fl
void OH_Drawing_CanvasDrawPath(OH_Drawing_Canvas* canvas, const OH_Drawing_Path* path);
/**
- * @brief 在网格上绘制像素图，网格均匀分布在像素图上。（只支持brush，使用pen没有绘制效果。）
+ * @brief 在网格上绘制像素图，网格均匀分布在像素图上。（只支持画刷，使用画笔没有绘制效果。）
*
- * @param cCanvas 指向画布对象{@link OH_Drawing_Canvas}的指针。
+ * @param cCanvas 指向画布对象{@link OH_Drawing_Canvas}的指针，画布需已设置画刷，仅使用画笔无绘制效果。
* @param pixelMap 指向像素图{@link OH_Drawing_PixelMap}的指针。
- * @param meshWidth 网格的列数，取值为大于0的整数。
- * @param meshHeight 网格的行数，取值为大于0的整数。
+ * @param meshWidth 网格的列数，取值范围为大于0的整数。
+ * @param meshHeight 网格的行数，取值范围为大于0的整数。
* @param vertices 指向网格顶点数组的指针。
- * @param verticesSize 网格顶点数组的大小，大小必须为((meshWidth + 1) * (meshHeight + 1) + vertoffset) * 2。
+ * @param verticesSize 网格顶点数组的大小，大小必须为((meshWidth + 1) * (meshHeight + 1) + vertOffset) * 2。
* @param vertOffset 在绘图前需要跳过的顶点数，取值为大于等于0的整数。
- * @param colors 指向网格颜色数组的指针，可为nullptr。
+ * @param colors 指向网格颜色数组的指针，可为NULL。
* @param colorsSize 网格颜色数组的大小，若存在则大小必须为(meshWidth + 1) * (meshHeight + 1) + colorOffset。
* @param colorOffset 在绘图前需要跳过的颜色数，取值为大于等于0的整数。
* @return 函数返回执行错误码。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INCORRECT_PARAMETER，表示出现cCanvas、pixelMap、vertices等参数为空或传参不符合取值规则的情况。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INCORRECT_PARAMETER，表示出现cCanvas、pixelMap、
+ * vertices等参数为空或传参不符合取值规则的情况。
* @since 23
* @version 1.0
*/
@@ -262,18 +273,18 @@ OH_Drawing_ErrorCode OH_Drawing_CanvasDrawPixelMapMesh(OH_Drawing_Canvas* cCanva
const uint32_t* colors, uint32_t colorsSize, uint32_t colorOffset);
/**
- * @brief 通过绘制两条水平线和两条垂直线将像素图分割成9个部分：四个边，四个角和中心。
- * 若角落的4个区域尺寸不超过目标矩形，则会在不缩放的情况下被绘制在目标矩形，反之则会按比例缩放绘制在目标矩形。
- * 如果还有剩余空间，剩下的5个区域会通过拉伸或压缩来绘制，以便能够完全覆盖目标矩形。
+ * @brief 通过绘制两条水平线和两条垂直线将像素图分割成9个部分：四个边、四个角和中心。
+ *
若角落的4个区域尺寸不超过目标矩形，则会在不缩放的情况下被绘制在目标矩形，反之则会按比例缩放绘制在目标矩形。
+ *
如果还有剩余空间，剩下的5个区域会通过拉伸或压缩来绘制，以便能够完全覆盖目标矩形。
*
* @param canvas 指向画布对象{@link OH_Drawing_Canvas}的指针。
* @param pixelMap 指向像素图{@link OH_Drawing_PixelMap}的指针。
* @param center 指向矩形对象{@link OH_Drawing_Rect}的指针，表示分割像素图的中心矩形。矩形四条边所在的直线将像素图分成了9个部分。
* @param dst 指向矩形对象{@link OH_Drawing_Rect}的指针，表示画布上的目标区域。
- * @param mode 过滤模式枚举{@link OH_Drawing_FilterMode}。
+ * @param mode 过滤模式，不同模式影响像素图缩放时的插值质量。
* @return 函数返回执行错误码。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数canvas、pixelMap或dst为空。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数canvas、pixelMap或dst为空。
* @since 18
* @version 1.0
*/
@@ -281,9 +292,10 @@ OH_Drawing_ErrorCode OH_Drawing_CanvasDrawPixelMapNine(OH_Drawing_Canvas* canvas
const OH_Drawing_Rect* center, const OH_Drawing_Rect* dst, OH_Drawing_FilterMode mode);
/**
- * @brief 用于将像素图的指定区域绘制到画布的指定区域。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas、pixelMap、dst任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ * @brief 用于将像素图的指定区域绘制到画布的指定区域。与{@link OH_Drawing_CanvasDrawPixelMapRectConstraint}的区别是，
+ * 本接口不支持指定源矩形区域约束类型。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas、pixelMap、dst任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象{@link OH_Drawing_Canvas}的指针。
* @param pixelMap 指向像素图{@link OH_Drawing_PixelMap}的指针。
@@ -304,10 +316,10 @@ void OH_Drawing_CanvasDrawPixelMapRect(OH_Drawing_Canvas* canvas, OH_Drawing_Pix
* @param src 像素图指定矩形区域，为NULL将指定整个像素图区域。
* @param dst 目标画布指定矩形区域。
* @param samplingOptions 指向采样选项对象{@link OH_Drawing_SamplingOptions}的指针，为NULL将使用默认采样选项。
- * @param constraint 约束类型，支持可选的具体类型可见{@link OH_Drawing_SrcRectConstraint}枚举。
+ * @param constraint 约束类型。支持可选的具体类型可见{@link OH_Drawing_SrcRectConstraint}枚举。
* @return 函数返回执行结果。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数canvas、pixelMap或dst为空。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数canvas、pixelMap或dst为空。
* @since 20
* @version 1.0
*/
@@ -316,9 +328,9 @@ OH_Drawing_ErrorCode OH_Drawing_CanvasDrawPixelMapRectConstraint(OH_Drawing_Canv
const OH_Drawing_SamplingOptions* samplingOptions, OH_Drawing_SrcRectConstraint constraint);
/**
- * @brief 用于画一个背景，此背景以画刷填充。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas、brush任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ * @brief 用于以画刷填充画布的当前裁剪区域作为背景。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas、brush任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象的指针。
* @param brush 指向画刷对象的指针。
@@ -328,9 +340,9 @@ OH_Drawing_ErrorCode OH_Drawing_CanvasDrawPixelMapRectConstraint(OH_Drawing_Canv
void OH_Drawing_CanvasDrawBackground(OH_Drawing_Canvas* canvas, const OH_Drawing_Brush* brush);
/**
- * @brief 用于画一块区域。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas、region任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ * @brief 用于绘制一个区域，使用画刷填充区域内部、画笔绘制区域轮廓。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas、region任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象的指针。
* @param region 指向区域对象的指针。
@@ -361,13 +373,13 @@ typedef enum {
} OH_Drawing_PointMode;
/**
- * @brief 用于画一个点。
+ * @brief 用于画一个点。点的视觉大小由当前画布上设置的画笔笔触宽度决定，颜色由画笔颜色决定。
*
* @param canvas 指向画布对象{@link OH_Drawing_Canvas}的指针。
* @param point 指向点对象{@link OH_Drawing_Point2D}的指针。
* @return 函数返回执行错误码。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数canvas或者point为空。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数canvas或者point为空。
* @since 12
* @version 1.0
*/
@@ -375,14 +387,14 @@ OH_Drawing_ErrorCode OH_Drawing_CanvasDrawPoint(OH_Drawing_Canvas* canvas, const
/**
* @brief 用于画多个点，绘制方式分为绘制单独的点、绘制成线段或绘制成开放多边形。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas、point2D任意一个为NULL或者count等于0时返回OH_DRAWING_ERROR_INVALID_PARAMETER；
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas、point2D任意一个为NULL或者count等于0时返回OH_DRAWING_ERROR_INVALID_PARAMETER；
* mode不在枚举范围内时返回OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE。
*
* @param canvas 指向画布对象的指针。
* @param mode 绘制多个点的方式，支持方式参考{@link OH_Drawing_PointMode}。
- * @param count 点的数量，即点数组中点的个数。
- * @param point2D 指向多个点的数组。
+ * @param count 点的数量，即点数组中点的个数，值必须大于0。
+ * @param point2D 指向多个点的数组，数组大小需等于count参数值。
* @since 12
* @version 1.0
*/
@@ -391,13 +403,13 @@ void OH_Drawing_CanvasDrawPoints(OH_Drawing_Canvas* canvas, OH_Drawing_PointMode
/**
* @brief 用于画一个位图，位图又称为点阵图像、像素图或栅格图像，是由像素（图片元素）的单个点组成。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas、bitmap任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas、bitmap任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象的指针。
* @param bitmap 指向位图对象的指针。
- * @param left 位图对象左上角的横坐标。
- * @param top 位图对象左上角的纵坐标。
+ * @param left 位图对象左上角的横坐标，单位为物理像素px。
+ * @param top 位图对象左上角的纵坐标，单位为物理像素px。
* @since 11
* @version 1.0
*/
@@ -405,8 +417,8 @@ void OH_Drawing_CanvasDrawBitmap(OH_Drawing_Canvas* canvas, const OH_Drawing_Bit
/**
* @brief 将位图的指定区域绘制到画布的指定区域。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas、bitmap、dst任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas、bitmap、dst任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象{@link OH_Drawing_Canvas}的指针。
* @param bitmap 指向位图对象{@link OH_Drawing_Bitmap}的指针。
@@ -421,8 +433,8 @@ void OH_Drawing_CanvasDrawBitmapRect(OH_Drawing_Canvas* canvas, const OH_Drawing
/**
* @brief 用于画一个矩形。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas、OH_Drawing_Rect任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas、rect任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象的指针。
* @param rect 指向矩形对象的指针。
@@ -432,28 +444,31 @@ void OH_Drawing_CanvasDrawBitmapRect(OH_Drawing_Canvas* canvas, const OH_Drawing
void OH_Drawing_CanvasDrawRect(OH_Drawing_Canvas* canvas, const OH_Drawing_Rect* rect);
/**
- * @brief 用于画一个圆形。本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。canvas、
- * point任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER；
- * radius小于等于0时返回OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE。
+ * @brief 用于画一个圆形。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas、point任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER；
+ *
radius小于等于0时返回OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE。
*
* @param canvas 指向画布对象的指针。
* @param point 指向坐标点对象的指针，表示圆心。
- * @param radius 圆形的半径，小于等于0时无效。
+ * @param radius 圆形的半径，单位为物理像素px，取值范围大于0。
* @since 11
* @version 1.0
*/
void OH_Drawing_CanvasDrawCircle(OH_Drawing_Canvas* canvas, const OH_Drawing_Point* point, float radius);
/**
- * @brief 用于使用指定的颜色及混合模式来填充整个画布。
+ * @brief 用于以指定的颜色及混合模式填充整个画布。该函数将指定颜色按照blendMode定义的混合规则与画布上已有内容进行合成，
+ * 不同混合模式产生不同的视觉效果。
*
* @param canvas 指向画布对象{@link OH_Drawing_Canvas}的指针。
- * @param color 表示指定的颜色，用一个32位（ARGB）的变量表示。
- * @param blendMode 表示指定的混合模式。
+ * @param color 表示指定的颜色，用一个32位（ARGB）的参数表示。参数整体取值范围[0x00000000, 0xFFFFFFFF]，
+ * 每个颜色通道（A、R、G、B）取值范围[0, 255]。
+ * @param blendMode 表示指定的混合模式，用于控制颜色填充画布时的混合方式。
* @return 函数返回执行错误码。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数canvas为空。
- * 返回OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE，表示blendMode不在枚举范围内。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数canvas为空。
+ *
返回OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE，表示blendMode不在枚举范围内。
* @since 12
* @version 1.0
*/
@@ -461,7 +476,8 @@ OH_Drawing_ErrorCode OH_Drawing_CanvasDrawColor(OH_Drawing_Canvas* canvas, uint3
OH_Drawing_BlendMode blendMode);
/**
- * @brief 用于画一个椭圆。本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。canvas、
+ * @brief 用于画一个椭圆，椭圆内接于参数rect所指定的矩形区域。本接口会产生错误码，
+ * 可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。canvas、
* rect任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象的指针。
@@ -472,14 +488,18 @@ OH_Drawing_ErrorCode OH_Drawing_CanvasDrawColor(OH_Drawing_Canvas* canvas, uint3
void OH_Drawing_CanvasDrawOval(OH_Drawing_Canvas* canvas, const OH_Drawing_Rect* rect);
/**
- * @brief 用于画一个弧。当扫描角度的绝对值大于360度时，本接口绘制的是一个椭圆。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas、rect任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ * @brief 用于绘制内接于参数rect所定义椭圆的一段弧线。当扫描角度的绝对值大于360度时，本接口绘制的是一个椭圆。
+ * 与{@link OH_Drawing_CanvasDrawArcWithCenter}的区别是，
+ * 本接口不支持指定圆弧的起点和终点是否连接圆弧的中心点。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas、rect任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象的指针。
- * @param rect 指向矩形对象的指针。
- * @param startAngle 弧的起始角度，0度时起始点位于椭圆的右端点，正数时以顺时针方向放置起始点，负数时以逆时针方向放置起始点。
- * @param sweepAngle 弧的扫描角度，正数时顺时针扫描，负数时逆时针扫描。它的有效范围在-360度到360度之间，当绝对值大于360度时，该函数绘制的是一个椭圆。
+ * @param rect 指向矩形对象的指针，用于定义弧所在椭圆的边界矩形。弧将在此矩形定义的椭圆上绘制。
+ * @param startAngle 弧的起始角度，单位为度。0度时起始点位于椭圆的右端点，正数时以顺时针方向放置起始点，
+ * 负数时以逆时针方向放置起始点。
+ * @param sweepAngle 弧的扫描角度，单位为度。正数时顺时针扫描，负数时逆时针扫描。它的有效范围在-360度到360度之间，
+ * 当绝对值大于360度时，该函数绘制的是一个椭圆。
* @since 11
* @version 1.0
*/
@@ -487,16 +507,19 @@ void OH_Drawing_CanvasDrawArc(OH_Drawing_Canvas* canvas,
const OH_Drawing_Rect* rect, float startAngle, float sweepAngle);
/**
- * @brief 绘制一段圆弧。该方法允许指定圆弧的起始角度、扫描角度以及圆弧的起点和终点是否连接圆弧的中心点。
+ * @brief 用于绘制一段圆弧，弧线内接于参数rect所定义的椭圆。本接口允许指定圆弧的起始角度、
+ * 扫描角度以及圆弧的起点和终点是否连接椭圆的中心点（即rect的中心点）。
*
* @param canvas 指向画布对象{@link OH_Drawing_Canvas}的指针。
- * @param rect 指向矩形对象{@link OH_Drawing_Rect}的指针。
- * @param startAngle 弧的起始角度，单位为度，该参数为浮点数。0度时起始点位于椭圆的右端点，为正数时以顺时针方向放置起始点，为负数时以逆时针方向放置起始点。
- * @param sweepAngle 弧的扫描角度，单位为度，该参数为浮点数。为正数时顺时针扫描，为负数时逆时针扫描。扫描角度可以超过360度，将绘制一个完整的椭圆。
+ * @param rect 指向矩形对象{@link OH_Drawing_Rect}的指针，用于定义弧所在椭圆的边界矩形。弧将在此矩形定义的椭圆上绘制。
+ * @param startAngle 弧的起始角度，单位为度。0度时起始点位于椭圆的右端点，为正数时以顺时针方向放置起始点，
+ * 为负数时以逆时针方向放置起始点。
+ * @param sweepAngle 弧的扫描角度，单位为度。正数时顺时针扫描，负数时逆时针扫描。扫描角度的有效范围在-360度到360度之间，
+ * 绝对值大于360度时将绘制一个完整的椭圆。
* @param useCenter 表示绘制时弧形的起点和终点是否连接弧形的中心点。true表示连接，false表示不连接。
* @return 函数返回执行错误码。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数canvas或者rect为空。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数canvas或者rect为空。
* @since 18
* @version 1.0
*/
@@ -515,14 +538,15 @@ OH_Drawing_ErrorCode OH_Drawing_CanvasDrawArcWithCenter(OH_Drawing_Canvas* canva
void OH_Drawing_CanvasDrawRoundRect(OH_Drawing_Canvas* canvas, const OH_Drawing_RoundRect* roundRect);
/**
- * @brief 绘制两个嵌套的圆角矩形，外部矩形边界必须包含内部矩形边界，否则无绘制效果。
+ * @brief 用于绘制两个嵌套的圆角矩形，外部矩形边界必须包含内部矩形边界，否则无绘制效果。
*
* @param canvas 指向画布对象{@link OH_Drawing_Canvas}的指针。
- * @param outer 指向圆角矩形对象{@link OH_Drawing_RoundRect}的指针，表示外部圆角矩形边界。
+ * @param outer 指向圆角矩形对象{@link OH_Drawing_RoundRect}的指针，表示外部圆角矩形边界，
+ * 外部矩形边界必须包含内部矩形边界，否则无绘制效果。
* @param inner 指向圆角矩形对象{@link OH_Drawing_RoundRect}的指针，表示内部圆角矩形边界。
* @return 函数返回执行错误码。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数canvas、outer或者inner为空。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数canvas、outer或者inner为空。
* @since 18
* @version 1.0
*/
@@ -531,15 +555,18 @@ OH_Drawing_ErrorCode OH_Drawing_CanvasDrawNestedRoundRect(OH_Drawing_Canvas* can
/**
* @brief 用于绘制单个字符。当前字型中的字体不支持待绘制字符时，退化到使用系统字体绘制字符。
+ * 与{@link OH_Drawing_CanvasDrawSingleCharacterWithFeatures}的区别是，
+ * 本接口不支持设置字体特征。如需指定字体特征（如连字、字距调整等），
+ * 请使用{@link OH_Drawing_CanvasDrawSingleCharacterWithFeatures}。
*
* @param canvas 指向画布对象{@link OH_Drawing_Canvas}的指针。
* @param str 待绘制的单个字符。可以传入字符串，但只会以UTF-8编码解析并绘制字符串中的首个字符。
* @param font 指向字型对象{@link OH_Drawing_Font}的指针。
- * @param x 字符对象基线左端点（靠近字符左下角）的横坐标。
- * @param y 字符对象基线左端点（靠近字符左下角）的纵坐标。
+ * @param x 字符对象基线左端点（靠近字符左下角）的横坐标，单位为物理像素px。
+ * @param y 字符对象基线左端点（靠近字符左下角）的纵坐标，单位为物理像素px。
* @return 函数返回执行错误码。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数canvas、str、font任意一个为NULL或者str的长度为0。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数canvas、str、font任意一个为空或者str的长度为0。
* @since 12
* @version 1.0
*/
@@ -552,12 +579,14 @@ OH_Drawing_ErrorCode OH_Drawing_CanvasDrawSingleCharacter(OH_Drawing_Canvas* can
* @param canvas 指向画布对象{@link OH_Drawing_Canvas}的指针。
* @param str 待绘制的单个字符。可以传入字符串，但只会以UTF-8编码解析并绘制字符串中的首个字符。
* @param font 指向字型对象{@link OH_Drawing_Font}的指针。
- * @param x 字符对象基线左端点（靠近字符左下角）的横坐标。
- * @param y 字符对象基线左端点（靠近字符左下角）的纵坐标。
- * @param fontFeatures 指向字体特征容器对象{@link OH_Drawing_FontFeatures}的指针。容器中未加入任何字体特征时使用TTF(TrueType Font)文件中预设的字体特征。
+ * @param x 字符对象基线左端点（靠近字符左下角）的横坐标，单位为物理像素px。
+ * @param y 字符对象基线左端点（靠近字符左下角）的纵坐标，单位为物理像素px。
+ * @param fontFeatures 指向字体特征容器对象{@link OH_Drawing_FontFeatures}的指针。
+ * 容器中未加入任何字体特征时使用TTF（TrueType Font）文件中预设的字体特征。
* @return 函数返回执行结果。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数canvas、str、font或者fontFeatures任意一个为NULL或者str的长度为0。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数canvas、str、
+ * font或者fontFeatures任意一个为NULL或者str的长度为0。
* @since 20
* @version 1.0
*/
@@ -566,13 +595,13 @@ OH_Drawing_ErrorCode OH_Drawing_CanvasDrawSingleCharacterWithFeatures(OH_Drawing
/**
* @brief 用于画一段文字。若构造OH_Drawing_TextBlob的字体不支持待绘制字符，则该部分字符无法绘制。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas、textBlob任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas、textBlob任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象的指针。
* @param textBlob 指向文本对象的指针。
- * @param x 文本对象基线左端点（靠近文本左下角）的横坐标。
- * @param y 文本对象基线左端点（靠近文本左下角）的纵坐标。
+ * @param x 文本对象基线左端点（靠近文本左下角）的横坐标，单位为物理像素px。
+ * @param y 文本对象基线左端点（靠近文本左下角）的纵坐标，单位为物理像素px。
* @since 11
* @version 1.0
*/
@@ -597,14 +626,14 @@ typedef enum {
/**
* @brief 用于裁剪一个矩形。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas、rect任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER；
- * clipOp不在枚举范围内时返回OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas、rect任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER；
+ *
clipOp不在枚举范围内时返回OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE。
*
* @param canvas 指向画布对象的指针。
* @param rect 指向矩形对象的指针。
* @param clipOp 裁剪方式。支持可选的具体裁剪方式可见{@link OH_Drawing_CanvasClipOp}枚举。
- * @param doAntiAlias 值为true则做抗锯齿处理，值为false不做抗锯齿处理。
+ * @param doAntiAlias 表示是否需要做抗锯齿处理，值为true则做抗锯齿处理，值为false不做抗锯齿处理。
* @since 11
* @version 1.0
*/
@@ -613,14 +642,14 @@ void OH_Drawing_CanvasClipRect(OH_Drawing_Canvas* canvas, const OH_Drawing_Rect*
/**
* @brief 用于裁剪一个圆角矩形。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas、roundRect任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER；
- * clipOp不在枚举范围内时返回OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas、roundRect任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER；
+ *
clipOp不在枚举范围内时返回OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE。
*
* @param canvas 指向画布对象的指针。
* @param roundRect 指向圆角矩形对象的指针。
- * @param clipOp 裁剪方式。支持可选的具体裁剪方式可见@{link OH_Drawing_CanvasClipOp}枚举。
- * @param doAntiAlias 表示是否需要做抗锯齿处理，值为true时为需要，为false时为不需要。
+ * @param clipOp 裁剪方式。支持可选的具体裁剪方式可见{@link OH_Drawing_CanvasClipOp}枚举。
+ * @param doAntiAlias 表示是否需要做抗锯齿处理，值为true则做抗锯齿处理，值为false不做抗锯齿处理。
* @since 12
* @version 1.0
*/
@@ -629,14 +658,14 @@ void OH_Drawing_CanvasClipRoundRect(OH_Drawing_Canvas* canvas, const OH_Drawing_
/**
* @brief 用于裁剪一个自定义路径。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas、path任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER；
- * clipOp不在枚举范围内时返回OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas、path任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER；
+ *
clipOp不在枚举范围内时返回OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE。
*
* @param canvas 指向画布对象的指针。
* @param path 指向路径对象的指针。
- * @param clipOp 裁剪方式。支持可选的具体裁剪方式可见@{link OH_Drawing_CanvasClipOp}枚举。
- * @param doAntiAlias 真为抗锯齿，假则不做抗锯齿处理。
+ * @param clipOp 裁剪方式。支持可选的具体裁剪方式可见{@link OH_Drawing_CanvasClipOp}枚举。
+ * @param doAntiAlias 表示是否需要做抗锯齿处理，值为true则做抗锯齿处理，值为false不做抗锯齿处理。
* @since 11
* @version 1.0
*/
@@ -648,11 +677,11 @@ void OH_Drawing_CanvasClipPath(OH_Drawing_Canvas* canvas, const OH_Drawing_Path*
*
* @param canvas 指向画布对象{@link OH_Drawing_Canvas}的指针。
* @param region 指向区域对象{@link OH_Drawing_Region}的指针。
- * @param clipOp 表示裁剪类型。支持可选的具体裁剪方式可见@{link OH_Drawing_CanvasClipOp}枚举。
+ * @param clipOp 表示裁剪类型。支持可选的具体裁剪方式可见{@link OH_Drawing_CanvasClipOp}枚举。
* @return 函数返回执行错误码。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数canvas或者region为空。
- * 返回OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE，表示clipOp不在枚举范围内。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数canvas或者region为空。
+ *
返回OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE，表示clipOp不在枚举范围内。
* @since 12
* @version 1.0
*/
@@ -660,14 +689,14 @@ OH_Drawing_ErrorCode OH_Drawing_CanvasClipRegion(OH_Drawing_Canvas* canvas, cons
OH_Drawing_CanvasClipOp clipOp);
/**
- * @brief 用于画布旋转一定的角度，正数表示顺时针旋转，负数反之。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ * @brief 用于旋转画布。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象的指针。
- * @param degrees 旋转角度。
- * @param px 旋转中心的横坐标。
- * @param py 旋转中心的纵坐标。
+ * @param degrees 旋转角度，单位为度。正值表示顺时针旋转，负值表示逆时针旋转。
+ * @param px 旋转中心的横坐标，单位为物理像素px。
+ * @param py 旋转中心的纵坐标，单位为物理像素px。
* @since 11
* @version 1.0
*/
@@ -675,12 +704,12 @@ void OH_Drawing_CanvasRotate(OH_Drawing_Canvas* canvas, float degrees, float px,
/**
* @brief 用于平移画布一段距离。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象的指针。
- * @param dx x轴方向的移动距离。
- * @param dy y轴方向的移动距离。
+ * @param dx x轴方向的移动距离，单位为物理像素px。
+ * @param dy y轴方向的移动距离，单位为物理像素px。
* @since 11
* @version 1.0
*/
@@ -688,8 +717,8 @@ void OH_Drawing_CanvasTranslate(OH_Drawing_Canvas* canvas, float dx, float dy);
/**
* @brief 用于画布缩放。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象的指针。
* @param sx x轴方向的缩放比例。
@@ -701,11 +730,11 @@ void OH_Drawing_CanvasScale(OH_Drawing_Canvas* canvas, float sx, float sy);
/**
* @brief 用于画布倾斜变换。等同于将当前画布矩阵左乘（premultiply）倾斜变换矩阵，并应用到画布上。其中倾斜变换矩阵为：
- * |1 sx 0|
- * |sy 1 0|
- * |0 0 1|。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
|1 sx 0|
+ *
|sy 1 0|
+ *
|0 0 1|。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象的指针。
* @param sx 沿x轴的倾斜量。正值会使绘制沿y轴增量方向向右倾斜；负值会使绘制沿y轴增量方向向左倾斜。
@@ -717,11 +746,11 @@ void OH_Drawing_CanvasSkew(OH_Drawing_Canvas* canvas, float sx, float sy);
/**
* @brief 获取画布宽度。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象{@link OH_Drawing_Canvas}的指针。
- * @return 返回画布宽度。
+ * @return 函数返回画布宽度，单位为物理像素px。
* @since 12
* @version 1.0
*/
@@ -729,11 +758,11 @@ int32_t OH_Drawing_CanvasGetWidth(OH_Drawing_Canvas* canvas);
/**
* @brief 获取画布高度。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象{@link OH_Drawing_Canvas}的指针。
- * @return 返回画布高度。
+ * @return 函数返回画布高度，单位为物理像素px。
* @since 12
* @version 1.0
*/
@@ -741,8 +770,8 @@ int32_t OH_Drawing_CanvasGetHeight(OH_Drawing_Canvas* canvas);
/**
* @brief 获取画布裁剪区域的边界。该接口不可用于录制类型画布。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas、rect任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas、rect任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象{@link OH_Drawing_Canvas}的指针。
* @param rect 指向矩形对象{@link OH_Drawing_Rect}的指针，开发者可调用{@link OH_Drawing_RectCreate}接口创建。
@@ -753,8 +782,8 @@ void OH_Drawing_CanvasGetLocalClipBounds(OH_Drawing_Canvas* canvas, OH_Drawing_R
/**
* @brief 获取画布3x3矩阵。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas、matrix任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas、matrix任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象{@link OH_Drawing_Canvas}的指针。
* @param matrix 指向矩阵对象{@link OH_Drawing_Matrix}的指针，开发者可调用{@link OH_Drawing_MatrixCreate}接口创建。
@@ -765,8 +794,8 @@ void OH_Drawing_CanvasGetTotalMatrix(OH_Drawing_Canvas* canvas, OH_Drawing_Matri
/**
* @brief 画布现有矩阵左乘以传入矩阵，不影响该接口之前的绘制操作。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas、matrix任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas、matrix任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象{@link OH_Drawing_Canvas}的指针。
* @param matrix 指向矩阵对象{@link OH_Drawing_Matrix}的指针。
@@ -801,19 +830,21 @@ typedef enum {
} OH_Drawing_CanvasShadowFlags;
/**
- * @brief 绘制射灯类型阴影，使用路径描述环境光阴影的轮廓。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas、path任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER；
- * flag不在枚举范围内返回OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE。
+ * @brief 用于绘制射灯类型阴影，使用路径描述环境光阴影的轮廓。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas、path任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER；
+ *
flag不在枚举范围内返回OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE。
*
* @param canvas 指向画布对象{@link OH_Drawing_Canvas}的指针。
* @param path 指向路径对象{@link OH_Drawing_Path}的指针，用于生成阴影。
* @param planeParams 表示遮挡物相对于画布在Z轴上的偏移量，其值取决于x与y坐标。
- * @param devLightPos 光线相对于画布的位置。
- * @param lightRadius 光源半径，需大于或等于0。
- * @param ambientColor 环境阴影颜色，用一个32位（ARGB）的变量表示。
- * @param spotColor 点阴影颜色，用一个32位（ARGB）的变量表示。
- * @param flag 阴影标志枚举{@link OH_Drawing_CanvasShadowFlags}。
+ * @param devLightPos 光线相对于画布的位置，其中x、y表示光源在画布平面上的坐标，z表示光源距离画布平面的高度。
+ * @param lightRadius 光源半径，单位为物理像素px，取值范围大于等于0。
+ * @param ambientColor 环境阴影颜色，用一个32位（ARGB）的参数表示。参数整体取值范围[0x00000000, 0xFFFFFFFF]，
+ * 每个颜色通道（A、R、G、B）取值范围[0, 255]。
+ * @param spotColor 点阴影颜色，用一个32位（ARGB）的参数表示。参数整体取值范围[0x00000000, 0xFFFFFFFF]，
+ * 每个颜色通道（A、R、G、B）取值范围[0, 255]。
+ * @param flag 阴影标志。
* @since 12
* @version 1.0
*/
@@ -822,21 +853,23 @@ void OH_Drawing_CanvasDrawShadow(OH_Drawing_Canvas* canvas, OH_Drawing_Path* pat
OH_Drawing_CanvasShadowFlags flag);
/**
- * @brief 用于使用指定颜色去清空画布。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ * @brief 使用指定颜色清空画布。与{@link OH_Drawing_CanvasDrawColor}的区别是，本接口直接用指定颜色替换画布所有内容，
+ * 而OH_Drawing_CanvasDrawColor通过混合模式将颜色与画布现有内容混合。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象的指针。
- * @param color 描述颜色的32位（ARGB）变量。
+ * @param color 表示指定的颜色，用一个32位（ARGB）的参数表示。参数整体取值范围[0x00000000, 0xFFFFFFFF]，
+ * 每个颜色通道（A、R、G、B）取值范围[0, 255]。
* @since 8
* @version 1.0
*/
void OH_Drawing_CanvasClear(OH_Drawing_Canvas* canvas, uint32_t color);
/**
- * @brief 设置画布的矩阵状态。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas、matrix任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ * @brief 设置画布的矩阵状态，将画布当前矩阵替换为传入的矩阵，影响后续绘制操作的坐标变换。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas、matrix任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象{@link OH_Drawing_Canvas}的指针。
* @param matrix 指向矩阵对象{@link OH_Drawing_Matrix}的指针，开发者可调用{@link OH_Drawing_MatrixCreate}接口创建。
@@ -847,8 +880,8 @@ void OH_Drawing_CanvasSetMatrix(OH_Drawing_Canvas* canvas, OH_Drawing_Matrix* ma
/**
* @brief 重置当前画布的矩阵为单位矩阵。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象{@link OH_Drawing_Canvas}的指针。
* @since 12
@@ -857,27 +890,27 @@ void OH_Drawing_CanvasSetMatrix(OH_Drawing_Canvas* canvas, OH_Drawing_Matrix* ma
void OH_Drawing_CanvasResetMatrix(OH_Drawing_Canvas* canvas);
/**
- * @brief 重置剪辑状态。
+ * @brief 将当前画布的裁剪状态重置为初始状态。
*
- * @param canvas 指向OH_Drawing_Canvas对象的指针。
- * @return 返回错误码。
- * 如果操作成功，则返回OH_DRAWING_SUCCESS。
- * 如果canvas为nullptr，则返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ * @param canvas 指向{@link OH_Drawing_Canvas}对象的指针。
+ * @return 返回执行结果。
+ *
如果操作成功，则返回OH_DRAWING_SUCCESS。
+ *
如果canvas为nullptr，则返回OH_DRAWING_ERROR_INVALID_PARAMETER。
* @since 26.0.0
*/
OH_Drawing_ErrorCode OH_Drawing_CanvasResetClip(OH_Drawing_Canvas* canvas);
/**
* @brief 将图片绘制到画布的指定区域上，源矩形选定的区域会缩放平移到目标矩形。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas、image、src、dst任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas、image、src、dst任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象{@link OH_Drawing_Canvas}的指针。
* @param image 指向图片对象{@link OH_Drawing_Image}的指针。
- * @param src 指向目标矩形对象{@link OH_Drawing_Rect}的指针。
- * @param dst 指向目标矩形对象{@link OH_Drawing_Rect}的指针。
+ * @param src 指向源矩形对象{@link OH_Drawing_Rect}的指针，用于指定图片中要绘制的源区域。
+ * @param dst 指向目标矩形对象{@link OH_Drawing_Rect}的指针，表示画布上的目标绘制区域。
* @param samplingOptions 指向采样选项对象{@link OH_Drawing_SamplingOptions}的指针，为NULL将使用默认采样选项。
- * @param srcRectConstraint 约束类型，支持可选的具体类型可见{@link OH_Drawing_SrcRectConstraint}枚举。
+ * @param srcRectConstraint 约束类型。
* @since 12
* @version 1.0
*/
@@ -886,13 +919,14 @@ void OH_Drawing_CanvasDrawImageRectWithSrc(OH_Drawing_Canvas* canvas, const OH_D
OH_Drawing_SrcRectConstraint srcRectConstraint);
/**
- * @brief 将图片绘制到画布的指定区域上。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas、image、dst任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ * @brief 将图片绘制到画布的指定区域上。与{@link OH_Drawing_CanvasDrawImageRectWithSrc}的区别是，
+ * 本接口不支持指定源矩形区域约束类型。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas、image、rect任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象{@link OH_Drawing_Canvas}的指针。
* @param image 指向图片对象{@link OH_Drawing_Image}的指针。
- * @param rect 指向矩形对象{@link OH_Drawing_Rect}的指针。
+ * @param rect 指向矩形对象{@link OH_Drawing_Rect}的指针，表示画布上绘制图片的目标区域。
* @param samplingOptions 指向采样选项对象{@link OH_Drawing_SamplingOptions}的指针，为NULL将使用默认采样选项。
* @since 12
* @version 1.0
@@ -923,19 +957,24 @@ typedef enum {
/**
* @brief 用于画顶点数组描述的三角网格。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas或positions为NULL、vertexCount值小于3、indexCount值小于3且不为0，存在以上任意一种情况时设置错误码为OH_DRAWING_ERROR_INVALID_PARAMETER；
- * vertexMmode、mode任意一个不在枚举范围内时设置错误码为OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas或positions为NULL、vertexCount值小于3、indexCount值小于3且不为0，
+ * 存在以上任意一种情况时设置错误码为OH_DRAWING_ERROR_INVALID_PARAMETER；
+ *
vertexMmode、mode任意一个不在枚举范围内时设置错误码为OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE。
*
* @param canvas 指向画布对象的指针。
- * @param vertexMmode 绘制顶点的连接方式，支持方式参考{@link OH_Drawing_VertexMode}。
+ * @param vertexMmode 绘制顶点的连接方式。支持方式参考{@link OH_Drawing_VertexMode}。
* @param vertexCount 顶点数组元素的数量，值必须大于等于3。
* @param positions 描述顶点位置的数组指针，不能为空，其长度必须等于vertexCount。
- * @param texs 描述顶点对应纹理空间坐标的数组指针，可以为空，若不为空其长度必须等于vertexCount。
- * @param colors 描述顶点对应颜色的数组指针，用于在三角形中进行插值，可以为空，若不为空其长度必须等于vertexCount。
+ * @param texs 描述顶点对应纹理空间坐标的数组指针，可以为空。为空时不应用纹理映射，仅使用颜色或默认填充绘制；
+ * 不为空时将纹理按顶点纹理坐标映射到三角网格上，其长度必须等于vertexCount。
+ * @param colors 描述顶点对应颜色的数组指针，用于在三角形中进行颜色插值，可以为空。为空时不使用逐顶点颜色，
+ * 使用画刷默认颜色绘制；不为空时在三角网格中对各顶点颜色进行插值混合产生渐变效果，
+ * 其长度必须等于vertexCount。
* @param indexCount 索引的数量，可以为0，若不为0则值必须大于等于3。
- * @param indices 描述顶点对应索引的数组指针，可以为空，若不为空其长度必须等于indexCount。
- * @param mode 混合模式枚举，支持方式参考{@link OH_Drawing_BlendMode}。
+ * @param indices 描述顶点对应索引的数组指针，可以为空。为空时按顶点数组顺序依次绘制三角形；
+ * 不为空时按索引指定顺序绘制三角形，可复用顶点以减少数据量，其长度必须等于indexCount。
+ * @param mode 混合模式，用于控制顶点颜色的混合方式。支持方式参考{@link OH_Drawing_BlendMode}。
* @since 12
* @version 1.0
*/
@@ -945,15 +984,15 @@ void OH_Drawing_CanvasDrawVertices(OH_Drawing_Canvas* canvas, OH_Drawing_VertexM
/**
* @brief 从画布中拷贝像素数据到指定地址。该接口不可用于录制类型画布。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas、imageInfo、dstPixels任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas、imageInfo、dstPixels任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象{@link OH_Drawing_Canvas}的指针。
* @param imageInfo 指向图片信息{@link OH_Drawing_Image_Info}的指针。
- * @param dstPixels 目标像素存储首地址。
- * @param dstRowBytes 一行像素的大小，小于等于0时无效。
- * @param srcX 画布像素的x轴偏移量，单位为像素。
- * @param srcY 画布像素的y轴偏移量，单位为像素。
+ * @param dstPixels 目标像素存储首地址，缓冲区大小至少为dstRowBytes × 图像高度。
+ * @param dstRowBytes 一行像素的大小，单位为字节，取值范围大于0。等于0时拷贝失败。
+ * @param srcX 画布像素的x轴偏移量，单位为物理像素px。
+ * @param srcY 画布像素的y轴偏移量，单位为物理像素px。
* @return 函数返回true表示像素成功拷贝到目标像素存储首地址，函数返回false表示拷贝失败。
* @since 12
* @version 1.0
@@ -963,13 +1002,13 @@ bool OH_Drawing_CanvasReadPixels(OH_Drawing_Canvas* canvas, OH_Drawing_Image_Inf
/**
* @brief 从画布拷贝像素数据到位图中。该接口不可用于录制类型画布。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * canvas、bitmap任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
canvas、bitmap任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param canvas 指向画布对象{@link OH_Drawing_Canvas}的指针。
* @param bitmap 指向位图对象{@link OH_Drawing_Bitmap}的指针。
- * @param srcX 画布像素的x轴偏移量，单位为像素。
- * @param srcY 画布像素的y轴偏移量，单位为像素。
+ * @param srcX 画布像素的x轴偏移量，单位为物理像素px。
+ * @param srcY 画布像素的y轴偏移量，单位为物理像素px。
* @return 函数返回true表示像素成功拷贝到位图，函数返回false表示拷贝失败。
* @since 12
* @version 1.0
@@ -983,8 +1022,8 @@ bool OH_Drawing_CanvasReadPixelsToBitmap(OH_Drawing_Canvas* canvas,
* @param canvas 指向画布对象{@link OH_Drawing_Canvas}的指针。
* @param isClipEmpty 表示裁剪后可绘制区域是否为空。true表示为空，false表示不为空。
* @return 函数返回执行错误码。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数canvas或者isClipEmpty为空。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数canvas或者isClipEmpty为空。
* @since 12
* @version 1.0
*/
@@ -996,8 +1035,8 @@ OH_Drawing_ErrorCode OH_Drawing_CanvasIsClipEmpty(OH_Drawing_Canvas* canvas, boo
* @param canvas 指向画布对象{@link OH_Drawing_Canvas}的指针。
* @param imageInfo 指向图像信息对象{@link OH_Drawing_Image_Info}的指针。
* @return 函数返回执行错误码。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数canvas或者imageInfo为空。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数canvas或者imageInfo为空。
* @since 12
* @version 1.0
*/
@@ -1009,8 +1048,8 @@ OH_Drawing_ErrorCode OH_Drawing_CanvasGetImageInfo(OH_Drawing_Canvas* canvas, OH
* @param canvas 指向画布对象{@link OH_Drawing_Canvas}的指针，仅支持录制类型画布。
* @param recordCmd 指向录制指令对象{@link OH_Drawing_RecordCmd}的指针。
* @return 函数返回执行错误码。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数canvas或者recordCmd为空。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数canvas或者recordCmd为空。
* @since 13
* @version 1.0
*/
@@ -1018,12 +1057,14 @@ OH_Drawing_ErrorCode OH_Drawing_CanvasDrawRecordCmd(OH_Drawing_Canvas* canvas, O
/**
* @brief 用于绘制录制指令对象，支持嵌套。
+ *
本接口支持{@link OH_Drawing_RecordCmdUtilsBeginRecording}接口生成的画布对象作为入参，嵌套调用。不建议多层嵌套，
+ * 会影响性能。
*
* @param canvas 指向画布对象{@link OH_Drawing_Canvas}的指针，仅支持录制类型画布。
* @param recordCmd 指向录制指令对象{@link OH_Drawing_RecordCmd}的指针。
- * @return 函数返回执行操作码。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数canvas或者recordCmd为空。
+ * @return 函数返回执行结果。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数canvas或者recordCmd为空。
* @since 19
* @version 1.0
*/
@@ -1036,8 +1077,8 @@ OH_Drawing_ErrorCode OH_Drawing_CanvasDrawRecordCmdNesting(OH_Drawing_Canvas* ca
* @param path 指向路径对象{@link OH_Drawing_Path}的指针。
* @param quickReject 表示路径与画布区域是否不相交，true表示路径与画布区域不相交，false表示路径与画布区域相交。
* @return 函数返回执行错误码。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数canvas、path或者quickReject为空。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数canvas、path或者quickReject为空。
* @since 18
* @version 1.0
*/
@@ -1051,8 +1092,8 @@ OH_Drawing_ErrorCode OH_Drawing_CanvasQuickRejectPath(OH_Drawing_Canvas* canvas,
* @param rect 指向矩形对象{@link OH_Drawing_Rect}的指针。
* @param quickReject 表示矩形与画布区域是否不相交，true表示矩形与画布区域不相交，false表示矩形与画布区域相交。
* @return 函数返回执行错误码。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数canvas、rect或者quickReject为空。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数canvas、rect或者quickReject为空。
* @since 18
* @version 1.0
*/
@@ -1060,13 +1101,13 @@ OH_Drawing_ErrorCode OH_Drawing_CanvasQuickRejectRect(OH_Drawing_Canvas* canvas,
bool* quickReject);
/**
- * @brief 检查当前图层绘制设备是否是不透明的。
+ * @brief 检查当前绘制到设备上的图层是否是不透明的。
*
- * @param canvas 指向 OH_Drawing_Canvas 对象的指针。
- * @param isOpaque 表示画布是否为不透明。
- * @return 返回错误码。
- * 如果操作成功，返回OH_DRAWING_SUCCESS。
- * 如果 canvas 或 isOpaque 为空，返回 OH_DRAWING_ERROR_INCORRECT_PARAMETER。
+ * @param canvas 指向画布对象{@link OH_Drawing_Canvas}的指针。
+ * @param isOpaque 输出参数，表示画布是否不透明，true表示不透明，false表示透明。
+ * @return 函数返回执行错误码。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INCORRECT_PARAMETER，表示参数canvas或者isOpaque为空。
* @since 26.0.0
*/
OH_Drawing_ErrorCode OH_Drawing_CanvasIsOpaque(const OH_Drawing_Canvas* canvas, bool* isOpaque);
diff --git a/zh-cn/graphic/graphic_2d/native_drawing/drawing_filter.h b/zh-cn/graphic/graphic_2d/native_drawing/drawing_filter.h
index 95e670669..3f5de45a4 100644
--- a/zh-cn/graphic/graphic_2d/native_drawing/drawing_filter.h
+++ b/zh-cn/graphic/graphic_2d/native_drawing/drawing_filter.h
@@ -25,7 +25,8 @@
/**
* @file drawing_filter.h
*
- * @brief This file declares the functions related to the filter in the drawing module.
+ * @brief 声明与绘图模块中的滤波器对象相关的函数。
+ *
本模块为单线程模型策略，需要调用方自行管理线程安全和上下文状态的切换。
*
* @kit ArkGraphics2D
* @library libnative_drawing.so
@@ -54,8 +55,8 @@ OH_Drawing_Filter* OH_Drawing_FilterCreate(void);
/**
* @brief 为滤波器对象设置图像滤波器对象。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * filter为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
filter为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param filter 指示指向滤波器对象{@link OH_Drawing_Filter}的指针。
* @param imageFilter 指示指向图像滤波器{@link OH_Drawing_ImageFilter}对象的指针，为NULL表示清空滤波器对象中的图像滤波器效果。
@@ -66,8 +67,8 @@ void OH_Drawing_FilterSetImageFilter(OH_Drawing_Filter* filter, OH_Drawing_Image
/**
* @brief 为滤波器对象设置蒙版滤波器对象。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * filter为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
filter为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param filter 指示指向滤波器对象{@link OH_Drawing_Filter}的指针。
* @param maskFilter 指示指向蒙版滤波器对象{@link OH_Drawing_MaskFilter}的指针，为NULL表示清空滤波器对象中的蒙版滤波器效果。
@@ -78,8 +79,8 @@ void OH_Drawing_FilterSetMaskFilter(OH_Drawing_Filter* filter, OH_Drawing_MaskFi
/**
* @brief 为滤波器对象设置颜色滤波器对象。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * filter为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
filter为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param filter 指示指向滤波器对象{@link OH_Drawing_Filter}的指针。
* @param colorFilter 指示指向颜色滤波器对象{@link OH_Drawing_ColorFilter}的指针，为NULL表示清空滤波器对象中的颜色滤波器效果。
@@ -90,8 +91,8 @@ void OH_Drawing_FilterSetColorFilter(OH_Drawing_Filter* filter, OH_Drawing_Color
/**
* @brief 从滤波器对象获取颜色滤波器对象。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * filter、colorFilter任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
filter、colorFilter任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param filter 指示指向滤波器对象{@link OH_Drawing_Filter}的指针。
* @param colorFilter 指示指向颜色滤波器对象{@link OH_Drawing_ColorFilter}的指针。
diff --git a/zh-cn/graphic/graphic_2d/native_drawing/drawing_mask_filter.h b/zh-cn/graphic/graphic_2d/native_drawing/drawing_mask_filter.h
index 3db9d4488..e61aafeeb 100644
--- a/zh-cn/graphic/graphic_2d/native_drawing/drawing_mask_filter.h
+++ b/zh-cn/graphic/graphic_2d/native_drawing/drawing_mask_filter.h
@@ -25,7 +25,8 @@
/**
* @file drawing_mask_filter.h
*
- * @brief This file declares the functions related to the mask filter in the drawing module.
+ * @brief 声明与绘图模块中的对象相关的函数。
+ *
本模块为单线程模型策略，需要调用方自行管理线程安全和上下文状态的切换。
*
* @kit ArkGraphics2D
* @library libnative_drawing.so
@@ -55,7 +56,7 @@ typedef enum {
*/
NORMAL,
/**
- * 内部实体，外部模糊。
+ * 内部实心，外部模糊。
*/
SOLID,
/**
@@ -69,11 +70,13 @@ typedef enum {
} OH_Drawing_BlurType;
/**
- * @brief 创建具有模糊效果的蒙版滤波器。
+ * @brief 创建具有模糊效果的蒙版滤波器。常用于为图形、文本等绘制内容添加模糊视觉效果。创建的蒙版滤波器对象使用完毕后，
+ * 必须调用{@link OH_Drawing_MaskFilterDestroy}销毁并释放内存。
*
- * @param blurType 表示模糊类型。
- * @param sigma 表示要应用的高斯模糊的标准偏差。必须大于0。
- * @param respectCTM 表示模糊标准差值被CTM（当前变换矩阵）修改，默认为真。true表示模糊标准差值受CTM影响，false表示模糊标准差值固定，不受CTM影响。
+ * @param blurType 表示模糊类型，用于指定蒙版滤波器的模糊操作方式。
+ * @param sigma 表示要应用的高斯模糊的标准差，单位为px。必须大于0。
+ * @param respectCTM 表示模糊标准差值是否受CTM（当前变换矩阵）影响。传入true表示受CTM影响，传入false表示不受CTM影响，
+ * 标准差值固定。
* @return 返回创建的蒙版滤波器对象的指针。
* @since 11
* @version 1.0
diff --git a/zh-cn/graphic/graphic_2d/native_drawing/drawing_matrix.h b/zh-cn/graphic/graphic_2d/native_drawing/drawing_matrix.h
index eae17c6ff..46d9ddbc5 100644
--- a/zh-cn/graphic/graphic_2d/native_drawing/drawing_matrix.h
+++ b/zh-cn/graphic/graphic_2d/native_drawing/drawing_matrix.h
@@ -25,7 +25,9 @@
/**
* @file drawing_matrix.h
*
- * @brief This file declares the functions related to the matrix in the drawing module.
+ * @brief 文件中定义了矩阵的创建、拷贝、变换（旋转、缩放、平移、倾斜）、查询（判断相等、判断单位矩阵、
+ * 获取元素值）和映射等功能函数。
+ *
本模块为单线程模型策略，需要调用方自行管理线程安全和上下文状态的切换。
*
* @kit ArkGraphics2D
* @library libnative_drawing.so
@@ -45,19 +47,21 @@ extern "C" {
#endif
/**
- * @brief 用于创建一个矩阵对象。
+ * @brief 用于创建一个矩阵对象。调用此函数创建的矩阵对象，
+ * 在使用完毕后必须调用{@link OH_Drawing_MatrixDestroy}释放该对象占用的内存，否则会导致内存泄漏。
*
- * @return 函数会返回一个指针，指针指向创建的矩阵对象。
+ * @return 函数返回一个指针，指针指向创建的矩阵对象{@link OH_Drawing_Matrix}。
* @since 11
* @version 1.0
*/
OH_Drawing_Matrix* OH_Drawing_MatrixCreate(void);
/**
- * @brief 用于创建一个矩阵对象的拷贝。
+ * @brief 用于创建一个矩阵对象的拷贝。调用此函数返回的是一个新的独立矩阵对象，
+ * 在使用完毕后必须调用{@link OH_Drawing_MatrixDestroy}单独释放拷贝对象占用的内存，否则会导致内存泄漏。
*
* @param matrix 指向用于拷贝的矩阵对象{@link OH_Drawing_Matrix}的指针。
- * @return 函数会返回一个指针，指针指向创建的新矩阵对象。
+ * @return 函数返回一个指针，指针指向创建的新矩阵对象{@link OH_Drawing_Matrix}。
* @since 20
* @version 1.0
*/
@@ -65,12 +69,14 @@ OH_Drawing_Matrix* OH_Drawing_MatrixCopy(const OH_Drawing_Matrix* matrix);
/**
* @brief 创建一个带旋转属性的矩阵对象。
- * 该矩阵对象为：单位矩阵在(x, y)旋转点以度为单位进行旋转后得到的矩阵。
+ *
该矩阵对象为：单位矩阵在(x, y)旋转中心点以度为单位进行旋转后得到的矩阵。调用此函数创建的矩阵对象，
+ * 在使用完毕后必须调用{@link OH_Drawing_MatrixDestroy}释放该对象占用的内存，
+ * 否则会导致内存泄漏。
*
- * @param deg 旋转的角度，单位为度。正数表示按顺时针旋转，负数表示按逆时针旋转。
- * @param x x轴上坐标点。
- * @param y y轴上坐标点。
- * @return 函数会返回一个指针，指针指向创建的新矩阵对象。
+ * @param deg 旋转的角度，单位为度。正数表示顺时针旋转，负数表示逆时针旋转。
+ * @param x 旋转中心点的x轴坐标，单位为物理像素px。
+ * @param y 旋转中心点的y轴坐标，单位为物理像素px。
+ * @return 函数返回一个指针，指针指向创建的矩阵对象{@link OH_Drawing_Matrix}。
* @since 12
* @version 1.0
*/
@@ -78,12 +84,13 @@ OH_Drawing_Matrix* OH_Drawing_MatrixCreateRotation(float deg, float x, float y);
/**
* @brief 创建一个带缩放属性的矩阵对象。
- * 该矩阵对象为：单位矩阵在(px, py)旋转点以sx和sy为缩放因子进行缩放后得到的矩阵。
+ *
该矩阵对象为：单位矩阵在(px, py)缩放中心点以sx和sy为缩放因子进行缩放后得到的矩阵。调用此函数创建的矩阵对象，
+ * 在使用完毕后必须调用{@link OH_Drawing_MatrixDestroy}释放该对象占用的内存。
*
- * @param sx 水平缩放因子，为负数时可看作是先关于y = px作镜像翻转后再进行缩放，该参数为浮点数。
- * @param sy 垂直缩放因子，为负数时可看作是先关于x = py作镜像翻转后再进行缩放，该参数为浮点数。
- * @param px x轴上坐标点。
- * @param py y轴上坐标点。
+ * @param sx 水平缩放因子，为负数时可看作是先关于x = px作镜像翻转后再进行缩放。
+ * @param sy 垂直缩放因子，为负数时可看作是先关于y = py作镜像翻转后再进行缩放。
+ * @param px 缩放中心点的x轴坐标，单位为物理像素px。
+ * @param py 缩放中心点的y轴坐标，单位为物理像素px。
* @return 函数返回一个指针，指针指向创建的矩阵对象{@link OH_Drawing_Matrix}。
* @since 12
* @version 1.0
@@ -92,10 +99,11 @@ OH_Drawing_Matrix* OH_Drawing_MatrixCreateScale(float sx, float sy, float px, fl
/**
* @brief 创建一个带平移属性的矩阵对象。
- * 该矩阵对象为：单位矩阵平移(dx, dy)后得到的矩阵。
+ *
该矩阵对象为：单位矩阵平移(dx, dy)后得到的矩阵。调用此函数创建的矩阵对象，
+ * 在使用完毕后必须调用{@link OH_Drawing_MatrixDestroy}释放该对象占用的内存，否则会导致内存泄漏。
*
- * @param dx 水平方向平移距离，正数表示往x轴正方向平移，负数表示往x轴负方向平移，该参数为浮点数。
- * @param dy 垂直方向平移距离，正数表示往y轴正方向平移，负数表示往y轴负方向平移，该参数为浮点数。
+ * @param dx 水平方向平移距离，单位为物理像素px。正数表示往x轴正方向平移，负数表示往x轴负方向平移。
+ * @param dy 垂直方向平移距离，单位为物理像素px。正数表示往y轴正方向平移，负数表示往y轴负方向平移。
* @return 函数返回一个指针，指针指向创建的矩阵对象{@link OH_Drawing_Matrix}。
* @since 12
* @version 1.0
@@ -103,19 +111,19 @@ OH_Drawing_Matrix* OH_Drawing_MatrixCreateScale(float sx, float sy, float px, fl
OH_Drawing_Matrix* OH_Drawing_MatrixCreateTranslation(float dx, float dy);
/**
- * @brief 用于给矩阵对象设置参数。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * OH_Drawing_Matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ * @brief 用于给矩阵对象设置变换参数，包括缩放、倾斜、位移和透视系数。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
OH_Drawing_Matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param matrix 指向矩阵对象的指针。
- * @param scaleX 水平缩放系数。
+ * @param scaleX 水平缩放因子。
* @param skewX 水平倾斜系数。
* @param transX 水平位移系数。
* @param skewY 垂直倾斜系数。
- * @param scaleY 垂直缩放系数。
+ * @param scaleY 垂直缩放因子。
* @param transY 垂直位移系数。
- * @param persp0 X轴透视系数。
- * @param persp1 Y轴透视系数。
+ * @param persp0 x轴透视系数。
+ * @param persp1 y轴透视系数。
* @param persp2 透视缩放系数。
* @since 11
* @version 1.0
@@ -131,7 +139,7 @@ void OH_Drawing_MatrixSetMatrix(OH_Drawing_Matrix* matrix, float scaleX, float s
*/
typedef enum {
/**
- * 按水平轴和垂直轴缩放以填充目标矩形。
+ * 按水平轴和垂直轴缩放以填充目标矩形，不保留源矩形宽高比例。
*/
SCALE_TO_FIT_FILL,
/**
@@ -149,17 +157,17 @@ typedef enum {
} OH_Drawing_ScaleToFit;
/**
- * @brief 将矩阵以缩放方式适配目标矩阵。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * matrix、src、dst任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ * @brief 将矩阵以缩放方式适配目标矩形。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
matrix、src或dst任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param matrix 指向矩阵对象{@link OH_Drawing_Matrix}的指针。
- * @param src 指向映射源的{@link OH_Drawing_Rect}对象Rect的指针。
- * @param dst 指向要映射到的{@link OH_Drawing_Rect}对象Rect的指针。
- * @param stf 缩放方式，支持方式{@link OH_Drawing_ScaleToFit}。
- * @return 如果设置失败，则返回false；如果设置成功，则返回true；如果矩阵为空，则返回true，并将矩阵设置为：
- * 如果源矩形src的宽高任意一个小于等于0，则返回false，并将矩阵设置为单位矩阵；
- * 如果目标矩形dst的宽高任意一个小于等于0，则返回true，并将矩阵设置为除透视缩放系数为1外其余值皆为0的矩阵;
+ * @param src 指向源矩形对象{@link OH_Drawing_Rect}的指针。
+ * @param dst 指向目标矩形对象{@link OH_Drawing_Rect}的指针。
+ * @param stf 缩放方式，详见{@link OH_Drawing_ScaleToFit}。
+ * @return 如果设置成功，则返回true；如果设置失败，则返回false。特殊情况：
+ *
如果源矩形src的宽高任意一个小于等于0，则返回false，并将矩阵设置为单位矩阵；
+ *
如果目标矩形dst的宽高任意一个小于等于0，则返回true，并将矩阵设置为除透视缩放系数为1外其余值皆为0的矩阵。
* @since 12
* @version 1.0
*/
@@ -167,82 +175,84 @@ bool OH_Drawing_MatrixSetRectToRect(OH_Drawing_Matrix* matrix, const OH_Drawing_
const OH_Drawing_Rect* dst, OH_Drawing_ScaleToFit stf);
/**
- * @brief 将矩阵设置为矩阵左乘围绕轴心点旋转一定角度的单位矩阵后得到的矩阵。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ * @brief 将矩阵设置为矩阵左乘围绕旋转中心点旋转degree指定角度的单位矩阵后得到的矩阵。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param matrix 指向矩阵对象{@link OH_Drawing_Matrix}的指针。
* @param degree 旋转角度，单位为度。正数表示顺时针旋转，负数表示逆时针旋转。
- * @param px 旋转中心点的横坐标。
- * @param py 旋转中心点的纵坐标。
+ * @param px 旋转中心点的x轴坐标，单位为物理像素px。
+ * @param py 旋转中心点的y轴坐标，单位为物理像素px。
* @since 12
* @version 1.0
*/
void OH_Drawing_MatrixPreRotate(OH_Drawing_Matrix* matrix, float degree, float px, float py);
/**
- * @brief 将矩阵设置为矩阵左乘围绕轴心点按一定缩放因子缩放后的单位矩阵后得到的矩阵。
+ * @brief 将矩阵设置为矩阵左乘围绕缩放中心点按缩放因子sx和sy缩放后的单位矩阵后得到的矩阵。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param matrix 指向矩阵对象{@link OH_Drawing_Matrix}的指针。
- * @param sx x轴方向的缩放比例因子，为负数时可看作是先关于y = px作镜像翻转后再进行缩放，该参数为浮点数。
- * @param sy y轴方向的缩放比例因子，为负数时可看作是先关于x = py作镜像翻转后再进行缩放，该参数为浮点数。
- * @param px 缩放中心点的横坐标。
- * @param py 缩放中心点的纵坐标。
+ * @param sx 水平缩放因子，为负数时可看作是先关于x = px作镜像翻转后再进行缩放。
+ * @param sy 垂直缩放因子，为负数时可看作是先关于y = py作镜像翻转后再进行缩放。
+ * @param px 缩放中心点的x轴坐标，单位为物理像素px。
+ * @param py 缩放中心点的y轴坐标，单位为物理像素px。
* @since 12
* @version 1.0
*/
void OH_Drawing_MatrixPreScale(OH_Drawing_Matrix* matrix, float sx, float sy, float px, float py);
/**
- * @brief 将矩阵设置为矩阵左乘平移一定距离后的单位矩阵后得到的矩阵。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ * @brief 将矩阵设置为矩阵左乘平移dx和dy距离后的单位矩阵后得到的矩阵。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param matrix 指向矩阵对象{@link OH_Drawing_Matrix}的指针。
- * @param dx 表示在x轴方向上的平移距离，正数表示往x轴正方向平移，负数表示往x轴负方向平移，该参数为浮点数。
- * @param dy 表示在y轴方向上的平移距离，正数表示往y轴正方向平移，负数表示往y轴负方向平移，该参数为浮点数。
+ * @param dx 水平方向平移距离，单位为物理像素px。正数表示往x轴正方向平移，负数表示往x轴负方向平移。
+ * @param dy 垂直方向平移距离，单位为物理像素px。正数表示往y轴正方向平移，负数表示往y轴负方向平移。
* @since 12
* @version 1.0
*/
void OH_Drawing_MatrixPreTranslate(OH_Drawing_Matrix* matrix, float dx, float dy);
/**
- * @brief 将矩阵设置为矩阵右乘围绕轴心点旋转一定角度的单位矩阵后得到的矩阵。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ * @brief 将矩阵设置为矩阵右乘围绕旋转中心点旋转degree角度的单位矩阵后得到的矩阵。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param matrix 指向矩阵对象{@link OH_Drawing_Matrix}的指针。
* @param degree 旋转角度，单位为度。正数表示顺时针旋转，负数表示逆时针旋转。
- * @param px 旋转中心点的横坐标。
- * @param py 旋转中心点的纵坐标。
+ * @param px 旋转中心点的x轴坐标，单位为物理像素px。
+ * @param py 旋转中心点的y轴坐标，单位为物理像素px。
* @since 12
* @version 1.0
*/
void OH_Drawing_MatrixPostRotate(OH_Drawing_Matrix* matrix, float degree, float px, float py);
/**
- * @brief 将矩阵设置为矩阵右乘围绕轴心点按一定缩放因子缩放后的单位矩阵后得到的矩阵。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ * @brief 将矩阵设置为矩阵右乘围绕缩放中心点按sx和sy缩放因子缩放后的单位矩阵后得到的矩阵。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param matrix 指向矩阵对象{@link OH_Drawing_Matrix}的指针。
- * @param sx x轴方向的缩放比例因子，为负数时可看作是先关于y = px作镜像翻转后再进行缩放，该参数为浮点数。
- * @param sy y轴方向的缩放比例因子，为负数时可看作是先关于x = py作镜像翻转后再进行缩放，该参数为浮点数。
- * @param px 缩放中心点的横坐标。
- * @param py 缩放中心点的纵坐标。
+ * @param sx 水平缩放因子，为负数时可看作是先关于x = px作镜像翻转后再进行缩放。
+ * @param sy 垂直缩放因子，为负数时可看作是先关于y = py作镜像翻转后再进行缩放。
+ * @param px 缩放中心点的x轴坐标，单位为物理像素px。
+ * @param py 缩放中心点的y轴坐标，单位为物理像素px。
* @since 12
* @version 1.0
*/
void OH_Drawing_MatrixPostScale(OH_Drawing_Matrix* matrix, float sx, float sy, float px, float py);
/**
- * @brief 将矩阵设置为矩阵右乘平移一定距离后的单位矩阵后得到的矩阵。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ * @brief 将矩阵设置为矩阵右乘平移dx和dy距离后的单位矩阵后得到的矩阵。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param matrix 指向矩阵对象{@link OH_Drawing_Matrix}的指针。
- * @param dx 表示在x轴方向上的平移距离，正数表示往x轴正方向平移，负数表示往x轴负方向平移，该参数为浮点数。
- * @param dy 表示在y轴方向上的平移距离，正数表示往y轴正方向平移，负数表示往y轴负方向平移，该参数为浮点数。
+ * @param dx 水平方向平移距离，单位为物理像素px。正数表示往x轴正方向平移，负数表示往x轴负方向平移。
+ * @param dy 垂直方向平移距离，单位为物理像素px。正数表示往y轴正方向平移，负数表示往y轴负方向平移。
* @since 12
* @version 1.0
*/
@@ -250,8 +260,8 @@ void OH_Drawing_MatrixPostTranslate(OH_Drawing_Matrix* matrix, float dx, float d
/**
* @brief 重置当前矩阵为单位矩阵。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param matrix 指向矩阵对象{@link OH_Drawing_Matrix}的指针。
* @since 12
@@ -261,8 +271,8 @@ void OH_Drawing_MatrixReset(OH_Drawing_Matrix* matrix);
/**
* @brief 将矩阵total设置为矩阵a乘以矩阵b。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * total、a、b任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
total、a或b任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param total 指向最终的矩阵对象{@link OH_Drawing_Matrix}的指针。
* @param a 指向矩阵对象a{@link OH_Drawing_Matrix}的指针。
@@ -274,26 +284,27 @@ void OH_Drawing_MatrixConcat(OH_Drawing_Matrix* total, const OH_Drawing_Matrix*
const OH_Drawing_Matrix* b);
/**
- * @brief 获取矩阵所有元素值。
+ * @brief 获取矩阵所有元素值。9个元素按行主序存储，对应3×3矩阵结构，具体排列方式参见{@link OH_Drawing_MatrixSetMatrix}。
*
* @param matrix 指向矩阵对象{@link OH_Drawing_Matrix}的指针。
* @param value 用于存储得到的矩阵元素值的数组。
* @return 返回错误码。
- * 返回OH_DRAWING_SUCCESS，表示成功获取矩阵的所有元素值。
- * 返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示获取矩阵元素值失败，原因是矩阵对象或者存储矩阵元素值数组为空。
+ *
返回OH_DRAWING_SUCCESS，表示成功获取矩阵的所有元素值。
+ *
返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示matrix或value为NULL。
* @since 12
* @version 1.0
*/
OH_Drawing_ErrorCode OH_Drawing_MatrixGetAll(OH_Drawing_Matrix* matrix, float value[9]);
/**
- * @brief 对矩阵a左乘矩阵b。
+ * @brief 对矩阵a左乘矩阵b。与{@link OH_Drawing_MatrixConcat}功能类似，
+ * 区别在于OH_Drawing_MatrixConcat将结果存入单独的total矩阵，而本方法直接修改矩阵a。
*
- * @param a 指向矩阵对象{@link OH_Drawing_Matrix}的指针。
- * @param b 指向矩阵对象{@link OH_Drawing_Matrix}的指针。
+ * @param a 指向被左乘的矩阵对象{@link OH_Drawing_Matrix}的指针，左乘后该矩阵会被修改为a × b的结果。
+ * @param b 指向作为乘数的矩阵对象{@link OH_Drawing_Matrix}的指针。
* @return 返回错误码。
- * 返回OH_DRAWING_SUCCESS，表示成功执行左乘方法。
- * 返回OH_DRAWING_ERROR_INCORRECT_PARAMETER，表示入参异常，rect或other为空。
+ *
返回OH_DRAWING_SUCCESS，表示成功执行左乘方法。
+ *
返回OH_DRAWING_ERROR_INCORRECT_PARAMETER，表示a或b为NULL。
* @since 22
* @version 1.0
*/
@@ -301,9 +312,9 @@ OH_Drawing_ErrorCode OH_Drawing_MatrixPreConcat(OH_Drawing_Matrix* a, OH_Drawing
/**
* @brief 获取矩阵给定索引位的值。索引范围0-8。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER；
- * index小于0或者大于8时返回OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER；
+ *
index小于0或者大于8时返回OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE。
*
* @param matrix 指向矩阵对象{@link OH_Drawing_Matrix}的指针。
* @param index 索引位置，范围0-8。
@@ -314,14 +325,14 @@ OH_Drawing_ErrorCode OH_Drawing_MatrixPreConcat(OH_Drawing_Matrix* a, OH_Drawing
float OH_Drawing_MatrixGetValue(OH_Drawing_Matrix* matrix, int index);
/**
- * @brief 设置矩阵为单位矩阵，并围绕位于(px, py)的旋转轴点进行旋转。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ * @brief 设置矩阵为单位矩阵，并围绕位于(px, py)的旋转中心点进行旋转。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param matrix 指向矩阵对象{@link OH_Drawing_Matrix}的指针。
* @param degree 角度，单位为度。正数表示顺时针旋转，负数表示逆时针旋转。
- * @param px x轴上坐标点。
- * @param py y轴上坐标点。
+ * @param px 旋转中心点的x轴坐标，单位为物理像素px。
+ * @param py 旋转中心点的y轴坐标，单位为物理像素px。
* @since 12
* @version 1.0
*/
@@ -329,27 +340,27 @@ void OH_Drawing_MatrixRotate(OH_Drawing_Matrix* matrix, float degree, float px,
/**
* @brief 设置矩阵为单位矩阵，并平移(dx, dy)。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param matrix 指向矩阵对象{@link OH_Drawing_Matrix}的指针。
- * @param dx 水平方向平移距离，正数表示往x轴正方向平移，负数表示往x轴负方向平移，该参数为浮点数。
- * @param dy 垂直方向平移距离，正数表示往y轴正方向平移，负数表示往y轴负方向平移，该参数为浮点数。
+ * @param dx 水平方向平移距离，单位为物理像素px。正数表示往x轴正方向平移，负数表示往x轴负方向平移。
+ * @param dy 垂直方向平移距离，单位为物理像素px。正数表示往y轴正方向平移，负数表示往y轴负方向平移。
* @since 12
* @version 1.0
*/
void OH_Drawing_MatrixTranslate(OH_Drawing_Matrix* matrix, float dx, float dy);
/**
- * @brief 设置矩阵为单位矩阵，并围绕位于(px, py)的旋转轴点，以sx和sy进行缩放。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ * @brief 设置矩阵为单位矩阵，并围绕位于(px, py)的缩放中心点，以sx和sy进行缩放。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param matrix 指向矩阵对象{@link OH_Drawing_Matrix}的指针。
- * @param sx 水平缩放因子，为负数时可看作是先关于y = px作镜像翻转后再进行缩放，该参数为浮点数。
- * @param sy 垂直缩放因子，为负数时可看作是先关于x = py作镜像翻转后再进行缩放，该参数为浮点数。
- * @param px x轴上坐标点。
- * @param py y轴上坐标点。
+ * @param sx 水平缩放因子，为负数时可看作是先关于x = px作镜像翻转后再进行缩放。
+ * @param sy 垂直缩放因子，为负数时可看作是先关于y = py作镜像翻转后再进行缩放。
+ * @param px 缩放中心点的x轴坐标，单位为物理像素px。
+ * @param py 缩放中心点的y轴坐标，单位为物理像素px。
* @since 12
* @version 1.0
*/
@@ -357,8 +368,8 @@ void OH_Drawing_MatrixScale(OH_Drawing_Matrix* matrix, float sx, float sy, float
/**
* @brief 将矩阵inverse设置为矩阵的逆矩阵，并返回结果。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * matrix、inverse任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
matrix或inverse任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param matrix 指向矩阵对象{@link OH_Drawing_Matrix}的指针。
* @param inverse 指向逆矩阵对象{@link OH_Drawing_Matrix}的指针，开发者可调用{@link OH_Drawing_MatrixCreate}接口创建。
@@ -370,15 +381,16 @@ bool OH_Drawing_MatrixInvert(OH_Drawing_Matrix* matrix, OH_Drawing_Matrix* inver
/**
* @brief 通过设置源点以及目标点，生成对应的变换矩阵。
- * 源点以及目标点的个数要大于等于0，小于等于4。本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER；
- * count小于0或者大于4时返回OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE。
+ *
源点以及目标点的个数要大于等于0，小于等于4。本接口会产生错误码，
+ * 可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER；
+ *
count小于0或者大于4时返回OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE。
*
* @param matrix 指向矩阵对象{@link OH_Drawing_Matrix}的指针。
* @param src 源点数组，为NULL时count应当为0。
* @param dst 目标点数组，个数要与源点相等，为NULL时count应当为0。
- * @param count 源点数组以及目标点数组的个数，为0时将矩阵对象设为单位矩阵。
- * @return 函数返回是否可以生成对应矩阵以用来完成变换。true表示矩阵生成成功，false表示无法生成对应矩阵。
+ * @param count 源点数组以及目标点数组的个数，取值范围为[0, 4]，为0时将矩阵对象设为单位矩阵。
+ * @return 函数返回是否可以生成对应矩阵用来完成变换。true表示矩阵生成成功，false表示无法生成对应矩阵。
* @since 12
* @version 1.0
*/
@@ -387,13 +399,13 @@ bool OH_Drawing_MatrixSetPolyToPoly(OH_Drawing_Matrix* matrix, const OH_Drawing_
/**
* @brief 通过矩阵变换将源点数组映射到目标点数组。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * matrix、src、dst任意一个为NULL或者count小于等于0时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
matrix、src或dst任意一个为NULL或者count小于等于0时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param matrix 指向矩阵对象{@link OH_Drawing_Matrix}的指针。
- * @param src 源点数组。
- * @param dst 目标点数组，个数要与源点相等。
- * @param count 源点数组以及目标点数组的个数。
+ * @param src 源点数组，数组长度应大于等于count，否则可能导致越界访问。
+ * @param dst 目标点数组，数组长度应大于等于count，否则可能导致越界访问。
+ * @param count 源点数组以及目标点数组的个数，必须大于0。
* @since 12
* @version 1.0
*/
@@ -402,12 +414,12 @@ void OH_Drawing_MatrixMapPoints(const OH_Drawing_Matrix* matrix, const OH_Drawin
/**
* @brief 将目标矩形设置为一个新的矩形，该矩形是能够包围源矩形的四个顶点通过矩阵变换映射后形成的新顶点的最小矩形。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * matrix、src、dst任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
matrix、src或dst任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param matrix 指向矩阵对象{@link OH_Drawing_Matrix}的指针。
- * @param src 源矩形。
- * @param dst 目标矩形。
+ * @param src 指向源矩形{@link OH_Drawing_Rect}的指针。
+ * @param dst 指向目标矩形{@link OH_Drawing_Rect}的指针，用于存储映射后的结果。
* @return 函数返回源矩形与映射后的目标矩形是否相等。true表示相等，false表示不相等。
* @since 12
* @version 1.0
@@ -416,8 +428,8 @@ bool OH_Drawing_MatrixMapRect(const OH_Drawing_Matrix* matrix, const OH_Drawing_
/**
* @brief 判断两个矩阵是否相等。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * matrix、other任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
matrix或other任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param matrix 指向用于判断的其中一个矩阵对象{@link OH_Drawing_Matrix}的指针。
* @param other 指向用于判断的另一个矩阵对象{@link OH_Drawing_Matrix}的指针。
@@ -428,9 +440,10 @@ bool OH_Drawing_MatrixMapRect(const OH_Drawing_Matrix* matrix, const OH_Drawing_
bool OH_Drawing_MatrixIsEqual(OH_Drawing_Matrix* matrix, OH_Drawing_Matrix* other);
/**
- * @brief 判断矩阵是否是单位矩阵。
- * 单位矩阵为 : | 1 0 0 || 0 1 0 || 0 0 1 |本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ * @brief 判断矩阵是否是单位矩阵。单位矩阵为：`[1 0 0; 0 1 0; 0 0 1]`。
+ *
如需判断两个矩阵是否相等，请使用{@link OH_Drawing_MatrixIsEqual}。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
matrix为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param matrix 指向矩阵对象{@link OH_Drawing_Matrix}的指针。
* @return 函数返回true表示矩阵是单位矩阵，函数返回false表示矩阵不是单位矩阵。
@@ -445,42 +458,47 @@ bool OH_Drawing_MatrixIsIdentity(OH_Drawing_Matrix* matrix);
* @param matrix 指向矩阵对象{@link OH_Drawing_Matrix}的指针。
* @param isAffine 表示当前矩阵是否为仿射矩阵。作为出参使用。true表示当前矩阵是仿射矩阵，false表示当前矩阵不是仿射矩阵。
* @return 函数返回执行结果。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INCORRECT_PARAMETER，表示matrix或isAffine是空指针。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INCORRECT_PARAMETER，表示matrix或isAffine为NULL。
* @since 23
*/
OH_Drawing_ErrorCode OH_Drawing_MatrixIsAffine(const OH_Drawing_Matrix* matrix, bool* isAffine);
/**
- * @brief 将当前矩阵左乘一个以(px, py)为中心按(kx, ky)倾斜构造的矩阵。
+ * @brief 将当前矩阵左乘一个以(px, py)为中心按(kx, ky)倾斜构造的矩阵。与{@link OH_Drawing_MatrixPreRotate}、
+ * {@link OH_Drawing_MatrixPreScale}、
+ * {@link OH_Drawing_MatrixPreTranslate}同属Pre系列方法。
*
* @param matrix 指向矩阵对象{@link OH_Drawing_Matrix}的指针。
* @param kx 表示x轴上的倾斜量。
* @param ky 表示y轴上的倾斜量。
- * @param px 表示倾斜中心点的x轴坐标。
- * @param py 表示倾斜中心点的y轴坐标。
+ * @param px 表示倾斜中心点的x轴坐标，单位为物理像素px。
+ * @param py 表示倾斜中心点的y轴坐标，单位为物理像素px。
* @return 函数返回执行结果。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INCORRECT_PARAMETER，表示matrix是空指针。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INCORRECT_PARAMETER，表示matrix为NULL。
* @since 23
*/
OH_Drawing_ErrorCode OH_Drawing_MatrixPreSkew(OH_Drawing_Matrix* matrix, float kx, float ky, float px, float py);
/**
- * @brief 判断矩形经过当前矩阵映射后是否仍保持矩形形状。当矩阵是单位矩阵或仅包含平移、缩放、旋转90度倍数等仿射变换时满足该条件。
+ * @brief 判断矩形经过当前矩阵映射后是否仍保持矩形形状。当矩阵是单位矩阵或仅包含平移、缩放、
+ * 旋转90度倍数这类仿射变换时满足该条件。
*
* @param matrix 指向矩阵对象{@link OH_Drawing_Matrix}的指针。
* @param isRectStaysRect 表示经过该矩阵映射后的矩形的形状是否仍为矩形。作为出参使用。
- * true表示映射后的矩形形状是矩形，false表示映射后的矩形形状不是矩形。
+ *
true表示映射后的矩形形状是矩形，false表示映射后的矩形形状不是矩形。
* @return 函数返回执行结果。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INCORRECT_PARAMETER，表示matrix或isRectStaysRect是空指针。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INCORRECT_PARAMETER，表示matrix或isRectStaysRect为NULL。
* @since 23
*/
OH_Drawing_ErrorCode OH_Drawing_MatrixRectStaysRect(const OH_Drawing_Matrix* matrix, bool* isRectStaysRect);
/**
* @brief 设置矩阵，使其围绕旋转中心 (px, py) 以指定的正弦值和余弦值进行旋转。
+ * 与{@link OH_Drawing_MatrixRotate}功能类似，
+ * 区别在于OH_Drawing_MatrixRotate直接传入角度值，而本方法传入正弦值和余弦值。
*
* @param matrix 指向矩阵对象{@link OH_Drawing_Matrix}的指针。
* @param sinValue 表示旋转角度的正弦值。
@@ -488,15 +506,15 @@ OH_Drawing_ErrorCode OH_Drawing_MatrixRectStaysRect(const OH_Drawing_Matrix* mat
* @param px 表示旋转中心的x轴坐标。
* @param py 表示旋转中心的y轴坐标。
* @return 函数返回执行结果。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INCORRECT_PARAMETER，表示matrix是空指针。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INCORRECT_PARAMETER，表示matrix为NULL。
* @since 23
*/
OH_Drawing_ErrorCode OH_Drawing_MatrixSetSinCos(OH_Drawing_Matrix* matrix, float sinValue, float cosValue,
float px, float py);
/**
- * @brief 用于销毁矩阵对象并回收该对象占有的内存。
+ * @brief 用于销毁矩阵对象并回收该对象占用的内存。
*
* @param matrix 指向矩阵对象的指针。
* @since 11
diff --git a/zh-cn/graphic/graphic_2d/native_drawing/drawing_memory_stream.h b/zh-cn/graphic/graphic_2d/native_drawing/drawing_memory_stream.h
index 5bf248100..3f9624c08 100644
--- a/zh-cn/graphic/graphic_2d/native_drawing/drawing_memory_stream.h
+++ b/zh-cn/graphic/graphic_2d/native_drawing/drawing_memory_stream.h
@@ -25,7 +25,9 @@
/**
* @file drawing_memory_stream.h
*
- * @brief This file declares the functions related to the memory stream in the drawing module.
+ * @brief 文件中定义了与内存流相关的功能函数，支持基于内存数据创建和销毁内存流对象。
+ * 内存流支持数据拷贝或直接引用两种访问方式。
+ *
本模块为单线程模型策略，需要调用方自行管理线程安全和上下文状态的切换。
*
* @kit ArkGraphics2D
* @library libnative_drawing.so
@@ -44,13 +46,18 @@ extern "C" {
#endif
/**
- * @brief 创建一个内存流对象。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * data为NULL或者length等于0时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ * @brief 创建一个内存流对象，用于将内存中的数据封装为流，可作为数据源供图形处理接口（如图像解码）等后续绘制接口使用。
+ * 创建的内存流对象使用完毕后，需要调用
+ * {@link OH_Drawing_MemoryStreamDestroy()}销毁并回收内存。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
data为NULL或者length等于0时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
- * @return 函数会返回一个指针，指针指向创建的内存流对象{@link OH_Drawing_MemoryStream}。
- * @param data 数据段。
- * @param length 数据段长度。
+ * @return 指向创建的内存流对象{@link OH_Drawing_MemoryStream}的指针，
+ * 可作为数据源传递给后续图形处理接口（如图像解码）使用。
+ * @param data 要创建内存流的数据缓冲区，数据为二进制字节流，长度由length参数指定，单位为字节。data不能为NULL，
+ * 为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ * 当copyData为false时，调用者还需确保data指向的数据在内存流对象生命周期内保持有效。
+ * @param length 数据段长度，单位为字节，取值必须大于0。为0时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
* @param copyData 是否拷贝数据。true表示内存流对象会拷贝一份数据段数据，false表示内存流对象直接使用数据段数据，不拷贝。
* @since 12
* @version 1.0
@@ -58,7 +65,8 @@ extern "C" {
OH_Drawing_MemoryStream* OH_Drawing_MemoryStreamCreate(const void* data, size_t length, bool copyData);
/**
- * @brief 销毁内存流对象并回收该对象占用的内存。
+ * @brief 销毁由{@link OH_Drawing_MemoryStreamCreate()}创建的内存流对象并回收该对象占用的内存。
+ * 销毁后不应再访问内存流对象。
*
* @param memoryStream 指向内存流对象{@link OH_Drawing_MemoryStream}的指针。
* @since 12
diff --git a/zh-cn/graphic/graphic_2d/native_drawing/drawing_path_effect.h b/zh-cn/graphic/graphic_2d/native_drawing/drawing_path_effect.h
index c26657029..f77e97529 100644
--- a/zh-cn/graphic/graphic_2d/native_drawing/drawing_path_effect.h
+++ b/zh-cn/graphic/graphic_2d/native_drawing/drawing_path_effect.h
@@ -25,7 +25,12 @@
/**
* @file drawing_path_effect.h
*
- * @brief This file declares the functions related to the path effect in the drawing module.
+ * @brief 文件中定义了与路径效果相关的功能函数。路径效果是对绘制路径进行几何变换的效果处理机制，
+ * 在路径绘制到画布之前对路径的几何形状进行修改，例如将尖角变为圆角、将连续路径变为虚线等。
+ * 多个路径效果可以通过组合（按顺序依次应用）
+ * 或叠加（各自独立应用后合并结果）的方式一起使用。支持创建组合路径效果、圆角路径效果、虚线路径效果、打散路径效果、
+ * 叠加路径效果等。
+ *
本模块为单线程模型策略，需要调用方自行管理线程安全和上下文状态的切换。
*
* @kit ArkGraphics2D
* @library libnative_drawing.so
@@ -51,37 +56,40 @@ extern "C" {
*/
typedef enum {
/**
- * 表示路径效果是平移效果。
+ * 表示虚线段沿路径平移绘制，不发生旋转或变形。
*/
DRAWING_PATH_DASH_STYLE_TRANSLATE,
/**
- * 表示路径效果是旋转效果。
+ * 表示虚线段沿路径旋转，使其方向跟随路径切线方向。
*/
DRAWING_PATH_DASH_STYLE_ROTATE,
/**
- * 表示路径效果是变形效果。
+ * 表示虚线段沿路径发生变形，以适应路径走向。
*/
DRAWING_PATH_DASH_STYLE_MORPH,
} OH_Drawing_PathDashStyle;
/**
* @brief 创建路径组合的路径效果对象。首先应用内部路径效果，然后应用外部路径效果。
+ * 使用完毕后必须调用{@link OH_Drawing_PathEffectDestroy}销毁该路径效果对象，否则会导致内存泄漏。
*
* @param outer 表示组合路径效果中外部路径效果{@link OH_Drawing_PathEffect}的指针。
* @param inner 表示组合路径效果中内部路径效果{@link OH_Drawing_PathEffect}的指针。
- * @return 函数返回一个指针，指针指向创建的路径效果对象{@link OH_Drawing_PathEffect}。
- * 如果返回nullptr，则创建失败，失败的原因可能是outer或者inner为nullptr。
+ * @return 返回指向创建的路径效果对象{@link OH_Drawing_PathEffect}的指针。
+ *
如果返回nullptr，则创建失败，原因是outer或者inner为nullptr。
* @since 18
* @version 1.0
*/
OH_Drawing_PathEffect* OH_Drawing_CreateComposePathEffect(OH_Drawing_PathEffect* outer, OH_Drawing_PathEffect* inner);
/**
- * @brief 创建一个将路径的夹角变成指定半径的圆角的路径效果对象。
+ * @brief 创建一个将路径的夹角变成指定半径的圆角的路径效果对象。该路径效果会检测路径中的夹角（拐点），
+ * 并将尖角替换为指定半径的圆弧，使路径在拐点处平滑过渡。使用完毕后必须调用
+ * {@link OH_Drawing_PathEffectDestroy}销毁该路径效果对象，否则会导致内存泄漏。
*
- * @param radius 表示圆角的半径，该值必须大于0时才生效。
- * @return 函数返回一个指针，指针指向创建的路径效果对象{@link OH_Drawing_PathEffect}。
- * 如果返回nullptr，则创建失败，失败的可能原因是radius小于等于0。
+ * @param radius 表示圆角的半径，取值范围>0，单位为物理像素px。
+ * @return 返回指向创建的路径效果对象{@link OH_Drawing_PathEffect}的指针。
+ *
如果返回nullptr，则创建失败，原因是radius小于等于0。
* @since 18
* @version 1.0
*/
@@ -89,38 +97,45 @@ OH_Drawing_PathEffect* OH_Drawing_CreateCornerPathEffect(float radius);
/**
* @brief 创建一个虚线效果的路径效果对象。虚线效果由一组虚线开的间隔、虚线关的间隔数据决定。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * intervals为NULL或者count小于等于0时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ * 使用完毕后必须调用{@link OH_Drawing_PathEffectDestroy}销毁该路径效果对象，否则会导致内存泄漏。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
intervals为nullptr或count小于等于0时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
- * @param intervals 虚线间隔数组首地址，偶数项的值表示虚线开的间隔长度，奇数项的值表示虚线关的间隔长度，单位为像素。
- * @param count 虚线间隔数组元素的个数，必须为大于0的偶数。
- * @param phase 虚线间隔数组中偏移量。
- * @return 函数返回一个指针，指针指向创建的路径效果对象{@link OH_Drawing_PathEffect}。
+ * @param intervals 虚线间隔数组首地址，偶数项的值表示虚线可见段（开）的间隔长度，
+ * 奇数项的值表示虚线间隙段（关）的间隔长度，单位为物理像素px。
+ * @param count 虚线间隔数组元素的个数，取值范围>0，且为偶数。
+ * @param phase 虚线间隔数组中的偏移量，用于控制虚线绘制的起始位置，单位为物理像素px。
+ * @return 返回指向创建的路径效果对象{@link OH_Drawing_PathEffect}的指针。
* @since 12
* @version 1.0
*/
OH_Drawing_PathEffect* OH_Drawing_CreateDashPathEffect(float* intervals, int count, float phase);
/**
- * @brief 创建一种将路径打散并且在路径上产生不规则分布的路径效果对象。
+ * @brief 创建一种将路径打散并且在路径上产生不规则分布的路径效果对象。该路径效果按照segLength将路径分割为多个线段，
+ * 并对每个线段的末端点在deviation范围内进行随机偏移，从而产生不规则分布的视觉效果。
+ * 使用完毕后必须调用{@link OH_Drawing_PathEffectDestroy}销毁该路径效果对象，否则会导致内存泄漏。
*
- * @param segLength 表示路径中每进行一次打散操作的长度，该值大于0时有效果。
- * @param deviation 表示绘制时的末端点的最大移动偏离量。
- * @return 函数返回一个指针，指针指向创建的路径效果对象{@link OH_Drawing_PathEffect}。
+ * @param segLength 表示路径中每进行一次打散操作的长度，取值范围>0，单位为物理像素px。
+ * @param deviation 表示绘制时的末端点的最大移动偏离量，单位为物理像素px。
+ * @return 返回指向创建的路径效果对象{@link OH_Drawing_PathEffect}的指针。
* @since 18
* @version 1.0
*/
OH_Drawing_PathEffect* OH_Drawing_CreateDiscretePathEffect(float segLength, float deviation);
/**
- * @brief 创建一个虚线效果的路径效果对象。
+ * @brief 创建一个虚线效果的路径效果对象，使用指定路径作为虚线段样式，按照advance指定的步长沿目标路径重复排列。
+ * 与{@link OH_Drawing_CreateDashPathEffect}使用虚线间隔数组控制开关不同，
+ * 本接口使用指定路径作为虚线段形状。使用完毕后必须调用{@link OH_Drawing_PathEffectDestroy}销毁该路径效果对象，
+ * 否则会导致内存泄漏。
*
* @param path 表示虚线样式的路径对象{@link OH_Drawing_Path}的指针。
- * @param advance 表示虚线段的步长。
- * @param phase 表示虚线段内图形在虚线步长范围内的偏移量。
- * @param type 表示虚线路径效果样式。
- * @return 函数返回一个指针，指针指向创建的路径效果对象{@link OH_Drawing_PathEffect}。
- * 如果返回nullptr，则创建失败，失败的可能原因是path为nullptr或者advance小于等于0。
+ * @param advance 表示虚线段的步长，取值范围>0，单位为物理像素px。
+ * @param phase 表示虚线样式的起始偏移量，用于控制虚线段绘制的起始位置，单位为物理像素px。
+ * @param type 表示虚线路径效果样式，取值见{@link OH_Drawing_PathDashStyle}枚举。
+ * @return 返回指向创建的路径效果对象{@link OH_Drawing_PathEffect}的指针。
+ *
如果返回nullptr，则创建失败，原因是path为nullptr或者advance小于等于0。
* @since 18
* @version 1.0
*/
@@ -128,12 +143,14 @@ OH_Drawing_PathEffect* OH_Drawing_CreatePathDashEffect(const OH_Drawing_Path* pa
OH_Drawing_PathDashStyle type);
/**
- * @brief 创建一个使用两种路径效果分别生效后叠加的路径效果对象。
+ * @brief 创建一个使用两种路径效果叠加的路径效果对象。与{@link OH_Drawing_CreateComposePathEffect}的先后顺序应用不同，
+ * 本接口将两种路径效果各自独立应用后将结果叠加。使用完毕后必须调用
+ * {@link OH_Drawing_PathEffectDestroy}销毁该路径效果对象，否则会导致内存泄漏。
*
- * @param firstPathEffect 指向路径对象{@link OH_Drawing_PathEffect}的指针。
- * @param secondPathEffect 指向路径对象{@link OH_Drawing_PathEffect}的指针。
- * @return 函数返回一个指针，指针指向创建的路径效果对象{@link OH_Drawing_PathEffect}。
- * 如果返回nullptr，则创建失败，失败的可能原因是firstPathEffect或者secondPathEffect为nullptr。
+ * @param firstPathEffect 表示参与叠加的第一个路径效果对象{@link OH_Drawing_PathEffect}的指针。
+ * @param secondPathEffect 表示参与叠加的第二个路径效果对象{@link OH_Drawing_PathEffect}的指针。
+ * @return 返回指向创建的路径效果对象{@link OH_Drawing_PathEffect}的指针。
+ *
如果返回nullptr，则创建失败，原因是firstPathEffect或者secondPathEffect为nullptr。
* @since 18
* @version 1.0
*/
@@ -141,9 +158,9 @@ OH_Drawing_PathEffect* OH_Drawing_CreateSumPathEffect(OH_Drawing_PathEffect* fir
OH_Drawing_PathEffect* secondPathEffect);
/**
- * @brief 销毁路径效果对象并回收该对象占有内存。
+ * @brief 销毁路径效果对象，并回收该对象占用的内存。路径效果对象使用完毕后必须调用此方法，否则会导致内存泄漏。
*
- * @param pathEffect 指向路径效果对象{@link OH_Drawing_PathEffect}的指针。
+ * @param pathEffect 指向需要销毁的路径效果对象{@link OH_Drawing_PathEffect}的指针。
* @since 12
* @version 1.0
*/
diff --git a/zh-cn/graphic/graphic_2d/native_drawing/drawing_point.h b/zh-cn/graphic/graphic_2d/native_drawing/drawing_point.h
index 13d565453..498d5d2c3 100644
--- a/zh-cn/graphic/graphic_2d/native_drawing/drawing_point.h
+++ b/zh-cn/graphic/graphic_2d/native_drawing/drawing_point.h
@@ -25,7 +25,9 @@
/**
* @file drawing_point.h
*
- * @brief This file declares the functions related to the coordinate point in the drawing module.
+ * @brief 文件中定义了与坐标点相关的功能函数，支持创建、获取、设置、取反、偏移及销毁坐标点对象等操作，
+ * 便于在2D图形绘制中对坐标点进行管理与变换。
+ *
本模块为单线程模型策略，需要调用方自行管理线程安全和上下文状态的切换。
*
* @kit ArkGraphics2D
* @library libnative_drawing.so
@@ -45,82 +47,82 @@ extern "C" {
#endif
/**
- * @brief 用于创建一个坐标点对象。
+ * @brief 创建一个坐标点对象。当此坐标点对象不再需要时，必须调用{@link OH_Drawing_PointDestroy}销毁并回收内存。
*
- * @param x X轴坐标。
- * @param y Y轴坐标。
- * @return 函数会返回一个指针，指针指向创建的坐标点对象。
+ * @param x 表示坐标点的x轴坐标，单位为物理像素px。
+ * @param y 表示坐标点的y轴坐标，单位为物理像素px。
+ * @return 函数返回指向创建的坐标点对象的指针。
* @since 11
* @version 1.0
*/
OH_Drawing_Point* OH_Drawing_PointCreate(float x, float y);
/**
- * @brief 用于获取点的x轴坐标。
+ * @brief 获取坐标点的x轴坐标值。
*
* @param point 指向坐标点对象{@link OH_Drawing_Point}的指针。
- * @param x 表示点的x轴坐标。
+ * @param x 输出参数，用于接收坐标点的x轴坐标值，单位为物理像素px。
* @return 函数返回执行错误码。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数point或者x为空。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数point或者x为空。
* @since 12
* @version 1.0
*/
OH_Drawing_ErrorCode OH_Drawing_PointGetX(const OH_Drawing_Point* point, float* x);
/**
- * @brief 用于获取点的y轴坐标。
+ * @brief 获取坐标点的y轴坐标值。
*
* @param point 指向坐标点对象{@link OH_Drawing_Point}的指针。
- * @param y 表示点的y轴坐标。
+ * @param y 输出参数，用于接收坐标点的y轴坐标值，单位为物理像素px。
* @return 函数返回执行错误码。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数point或者y为空。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数point或者y为空。
* @since 12
* @version 1.0
*/
OH_Drawing_ErrorCode OH_Drawing_PointGetY(const OH_Drawing_Point* point, float* y);
/**
- * @brief 用于设置点的x轴和y轴坐标。
+ * @brief 设置坐标点的x轴和y轴坐标。
*
* @param point 指向坐标点对象{@link OH_Drawing_Point}的指针。
- * @param x 表示点的x轴坐标。
- * @param y 表示点的y轴坐标。
+ * @param x 表示坐标点的x轴坐标，单位为物理像素px。
+ * @param y 表示坐标点的y轴坐标，单位为物理像素px。
* @return 函数返回执行错误码。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数point为空。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数point为空。
* @since 12
* @version 1.0
*/
OH_Drawing_ErrorCode OH_Drawing_PointSet(OH_Drawing_Point* point, float x, float y);
/**
- * @brief 对point对象的坐标取反。
+ * @brief 对坐标点的x轴和y轴坐标取反。
*
- * @param point 需要被操作的point对象指针。
- * @return 返回错误码。
- * 操作成功时，返回 {@link OH_DRAWING_SUCCESS}.
- * Point对象指针为空时，返回 {@link OH_DRAWING_ERROR_INCORRECT_PARAMETER}
+ * @param point 指向坐标点对象{@link OH_Drawing_Point}的指针。
+ * @return 函数返回执行错误码。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INCORRECT_PARAMETER，表示参数point为空。
* @since 26.0.0
*/
OH_Drawing_ErrorCode OH_Drawing_PointNegate(OH_Drawing_Point* point);
/**
- * @brief 对point对象的坐标分别偏移dx、dy。
+ * @brief 将坐标点沿x轴和y轴方向偏移指定距离。
*
- * @param point 表示被操作的point对象指针。
- * @param dx 表示x轴方向的偏移量，单位为像素。
- * @param dy 表示y轴方向的偏移量，单位为像素。
- * @return 返回错误码。
- * 操作成功时，返回{@link OH_DRAWING_SUCCESS}.
- * Point对象指针为空时，返回 {@link OH_DRAWING_ERROR_INCORRECT_PARAMETER}
+ * @param point 指向坐标点对象{@link OH_Drawing_Point}的指针。
+ * @param dx 表示在x轴上的偏移量，单位为物理像素px。正数表示往x轴正方向平移，负数表示往x轴负方向平移。
+ * @param dy 表示在y轴上的偏移量，单位为物理像素px。正数表示往y轴正方向平移，负数表示往y轴负方向平移。
+ * @return 函数返回执行错误码。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INCORRECT_PARAMETER，表示参数point为空。
* @since 26.0.0
*/
OH_Drawing_ErrorCode OH_Drawing_PointOffset(OH_Drawing_Point* point, float dx, float dy);
/**
- * @brief 用于销毁坐标点对象并回收该对象占有的内存。
+ * @brief 销毁坐标点对象并回收该对象占用的内存。需在{@link OH_Drawing_PointCreate}创建对象后且该对象不再使用时调用。
*
* @param point 指向坐标点对象的指针。
* @since 11
diff --git a/zh-cn/graphic/graphic_2d/native_drawing/drawing_record_cmd.h b/zh-cn/graphic/graphic_2d/native_drawing/drawing_record_cmd.h
index 5a2357bd6..c63575b8c 100644
--- a/zh-cn/graphic/graphic_2d/native_drawing/drawing_record_cmd.h
+++ b/zh-cn/graphic/graphic_2d/native_drawing/drawing_record_cmd.h
@@ -25,7 +25,9 @@
/**
* @file drawing_record_cmd.h
*
- * @brief This file declares the functions related to a recording command object.
+ * @brief 文件中定义了与录制指令对象相关的功能函数。用于录制和回放绘制指令序列，支持创建录制画布、记录绘制操作、
+ * 生成可回放的指令对象。
+ *
本模块为单线程模型策略，需要调用方自行管理线程安全和上下文状态的切换。
*
* @kit ArkGraphics2D
* @library libnative_drawing.so
@@ -45,7 +47,7 @@ extern "C" {
#endif
/**
- * @brief 创建一个录制指令工具对象。
+ * @brief 创建一个指令录制工具对象。
*
* @return 返回用于录制指令的工具对象。
* @since 13
@@ -54,12 +56,12 @@ extern "C" {
OH_Drawing_RecordCmdUtils* OH_Drawing_RecordCmdUtilsCreate(void);
/**
- * @brief 销毁一个录制指令工具对象，并回收该对象占用的内存。
+ * @brief 销毁一个指令录制工具对象，并回收该对象占用的内存。
*
- * @param recordCmdUtils 指向录制指令工具对象{@link OH_Drawing_RecordCmdUtils}的指针。
+ * @param recordCmdUtils 指向指令录制工具对象{@link OH_Drawing_RecordCmdUtils}的指针。
* @return 函数返回执行错误码。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数recordCmdUtils为空。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数recordCmdUtils为空。
* @since 13
* @version 1.0
*/
@@ -67,18 +69,18 @@ OH_Drawing_ErrorCode OH_Drawing_RecordCmdUtilsDestroy(OH_Drawing_RecordCmdUtils*
/**
* @brief 开始录制。此接口需要与{@link OH_Drawing_RecordCmdUtilsFinishRecording}接口成对使用。
- * 指令录制工具生成录制类型的画布对象，可调用drawing的绘制接口，记录接下来所有的绘制指令。
+ *
指令录制工具生成录制类型的画布对象，可调用drawing的绘制接口，记录接下来所有的绘制指令。
*
- * @param recordCmdUtils 指向录制工具对象{@link OH_Drawing_RecordCmdUtils}的指针。
- * @param width 画布的宽度。
- * @param height 画布的高度。
+ * @param recordCmdUtils 指向指令录制工具对象{@link OH_Drawing_RecordCmdUtils}的指针。
+ * @param width 画布的宽度，必须大于0。
+ * @param height 画布的高度，必须大于0。
* @param canvas 指向画布对象{@link OH_Drawing_Canvas}的二级指针，作为出参，开发者无需释放。
- * 该画布对象不支持嵌套调用{@link OH_Drawing_CanvasDrawRecordCmd}接口。
+ *
该画布对象不支持嵌套调用{@link OH_Drawing_CanvasDrawRecordCmd}接口。
* @return 函数返回执行错误码。
- * 返回OH_DRAWING_SUCCESS, 表示执行成功。
- * 返回OH_DRAWING_ERROR_INVALID_PARAMETER, 表示参数recordCmdUtils或者canvas为空。
- * 当width和height小于等于0的时，也会返回OH_DRAWING_ERROR_INVALID_PARAMETER。
- * 返回OH_DRAWING_ERROR_ALLOCATION_FAILED，表示系统内存不足。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数recordCmdUtils或者canvas为空。
+ *
当width和height小于等于0时，也会返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
返回OH_DRAWING_ERROR_ALLOCATION_FAILED，表示系统内存不足。
* @since 13
* @version 1.0
*/
@@ -87,16 +89,16 @@ OH_Drawing_ErrorCode OH_Drawing_RecordCmdUtilsBeginRecording(OH_Drawing_RecordCm
/**
* @brief 结束录制。在调用此接口前，需要先调用{@link OH_Drawing_RecordCmdUtilsBeginRecording}接口。
- * 指令录制工具结束录制指令，将录制类型画布对象记录的绘制指令存入生成的录制指令对象。
+ *
指令录制工具结束录制指令，将录制类型画布对象记录的绘制指令存入生成的录制指令对象。
*
- * @param recordCmdUtils 指向录制指令工具对象{@link OH_Drawing_RecordCmdUtils}的指针。
- * @param recordCmd 指向录制指令对象 {@link OH_Drawing_RecordCmd} 的二级指针，作为出参，开发者调用 {@link OH_Drawing_CanvasDrawRecordCmd}
- * 接口绘制该对象。需要调用 {@link OH_Drawing_RecordCmdDestroy}
- * 接口释放。
+ * @param recordCmdUtils 指向指令录制工具对象{@link OH_Drawing_RecordCmdUtils}的指针，不能为空。
+ * @param recordCmd 指向录制指令对象{@link OH_Drawing_RecordCmd}的二级指针，作为出参，
+ * 开发者调用{@link OH_Drawing_CanvasDrawRecordCmd}接口绘制该对象。
+ * 需要调用{@link OH_Drawing_RecordCmdDestroy}接口释放。
* @return 函数返回执行错误码。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数recordCmdUtils或者recordCmd为空。
- * 返回OH_DRAWING_ERROR_ALLOCATION_FAILED，表示系统内存不足。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数recordCmdUtils或者recordCmd为空。
+ *
返回OH_DRAWING_ERROR_ALLOCATION_FAILED，表示系统内存不足。
* @since 13
* @version 1.0
*/
@@ -106,10 +108,10 @@ OH_Drawing_ErrorCode OH_Drawing_RecordCmdUtilsFinishRecording(OH_Drawing_RecordC
/**
* @brief 销毁录制指令对象，并回收该对象占用的内存。
*
- * @param recordCmd 指向对象{@link OH_Drawing_RecordCmd}的指针。
+ * @param recordCmd 指向录制指令对象{@link OH_Drawing_RecordCmd}的指针。
* @return 函数返回执行错误码。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数recordCmd为空。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数recordCmd为空。
* @since 13
* @version 1.0
*/
diff --git a/zh-cn/graphic/graphic_2d/native_drawing/drawing_round_rect.h b/zh-cn/graphic/graphic_2d/native_drawing/drawing_round_rect.h
index b541854bf..76e84b32e 100644
--- a/zh-cn/graphic/graphic_2d/native_drawing/drawing_round_rect.h
+++ b/zh-cn/graphic/graphic_2d/native_drawing/drawing_round_rect.h
@@ -25,7 +25,8 @@
/**
* @file drawing_round_rect.h
*
- * @brief This file declares the functions related to the rounded rectangle in the drawing module.
+ * @brief 文件中定义了与圆角矩形相关的功能函数。
+ *
本模块为单线程模型策略，需要调用方自行管理线程安全和上下文状态的切换。
*
* @kit ArkGraphics2D
* @library libnative_drawing.so
@@ -71,11 +72,11 @@ typedef enum {
/**
* @brief 用于创建一个圆角矩形对象。本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * rect为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
rect为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
* @param rect 指向矩形对象的指针。
- * @param xRad X轴上的圆角半径，小于或等于0时无效。
- * @param yRad Y轴上的圆角半径，小于或等于0时无效。
+ * @param xRad X轴上的圆角半径，小于或等于0时无效。单位为物理像素px。
+ * @param yRad Y轴上的圆角半径，小于或等于0时无效。单位为物理像素px。
* @return 函数会返回一个指针，指针指向创建的圆角矩形对象。
* @since 11
* @version 1.0
@@ -85,7 +86,7 @@ OH_Drawing_RoundRect* OH_Drawing_RoundRectCreate(const OH_Drawing_Rect* rect, fl
/**
* @brief 用于创建圆角矩形的拷贝。
*
- * @param roundRect 指向用于拷贝的圆角矩形对象{@link OH_Drawing_RoundRect}的指针。
+ * @param roundRect 指向圆角矩形对象OH_Drawing_RoundRect的指针
* @return 函数会返回一个指针，指针指向创建的新圆角矩形对象。
* @since 20
* @version 1.0
@@ -94,12 +95,13 @@ OH_Drawing_RoundRect* OH_Drawing_RoundRectCopy(const OH_Drawing_RoundRect* round
/**
* @brief 用于设置圆角矩形中指定圆角位置的圆角半径。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * roundRect为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
roundRect为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
- * @param roundRect 指向圆角矩形对象的指针。
+ * @param roundRect 指向圆角矩形对象的指针
* @param pos 圆角位置的枚举，支持类型可见{@link OH_Drawing_CornerPos}。
- * @param radii 圆角半径结构体OH_Drawing_Corner_Radii，其中包含x轴方向和y轴方向上的半径，半径小于等于0时无效。
+ * @param radii 圆角半径结构体OH_Drawing_Corner_Radii，其中包含x轴方向和y轴方向上的半径，单位为物理像素px，
+ * 半径小于等于0时无效。
* @since 12
* @version 1.0
*/
@@ -108,10 +110,10 @@ void OH_Drawing_RoundRectSetCorner(OH_Drawing_RoundRect* roundRect,
/**
* @brief 用于获取圆角矩形中指定圆角位置的圆角半径。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * roundRect为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
roundRect为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
- * @param roundRect 指向圆角矩形对象的指针。
+ * @param roundRect 指向圆角矩形对象的指针
* @param pos 圆角位置的枚举，支持类型可见{@link OH_Drawing_CornerPos}。
* @return 返回指定圆角位置的圆角半径结构体OH_Drawing_Corner_Radii，其中包含x轴方向和y轴方向上的半径。
* @since 12
@@ -131,12 +133,12 @@ void OH_Drawing_RoundRectDestroy(OH_Drawing_RoundRect* roundRect);
/**
* @brief 用于将圆角矩形沿x轴方向和y轴方向平移指定距离。
*
- * @param roundRect 指向圆角矩形对象{@link OH_Drawing_Point2D}的指针。
- * @param dx x轴方向偏移量。
- * @param dy y轴方向偏移量。
+ * @param roundRect 指向圆角矩形对象的指针。
+ * @param dx x轴方向偏移量，单位为物理像素px。正值表示向x轴正方向偏移，负值表示向x轴负方向偏移，0表示不偏移。
+ * @param dy y轴方向偏移量，单位为物理像素px。正值表示向y轴正方向偏移，负值表示向y轴负方向偏移，0表示不偏移。
* @return 函数返回执行错误码。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数roundRect为空。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数roundRect为NULL。
* @since 12
* @version 1.0
*/
diff --git a/zh-cn/graphic/graphic_2d/native_drawing/drawing_surface.h b/zh-cn/graphic/graphic_2d/native_drawing/drawing_surface.h
index d5712f8c3..d8e064085 100644
--- a/zh-cn/graphic/graphic_2d/native_drawing/drawing_surface.h
+++ b/zh-cn/graphic/graphic_2d/native_drawing/drawing_surface.h
@@ -25,8 +25,9 @@
/**
* @file drawing_surface.h
*
- * @brief This file declares the functions related to the surface in the drawing module, including creating, destroying,
- * and using the surface.
+ * @brief 本文件定义了与surface相关的功能函数，包括surface的创建、销毁和使用等。surface对象用于管理画布绘制的内容，
+ * 支持通过图形处理器上下文创建离屏surface和与屏幕窗口绑定的surface。
+ *
本模块为单线程模型策略，需要调用方自行管理线程安全和上下文状态的切换。
*
* @kit ArkGraphics2D
* @library libnative_drawing.so
@@ -46,14 +47,20 @@ extern "C" {
#endif
/**
- * @brief 使用图形处理器上下文创建一个surface对象，用于管理画布绘制的内容。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * gpuContext为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ * @brief 使用图形处理器上下文创建离屏surface对象，用于管理画布绘制的内容。
+ * 若需将绘制内容上屏显示（配合{@link OH_Drawing_SurfaceFlush}使用），请改用
+ * {@link OH_Drawing_SurfaceCreateOnScreen}创建与屏幕窗口绑定的surface对象。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
gpuContext为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
- * @param gpuContext 指向图形处理器上下文对象的指针{@link OH_Drawing_GpuContext}。
- * @param flag 用于控制内存分配是否计入缓存预算。true则计入高速缓存预算，false则不计入高速缓存预算。
- * @param imageInfo 图片信息{@link OH_Drawing_Image_Info}结构体。
- * @return 返回一个指针，指针指向创建的surface对象{@link OH_Drawing_Surface}。
+ * @param gpuContext 指向图形处理器上下文对象{@link OH_Drawing_GpuContext}的指针。
+ * @param flag 用于控制内存分配是否计入缓存预算。true则计入缓存预算，false则不计入缓存预算。
+ * 缓存预算为图形处理器缓存可使用的内存上限，计入预算的内存分配会占用缓存额度。
+ * 当需要将绘制内容纳入缓存管理以提升性能时，
+ * flag设置为true；当绘制内容为临时数据、不需要长期缓存时，flag设置为false。
+ * @param imageInfo 图像信息{@link OH_Drawing_Image_Info}结构体，用于指定所创建surface的图像宽度、高度、
+ * 颜色类型和透明度类型等属性。
+ * @return 返回指向创建的surface对象{@link OH_Drawing_Surface}的指针。
* @since 12
* @version 1.0
*/
@@ -61,16 +68,18 @@ OH_Drawing_Surface* OH_Drawing_SurfaceCreateFromGpuContext(
OH_Drawing_GpuContext* gpuContext, bool flag, OH_Drawing_Image_Info imageInfo);
/**
- * @brief 使用图形处理器上下文创建一个与屏幕窗口绑定的surface对象，用于管理画布绘制的内容。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * gpuContext或window为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
- * imageInfo的宽高和window的宽高需保持一致。
+ * @brief 使用图形处理器上下文创建一个与屏幕窗口绑定的surface对象，用于管理画布绘制的内容。若不需要上屏显示，
+ * 请改用{@link OH_Drawing_SurfaceCreateFromGpuContext}
+ * 创建离屏surface对象。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
gpuContext或window为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
imageInfo的宽高和window的宽高需保持一致，否则对象创建失败。
*
- * @param gpuContext 指向图形处理器上下文对象的指针{@link OH_Drawing_GpuContext}。
- * 该图形处理器上下文对象必须由{@link OH_Drawing_GpuContextCreate}创建，否则surface对象会创建失败。
- * @param imageInfo 图片信息{@link OH_Drawing_Image_Info}结构体。
- * @param window 指向屏幕窗口对象的指针。
- * @return 返回一个指针，指针指向创建的surface对象{@link OH_Drawing_Surface}。
+ * @param gpuContext 指向图形处理器上下文对象{@link OH_Drawing_GpuContext}的指针。
+ * @param imageInfo 图像信息{@link OH_Drawing_Image_Info}结构体，用于指定所创建surface的图像宽度、高度、
+ * 颜色类型和透明度类型等属性。
+ * @param window 指向屏幕窗口对象（OHNativeWindow）的指针，实际应传入OHNativeWindow*类型。
+ * @return 返回指向创建的surface对象{@link OH_Drawing_Surface}的指针。
* @since 16
* @version 1.0
*/
@@ -79,33 +88,39 @@ OH_Drawing_Surface* OH_Drawing_SurfaceCreateOnScreen(
/**
* @brief 通过surface对象获取画布对象。
- * 本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
- * surface为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
+ *
本接口会产生错误码，可以通过{@link OH_Drawing_ErrorCodeGet}查看错误码的取值。
+ *
surface为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。
*
- * @param surface 指向创建的surface对象的指针。
- * @return 返回一个指针，指针指向创建的画布对象{@link OH_Drawing_Canvas}。返回的指针不需要由调用者管理。
+ * @param surface 指向已创建的surface对象的指针{@link OH_Drawing_Surface}，用于从中获取画布对象。该surface对象可由
+ * {@link OH_Drawing_SurfaceCreateFromGpuContext}或{@link OH_Drawing_SurfaceCreateOnScreen}创建。
+ * @return 返回指向获取的画布对象{@link OH_Drawing_Canvas}的指针。返回的指针不需要由调用者管理，
+ * 其生命周期由对应的surface对象管理。调用
+ * {@link OH_Drawing_SurfaceDestroy}销毁surface对象后，不应再使用该画布对象。
* @since 12
* @version 1.0
*/
OH_Drawing_Canvas* OH_Drawing_SurfaceGetCanvas(OH_Drawing_Surface* surface);
/**
- * @brief 将surface对象上的画布绘制内容提交给GPU处理，完成绘制内容上屏显示。
+ * @brief 将surface对象上的画布绘制内容提交给图形处理器处理，完成绘制内容上屏显示。
*
* @param surface 指向创建的surface对象的指针{@link OH_Drawing_Surface}。该surface对象必须由{@link OH_Drawing_SurfaceCreateOnScreen}创建，
- * 否则该接口调用将没有任何效果。
+ * 否则该接口调用不会将绘制内容上屏显示。
* @return 函数返回执行错误码。
- * 返回OH_DRAWING_SUCCESS，表示执行成功。
- * 返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数surface为空。
+ *
返回OH_DRAWING_SUCCESS，表示执行成功。
+ *
返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数surface为NULL。
* @since 16
* @version 1.0
*/
OH_Drawing_ErrorCode OH_Drawing_SurfaceFlush(OH_Drawing_Surface* surface);
/**
- * @brief 销毁surface对象并回收该对象占用的内存。
+ * @brief 销毁surface对象并回收该对象占用的内存。调用本接口销毁surface对象后，
+ * 通过{@link OH_Drawing_SurfaceGetCanvas}获取的画布对象不应再使用，其生命周期由surface对象管理。
*
- * @param surface 指向创建的surface对象的指针。
+ * @param surface 指向待销毁的surface对象的指针{@link OH_Drawing_Surface}。该surface对象可由
+ * {@link OH_Drawing_SurfaceCreateFromGpuContext}或{@link OH_Drawing_SurfaceCreateOnScreen}创建，
+ * 销毁后该指针不应再被使用。
* @since 12
* @version 1.0
*/