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