1 /* 2 * Copyright (c) 2023-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 #ifndef C_INCLUDE_DRAWING_FONT_H 17 #define C_INCLUDE_DRAWING_FONT_H 18 19 /** 20 * @addtogroup Drawing 21 * @{ 22 * 23 * @brief Provides functions such as 2D graphics rendering, text drawing, and image display. 24 * 25 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 26 * 27 * @since 11 28 * @version 1.0 29 */ 30 31 /** 32 * @file drawing_font.h 33 * 34 * @brief Declares functions related to the <b>font</b> object in the drawing module. 35 * 36 * @since 11 37 * @version 1.0 38 */ 39 40 #include "drawing_error_code.h" 41 #include "drawing_types.h" 42 43 #ifdef __cplusplus 44 extern "C" { 45 #endif 46 47 /** 48 * @brief Creates an <b>OH_Drawing_Font</b> object. 49 * 50 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 51 * @return Returns the pointer to the <b>OH_Drawing_Font</b> object created. 52 * @since 11 53 * @version 1.0 54 */ 55 OH_Drawing_Font* OH_Drawing_FontCreate(void); 56 57 /** 58 * @brief Enumerates font hinting pattern. 59 * 60 * @since 12 61 * @version 1.0 62 */ 63 typedef enum { 64 /** glyph outlines unchanged */ 65 FONT_HINTING_NONE, 66 /** minimal modification to improve contrast */ 67 FONT_HINTING_SLIGHT, 68 /** glyph outlines modified to improve contrast */ 69 FONT_HINTING_NORMAL, 70 /** modifies glyph outlines for maximum contrast */ 71 FONT_HINTING_FULL, 72 } OH_Drawing_FontHinting; 73 74 /** 75 * @brief Enumerates font edging effect. 76 * 77 * @since 12 78 * @version 1.0 79 */ 80 typedef enum { 81 /** no transparent pixels on glyph edges */ 82 FONT_EDGING_ALIAS, 83 /** may have transparent pixels on glyph edges */ 84 FONT_EDGING_ANTI_ALIAS, 85 /** glyph positioned in pixel using transparency */ 86 FONT_EDGING_SUBPIXEL_ANTI_ALIAS, 87 } OH_Drawing_FontEdging; 88 89 /** 90 * @brief Sets whether the font baselines and pixels alignment when the transformation matrix is axis aligned. 91 * 92 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 93 * @param OH_Drawing_Font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 94 * @param baselineSnap Indicates whether the font baselines and pixels alignment. 95 * @since 12 96 * @version 1.0 97 */ 98 void OH_Drawing_FontSetBaselineSnap(OH_Drawing_Font*, bool baselineSnap); 99 100 /** 101 * @brief Gets whether the font baselines and pixels alignment when the transformation matrix is axis aligned. 102 * 103 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 104 * @param OH_Drawing_Font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 105 * @return Returns <b>true</b> if the font baselines and pixels alignment; returns <b>false</b> otherwise. 106 * @since 12 107 * @version 1.0 108 */ 109 bool OH_Drawing_FontIsBaselineSnap(const OH_Drawing_Font*); 110 111 /** 112 * @brief Sets whether the font uses sub-pixel rendering. 113 * 114 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 115 * @param OH_Drawing_Font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 116 * @param isSubpixel Indicates whether the font uses sub-pixel rendering. 117 * @since 12 118 * @version 1.0 119 */ 120 void OH_Drawing_FontSetSubpixel(OH_Drawing_Font*, bool isSubpixel); 121 122 /** 123 * @brief Gets whether the font uses sub-pixel rendering. 124 * 125 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 126 * @param OH_Drawing_Font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 127 * @return Returns <b>true</b> if the font uses sub-pixel rendering; returns <b>false</b> otherwise. 128 * @since 12 129 * @version 1.0 130 */ 131 bool OH_Drawing_FontIsSubpixel(const OH_Drawing_Font*); 132 133 /** 134 * @brief Sets whether the font outline is automatically adjusted. 135 * 136 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 137 * @param OH_Drawing_Font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 138 * @param isForceAutoHinting Indicates whether the font outline is automatically adjusted. 139 * @since 12 140 * @version 1.0 141 */ 142 void OH_Drawing_FontSetForceAutoHinting(OH_Drawing_Font*, bool isForceAutoHinting); 143 144 /** 145 * @brief Gets whether the font outline is automatically adjusted. 146 * 147 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 148 * @param OH_Drawing_Font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 149 * @return Returns <b>true</b> if the font outline is automatically adjusted; returns <b>false</b> otherwise. 150 * @since 12 151 * @version 1.0 152 */ 153 bool OH_Drawing_FontIsForceAutoHinting(const OH_Drawing_Font*); 154 155 /** 156 * @brief Sets an <b>OH_Drawing_Typeface</b> object for an <b>OH_Drawing_Font</b> object. 157 * 158 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 159 * @param OH_Drawing_Font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 160 * @param OH_Drawing_Typeface Indicates the pointer to an <b>OH_Drawing_Typeface</b> object. 161 * @since 11 162 * @version 1.0 163 */ 164 void OH_Drawing_FontSetTypeface(OH_Drawing_Font*, OH_Drawing_Typeface*); 165 166 /** 167 * @brief Gets an <b>OH_Drawing_Typeface</b> object from the <b>OH_Drawing_Typeface</b> object. 168 * 169 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 170 * @param OH_Drawing_Font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 171 * @return OH_Drawing_Typeface Indicates the pointer to an <b>OH_Drawing_Typeface</b> object. 172 * @since 12 173 * @version 1.0 174 */ 175 OH_Drawing_Typeface* OH_Drawing_FontGetTypeface(OH_Drawing_Font*); 176 177 /** 178 * @brief Sets text size for an <b>OH_Drawing_Font</b> object. 179 * 180 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 181 * @param OH_Drawing_Font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 182 * @param textSize Indicates the text size. 183 * @since 11 184 * @version 1.0 185 */ 186 void OH_Drawing_FontSetTextSize(OH_Drawing_Font*, float textSize); 187 188 /** 189 * @brief Gets text size for an <b>OH_Drawing_Font</b> object. 190 * 191 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 192 * @param OH_Drawing_Font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 193 * @return Returns the size of text. 194 * @since 12 195 * @version 1.0 196 */ 197 float OH_Drawing_FontGetTextSize(const OH_Drawing_Font*); 198 199 /** 200 * @brief Calculate number of glyphs represented by text. 201 * 202 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 203 * @param OH_Drawing_Font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 204 * @param text Indicates the character storage encoded with text encoding. 205 * @param byteLength Indicates the text length in bytes. 206 * @param encoding Indicates the text encoding. 207 * @since 12 208 * @version 1.0 209 */ 210 int OH_Drawing_FontCountText(OH_Drawing_Font*, const void* text, size_t byteLength, 211 OH_Drawing_TextEncoding encoding); 212 213 /** 214 * @brief Converts text into glyph indices. 215 * 216 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 217 * @param OH_Drawing_Font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 218 * @param text Indicates the character storage encoded with text encoding. 219 * @param byteLength Indicates the text length in bytes. 220 * @param encoding Indicates the text encoding. 221 * @param glyphs Indicates the storage for glyph indices. 222 * @param maxGlyphCount Indicates the storage capacity. 223 * @return Returns the number of glyph indices represented by text. 224 * @since 12 225 * @version 1.0 226 */ 227 uint32_t OH_Drawing_FontTextToGlyphs(const OH_Drawing_Font*, const void* text, uint32_t byteLength, 228 OH_Drawing_TextEncoding encoding, uint16_t* glyphs, int maxGlyphCount); 229 230 /** 231 * @brief Retrieves the advance for each glyph in glyphs. 232 * 233 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 234 * @param OH_Drawing_Font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 235 * @param glyphs Indicates the array of glyph indices to be measured. 236 * @param count Indicates the number of glyphs. 237 * @param widths Indicates the text advances for each glyph returned to the caller. 238 * @since 12 239 * @version 1.0 240 */ 241 void OH_Drawing_FontGetWidths(const OH_Drawing_Font*, const uint16_t* glyphs, int count, float* widths); 242 243 /** 244 * @brief Measures the width of a single character. 245 * 246 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 247 * @param font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 248 * @param str Indicates the single character encoded in UTF-8. 249 * @param textWidth Indicates the width of the single character. 250 * @return Returns the error code. 251 * Returns {@link OH_DRAWING_SUCCESS} if the operation is successful. 252 * Returns {@link OH_DRAWING_ERROR_INVALID_PARAMETER} if any of font, str 253 * and textWidth is nullptr or strlen(str) is 0. 254 * @since 12 255 * @version 1.0 256 */ 257 OH_Drawing_ErrorCode OH_Drawing_FontMeasureSingleCharacter(const OH_Drawing_Font* font, const char* str, 258 float* textWidth); 259 260 /** 261 * @brief Measures the width of text. 262 * 263 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 264 * @param font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 265 * @param text Indicates the character storage encoded with text encoding. 266 * @param byteLength Indicates the text length in bytes. 267 * @param encoding Indicates the text encoding. 268 * @param bounds Gets the bounding box relative to (0, 0) if not nullptr. 269 * @param textWidth Indicates the width of text. 270 * @return Returns the error code. 271 * Returns {@link OH_DRAWING_SUCCESS} if the operation is successful. 272 * Returns {@link OH_DRAWING_ERROR_INVALID_PARAMETER} if any of font, text 273 * and textWidth is nullptr or byteLength is 0. 274 * @since 12 275 * @version 1.0 276 */ 277 OH_Drawing_ErrorCode OH_Drawing_FontMeasureText(const OH_Drawing_Font* font, const void* text, size_t byteLength, 278 OH_Drawing_TextEncoding encoding, OH_Drawing_Rect* bounds, float* textWidth); 279 280 /** 281 * @brief Enables or disables linearly scalable font for an <b>OH_Drawing_Font</b> object. 282 * 283 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 284 * @param OH_Drawing_Font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 285 * @param isLinearText Indicates whether to enable linearly scalable font. 286 * @since 11 287 * @version 1.0 288 */ 289 void OH_Drawing_FontSetLinearText(OH_Drawing_Font*, bool isLinearText); 290 291 /** 292 * @brief Gets whether the font is linearly scalable. 293 * 294 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 295 * @param OH_Drawing_Font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 296 * @return Returns <b>true</b> if the font is linearly scalable; returns <b>false</b> otherwise. 297 * @since 12 298 * @version 1.0 299 */ 300 bool OH_Drawing_FontIsLinearText(const OH_Drawing_Font*); 301 302 /** 303 * @brief Sets text skew on x-axis for an <b>OH_Drawing_Font</b> object. 304 * 305 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 306 * @param OH_Drawing_Font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 307 * @param skewX Indicates the additional shear on x-axis relative to y-axis. 308 * @since 11 309 * @version 1.0 310 */ 311 void OH_Drawing_FontSetTextSkewX(OH_Drawing_Font*, float skewX); 312 313 /** 314 * @brief Gets text skew on x-axis for an <b>OH_Drawing_Font</b> object. 315 * 316 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 317 * @param OH_Drawing_Font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 318 * @return Returns additional skew on x-axis relative to y-axis. 319 * @since 12 320 * @version 1.0 321 */ 322 float OH_Drawing_FontGetTextSkewX(const OH_Drawing_Font*); 323 324 /** 325 * @brief Enables or disables to increase stroke width to approximate bold fonts for an <b>OH_Drawing_Font</b> object. 326 * 327 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 328 * @param OH_Drawing_Font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 329 * @param isFakeBoldText Indicates whether to enable to increase stroke width. 330 * @since 11 331 * @version 1.0 332 */ 333 void OH_Drawing_FontSetFakeBoldText(OH_Drawing_Font*, bool isFakeBoldText); 334 335 /** 336 * @brief Gets whether to increase the stroke width to approximate bold fonts. 337 * 338 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 339 * @param OH_Drawing_Font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 340 * @return Returns <b>true</b> to increase the stroke width to approximate bold fonts; returns <b>false</b> otherwise. 341 * @since 12 342 * @version 1.0 343 */ 344 bool OH_Drawing_FontIsFakeBoldText(const OH_Drawing_Font*); 345 346 /** 347 * @brief Sets text scale on x-axis for an <b>OH_Drawing_Font</b> object. 348 * 349 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 350 * @param OH_Drawing_Font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 351 * @param scaleX Indicates the text horizontal scale. 352 * @since 12 353 * @version 1.0 354 */ 355 void OH_Drawing_FontSetScaleX(OH_Drawing_Font*, float scaleX); 356 357 /** 358 * @brief Gets text scale on x-axis from an <b>OH_Drawing_Font</b> object. 359 * 360 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 361 * @param OH_Drawing_Font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 362 * @return Returns text horizontal scale on x-axis. 363 * @since 12 364 * @version 1.0 365 */ 366 float OH_Drawing_FontGetScaleX(const OH_Drawing_Font*); 367 368 /** 369 * @brief Sets hinting pattern for an <b>OH_Drawing_Font</b> object. 370 * 371 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 372 * @param OH_Drawing_Font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 373 * @param OH_Drawing_FontHinting Indicates the font hinting pattern. 374 * @since 12 375 * @version 1.0 376 */ 377 void OH_Drawing_FontSetHinting(OH_Drawing_Font*, OH_Drawing_FontHinting); 378 379 /** 380 * @brief Gets hinting pattern from an <b>OH_Drawing_Font</b> object. 381 * 382 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 383 * @param OH_Drawing_Font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 384 * @return Returns the font hinting pattern. 385 * @since 12 386 * @version 1.0 387 */ 388 OH_Drawing_FontHinting OH_Drawing_FontGetHinting(const OH_Drawing_Font*); 389 390 /** 391 * @brief Sets whether to use bitmaps instead of outlines in the <b>OH_Drawing_Font</b> object. 392 * 393 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 394 * @param OH_Drawing_Font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 395 * @param isEmbeddedBitmaps Indicates whether to use bitmaps instead of outlines. 396 * @since 12 397 * @version 1.0 398 */ 399 void OH_Drawing_FontSetEmbeddedBitmaps(OH_Drawing_Font*, bool isEmbeddedBitmaps); 400 401 /** 402 * @brief Gets whether to use bitmaps instead of outlines in the <b>OH_Drawing_Font</b> object. 403 * 404 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 405 * @param OH_Drawing_Font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 406 * @return Returns <b>true</b> if using bitmaps instead of outlines; returns <b>false</b> otherwise. 407 * @since 12 408 * @version 1.0 409 */ 410 bool OH_Drawing_FontIsEmbeddedBitmaps(const OH_Drawing_Font*); 411 412 /** 413 * @brief Sets the font edging effect for an <b>OH_Drawing_Font</b> object. 414 * 415 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 416 * @param OH_Drawing_Font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 417 * @param OH_Drawing_FontEdging Indicates the font edging effect. 418 * @since 12 419 * @version 1.0 420 */ 421 void OH_Drawing_FontSetEdging(OH_Drawing_Font*, OH_Drawing_FontEdging); 422 423 /** 424 * @brief Gets the font edging effect from an <b>OH_Drawing_Font</b> object. 425 * 426 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 427 * @param OH_Drawing_Font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 428 * @return Returns the font edging effect. 429 * @since 12 430 * @version 1.0 431 */ 432 OH_Drawing_FontEdging OH_Drawing_FontGetEdging(const OH_Drawing_Font*); 433 434 /** 435 * @brief Destroys an <b>OH_Drawing_Font</b> object and reclaims the memory occupied by the object. 436 * 437 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 438 * @param OH_Drawing_Font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 439 * @since 11 440 * @version 1.0 441 */ 442 void OH_Drawing_FontDestroy(OH_Drawing_Font*); 443 444 /** 445 * @brief Defines a run, supplies storage for the metrics of an <b>OH_Drawing_Font</b>. 446 * 447 * @since 12 448 * @version 1.0 449 */ 450 typedef struct { 451 /** Indicating which metrics are valid */ 452 uint32_t flags; 453 /** storage for top in font metrics */ 454 float top; 455 /** storage for ascent in font metrics */ 456 float ascent; 457 /** storage for descent in font metrics */ 458 float descent; 459 /** storage for bottom in font metrics */ 460 float bottom; 461 /** storage for leading in font metrics */ 462 float leading; 463 /** Average character width, zero if unknown */ 464 float avgCharWidth; 465 /** Maximum character width, zero if unknown */ 466 float maxCharWidth; 467 /** Greatest extent to left of origin of any glyph bounding box, typically negative 468 * deprecated with variable fonts 469 */ 470 float xMin; 471 /** Greatest extent to right of origin of any glyph bounding box, typically positive 472 * deprecated with variable fonts 473 */ 474 float xMax; 475 /** Height of lower-case 'x', zero if unknown, typically negative */ 476 float xHeight; 477 /** Height of an upper-case letter, zero if unknown, typically negative */ 478 float capHeight; 479 /** Underline thickness */ 480 float underlineThickness; 481 /** Distance from baseline to top of stroke, typically positive */ 482 float underlinePosition; 483 /** Strikeout thickness */ 484 float strikeoutThickness; 485 /** Distance from baseline to bottom of stroke, typically negative */ 486 float strikeoutPosition; 487 } OH_Drawing_Font_Metrics; 488 489 /** 490 * @brief Obtains the metrics of a font. 491 * 492 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 493 * @param OH_Drawing_Font Indicates the pointer to an <b>OH_Drawing_Font</b> object. 494 * @param OH_Drawing_Font_Metrics Indicates the pointer to an <b>OH_Drawing_Font_Metrics</b> object. 495 * @return Returns a float variable that recommended spacing between lines. 496 * Returns -1 if OH_Drawing_Font or OH_Drawing_Font_Metrics is nullptr. 497 * @since 12 498 * @version 1.0 499 */ 500 float OH_Drawing_FontGetMetrics(OH_Drawing_Font*, OH_Drawing_Font_Metrics*); 501 502 #ifdef __cplusplus 503 } 504 #endif 505 /** @} */ 506 #endif 507