1 /* 2 * Copyright (c) 2021-2024 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_canvas.h 30 * 31 * @brief Declares functions related to the <b>canvas</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_H 41 #define C_INCLUDE_DRAWING_H 42 43 #include "drawing_error_code.h" 44 #include "drawing_types.h" 45 #include "drawing_sampling_options.h" 46 47 #ifdef __cplusplus 48 extern "C" { 49 #endif 50 51 /** 52 * @brief Enumeration defines the constraint type. 53 * 54 * @since 12 55 * @version 1.0 56 */ 57 typedef enum { 58 /** 59 * Using sampling only inside bounds in a slower manner. 60 */ 61 STRICT_SRC_RECT_CONSTRAINT, 62 /** 63 * Using sampling outside bounds in a faster manner. 64 */ 65 FAST_SRC_RECT_CONSTRAINT, 66 } OH_Drawing_SrcRectConstraint; 67 68 /** 69 * @brief Creates an <b>OH_Drawing_Canvas</b> object. 70 * 71 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 72 * @return Returns the pointer to the <b>OH_Drawing_Canvas</b> object created. 73 * @since 8 74 * @version 1.0 75 */ 76 OH_Drawing_Canvas* OH_Drawing_CanvasCreate(void); 77 78 /** 79 * @brief Creates an <b>OH_Drawing_Canvas</b> object from <b>OH_Drawing_PixelMap</b>. 80 * The OH_Drawing_PixelMap should be dissolved by OH_Drawing_PixelMapDissolve after the OH_Drawing_Canvas is destroyed. 81 * 82 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 83 * @param pixelMap Indicates the pointer to an <b>OH_Drawing_PixelMap</b> object. 84 * @return Returns the pointer to the <b>OH_Drawing_Canvas</b> object created. 85 * If nullptr is returned, the creation fails. 86 * The possible cause of the failure is that the available memory is empty or pixelMap is nullptr. 87 * @since 20 88 * @version 1.0 89 */ 90 OH_Drawing_Canvas* OH_Drawing_CanvasCreateWithPixelMap(OH_Drawing_PixelMap* pixelMap); 91 92 /** 93 * @brief Destroys an <b>OH_Drawing_Canvas</b> object and reclaims the memory occupied by the object. 94 * 95 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 96 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 97 * @since 8 98 * @version 1.0 99 */ 100 void OH_Drawing_CanvasDestroy(OH_Drawing_Canvas* canvas); 101 102 /** 103 * @brief Binds a bitmap to a canvas so that the content drawn on the canvas 104 * is output to the bitmap (this process is called CPU rendering). 105 * 106 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 107 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 108 * @param bitmap Indicates the pointer to an <b>OH_Drawing_Bitmap</b> object. 109 * @since 8 110 * @version 1.0 111 */ 112 void OH_Drawing_CanvasBind(OH_Drawing_Canvas* canvas, OH_Drawing_Bitmap* bitmap); 113 114 /** 115 * @brief Attaches a pen to a canvas so that the canvas will use the style and color of the pen to outline a shape. 116 * 117 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 118 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 119 * @param pen Indicates the pointer to an <b>OH_Drawing_Pen</b> object. 120 * @since 8 121 * @version 1.0 122 */ 123 void OH_Drawing_CanvasAttachPen(OH_Drawing_Canvas* canvas, const OH_Drawing_Pen* pen); 124 125 /** 126 * @brief Detaches the pen from a canvas so that the canvas will not use the style 127 * and color of the pen to outline a shape. 128 * 129 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 130 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 131 * @since 8 132 * @version 1.0 133 */ 134 void OH_Drawing_CanvasDetachPen(OH_Drawing_Canvas* canvas); 135 136 /** 137 * @brief Attaches a brush to a canvas so that the canvas will use the style and color of the brush to fill in a shape. 138 * 139 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 140 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 141 * @param brush Indicates the pointer to an <b>OH_Drawing_Brush</b> object. 142 * @since 8 143 * @version 1.0 144 */ 145 void OH_Drawing_CanvasAttachBrush(OH_Drawing_Canvas* canvas, const OH_Drawing_Brush* brush); 146 147 /** 148 * @brief Detaches the brush from a canvas so that the canvas will not use the style 149 * and color of the brush to fill in a shape. 150 * 151 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 152 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 153 * @since 8 154 * @version 1.0 155 */ 156 void OH_Drawing_CanvasDetachBrush(OH_Drawing_Canvas* canvas); 157 158 /** 159 * @brief Saves the current canvas status (canvas matrix) to the top of the stack. 160 * 161 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 162 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 163 * @since 8 164 * @version 1.0 165 */ 166 void OH_Drawing_CanvasSave(OH_Drawing_Canvas* canvas); 167 168 /** 169 * @brief Saves matrix and clip, and allocates a bitmap for subsequent drawing. 170 * Calling restore discards changes to matrix and clip, and draws the bitmap. 171 * 172 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 173 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 174 * @param rect Indicates the pointer to an <b>OH_Drawing_Rect</b> object. 175 * @param brush Indicates the pointer to an <b>OH_Drawing_Brush</b> object. 176 * @since 12 177 * @version 1.0 178 */ 179 void OH_Drawing_CanvasSaveLayer(OH_Drawing_Canvas* canvas, const OH_Drawing_Rect* rect, const OH_Drawing_Brush* brush); 180 181 /** 182 * @brief Restores the canvas status (canvas matrix) saved on the top of the stack. 183 * 184 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 185 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 186 * @since 8 187 * @version 1.0 188 */ 189 void OH_Drawing_CanvasRestore(OH_Drawing_Canvas* canvas); 190 191 /** 192 * @brief Gets the number of the canvas status (canvas matrix) saved in the stack. 193 * 194 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 195 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 196 * @return Returns a 32-bit variable that describes the number of canvas status. 197 * @since 11 198 * @version 1.0 199 */ 200 uint32_t OH_Drawing_CanvasGetSaveCount(OH_Drawing_Canvas* canvas); 201 202 /** 203 * @brief Restores the specific number of the canvas status (canvas matrix) saved in the stack. 204 * 205 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 206 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 207 * @param saveCount Indicates the specific number of canvas status. 208 * @since 11 209 * @version 1.0 210 */ 211 void OH_Drawing_CanvasRestoreToCount(OH_Drawing_Canvas* canvas, uint32_t saveCount); 212 213 /** 214 * @brief Draws a line segment. 215 * 216 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 217 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 218 * @param x1 Indicates the x coordinate of the start point of the line segment. 219 * @param y1 Indicates the y coordinate of the start point of the line segment. 220 * @param x2 Indicates the x coordinate of the end point of the line segment. 221 * @param y2 Indicates the y coordinate of the end point of the line segment. 222 * @since 8 223 * @version 1.0 224 */ 225 void OH_Drawing_CanvasDrawLine(OH_Drawing_Canvas* canvas, float x1, float y1, float x2, float y2); 226 227 /** 228 * @brief Draws a path. 229 * 230 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 231 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 232 * @param path Indicates the pointer to an <b>OH_Drawing_Path</b> object. 233 * @since 8 234 * @version 1.0 235 */ 236 void OH_Drawing_CanvasDrawPath(OH_Drawing_Canvas* canvas, const OH_Drawing_Path* path); 237 238 /** 239 * @brief Divides the pixelmap into a grid with nine sections: four sides, four corners, and the center. 240 * Draws the specified section of the pixelmap onto the canvas, corners are unmodified or scaled down if they exceed 241 * the destination rectangle, center and four sides are scaled to fit remaining space. 242 * 243 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 244 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 245 * @param pixelMap Indicates the pointer to an <b>OH_Drawing_PixelMap</b> object. 246 * @param center Divides the pixelmap into nine sections: four sides, four corners, and the center. 247 * @param dst The area of destination canvas. 248 * @param mode Filter mode. 249 * @return Returns the error code. 250 * Returns {@link OH_DRAWING_SUCCESS} if the operation is successful. 251 * Returns {@link OH_DRAWING_ERROR_INVALID_PARAMETER} if any of canvas, pixelMap 252 * and dst is nullptr. 253 * @since 18 254 * @version 1.0 255 */ 256 OH_Drawing_ErrorCode OH_Drawing_CanvasDrawPixelMapNine(OH_Drawing_Canvas* canvas, OH_Drawing_PixelMap* pixelMap, 257 const OH_Drawing_Rect* center, const OH_Drawing_Rect* dst, OH_Drawing_FilterMode mode); 258 259 /** 260 * @brief Draw the specified area of the Media::PixelMap to the specified area of the canvas. 261 * 262 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 263 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 264 * @param pixelMap Indicates the pointer to an <b>OH_Drawing_PixelMap</b> object. 265 * @param src the area of source pixelmap. 266 * @param dst the area of destination canvas. 267 * @param samplingOptions the sampling mode. 268 * @since 12 269 * @version 1.0 270 */ 271 void OH_Drawing_CanvasDrawPixelMapRect(OH_Drawing_Canvas* canvas, OH_Drawing_PixelMap* pixelMap, 272 const OH_Drawing_Rect* src, const OH_Drawing_Rect* dst, const OH_Drawing_SamplingOptions* samplingOptions); 273 274 /** 275 * @brief Draw the specified area of the Media::PixelMap to the specified area of the canvas. 276 * 277 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 278 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 279 * @param pixelMap Indicates the pointer to an <b>OH_Drawing_PixelMap</b> object. 280 * @param src Indicates the area of source pixelmap. 281 * @param dst Indicates the area of destination canvas. 282 * @param samplingOptions Indicates the sampling mode. 283 * @param constraint Indicates constraint type. 284 * @return Returns the error code. 285 * Returns {@link OH_DRAWING_SUCCESS} if the operation is successful. 286 * Returns {@link OH_DRAWING_ERROR_INVALID_PARAMETER} if any of canvas, pixelMap 287 * and dst is nullptr. 288 * @since 20 289 * @version 1.0 290 */ 291 OH_Drawing_ErrorCode OH_Drawing_CanvasDrawPixelMapRectConstraint(OH_Drawing_Canvas* canvas, 292 OH_Drawing_PixelMap* pixelMap, const OH_Drawing_Rect* src, const OH_Drawing_Rect* dst, 293 const OH_Drawing_SamplingOptions* samplingOptions, OH_Drawing_SrcRectConstraint constraint); 294 295 /** 296 * @brief Fills clipped canvas area with brush. 297 * 298 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 299 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 300 * @param brush Indicates the pointer to an <b>OH_Drawing_Brush</b> object. 301 * @since 12 302 * @version 1.0 303 */ 304 void OH_Drawing_CanvasDrawBackground(OH_Drawing_Canvas* canvas, const OH_Drawing_Brush* brush); 305 306 /** 307 * @brief Draws region using clip, matrix and paint. 308 * 309 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 310 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 311 * @param region Indicates the pointer to an <b>OH_Drawing_Region</b> object. 312 * @since 12 313 * @version 1.0 314 */ 315 void OH_Drawing_CanvasDrawRegion(OH_Drawing_Canvas* canvas, const OH_Drawing_Region* region); 316 317 /** 318 * @brief Enumerates of scale to fit flags, selects if an array of points are drawn as discrete points, as lines, 319 * or as an open polygon. 320 * 321 * @since 12 322 * @version 1.0 323 */ 324 typedef enum { 325 /** 326 * Draw each point separately. 327 */ 328 POINT_MODE_POINTS, 329 /** 330 * Draw each pair of points as a line segment. 331 */ 332 POINT_MODE_LINES, 333 /** 334 * Draw the array of points as a open polygon. 335 */ 336 POINT_MODE_POLYGON, 337 } OH_Drawing_PointMode; 338 339 /** 340 * @brief Draws a point. 341 * 342 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 343 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 344 * @param point Indicates the pointer to an <b>OH_Drawing_Point</b> object. 345 * @return Returns the error code. 346 * Returns {@link OH_DRAWING_SUCCESS} if the operation is successful. 347 * Returns {@link OH_DRAWING_ERROR_INVALID_PARAMETER} if canvas or point is nullptr. 348 * @since 12 349 * @version 1.0 350 */ 351 OH_Drawing_ErrorCode OH_Drawing_CanvasDrawPoint(OH_Drawing_Canvas* canvas, const OH_Drawing_Point2D* point); 352 353 /** 354 * @brief Draws point array as separate point, line segment or open polygon according to given point mode. 355 * 356 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 357 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 358 * @param mode Draw points enum. 359 * @param count The point count. 360 * @param point2D Point struct array. 361 * @since 12 362 * @version 1.0 363 */ 364 void OH_Drawing_CanvasDrawPoints(OH_Drawing_Canvas* canvas, OH_Drawing_PointMode mode, 365 uint32_t count, const OH_Drawing_Point2D* point2D); 366 367 /** 368 * @brief Draws a bitmap. 369 * 370 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 371 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 372 * @param bitmap Indicates the pointer to an <b>OH_Drawing_Bitmap</b> object. 373 * @param left Indicates the left position of the <b>OH_Drawing_Bitmap</b>. 374 * @param top Indicates the top position of the <b>OH_Drawing_Bitmap</b>. 375 * @since 11 376 * @version 1.0 377 */ 378 void OH_Drawing_CanvasDrawBitmap(OH_Drawing_Canvas* canvas, const OH_Drawing_Bitmap* bitmap, float left, float top); 379 380 /** 381 * @brief Draw the specified area of the bitmap to the specified area of the canvas. 382 * 383 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 384 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 385 * @param bitmap Indicates the pointer to an <b>OH_Drawing_Bitmap</b> object. 386 * @param src the area of source bitmap, can be nullptr. 387 * @param dst the area of destination canvas. 388 * @param samplingOptions the sampling mode. 389 * @since 12 390 * @version 1.0 391 */ 392 void OH_Drawing_CanvasDrawBitmapRect(OH_Drawing_Canvas* canvas, const OH_Drawing_Bitmap* bitmap, 393 const OH_Drawing_Rect* src, const OH_Drawing_Rect* dst, const OH_Drawing_SamplingOptions* samplingOptions); 394 395 /** 396 * @brief Draws a rect. 397 * 398 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 399 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 400 * @param rect Indicates the pointer to an <b>OH_Drawing_Rect</b> object. 401 * @since 11 402 * @version 1.0 403 */ 404 void OH_Drawing_CanvasDrawRect(OH_Drawing_Canvas* canvas, const OH_Drawing_Rect* rect); 405 406 /** 407 * @brief Draws a circle. 408 * 409 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 410 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 411 * @param point Indicates the pointer to an <b>OH_Drawing_Point</b> object. 412 * @param radius Indicates the radius of the circle. 413 * @since 11 414 * @version 1.0 415 */ 416 void OH_Drawing_CanvasDrawCircle(OH_Drawing_Canvas* canvas, const OH_Drawing_Point* point, float radius); 417 418 /** 419 * @brief Fills the entire canvas with the specified color and blend mode. 420 * 421 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 422 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 423 * @param color Indicates the color, which is a 32-bit variable. 424 * @param blendMode Indicates the blend mode. 425 * @return Returns the error code. 426 * Returns {@link OH_DRAWING_SUCCESS} if the operation is successful. 427 * Returns {@link OH_DRAWING_ERROR_INVALID_PARAMETER} if canvas is nullptr. 428 * @since 12 429 * @version 1.0 430 */ 431 OH_Drawing_ErrorCode OH_Drawing_CanvasDrawColor(OH_Drawing_Canvas* canvas, uint32_t color, 432 OH_Drawing_BlendMode blendMode); 433 434 /** 435 * @brief Draws an oval. 436 * 437 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 438 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 439 * @param rect Indicates the pointer to an <b>OH_Drawing_Rect</b> object. 440 * @since 11 441 * @version 1.0 442 */ 443 void OH_Drawing_CanvasDrawOval(OH_Drawing_Canvas* canvas, const OH_Drawing_Rect* rect); 444 445 /** 446 * @brief Draws an arc. 447 * 448 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 449 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 450 * @param rect Indicates the pointer to an <b>OH_Drawing_Rect</b> object. 451 * @param startAngle Indicates the startAngle of the arc. 452 * @param sweepAngle Indicates the sweepAngle of the arc. 453 * @since 11 454 * @version 1.0 455 */ 456 void OH_Drawing_CanvasDrawArc(OH_Drawing_Canvas* canvas, 457 const OH_Drawing_Rect* rect, float startAngle, float sweepAngle); 458 459 /** 460 * @brief Draws an arc with use center. 461 * 462 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 463 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 464 * @param rect Indicates the pointer to an <b>OH_Drawing_Rect</b> object. 465 * @param startAngle Indicates the startAngle of the arc. 466 * @param sweepAngle Indicates the sweepAngle of the arc. 467 * @param useCenter If true, include the center of the oval in the arc, and close it if it is being stroked. 468 * @return Returns the error code. 469 * Returns {@link OH_DRAWING_SUCCESS} if the operation is successful. 470 * Returns {@link OH_DRAWING_ERROR_INVALID_PARAMETER} if canvas or rect is nullptr. 471 * @since 18 472 * @version 1.0 473 */ 474 OH_Drawing_ErrorCode OH_Drawing_CanvasDrawArcWithCenter(OH_Drawing_Canvas* canvas, const OH_Drawing_Rect* rect, 475 float startAngle, float sweepAngle, bool useCenter); 476 477 478 /** 479 * @brief Draws a roundrect. 480 * 481 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 482 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 483 * @param roundRect Indicates the pointer to an <b>OH_Drawing_RoundRect</b> object. 484 * @since 11 485 * @version 1.0 486 */ 487 void OH_Drawing_CanvasDrawRoundRect(OH_Drawing_Canvas* canvas, const OH_Drawing_RoundRect* roundRect); 488 489 /** 490 * @brief Draw two nested rounded rectangles. 491 * 492 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 493 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 494 * @param outer Rounded rectangle object, representing the outer rounded rectangle boundary. 495 * @param inner Rounded rectangle object, representing the internal rounded rectangle boundary. 496 * @return Returns the error code. 497 * Returns {@link OH_DRAWING_SUCCESS} if the operation is successful. 498 * Returns {@link OH_DRAWING_ERROR_INVALID_PARAMETER} if any of canvas, outer 499 * and inner is nullptr. 500 * @since 18 501 * @version 1.0 502 */ 503 OH_Drawing_ErrorCode OH_Drawing_CanvasDrawNestedRoundRect(OH_Drawing_Canvas* canvas, const OH_Drawing_RoundRect* outer, 504 const OH_Drawing_RoundRect* inner); 505 506 /** 507 * @brief Draws a single character. 508 * 509 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 510 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 511 * @param str Indicates the single character encoded in UTF-8. 512 * @param font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 513 * @param x Indicates the horizontal offset applied to the single character. 514 * @param y Indicates the vertical offset applied to the single character. 515 * @return Returns the error code. 516 * Returns {@link OH_DRAWING_SUCCESS} if the operation is successful. 517 * Returns {@link OH_DRAWING_ERROR_INVALID_PARAMETER} if any of canvas, str 518 * and font is nullptr or strlen(str) is 0. 519 * @since 12 520 * @version 1.0 521 */ 522 OH_Drawing_ErrorCode OH_Drawing_CanvasDrawSingleCharacter(OH_Drawing_Canvas* canvas, const char* str, 523 const OH_Drawing_Font* font, float x, float y); 524 525 /** 526 * @brief Draws a single character with font features. 527 * 528 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 529 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 530 * @param str Indicates the single character encoded in UTF-8. 531 * @param font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 532 * @param x Indicates the horizontal offset applied to the single character. 533 * @param y Indicates the vertical offset applied to the single character. 534 * @param fontFeatures Indicates the pointer to an <b>OH_Drawing_FontFeatures</b> object. 535 * @return Returns the error code. 536 * Returns {@link OH_DRAWING_SUCCESS} if the operation is successful. 537 * Returns {@link OH_DRAWING_ERROR_INVALID_PARAMETER} if any of canvas, str, font 538 * or fontFeatures is nullptr, or if strlen(str) is 0. 539 * @since 20 540 * @version 1.0 541 */ 542 OH_Drawing_ErrorCode OH_Drawing_CanvasDrawSingleCharacterWithFeatures(OH_Drawing_Canvas* canvas, const char* str, 543 const OH_Drawing_Font* font, float x, float y, OH_Drawing_FontFeatures* fontFeatures); 544 545 /** 546 * @brief Draws a textblob. 547 * 548 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 549 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 550 * @param textBlob Indicates the pointer to an <b>OH_Drawing_TextBlob</b> object. 551 * @param x Indicates the horizontal offset applied to blob. 552 * @param y Indicates the vertical offset applied to blob. 553 * @since 11 554 * @version 1.0 555 */ 556 void OH_Drawing_CanvasDrawTextBlob(OH_Drawing_Canvas* canvas, const OH_Drawing_TextBlob* textBlob, float x, float y); 557 558 /** 559 * @brief Enumerates clip op. 560 * 561 * @since 11 562 * @version 1.0 563 */ 564 typedef enum { 565 /** 566 * Clip with difference. 567 */ 568 DIFFERENCE, 569 /** 570 * Clip with intersection. 571 */ 572 INTERSECT, 573 } OH_Drawing_CanvasClipOp; 574 575 /** 576 * @brief Clip a rect. 577 * 578 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 579 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 580 * @param rect Indicates the pointer to an <b>OH_Drawing_Rect</b> object. 581 * @param clipOp Indicates the operation to apply to clip. 582 * @param doAntiAlias Indicates whether clip operation requires anti-aliased. 583 * @since 11 584 * @version 1.0 585 */ 586 void OH_Drawing_CanvasClipRect(OH_Drawing_Canvas* canvas, const OH_Drawing_Rect* rect, 587 OH_Drawing_CanvasClipOp clipOp, bool doAntiAlias); 588 589 /** 590 * @brief Clip a round rect. 591 * 592 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 593 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 594 * @param roundRect Indicates the pointer to an <b>OH_Drawing_RoundRect</b> object. 595 * @param clipOp Indicates the operation to apply to clip. 596 * @param doAntiAlias Indicates whether clip operation requires anti-aliased. 597 * @since 12 598 * @version 1.0 599 */ 600 void OH_Drawing_CanvasClipRoundRect(OH_Drawing_Canvas* canvas, const OH_Drawing_RoundRect* roundRect, 601 OH_Drawing_CanvasClipOp clipOp, bool doAntiAlias); 602 603 /** 604 * @brief Clip a path. 605 * 606 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 607 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 608 * @param path Indicates the pointer to an <b>OH_Drawing_Path</b> object. 609 * @param clipOp Indicates the operation to apply to clip. 610 * @param doAntiAlias Indicates whether clip operation requires anti-aliased. 611 * @since 11 612 * @version 1.0 613 */ 614 void OH_Drawing_CanvasClipPath(OH_Drawing_Canvas* canvas, const OH_Drawing_Path* path, 615 OH_Drawing_CanvasClipOp clipOp, bool doAntiAlias); 616 617 /** 618 * @brief Clips a region. 619 * 620 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 621 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 622 * @param region Indicates the pointer to an <b>OH_Drawing_Region</b> object. 623 * @param clipOp To apply to clip. 624 * @return Returns the error code. 625 * Returns {@link OH_DRAWING_SUCCESS} if the operation is successful. 626 * Returns {@link OH_DRAWING_ERROR_INVALID_PARAMETER} if canvas or region is nullptr. 627 * @since 12 628 * @version 1.0 629 */ 630 OH_Drawing_ErrorCode OH_Drawing_CanvasClipRegion(OH_Drawing_Canvas* canvas, const OH_Drawing_Region* region, 631 OH_Drawing_CanvasClipOp clipOp); 632 633 /** 634 * @brief Rotates by degrees. Positive degrees rotates clockwise. 635 * 636 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 637 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 638 * @param degrees Indicates the amount to rotate, in degrees. 639 * @param px Indicates the x-axis value of the point to rotate about. 640 * @param py Indicates the y-axis value of the point to rotate about. 641 * @since 11 642 * @version 1.0 643 */ 644 void OH_Drawing_CanvasRotate(OH_Drawing_Canvas* canvas, float degrees, float px, float py); 645 646 /** 647 * @brief Translates by dx along the x-axis and dy along the y-axis. 648 * 649 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 650 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 651 * @param dx Indicates the distance to translate on x-axis. 652 * @param dy Indicates the distance to translate on y-axis. 653 * @since 11 654 * @version 1.0 655 */ 656 void OH_Drawing_CanvasTranslate(OH_Drawing_Canvas* canvas, float dx, float dy); 657 658 /** 659 * @brief Scales by sx on the x-axis and sy on the y-axis. 660 * 661 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 662 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 663 * @param sx Indicates the amount to scale on x-axis. 664 * @param sy Indicates the amount to scale on y-axis. 665 * @since 11 666 * @version 1.0 667 */ 668 void OH_Drawing_CanvasScale(OH_Drawing_Canvas* canvas, float sx, float sy); 669 670 /** 671 * @brief Skew by sx on the x-axis and sy on the y-axis. 672 * 673 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 674 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 675 * @param sx Indicates the amount to skew on x-axis. 676 * @param sy Indicates the amount to skew on y-axis. 677 * @since 12 678 * @version 1.0 679 */ 680 void OH_Drawing_CanvasSkew(OH_Drawing_Canvas* canvas, float sx, float sy); 681 682 /** 683 * @brief Get the width of a canvas. 684 * 685 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 686 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 687 * @since 12 688 * @version 1.0 689 */ 690 int32_t OH_Drawing_CanvasGetWidth(OH_Drawing_Canvas* canvas); 691 692 /** 693 * @brief Get the height of a canvas. 694 * 695 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 696 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 697 * @since 12 698 * @version 1.0 699 */ 700 int32_t OH_Drawing_CanvasGetHeight(OH_Drawing_Canvas* canvas); 701 702 /** 703 * @brief Get the bounds of clip of a canvas. 704 * 705 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 706 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 707 * @param rect Indicates the pointer to an <b>OH_Drawing_Rect</b> object. 708 * @since 12 709 * @version 1.0 710 */ 711 void OH_Drawing_CanvasGetLocalClipBounds(OH_Drawing_Canvas* canvas, OH_Drawing_Rect* rect); 712 713 /** 714 * @brief Get a 3x3 matrix of the transform from local coordinates to 'device'. 715 * 716 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 717 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 718 * @param matrix Indicates the pointer to an <b>OH_Drawing_Matrix</b> object. 719 * @since 12 720 * @version 1.0 721 */ 722 void OH_Drawing_CanvasGetTotalMatrix(OH_Drawing_Canvas* canvas, OH_Drawing_Matrix* matrix); 723 724 /** 725 * @brief Use the passed matrix to transforming the geometry, then use existing matrix. 726 * 727 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 728 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 729 * @param matrix Indicates the pointer to an <b>OH_Drawing_Matrix</b> object, 730 * represents the matrix which is passed. 731 * @since 12 732 * @version 1.0 733 */ 734 void OH_Drawing_CanvasConcatMatrix(OH_Drawing_Canvas* canvas, OH_Drawing_Matrix* matrix); 735 736 /** 737 * @brief Enumerates of shadow flags. 738 * 739 * @since 12 740 * @version 1.0 741 */ 742 typedef enum { 743 /** 744 * Use no shadow flags. 745 */ 746 SHADOW_FLAGS_NONE, 747 /** 748 * The occluding object is transparent. 749 */ 750 SHADOW_FLAGS_TRANSPARENT_OCCLUDER, 751 /** 752 * No need to analyze shadows. 753 */ 754 SHADOW_FLAGS_GEOMETRIC_ONLY, 755 /** 756 * Use all shadow flags. 757 */ 758 SHADOW_FLAGS_ALL, 759 } OH_Drawing_CanvasShadowFlags; 760 761 /** 762 * @brief Use circular light to draw an offset spot shadow and outlining ambient shadow for the given path. 763 * 764 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 765 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 766 * @param path Indicates the pointer to an <b>OH_Drawing_Path</b> object, use to generate shadows. 767 * @param planeParams Represents the value of the function which returns Z offset of the occluder from the 768 * canvas based on x and y. 769 * @param devLightPos Represents the position of the light relative to the canvas. 770 * @param lightRadius The radius of the circular light. 771 * @param ambientColor Ambient shadow's color. 772 * @param spotColor Spot shadow's color. 773 * @param flag Indicates the flag to control opaque occluder, shadow, and light position. 774 * @since 12 775 * @version 1.0 776 */ 777 void OH_Drawing_CanvasDrawShadow(OH_Drawing_Canvas* canvas, OH_Drawing_Path* path, OH_Drawing_Point3D planeParams, 778 OH_Drawing_Point3D devLightPos, float lightRadius, uint32_t ambientColor, uint32_t spotColor, 779 OH_Drawing_CanvasShadowFlags flag); 780 781 /** 782 * @brief Clears a canvas by using a specified color. 783 * 784 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 785 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 786 * @param color Indicates the color, which is a 32-bit (ARGB) variable. 787 * @since 8 788 * @version 1.0 789 */ 790 void OH_Drawing_CanvasClear(OH_Drawing_Canvas* canvas, uint32_t color); 791 792 /** 793 * @brief Sets matrix of canvas. 794 * 795 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 796 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 797 * @param matrix Indicates the pointer to an <b>OH_Drawing_Matrix</b> object. 798 * @since 12 799 * @version 1.0 800 */ 801 void OH_Drawing_CanvasSetMatrix(OH_Drawing_Canvas* canvas, OH_Drawing_Matrix* matrix); 802 803 /** 804 * @brief Reset matrix to the idenmtity matrix, any prior matrix state is overwritten. 805 * 806 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 807 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 808 * @since 12 809 * @version 1.0 810 */ 811 void OH_Drawing_CanvasResetMatrix(OH_Drawing_Canvas* canvas); 812 813 /** 814 * @brief Draws the specified source rectangle of the image onto the canvas, 815 * scaled and translated to the destination rectangle. 816 * 817 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 818 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 819 * @param image Indicates the pointer to an <b>OH_Drawing_Image</b> object. 820 * @param src The area of source image. 821 * @param dst The area of destination canvas. 822 * @param samplingOptions Indicates the pointer to an <b>OH_Drawing_SamplingOptions</b> object. 823 * @param srcRectConstraint Constraint type. 824 * @since 12 825 * @version 1.0 826 */ 827 void OH_Drawing_CanvasDrawImageRectWithSrc(OH_Drawing_Canvas* canvas, const OH_Drawing_Image* image, 828 const OH_Drawing_Rect* src, const OH_Drawing_Rect* dst, const OH_Drawing_SamplingOptions* samplingOptions, 829 OH_Drawing_SrcRectConstraint srcRectConstraint); 830 831 /** 832 * @brief Draws the specified source rectangle of the image onto the canvas, 833 * scaled and translated to the destination rectangle. 834 * 835 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 836 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 837 * @param image Indicates the pointer to an <b>OH_Drawing_Image</b> object. 838 * @param rect Indicates the pointer to an <b>OH_Drawing_Rect</b> object. 839 * @param samplingOptions Indicates the pointer to an <b>OH_Drawing_SamplingOptions</b> object. 840 * @since 12 841 * @version 1.0 842 */ 843 void OH_Drawing_CanvasDrawImageRect(OH_Drawing_Canvas* canvas, OH_Drawing_Image* image, 844 OH_Drawing_Rect* rect, OH_Drawing_SamplingOptions* samplingOptions); 845 846 /** 847 * @brief Enumerates of vertices flags. 848 * 849 * @since 12 850 * @version 1.0 851 */ 852 typedef enum { 853 /** 854 * The vertices are a triangle list. 855 */ 856 VERTEX_MODE_TRIANGLES, 857 /** 858 * The vertices are a triangle strip. 859 */ 860 VERTEX_MODE_TRIANGLES_STRIP, 861 /** 862 * The vertices are a triangle fan. 863 */ 864 VERTEX_MODE_TRIANGLE_FAN, 865 } OH_Drawing_VertexMode; 866 867 /** 868 * @brief Draw a triangular mesh with vertex descriptions. 869 * 870 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 871 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 872 * @param vertexMmode Draw a set of vertices. 873 * @param vertexCount Vertex count. 874 * @param positions Positions data pointer. 875 * @param texs Texture coordinate data pointer. 876 * @param colors Color data pointer. 877 * @param indexCount Index count. 878 * @param indices Index data pointer. 879 * @param mode Blend mode used for drawing. 880 * @since 12 881 * @version 1.0 882 */ 883 void OH_Drawing_CanvasDrawVertices(OH_Drawing_Canvas* canvas, OH_Drawing_VertexMode vertexMmode, 884 int32_t vertexCount, const OH_Drawing_Point2D* positions, const OH_Drawing_Point2D* texs, 885 const uint32_t* colors, int32_t indexCount, const uint16_t* indices, OH_Drawing_BlendMode mode); 886 887 /** 888 * @brief Read pixels data from canvas. 889 * 890 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 891 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 892 * @param imageInfo width, height, colorType, and alphaType of dstPixels. 893 * @param dstPixels destination pixel storage. 894 * @param dstRowBytes size of one row of pixels. 895 * @param srcX offset into canvas writable pixels on x-axis. 896 * @param srcY offset into canvas writable pixels on y-axis. 897 * @return true if pixels are copied to dstPixels. 898 * @since 12 899 * @version 1.0 900 */ 901 bool OH_Drawing_CanvasReadPixels(OH_Drawing_Canvas* canvas, OH_Drawing_Image_Info* imageInfo, 902 void* dstPixels, uint32_t dstRowBytes, int32_t srcX, int32_t srcY); 903 904 /** 905 * @brief Read pixels data to a bitmap from canvas. 906 * 907 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 908 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 909 * @param bitmap Indicates the pointer to an <b>OH_Drawing_Bitmap</b> object. 910 * @param srcX offset into canvas writable pixels on x-axis. 911 * @param srcY offset into canvas writable pixels on y-axis. 912 * @return true if pixels are copied to dstBitmap. 913 * @since 12 914 * @version 1.0 915 */ 916 bool OH_Drawing_CanvasReadPixelsToBitmap(OH_Drawing_Canvas* canvas, 917 OH_Drawing_Bitmap* bitmap, int32_t srcX, int32_t srcY); 918 919 /** 920 * @brief Checks whether the drawable area is empty. 921 * 922 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 923 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 924 * @param isClipEmpty Indicates if drawable area is empty. 925 * @return Returns the error code. 926 * Returns {@link OH_DRAWING_SUCCESS} if the operation is successful. 927 * Returns {@link OH_DRAWING_ERROR_INVALID_PARAMETER} if canvas or isClipEmpty is nullptr. 928 * @since 12 929 * @version 1.0 930 */ 931 OH_Drawing_ErrorCode OH_Drawing_CanvasIsClipEmpty(OH_Drawing_Canvas* canvas, bool* isClipEmpty); 932 933 /** 934 * @brief Gets image info of canvas. 935 * 936 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 937 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 938 * @param imageInfo Indicates the pointer to an <b>OH_Drawing_Image_Info</b> object. 939 * @return Returns the error code. 940 * Returns {@link OH_DRAWING_SUCCESS} if the operation is successful. 941 * Returns {@link OH_DRAWING_ERROR_INVALID_PARAMETER} if canvas or imageInfo is nullptr. 942 * @since 12 943 * @version 1.0 944 */ 945 OH_Drawing_ErrorCode OH_Drawing_CanvasGetImageInfo(OH_Drawing_Canvas* canvas, OH_Drawing_Image_Info* imageInfo); 946 947 /** 948 * @brief Replay drawing command. 949 * 950 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 951 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 952 * @param recordCmd Indicates the pointer to an <b>OH_Drawing_RecordCmd</b> object. 953 * @return Returns the error code. 954 * Returns {@link OH_DRAWING_SUCCESS} if the operation is successful. 955 * Returns {@link OH_DRAWING_ERROR_INVALID_PARAMETER} if canvas or recordCmd is nullptr. 956 * @since 13 957 * @version 1.0 958 */ 959 OH_Drawing_ErrorCode OH_Drawing_CanvasDrawRecordCmd(OH_Drawing_Canvas* canvas, OH_Drawing_RecordCmd* recordCmd); 960 961 /** 962 * @brief Replay drawing command. 963 * 964 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 965 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 966 * @param recordCmd Indicates the pointer to an <b>OH_Drawing_RecordCmd</b> object. 967 * @return Returns the error code. 968 * Returns {@link OH_DRAWING_SUCCESS} if the operation is successful. 969 * Returns {@link OH_DRAWING_ERROR_INVALID_PARAMETER} if canvas or recordCmd is nullptr. 970 * @since 19 971 * @version 1.0 972 */ 973 OH_Drawing_ErrorCode OH_Drawing_CanvasDrawRecordCmdNesting(OH_Drawing_Canvas* canvas, OH_Drawing_RecordCmd* recordCmd); 974 975 /** 976 * @brief Checks if the path has been cut off. 977 * 978 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 979 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 980 * @param path Indicates the pointer to an <b>OH_Drawing_Paht</b> object. 981 * @param quickReject Indicates if the path has been cut off. 982 * @return Returns the error code. 983 * Returns {@link OH_DRAWING_SUCCESS} if the operation is successful. 984 * Returns {@link OH_DRAWING_ERROR_INVALID_PARAMETER} if canvas or path is nullptr, 985 * or quickReject is nullptr. 986 * @since 18 987 * @version 1.0 988 */ 989 OH_Drawing_ErrorCode OH_Drawing_CanvasQuickRejectPath(OH_Drawing_Canvas* canvas, const OH_Drawing_Path* path, 990 bool* quickReject); 991 992 /** 993 * @brief Checks if the rect has been cut off. 994 * 995 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 996 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 997 * @param rect Indicates the pointer to an <b>OH_Drawing_Rect</b> object. 998 * @param quickReject Indicates if the rect has been cut off. 999 * @return Returns the error code. 1000 * Returns {@link OH_DRAWING_SUCCESS} if the operation is successful. 1001 * Returns {@link OH_DRAWING_ERROR_INVALID_PARAMETER} if canvas or rect is nullptr, 1002 * or quickReject is nullptr. 1003 * @since 18 1004 * @version 1.0 1005 */ 1006 OH_Drawing_ErrorCode OH_Drawing_CanvasQuickRejectRect(OH_Drawing_Canvas* canvas, const OH_Drawing_Rect* rect, 1007 bool* quickReject); 1008 #ifdef __cplusplus 1009 } 1010 #endif 1011 /** @} */ 1012 #endif 1013