1 /** @file 2 The file provides services to retrieve font information. 3 4 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> 5 SPDX-License-Identifier: BSD-2-Clause-Patent 6 7 @par Revision Reference: 8 This Protocol was introduced in UEFI Specification 2.1. 9 10 **/ 11 12 #ifndef __HII_FONT_H__ 13 #define __HII_FONT_H__ 14 15 #include <Protocol/GraphicsOutput.h> 16 #include <Protocol/HiiImage.h> 17 18 #define EFI_HII_FONT_PROTOCOL_GUID \ 19 { 0xe9ca4775, 0x8657, 0x47fc, { 0x97, 0xe7, 0x7e, 0xd6, 0x5a, 0x8, 0x43, 0x24 } } 20 21 typedef struct _EFI_HII_FONT_PROTOCOL EFI_HII_FONT_PROTOCOL; 22 23 typedef VOID *EFI_FONT_HANDLE; 24 25 /// 26 /// EFI_HII_OUT_FLAGS. 27 /// 28 typedef UINT32 EFI_HII_OUT_FLAGS; 29 30 #define EFI_HII_OUT_FLAG_CLIP 0x00000001 31 #define EFI_HII_OUT_FLAG_WRAP 0x00000002 32 #define EFI_HII_OUT_FLAG_CLIP_CLEAN_Y 0x00000004 33 #define EFI_HII_OUT_FLAG_CLIP_CLEAN_X 0x00000008 34 #define EFI_HII_OUT_FLAG_TRANSPARENT 0x00000010 35 #define EFI_HII_IGNORE_IF_NO_GLYPH 0x00000020 36 #define EFI_HII_IGNORE_LINE_BREAK 0x00000040 37 #define EFI_HII_DIRECT_TO_SCREEN 0x00000080 38 39 /** 40 Definition of EFI_HII_ROW_INFO. 41 **/ 42 typedef struct _EFI_HII_ROW_INFO { 43 /// 44 /// The index of the first character in the string which is displayed on the line. 45 /// 46 UINTN StartIndex; 47 /// 48 /// The index of the last character in the string which is displayed on the line. 49 /// If this is the same as StartIndex, then no characters are displayed. 50 /// 51 UINTN EndIndex; 52 UINTN LineHeight; ///< The height of the line, in pixels. 53 UINTN LineWidth; ///< The width of the text on the line, in pixels. 54 55 /// 56 /// The font baseline offset in pixels from the bottom of the row, or 0 if none. 57 /// 58 UINTN BaselineOffset; 59 } EFI_HII_ROW_INFO; 60 61 /// 62 /// Font info flag. All flags (FONT, SIZE, STYLE, and COLOR) are defined. 63 /// They are defined as EFI_FONT_INFO_*** 64 /// 65 typedef UINT32 EFI_FONT_INFO_MASK; 66 67 #define EFI_FONT_INFO_SYS_FONT 0x00000001 68 #define EFI_FONT_INFO_SYS_SIZE 0x00000002 69 #define EFI_FONT_INFO_SYS_STYLE 0x00000004 70 #define EFI_FONT_INFO_SYS_FORE_COLOR 0x00000010 71 #define EFI_FONT_INFO_SYS_BACK_COLOR 0x00000020 72 #define EFI_FONT_INFO_RESIZE 0x00001000 73 #define EFI_FONT_INFO_RESTYLE 0x00002000 74 #define EFI_FONT_INFO_ANY_FONT 0x00010000 75 #define EFI_FONT_INFO_ANY_SIZE 0x00020000 76 #define EFI_FONT_INFO_ANY_STYLE 0x00040000 77 78 // 79 // EFI_FONT_INFO 80 // 81 typedef struct { 82 EFI_HII_FONT_STYLE FontStyle; 83 UINT16 FontSize; ///< character cell height in pixels 84 CHAR16 FontName[1]; 85 } EFI_FONT_INFO; 86 87 /** 88 Describes font output-related information. 89 90 This structure is used for describing the way in which a string 91 should be rendered in a particular font. FontInfo specifies the 92 basic font information and ForegroundColor and BackgroundColor 93 specify the color in which they should be displayed. The flags 94 in FontInfoMask describe where the system default should be 95 supplied instead of the specified information. The flags also 96 describe what options can be used to make a match between the 97 font requested and the font available. 98 **/ 99 typedef struct _EFI_FONT_DISPLAY_INFO { 100 EFI_GRAPHICS_OUTPUT_BLT_PIXEL ForegroundColor; 101 EFI_GRAPHICS_OUTPUT_BLT_PIXEL BackgroundColor; 102 EFI_FONT_INFO_MASK FontInfoMask; 103 EFI_FONT_INFO FontInfo; 104 } EFI_FONT_DISPLAY_INFO; 105 106 /** 107 108 This function renders a string to a bitmap or the screen using 109 the specified font, color and options. It either draws the 110 string and glyphs on an existing bitmap, allocates a new bitmap, 111 or uses the screen. The strings can be clipped or wrapped. 112 Optionally, the function also returns the information about each 113 row and the character position on that row. If 114 EFI_HII_OUT_FLAG_CLIP is set, then text will be formatted only 115 based on explicit line breaks and all pixels which would lie 116 outside the bounding box specified by Width and Height are 117 ignored. The information in the RowInfoArray only describes 118 characters which are at least partially displayed. For the final 119 row, the LineHeight and BaseLine may describe pixels that are 120 outside the limit specified by Height (unless 121 EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is specified) even though those 122 pixels were not drawn. The LineWidth may describe pixels which 123 are outside the limit specified by Width (unless 124 EFI_HII_OUT_FLAG_CLIP_CLEAN_X is specified) even though those 125 pixels were not drawn. If EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set, 126 then it modifies the behavior of EFI_HII_OUT_FLAG_CLIP so that 127 if a character's right-most on pixel cannot fit, then it will 128 not be drawn at all. This flag requires that 129 EFI_HII_OUT_FLAG_CLIP be set. If EFI_HII_OUT_FLAG_CLIP_CLEAN_Y 130 is set, then it modifies the behavior of EFI_HII_OUT_FLAG_CLIP 131 so that if a row's bottom-most pixel cannot fit, then it will 132 not be drawn at all. This flag requires that 133 EFI_HII_OUT_FLAG_CLIP be set. If EFI_HII_OUT_FLAG_WRAP is set, 134 then text will be wrapped at the right-most line-break 135 opportunity prior to a character whose right-most extent would 136 exceed Width. If no line-break opportunity can be found, then 137 the text will behave as if EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set. 138 This flag cannot be used with EFI_HII_OUT_FLAG_CLIP_CLEAN_X. If 139 EFI_HII_OUT_FLAG_TRANSPARENT is set, then BackgroundColor is 140 ignored and all 'off' pixels in the character's drawn 141 will use the pixel value from Blt. This flag cannot be used if 142 Blt is NULL upon entry. If EFI_HII_IGNORE_IF_NO_GLYPH is set, 143 then characters which have no glyphs are not drawn. Otherwise, 144 they are replaced with Unicode character code 0xFFFD (REPLACEMENT 145 CHARACTER). If EFI_HII_IGNORE_LINE_BREAK is set, then explicit 146 line break characters will be ignored. If 147 EFI_HII_DIRECT_TO_SCREEN is set, then the string will be written 148 directly to the output device specified by Screen. Otherwise the 149 string will be rendered to the bitmap specified by Bitmap. 150 151 @param This A pointer to the EFI_HII_FONT_PROTOCOL instance. 152 153 @param Flags Describes how the string is to be drawn. 154 155 @param String Points to the null-terminated string to be 156 157 @param StringInfo Points to the string output information, 158 including the color and font. If NULL, then 159 the string will be output in the default 160 system font and color. 161 162 @param Blt If this points to a non-NULL on entry, this points 163 to the image, which is Width pixels wide and 164 Height pixels high. The string will be drawn onto 165 this image and EFI_HII_OUT_FLAG_CLIP is implied. 166 If this points to a NULL on entry, then a buffer 167 will be allocated to hold the generated image and 168 the pointer updated on exit. It is the caller's 169 responsibility to free this buffer. 170 171 @param BltX, BltY Specifies the offset from the left and top 172 edge of the image of the first character 173 cell in the image. 174 175 @param RowInfoArray If this is non-NULL on entry, then on 176 exit, this will point to an allocated buffer 177 containing row information and 178 RowInfoArraySize will be updated to contain 179 the number of elements. This array describes 180 the characters that were at least partially 181 drawn and the heights of the rows. It is the 182 caller's responsibility to free this buffer. 183 184 @param RowInfoArraySize If this is non-NULL on entry, then on 185 exit it contains the number of 186 elements in RowInfoArray. 187 188 @param ColumnInfoArray If this is non-NULL, then on return it 189 will be filled with the horizontal 190 offset for each character in the 191 string on the row where it is 192 displayed. Non-printing characters 193 will have the offset ~0. The caller is 194 responsible for allocating a buffer large 195 enough so that there is one entry for 196 each character in the string, not 197 including the null-terminator. It is 198 possible when character display is 199 normalized that some character cells 200 overlap. 201 202 @retval EFI_SUCCESS The string was successfully updated. 203 204 @retval EFI_OUT_OF_RESOURCES Unable to allocate an output buffer for RowInfoArray or Blt. 205 206 @retval EFI_INVALID_PARAMETER The String or Blt was NULL. 207 208 @retval EFI_INVALID_PARAMETER Flags were invalid combination. 209 **/ 210 typedef 211 EFI_STATUS 212 (EFIAPI *EFI_HII_STRING_TO_IMAGE)( 213 IN CONST EFI_HII_FONT_PROTOCOL *This, 214 IN EFI_HII_OUT_FLAGS Flags, 215 IN CONST EFI_STRING String, 216 IN CONST EFI_FONT_DISPLAY_INFO *StringInfo, 217 IN OUT EFI_IMAGE_OUTPUT **Blt, 218 IN UINTN BltX, 219 IN UINTN BltY, 220 OUT EFI_HII_ROW_INFO **RowInfoArray OPTIONAL, 221 OUT UINTN *RowInfoArraySize OPTIONAL, 222 OUT UINTN *ColumnInfoArray OPTIONAL 223 ); 224 225 226 227 /** 228 229 This function renders a string as a bitmap or to the screen 230 and can clip or wrap the string. The bitmap is either supplied 231 by the caller or allocated by the function. The 232 strings are drawn with the font, size and style specified and 233 can be drawn transparently or opaquely. The function can also 234 return information about each row and each character's 235 position on the row. If EFI_HII_OUT_FLAG_CLIP is set, then 236 text will be formatted based only on explicit line breaks, and 237 all pixels that would lie outside the bounding box specified 238 by Width and Height are ignored. The information in the 239 RowInfoArray only describes characters which are at least 240 partially displayed. For the final row, the LineHeight and 241 BaseLine may describe pixels which are outside the limit 242 specified by Height (unless EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is 243 specified) even though those pixels were not drawn. If 244 EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set, then it modifies the 245 behavior of EFI_HII_OUT_FLAG_CLIP so that if a character's 246 right-most on pixel cannot fit, then it will not be drawn at 247 all. This flag requires that EFI_HII_OUT_FLAG_CLIP be set. If 248 EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is set, then it modifies the 249 behavior of EFI_HII_OUT_FLAG_CLIP so that if a row's bottom 250 most pixel cannot fit, then it will not be drawn at all. This 251 flag requires that EFI_HII_OUT_FLAG_CLIP be set. If 252 EFI_HII_OUT_FLAG_WRAP is set, then text will be wrapped at the 253 right-most line-break opportunity prior to a character whose 254 right-most extent would exceed Width. If no line-break 255 opportunity can be found, then the text will behave as if 256 EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set. This flag cannot be used 257 with EFI_HII_OUT_FLAG_CLIP_CLEAN_X. If 258 EFI_HII_OUT_FLAG_TRANSPARENT is set, then BackgroundColor is 259 ignored and all off" pixels in the character's glyph will 260 use the pixel value from Blt. This flag cannot be used if Blt 261 is NULL upon entry. If EFI_HII_IGNORE_IF_NO_GLYPH is set, then 262 characters which have no glyphs are not drawn. Otherwise, they 263 are replaced with Unicode character code 0xFFFD (REPLACEMENT 264 CHARACTER). If EFI_HII_IGNORE_LINE_BREAK is set, then explicit 265 line break characters will be ignored. If 266 EFI_HII_DIRECT_TO_SCREEN is set, then the string will be 267 written directly to the output device specified by Screen. 268 Otherwise the string will be rendered to the bitmap specified 269 by Bitmap. 270 271 272 @param This A pointer to the EFI_HII_FONT_PROTOCOL instance. 273 274 @param Flags Describes how the string is to be drawn. 275 276 @param PackageList 277 The package list in the HII database to 278 search for the specified string. 279 280 @param StringId The string's id, which is unique within 281 PackageList. 282 283 @param Language Points to the language for the retrieved 284 string. If NULL, then the current system 285 language is used. 286 287 @param StringInfo Points to the string output information, 288 including the color and font. If NULL, then 289 the string will be output in the default 290 system font and color. 291 292 @param Blt If this points to a non-NULL on entry, this points 293 to the image, which is Width pixels wide and 294 Height pixels high. The string will be drawn onto 295 this image and EFI_HII_OUT_FLAG_CLIP is implied. 296 If this points to a NULL on entry, then a buffer 297 will be allocated to hold the generated image and 298 the pointer updated on exit. It is the caller's 299 responsibility to free this buffer. 300 301 @param BltX, BltY Specifies the offset from the left and top 302 edge of the output image of the first 303 character cell in the image. 304 305 @param RowInfoArray If this is non-NULL on entry, then on 306 exit, this will point to an allocated 307 buffer containing row information and 308 RowInfoArraySize will be updated to 309 contain the number of elements. This array 310 describes the characters which were at 311 least partially drawn and the heights of 312 the rows. It is the caller's 313 responsibility to free this buffer. 314 315 @param RowInfoArraySize If this is non-NULL on entry, then on 316 exit it contains the number of 317 elements in RowInfoArray. 318 319 @param ColumnInfoArray If non-NULL, on return it is filled 320 with the horizontal offset for each 321 character in the string on the row 322 where it is displayed. Non-printing 323 characters will have the offset ~0. 324 The caller is responsible to allocate 325 a buffer large enough so that there is 326 one entry for each character in the 327 string, not including the 328 null-terminator. It is possible when 329 character display is normalized that 330 some character cells overlap. 331 332 333 @retval EFI_SUCCESS The string was successfully updated. 334 335 @retval EFI_OUT_OF_RESOURCES Unable to allocate an output 336 buffer for RowInfoArray or Blt. 337 338 @retval EFI_INVALID_PARAMETER The String, or Blt, or Height, or 339 Width was NULL. 340 @retval EFI_INVALID_PARAMETER The Blt or PackageList was NULL. 341 @retval EFI_INVALID_PARAMETER Flags were invalid combination. 342 @retval EFI_NOT_FOUND The specified PackageList is not in the Database, 343 or the stringid is not in the specified PackageList. 344 345 **/ 346 typedef 347 EFI_STATUS 348 (EFIAPI *EFI_HII_STRING_ID_TO_IMAGE)( 349 IN CONST EFI_HII_FONT_PROTOCOL *This, 350 IN EFI_HII_OUT_FLAGS Flags, 351 IN EFI_HII_HANDLE PackageList, 352 IN EFI_STRING_ID StringId, 353 IN CONST CHAR8 *Language, 354 IN CONST EFI_FONT_DISPLAY_INFO *StringInfo OPTIONAL, 355 IN OUT EFI_IMAGE_OUTPUT **Blt, 356 IN UINTN BltX, 357 IN UINTN BltY, 358 OUT EFI_HII_ROW_INFO **RowInfoArray OPTIONAL, 359 OUT UINTN *RowInfoArraySize OPTIONAL, 360 OUT UINTN *ColumnInfoArray OPTIONAL 361 ); 362 363 364 /** 365 366 Convert the glyph for a single character into a bitmap. 367 368 @param This A pointer to the EFI_HII_FONT_PROTOCOL instance. 369 370 @param Char The character to retrieve. 371 372 @param StringInfo Points to the string font and color 373 information or NULL if the string should use 374 the default system font and color. 375 376 @param Blt This must point to a NULL on entry. A buffer will 377 be allocated to hold the output and the pointer 378 updated on exit. It is the caller's responsibility 379 to free this buffer. 380 381 @param Baseline The number of pixels from the bottom of the bitmap 382 to the baseline. 383 384 385 @retval EFI_SUCCESS The glyph bitmap created. 386 387 @retval EFI_OUT_OF_RESOURCES Unable to allocate the output buffer Blt. 388 389 @retval EFI_WARN_UNKNOWN_GLYPH The glyph was unknown and was 390 replaced with the glyph for 391 Unicode character code 0xFFFD. 392 393 @retval EFI_INVALID_PARAMETER Blt is NULL, or Width is NULL, or 394 Height is NULL 395 396 397 **/ 398 typedef 399 EFI_STATUS 400 (EFIAPI *EFI_HII_GET_GLYPH)( 401 IN CONST EFI_HII_FONT_PROTOCOL *This, 402 IN CONST CHAR16 Char, 403 IN CONST EFI_FONT_DISPLAY_INFO *StringInfo, 404 OUT EFI_IMAGE_OUTPUT **Blt, 405 OUT UINTN *Baseline OPTIONAL 406 ); 407 408 /** 409 410 This function iterates through fonts which match the specified 411 font, using the specified criteria. If String is non-NULL, then 412 all of the characters in the string must exist in order for a 413 candidate font to be returned. 414 415 @param This A pointer to the EFI_HII_FONT_PROTOCOL instance. 416 417 @param FontHandle On entry, points to the font handle returned 418 by a previous call to GetFontInfo() or NULL 419 to start with the first font. On return, 420 points to the returned font handle or points 421 to NULL if there are no more matching fonts. 422 423 @param StringInfoIn Upon entry, points to the font to return 424 information about. If NULL, then the information 425 about the system default font will be returned. 426 427 @param StringInfoOut Upon return, contains the matching font's information. 428 If NULL, then no information is returned. This buffer 429 is allocated with a call to the Boot Service AllocatePool(). 430 It is the caller's responsibility to call the Boot 431 Service FreePool() when the caller no longer requires 432 the contents of StringInfoOut. 433 434 @param String Points to the string which will be tested to 435 determine if all characters are available. If 436 NULL, then any font is acceptable. 437 438 @retval EFI_SUCCESS Matching font returned successfully. 439 440 @retval EFI_NOT_FOUND No matching font was found. 441 442 @retval EFI_OUT_OF_RESOURCES There were insufficient resources to complete the request. 443 444 **/ 445 typedef 446 EFI_STATUS 447 (EFIAPI *EFI_HII_GET_FONT_INFO)( 448 IN CONST EFI_HII_FONT_PROTOCOL *This, 449 IN OUT EFI_FONT_HANDLE *FontHandle, 450 IN CONST EFI_FONT_DISPLAY_INFO *StringInfoIn, OPTIONAL 451 OUT EFI_FONT_DISPLAY_INFO **StringInfoOut, 452 IN CONST EFI_STRING String OPTIONAL 453 ); 454 455 /// 456 /// The protocol provides the service to retrieve the font informations. 457 /// 458 struct _EFI_HII_FONT_PROTOCOL { 459 EFI_HII_STRING_TO_IMAGE StringToImage; 460 EFI_HII_STRING_ID_TO_IMAGE StringIdToImage; 461 EFI_HII_GET_GLYPH GetGlyph; 462 EFI_HII_GET_FONT_INFO GetFontInfo; 463 }; 464 465 extern EFI_GUID gEfiHiiFontProtocolGuid; 466 467 468 #endif 469 470