00001 /** @file00002 The file provides services to retrieve font information.00003 00004 Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR>00005 This program and the accompanying materials are licensed and made available under00006 the terms and conditions of the BSD License that accompanies this distribution.00007 The full text of the license may be found at00008 http://opensource.org/licenses/bsd-license.php.00009 00010 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,00011 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.00012 00013 **/00014
00015 #ifndef __HII_FONT_H__00016 #define __HII_FONT_H__00017 00018 FILE_LICENCE ( BSD3 );
00019
00020 #include <ipxe/efi/Protocol/GraphicsOutput.h>00021 #include <ipxe/efi/Protocol/HiiImage.h>00022
00023#define EFI_HII_FONT_PROTOCOL_GUID \00024 { 0xe9ca4775, 0x8657, 0x47fc, { 0x97, 0xe7, 0x7e, 0xd6, 0x5a, 0x8, 0x43, 0x24 } }00025 00026typedefstruct _EFI_HII_FONT_PROTOCOLEFI_HII_FONT_PROTOCOL;
00027
00028typedefVOID *EFI_FONT_HANDLE;
00029 00030 ///00031 /// EFI_HII_OUT_FLAGS.00032 ///00033typedefUINT32EFI_HII_OUT_FLAGS;
00034
00035#define EFI_HII_OUT_FLAG_CLIP 0x0000000100036#define EFI_HII_OUT_FLAG_WRAP 0x0000000200037#define EFI_HII_OUT_FLAG_CLIP_CLEAN_Y 0x0000000400038#define EFI_HII_OUT_FLAG_CLIP_CLEAN_X 0x0000000800039#define EFI_HII_OUT_FLAG_TRANSPARENT 0x0000001000040#define EFI_HII_IGNORE_IF_NO_GLYPH 0x0000002000041#define EFI_HII_IGNORE_LINE_BREAK 0x0000004000042#define EFI_HII_DIRECT_TO_SCREEN 0x0000008000043 00044 /**00045 Definition of EFI_HII_ROW_INFO.00046 **/00047typedefstruct _EFI_HII_ROW_INFO {00048 ///00049 /// The index of the first character in the string which is displayed on the line.00050 ///00051UINTNStartIndex;00052 ///00053 /// The index of the last character in the string which is displayed on the line.00054 /// If this is the same as StartIndex, then no characters are displayed.00055 ///00056UINTNEndIndex;
00057UINTNLineHeight; ///< The height of the line, in pixels.00058UINTNLineWidth; ///< The width of the text on the line, in pixels.00059 00060 ///00061 /// The font baseline offset in pixels from the bottom of the row, or 0 if none.00062 ///00063UINTNBaselineOffset;
00064 } EFI_HII_ROW_INFO;
00065 00066 ///00067 /// Font info flag. All flags (FONT, SIZE, STYLE, and COLOR) are defined.00068 /// They are defined as EFI_FONT_INFO_***00069 ///00070typedefUINT32EFI_FONT_INFO_MASK;
00071
00072#define EFI_FONT_INFO_SYS_FONT 0x0000000100073#define EFI_FONT_INFO_SYS_SIZE 0x0000000200074#define EFI_FONT_INFO_SYS_STYLE 0x0000000400075#define EFI_FONT_INFO_SYS_FORE_COLOR 0x0000001000076#define EFI_FONT_INFO_SYS_BACK_COLOR 0x0000002000077#define EFI_FONT_INFO_RESIZE 0x0000100000078#define EFI_FONT_INFO_RESTYLE 0x0000200000079#define EFI_FONT_INFO_ANY_FONT 0x0001000000080#define EFI_FONT_INFO_ANY_SIZE 0x0002000000081#define EFI_FONT_INFO_ANY_STYLE 0x0004000000082 00083 //00084 // EFI_FONT_INFO00085 //00086typedefstruct {
00087EFI_HII_FONT_STYLEFontStyle;
00088UINT16FontSize; ///< character cell height in pixels00089CHAR16 FontName[1];
00090 } EFI_FONT_INFO;
00091 00092 /**00093 Describes font output-related information.00094 00095 This structure is used for describing the way in which a string00096 should be rendered in a particular font. FontInfo specifies the00097 basic font information and ForegroundColor and BackgroundColor00098 specify the color in which they should be displayed. The flags00099 in FontInfoMask describe where the system default should be00100 supplied instead of the specified information. The flags also00101 describe what options can be used to make a match between the00102 font requested and the font available.00103 **/00104typedefstruct _EFI_FONT_DISPLAY_INFO {
00105EFI_GRAPHICS_OUTPUT_BLT_PIXELForegroundColor;
00106EFI_GRAPHICS_OUTPUT_BLT_PIXELBackgroundColor;
00107EFI_FONT_INFO_MASKFontInfoMask;
00108EFI_FONT_INFOFontInfo;
00109 } EFI_FONT_DISPLAY_INFO;
00110 00111 /**00112 00113 This function renders a string to a bitmap or the screen using00114 the specified font, color and options. It either draws the00115 string and glyphs on an existing bitmap, allocates a new bitmap,00116 or uses the screen. The strings can be clipped or wrapped.00117 Optionally, the function also returns the information about each00118 row and the character position on that row. If00119 EFI_HII_OUT_FLAG_CLIP is set, then text will be formatted only00120 based on explicit line breaks and all pixels which would lie00121 outside the bounding box specified by Width and Height are00122 ignored. The information in the RowInfoArray only describes00123 characters which are at least partially displayed. For the final00124 row, the LineHeight and BaseLine may describe pixels that are00125 outside the limit specified by Height (unless00126 EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is specified) even though those00127 pixels were not drawn. The LineWidth may describe pixels which00128 are outside the limit specified by Width (unless00129 EFI_HII_OUT_FLAG_CLIP_CLEAN_X is specified) even though those00130 pixels were not drawn. If EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set,00131 then it modifies the behavior of EFI_HII_OUT_FLAG_CLIP so that00132 if a character's right-most on pixel cannot fit, then it will00133 not be drawn at all. This flag requires that00134 EFI_HII_OUT_FLAG_CLIP be set. If EFI_HII_OUT_FLAG_CLIP_CLEAN_Y00135 is set, then it modifies the behavior of EFI_HII_OUT_FLAG_CLIP00136 so that if a row's bottom-most pixel cannot fit, then it will00137 not be drawn at all. This flag requires that00138 EFI_HII_OUT_FLAG_CLIP be set. If EFI_HII_OUT_FLAG_WRAP is set,00139 then text will be wrapped at the right-most line-break00140 opportunity prior to a character whose right-most extent would00141 exceed Width. If no line-break opportunity can be found, then00142 the text will behave as if EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set.00143 This flag cannot be used with EFI_HII_OUT_FLAG_CLIP_CLEAN_X. If00144 EFI_HII_OUT_FLAG_TRANSPARENT is set, then BackgroundColor is00145 ignored and all 'off' pixels in the character's drawn00146 will use the pixel value from Blt. This flag cannot be used if00147 Blt is NULL upon entry. If EFI_HII_IGNORE_IF_NO_GLYPH is set,00148 then characters which have no glyphs are not drawn. Otherwise,00149 they are replaced with Unicode character code 0xFFFD (REPLACEMENT00150 CHARACTER). If EFI_HII_IGNORE_LINE_BREAK is set, then explicit00151 line break characters will be ignored. If00152 EFI_HII_DIRECT_TO_SCREEN is set, then the string will be written00153 directly to the output device specified by Screen. Otherwise the00154 string will be rendered to the bitmap specified by Bitmap.00155 00156 @param This A pointer to the EFI_HII_FONT_PROTOCOL instance.00157 00158 @param Flags Describes how the string is to be drawn.00159 00160 @param String Points to the null-terminated string to be00161 00162 @param StringInfo Points to the string output information,00163 including the color and font. If NULL, then00164 the string will be output in the default00165 system font and color.00166 00167 @param Blt If this points to a non-NULL on entry, this points00168 to the image, which is Width pixels wide and00169 Height pixels high. The string will be drawn onto00170 this image and EFI_HII_OUT_FLAG_CLIP is implied.00171 If this points to a NULL on entry, then a buffer00172 will be allocated to hold the generated image and00173 the pointer updated on exit. It is the caller's00174 responsibility to free this buffer.00175 00176 @param BltX, BltY Specifies the offset from the left and top00177 edge of the image of the first character00178 cell in the image.00179 00180 @param RowInfoArray If this is non-NULL on entry, then on00181 exit, this will point to an allocated buffer00182 containing row information and00183 RowInfoArraySize will be updated to contain00184 the number of elements. This array describes00185 the characters that were at least partially00186 drawn and the heights of the rows. It is the00187 caller's responsibility to free this buffer.00188 00189 @param RowInfoArraySize If this is non-NULL on entry, then on00190 exit it contains the number of00191 elements in RowInfoArray.00192 00193 @param ColumnInfoArray If this is non-NULL, then on return it00194 will be filled with the horizontal00195 offset for each character in the00196 string on the row where it is00197 displayed. Non-printing characters00198 will have the offset ~0. The caller is00199 responsible for allocating a buffer large00200 enough so that there is one entry for00201 each character in the string, not00202 including the null-terminator. It is00203 possible when character display is00204 normalized that some character cells00205 overlap.00206 00207 @retval EFI_SUCCESS The string was successfully updated.00208 00209 @retval EFI_OUT_OF_RESOURCES Unable to allocate an output buffer for RowInfoArray or Blt.00210 00211 @retval EFI_INVALID_PARAMETER The String or Blt was NULL.00212 00213 @retval EFI_INVALID_PARAMETER Flags were invalid combination.00214 **/00215 typedef00216 EFI_STATUS00217 (EFIAPI *EFI_HII_STRING_TO_IMAGE)(
00218 INCONSTEFI_HII_FONT_PROTOCOL *This,
00219 INEFI_HII_OUT_FLAGSFlags,
00220 INCONSTEFI_STRING String,
00221 INCONSTEFI_FONT_DISPLAY_INFO *StringInfo,
00222 INOUTEFI_IMAGE_OUTPUT **Blt,
00223 INUINTN BltX,
00224 INUINTN BltY,
00225 OUTEFI_HII_ROW_INFO **RowInfoArray OPTIONAL,
00226 OUTUINTN *RowInfoArraySize OPTIONAL,
00227 OUTUINTN *ColumnInfoArray OPTIONAL00228 );
00229
00230
00231 00232 /**00233 00234 This function renders a string as a bitmap or to the screen00235 and can clip or wrap the string. The bitmap is either supplied00236 by the caller or allocated by the function. The00237 strings are drawn with the font, size and style specified and00238 can be drawn transparently or opaquely. The function can also00239 return information about each row and each character's00240 position on the row. If EFI_HII_OUT_FLAG_CLIP is set, then00241 text will be formatted based only on explicit line breaks, and00242 all pixels that would lie outside the bounding box specified00243 by Width and Height are ignored. The information in the00244 RowInfoArray only describes characters which are at least00245 partially displayed. For the final row, the LineHeight and00246 BaseLine may describe pixels which are outside the limit00247 specified by Height (unless EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is00248 specified) even though those pixels were not drawn. If00249 EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set, then it modifies the00250 behavior of EFI_HII_OUT_FLAG_CLIP so that if a character's00251 right-most on pixel cannot fit, then it will not be drawn at00252 all. This flag requires that EFI_HII_OUT_FLAG_CLIP be set. If00253 EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is set, then it modifies the00254 behavior of EFI_HII_OUT_FLAG_CLIP so that if a row's bottom00255 most pixel cannot fit, then it will not be drawn at all. This00256 flag requires that EFI_HII_OUT_FLAG_CLIP be set. If00257 EFI_HII_OUT_FLAG_WRAP is set, then text will be wrapped at the00258 right-most line-break opportunity prior to a character whose00259 right-most extent would exceed Width. If no line-break00260 opportunity can be found, then the text will behave as if00261 EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set. This flag cannot be used00262 with EFI_HII_OUT_FLAG_CLIP_CLEAN_X. If00263 EFI_HII_OUT_FLAG_TRANSPARENT is set, then BackgroundColor is00264 ignored and all off" pixels in the character's glyph will00265 use the pixel value from Blt. This flag cannot be used if Blt00266 is NULL upon entry. If EFI_HII_IGNORE_IF_NO_GLYPH is set, then00267 characters which have no glyphs are not drawn. Otherwise, they00268 are replaced with Unicode character code 0xFFFD (REPLACEMENT00269 CHARACTER). If EFI_HII_IGNORE_LINE_BREAK is set, then explicit00270 line break characters will be ignored. If00271 EFI_HII_DIRECT_TO_SCREEN is set, then the string will be00272 written directly to the output device specified by Screen.00273 Otherwise the string will be rendered to the bitmap specified00274 by Bitmap.00275 00276 00277 @param This A pointer to the EFI_HII_FONT_PROTOCOL instance.00278 00279 @param Flags Describes how the string is to be drawn.00280 00281 @param PackageList00282 The package list in the HII database to00283 search for the specified string.00284 00285 @param StringId The string's id, which is unique within00286 PackageList.00287 00288 @param Language Points to the language for the retrieved00289 string. If NULL, then the current system00290 language is used.00291 00292 @param StringInfo Points to the string output information,00293 including the color and font. If NULL, then00294 the string will be output in the default00295 system font and color.00296 00297 @param Blt If this points to a non-NULL on entry, this points00298 to the image, which is Width pixels wide and00299 Height pixels high. The string will be drawn onto00300 this image and EFI_HII_OUT_FLAG_CLIP is implied.00301 If this points to a NULL on entry, then a buffer00302 will be allocated to hold the generated image and00303 the pointer updated on exit. It is the caller's00304 responsibility to free this buffer.00305 00306 @param BltX, BltY Specifies the offset from the left and top00307 edge of the output image of the first00308 character cell in the image.00309 00310 @param RowInfoArray If this is non-NULL on entry, then on00311 exit, this will point to an allocated00312 buffer containing row information and00313 RowInfoArraySize will be updated to00314 contain the number of elements. This array00315 describes the characters which were at00316 least partially drawn and the heights of00317 the rows. It is the caller's00318 responsibility to free this buffer.00319 00320 @param RowInfoArraySize If this is non-NULL on entry, then on00321 exit it contains the number of00322 elements in RowInfoArray.00323 00324 @param ColumnInfoArray If non-NULL, on return it is filled00325 with the horizontal offset for each00326 character in the string on the row00327 where it is displayed. Non-printing00328 characters will have the offset ~0.00329 The caller is responsible to allocate00330 a buffer large enough so that there is00331 one entry for each character in the00332 string, not including the00333 null-terminator. It is possible when00334 character display is normalized that00335 some character cells overlap.00336 00337 00338 @retval EFI_SUCCESS The string was successfully updated.00339 00340 @retval EFI_OUT_OF_RESOURCES Unable to allocate an output00341 buffer for RowInfoArray or Blt.00342 00343 @retval EFI_INVALID_PARAMETER The String, or Blt, or Height, or00344 Width was NULL.00345 @retval EFI_INVALID_PARAMETER The Blt or PackageList was NULL.00346 @retval EFI_INVALID_PARAMETER Flags were invalid combination.00347 @retval EFI_NOT_FOUND The specified PackageList is not in the Database,00348 or the stringid is not in the specified PackageList.00349 00350 **/00351 typedef00352 EFI_STATUS00353 (EFIAPI *EFI_HII_STRING_ID_TO_IMAGE)(
00354 INCONSTEFI_HII_FONT_PROTOCOL *This,
00355 INEFI_HII_OUT_FLAGSFlags,
00356 INEFI_HII_HANDLE PackageList,
00357 INEFI_STRING_ID StringId,
00358 INCONSTCHAR8 *Language,
00359 INCONSTEFI_FONT_DISPLAY_INFO *StringInfo OPTIONAL,
00360 INOUTEFI_IMAGE_OUTPUT **Blt,
00361 INUINTN BltX,
00362 INUINTN BltY,
00363 OUTEFI_HII_ROW_INFO **RowInfoArray OPTIONAL,
00364 OUTUINTN *RowInfoArraySize OPTIONAL,
00365 OUTUINTN *ColumnInfoArray OPTIONAL00366 );
00367
00368 00369 /**00370 00371 Convert the glyph for a single character into a bitmap.00372 00373 @param This A pointer to the EFI_HII_FONT_PROTOCOL instance.00374 00375 @param Char The character to retrieve.00376 00377 @param StringInfo Points to the string font and color00378 information or NULL if the string should use00379 the default system font and color.00380 00381 @param Blt This must point to a NULL on entry. A buffer will00382 be allocated to hold the output and the pointer00383 updated on exit. It is the caller's responsibility00384 to free this buffer.00385 00386 @param Baseline The number of pixels from the bottom of the bitmap00387 to the baseline.00388 00389 00390 @retval EFI_SUCCESS The glyph bitmap created.00391 00392 @retval EFI_OUT_OF_RESOURCES Unable to allocate the output buffer Blt.00393 00394 @retval EFI_WARN_UNKNOWN_GLYPH The glyph was unknown and was00395 replaced with the glyph for00396 Unicode character code 0xFFFD.00397 00398 @retval EFI_INVALID_PARAMETER Blt is NULL, or Width is NULL, or00399 Height is NULL00400 00401 00402 **/00403 typedef00404 EFI_STATUS00405 (EFIAPI *EFI_HII_GET_GLYPH)(
00406 INCONSTEFI_HII_FONT_PROTOCOL *This,
00407 INCONSTCHAR16 Char,
00408 INCONSTEFI_FONT_DISPLAY_INFO *StringInfo,
00409 OUTEFI_IMAGE_OUTPUT **Blt,
00410 OUTUINTN *Baseline OPTIONAL00411 );
00412 00413 /**00414 00415 This function iterates through fonts which match the specified00416 font, using the specified criteria. If String is non-NULL, then00417 all of the characters in the string must exist in order for a00418 candidate font to be returned.00419 00420 @param This A pointer to the EFI_HII_FONT_PROTOCOL instance.00421 00422 @param FontHandle On entry, points to the font handle returned00423 by a previous call to GetFontInfo() or NULL00424 to start with the first font. On return,00425 points to the returned font handle or points00426 to NULL if there are no more matching fonts.00427 00428 @param StringInfoIn Upon entry, points to the font to return00429 information about. If NULL, then the information00430 about the system default font will be returned.00431 00432 @param StringInfoOut Upon return, contains the matching font's information.00433 If NULL, then no information is returned. This buffer00434 is allocated with a call to the Boot Service AllocatePool().00435 It is the caller's responsibility to call the Boot00436 Service FreePool() when the caller no longer requires00437 the contents of StringInfoOut.00438 00439 @param String Points to the string which will be tested to00440 determine if all characters are available. If00441 NULL, then any font is acceptable.00442 00443 @retval EFI_SUCCESS Matching font returned successfully.00444 00445 @retval EFI_NOT_FOUND No matching font was found.00446 00447 @retval EFI_OUT_OF_RESOURCES There were insufficient resources to complete the request.00448 00449 **/00450 typedef00451 EFI_STATUS00452 (EFIAPI *EFI_HII_GET_FONT_INFO)(
00453 INCONSTEFI_HII_FONT_PROTOCOL *This,
00454 INOUTEFI_FONT_HANDLE *FontHandle,
00455 INCONSTEFI_FONT_DISPLAY_INFO *StringInfoIn, OPTIONAL
00456 OUTEFI_FONT_DISPLAY_INFO **StringInfoOut,
00457 INCONSTEFI_STRING String OPTIONAL00458 );
00459 00460 ///00461 /// The protocol provides the service to retrieve the font informations.00462 ///00463struct _EFI_HII_FONT_PROTOCOL {
00464 EFI_HII_STRING_TO_IMAGE StringToImage;
00465 EFI_HII_STRING_ID_TO_IMAGE StringIdToImage;
00466 EFI_HII_GET_GLYPH GetGlyph;
00467 EFI_HII_GET_FONT_INFO GetFontInfo;
00468 };
00469
00470 externEFI_GUIDgEfiHiiFontProtocolGuid;
00471
00472
00473 #endif00474