1 /* 2 * Copyright (c) 2021-2025 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup Drawing 18 * @{ 19 * 20 * @brief Provides functions such as 2D graphics rendering, text drawing, and image display. 21 * 22 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 23 * 24 * @since 8 25 * @version 1.0 26 */ 27 28 /** 29 * @file drawing_pen.h 30 * 31 * @brief Declares functions related to the <b>pen</b> object in the drawing module. 32 * 33 * @kit ArkGraphics2D 34 * @library libnative_drawing.so 35 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 36 * @since 8 37 * @version 1.0 38 */ 39 40 #ifndef C_INCLUDE_DRAWING_PEN_H 41 #define C_INCLUDE_DRAWING_PEN_H 42 43 #include "drawing_error_code.h" 44 #include "drawing_types.h" 45 46 #ifdef __cplusplus 47 extern "C" { 48 #endif 49 50 /** 51 * @brief Defines a colorspace manager. Introduces the color space information defined by ColorManager. 52 * @since 20 53 */ 54 typedef struct OH_NativeColorSpaceManager OH_NativeColorSpaceManager; 55 56 /** 57 * @brief Creates an <b>OH_Drawing_Pen</b> object. 58 * 59 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 60 * @return Returns the pointer to the <b>OH_Drawing_Pen</b> object created. 61 * @since 8 62 * @version 1.0 63 */ 64 OH_Drawing_Pen* OH_Drawing_PenCreate(void); 65 66 /** 67 * @brief Creates an <b>OH_Drawing_Pen</b> copy object. 68 * 69 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 70 * @param pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object. 71 * @return Returns the pointer to the <b>OH_Drawing_Pen</b> object created. 72 * If nullptr is returned, the creation fails. 73 * The possible cause of the failure is that the available memory is empty or a nullptr is passed. 74 * @since 12 75 * @version 1.0 76 */ 77 OH_Drawing_Pen* OH_Drawing_PenCopy(OH_Drawing_Pen* pen); 78 79 /** 80 * @brief Destroys an <b>OH_Drawing_Pen</b> object and reclaims the memory occupied by the object. 81 * 82 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 83 * @param pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object. 84 * @since 8 85 * @version 1.0 86 */ 87 void OH_Drawing_PenDestroy(OH_Drawing_Pen* pen); 88 89 /** 90 * @brief Checks whether anti-aliasing is enabled for a pen. If anti-aliasing is enabled, 91 * edges will be drawn with partial transparency. 92 * 93 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 94 * @param pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object. 95 * @return Returns <b>true</b> if anti-aliasing is enabled; returns <b>false</b> otherwise. 96 * @since 8 97 * @version 1.0 98 */ 99 bool OH_Drawing_PenIsAntiAlias(const OH_Drawing_Pen* pen); 100 101 /** 102 * @brief Enables or disables anti-aliasing for a pen. If anti-aliasing is enabled, 103 * edges will be drawn with partial transparency. 104 * 105 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 106 * @param pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object. 107 * @param antiAlias Specifies whether to enable anti-aliasing. The value <b>true</b> means 108 * to enable anti-aliasing, and <b>false</b> means the opposite. 109 * @since 8 110 * @version 1.0 111 */ 112 void OH_Drawing_PenSetAntiAlias(OH_Drawing_Pen* pen, bool antiAlias); 113 114 /** 115 * @brief Obtains the color of a pen. The color is used by the pen to outline a shape. 116 * 117 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 118 * @param pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object. 119 * @return Returns a 32-bit (ARGB) variable that describes the color. 120 * @since 8 121 * @version 1.0 122 */ 123 uint32_t OH_Drawing_PenGetColor(const OH_Drawing_Pen* pen); 124 125 /** 126 * @brief Sets the color for a pen. The color is used by the pen to outline a shape. 127 * 128 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 129 * @param pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object. 130 * @param color Indicates the color to set, which is a 32-bit (ARGB) variable. 131 * @since 8 132 * @version 1.0 133 */ 134 void OH_Drawing_PenSetColor(OH_Drawing_Pen* pen, uint32_t color); 135 136 /** 137 * @brief Obtains the alpha of a pen. The alpha is used by the pen to outline a shape. 138 * 139 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 140 * @param pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object. 141 * @return Returns a 8-bit variable that describes the alpha. 142 * @since 11 143 * @version 1.0 144 */ 145 uint8_t OH_Drawing_PenGetAlpha(const OH_Drawing_Pen* pen); 146 147 /** 148 * @brief Sets the alpha for a pen. The alpha is used by the pen to outline a shape. 149 * 150 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 151 * @param pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object. 152 * @param alpha Indicates the alpha to set, which is a 8-bit variable. 153 * @since 11 154 * @version 1.0 155 */ 156 void OH_Drawing_PenSetAlpha(OH_Drawing_Pen* pen, uint8_t alpha); 157 158 /** 159 * @brief Sets the color for a pen. The color will be used by the pen to fill in a shape. 160 * The color is an ARGB structure described by floating point numbers and interpreted as being in the colorSpaceManager. 161 * If colorSpaceManager is nullptr, then color is assumed to be in the sRGB color space. 162 * 163 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 164 * @param pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object. 165 * @param a Indicates the alpha component of color, represented as a floating point number between 0 and 1. 166 * @param r Indicates the red component of color, represented as a floating point number between 0 and 1. 167 * @param g Indicates the green component of color, represented as a floating point number between 0 and 1. 168 * @param b Indicates the blue component of color, represented as a floating point number between 0 and 1. 169 * @param colorSpaceManager Indicates the pointer to an <b>OH_NativeColorSpaceManager</b> object. 170 * @return Returns the error code. 171 * Returns {@link OH_DRAWING_SUCCESS} if the operation is successful. 172 * Returns {@link OH_DRAWING_ERROR_INVALID_PARAMETER} if pen is nullptr. 173 * @since 20 174 * @version 1.0 175 */ 176 OH_Drawing_ErrorCode OH_Drawing_PenSetColor4f(OH_Drawing_Pen* pen, float a, float r, float g, float b, 177 OH_NativeColorSpaceManager* colorSpaceManager); 178 179 /** 180 * @brief Obtains the alpha component of a pen. 181 * 182 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 183 * @param pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object. 184 * @param a Indicates the alpha component of color. 185 * @return Returns the error code. 186 * Returns {@link OH_DRAWING_SUCCESS} if the operation is successful. 187 * Returns {@link OH_DRAWING_ERROR_INVALID_PARAMETER} if pen or a is nullptr. 188 * @since 20 189 * @version 1.0 190 */ 191 OH_Drawing_ErrorCode OH_Drawing_PenGetAlphaFloat(OH_Drawing_Pen* pen, float* a); 192 193 /** 194 * @brief Obtains the red component of a pen. 195 * 196 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 197 * @param pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object. 198 * @param r Indicates the red component of color. 199 * @return Returns the error code. 200 * Returns {@link OH_DRAWING_SUCCESS} if the operation is successful. 201 * Returns {@link OH_DRAWING_ERROR_INVALID_PARAMETER} if pen or r is nullptr. 202 * @since 20 203 * @version 1.0 204 */ 205 OH_Drawing_ErrorCode OH_Drawing_PenGetRedFloat(OH_Drawing_Pen* pen, float* r); 206 207 /** 208 * @brief Obtains the green component of a pen. 209 * 210 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 211 * @param pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object. 212 * @param g Indicates the green component of color. 213 * @return Returns the error code. 214 * Returns {@link OH_DRAWING_SUCCESS} if the operation is successful. 215 * Returns {@link OH_DRAWING_ERROR_INVALID_PARAMETER} if pen or g is nullptr. 216 * @since 20 217 * @version 1.0 218 */ 219 OH_Drawing_ErrorCode OH_Drawing_PenGetGreenFloat(OH_Drawing_Pen* pen, float* g); 220 221 /** 222 * @brief Obtains the blue component of a pen. 223 * 224 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 225 * @param pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object. 226 * @param b Indicates the blue component of color. 227 * @return Returns the error code. 228 * Returns {@link OH_DRAWING_SUCCESS} if the operation is successful. 229 * Returns {@link OH_DRAWING_ERROR_INVALID_PARAMETER} if pen or b is nullptr. 230 * @since 20 231 * @version 1.0 232 */ 233 OH_Drawing_ErrorCode OH_Drawing_PenGetBlueFloat(OH_Drawing_Pen* pen, float* b); 234 235 /** 236 * @brief Obtains the thickness of a pen. This thickness determines the width of the outline of a shape. 237 * 238 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 239 * @param pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object. 240 * @return Returns the thickness. 241 * @since 8 242 * @version 1.0 243 */ 244 float OH_Drawing_PenGetWidth(const OH_Drawing_Pen* pen); 245 246 /** 247 * @brief Sets the thickness for a pen. This thickness determines the width of the outline of a shape. 248 * 249 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 250 * @param pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object. 251 * @param width Indicates the thickness to set, which is a variable. 252 * @since 8 253 * @version 1.0 254 */ 255 void OH_Drawing_PenSetWidth(OH_Drawing_Pen* pen, float width); 256 257 /** 258 * @brief Obtains the stroke miter limit of a polyline drawn by a pen. 259 * 260 * When the corner type is bevel, a beveled corner is displayed if the miter limit is exceeded, 261 * and a mitered corner is displayed if the miter limit is not exceeded. 262 * 263 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 264 * @param pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object. 265 * @return Returns the miter limit. 266 * @since 8 267 * @version 1.0 268 */ 269 float OH_Drawing_PenGetMiterLimit(const OH_Drawing_Pen* pen); 270 271 /** 272 * @brief Sets the stroke miter limit for a polyline drawn by a pen. 273 * 274 * When the corner type is bevel, a beveled corner is displayed if the miter limit is exceeded, 275 * and a mitered corner is displayed if the miter limit is not exceeded. 276 * 277 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 278 * @param pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object. 279 * @param miter Indicates a variable that describes the miter limit. 280 * @since 8 281 * @version 1.0 282 */ 283 void OH_Drawing_PenSetMiterLimit(OH_Drawing_Pen* pen, float miter); 284 285 /** 286 * @brief Enumerates line cap styles of a pen. The line cap style defines 287 * the style of both ends of a line segment drawn by the pen. 288 * 289 * @since 8 290 * @version 1.0 291 */ 292 typedef enum { 293 /** 294 * There is no cap style. Both ends of the line segment are cut off square. 295 */ 296 LINE_FLAT_CAP, 297 /** 298 * Square cap style. Both ends have a square, the height of which 299 * is half of the width of the line segment, with the same width. 300 */ 301 LINE_SQUARE_CAP, 302 /** 303 * Round cap style. Both ends have a semicircle centered, the diameter of which 304 * is the same as the width of the line segment. 305 */ 306 LINE_ROUND_CAP 307 } OH_Drawing_PenLineCapStyle; 308 309 /** 310 * @brief Obtains the line cap style of a pen. 311 * 312 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 313 * @param pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object. 314 * @return Returns the line cap style. 315 * @since 8 316 * @version 1.0 317 */ 318 OH_Drawing_PenLineCapStyle OH_Drawing_PenGetCap(const OH_Drawing_Pen* pen); 319 320 /** 321 * @brief Sets the line cap style for a pen. 322 * 323 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 324 * @param pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object. 325 * @param capStyle Indicates a variable that describes the line cap style. 326 * @since 8 327 * @version 1.0 328 */ 329 void OH_Drawing_PenSetCap(OH_Drawing_Pen* pen, OH_Drawing_PenLineCapStyle capStyle); 330 331 /** 332 * @brief Enumerates pen line join styles. The line join style defines 333 * the shape of the joints of a polyline segment drawn by the pen. 334 * 335 * @since 8 336 * @version 1.0 337 */ 338 typedef enum { 339 /** 340 * Mitered corner. If the angle of a polyline is small, its miter length may be inappropriate. 341 * In this case, you need to use the miter limit to limit the miter length. 342 */ 343 LINE_MITER_JOIN, 344 /** Round corner. */ 345 LINE_ROUND_JOIN, 346 /** Beveled corner. */ 347 LINE_BEVEL_JOIN 348 } OH_Drawing_PenLineJoinStyle; 349 350 /** 351 * @brief Obtains the line join style of a pen. 352 * 353 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 354 * @param pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object. 355 * @return Returns the line join style. 356 * @since 8 357 * @version 1.0 358 */ 359 OH_Drawing_PenLineJoinStyle OH_Drawing_PenGetJoin(const OH_Drawing_Pen* pen); 360 361 /** 362 * @brief Sets the line join style for a pen. 363 * 364 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 365 * @param pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object. 366 * @param joinStyle Indicates a variable that describes the line join style. 367 * @since 8 368 * @version 1.0 369 */ 370 void OH_Drawing_PenSetJoin(OH_Drawing_Pen* pen, OH_Drawing_PenLineJoinStyle joinStyle); 371 372 /** 373 * @brief Sets the shaderEffect for a pen. 374 * 375 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 376 * @param pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object. 377 * @param shaderEffect Indicates the pointer to an <b>OH_Drawing_ShaderEffect</b> object. 378 * @since 11 379 * @version 1.0 380 */ 381 void OH_Drawing_PenSetShaderEffect(OH_Drawing_Pen* pen, OH_Drawing_ShaderEffect* shaderEffect); 382 383 /** 384 * @brief Sets the shadowLayer for a pen. 385 * 386 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 387 * @param pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object. 388 * @param shadowLayer Indicates the pointer to an <b>OH_Drawing_ShadowLayer</b> object. 389 * @since 12 390 * @version 1.0 391 */ 392 void OH_Drawing_PenSetShadowLayer(OH_Drawing_Pen* pen, OH_Drawing_ShadowLayer* shadowLayer); 393 394 /** 395 * @brief Sets the pathEffect for a pen. 396 * 397 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 398 * @param pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object. 399 * @param pathEffect Indicates the pointer to an <b>OH_Drawing_PathEffect</b> object. 400 * @since 12 401 * @version 1.0 402 */ 403 void OH_Drawing_PenSetPathEffect(OH_Drawing_Pen* pen, OH_Drawing_PathEffect* pathEffect); 404 405 /** 406 * @brief Sets the filter for a pen. 407 * 408 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 409 * @param pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object. 410 * @param filter Indicates the pointer to an <b>OH_Drawing_Filter</b> object. 411 * @since 11 412 * @version 1.0 413 */ 414 void OH_Drawing_PenSetFilter(OH_Drawing_Pen* pen, OH_Drawing_Filter* filter); 415 416 /** 417 * @brief Gets the filter from a pen. 418 * 419 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 420 * @param pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object. 421 * @param filter Indicates the pointer to an <b>OH_Drawing_Filter</b> object. 422 * @since 12 423 * @version 1.0 424 */ 425 void OH_Drawing_PenGetFilter(OH_Drawing_Pen* pen, OH_Drawing_Filter* filter); 426 427 /** 428 * @brief Sets a blender that implements the specified blendmode enum for a pen. 429 * 430 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 431 * @param pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object. 432 * @param blendMode Indicates the blend mode. 433 * @since 12 434 * @version 1.0 435 */ 436 void OH_Drawing_PenSetBlendMode(OH_Drawing_Pen* pen, OH_Drawing_BlendMode blendMode); 437 438 /** 439 * @brief Gets the filled equivalent of the src path. 440 * 441 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 442 * @param pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object. 443 * @param src Indicates the Path read to create a filled version. 444 * @param dst Indicates the resulting Path. 445 * @param rect Indicates the pointer to an <b>OH_Drawing_Rect</b> object that limits the PathEffect area if 446 Pen has PathEffect. 447 * @param matrix Indicates the pointer to an <b>OH_Drawing_Matrix</b> object that tranfomation applied to 448 PathEffect if Pen has PathEffect. 449 * @return Returns true if get successes; false if get fails. 450 * @since 12 451 * @version 1.0 452 */ 453 bool OH_Drawing_PenGetFillPath(OH_Drawing_Pen* pen, const OH_Drawing_Path* src, OH_Drawing_Path* dst, 454 const OH_Drawing_Rect* rect, const OH_Drawing_Matrix* matrix); 455 456 /** 457 * @brief Resets all pen contents to their initial values. 458 * 459 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 460 * @param pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object. 461 * @since 12 462 * @version 1.0 463 */ 464 void OH_Drawing_PenReset(OH_Drawing_Pen* pen); 465 466 #ifdef __cplusplus 467 } 468 #endif 469 /** @} */ 470 #endif 471