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