iPXE
HiiFont.h
Go to the documentation of this file.
00001 /** @file
00002   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 under
00006 the terms and conditions of the BSD License that accompanies this distribution.
00007 The full text of the license may be found at
00008 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 
00026 typedef struct _EFI_HII_FONT_PROTOCOL EFI_HII_FONT_PROTOCOL;
00027 
00028 typedef VOID    *EFI_FONT_HANDLE;
00029 
00030 ///
00031 /// EFI_HII_OUT_FLAGS.
00032 ///
00033 typedef UINT32  EFI_HII_OUT_FLAGS;
00034 
00035 #define EFI_HII_OUT_FLAG_CLIP         0x00000001
00036 #define EFI_HII_OUT_FLAG_WRAP         0x00000002
00037 #define EFI_HII_OUT_FLAG_CLIP_CLEAN_Y 0x00000004
00038 #define EFI_HII_OUT_FLAG_CLIP_CLEAN_X 0x00000008
00039 #define EFI_HII_OUT_FLAG_TRANSPARENT  0x00000010
00040 #define EFI_HII_IGNORE_IF_NO_GLYPH    0x00000020
00041 #define EFI_HII_IGNORE_LINE_BREAK     0x00000040
00042 #define EFI_HII_DIRECT_TO_SCREEN      0x00000080
00043 
00044 /**
00045   Definition of EFI_HII_ROW_INFO.
00046 **/
00047 typedef struct _EFI_HII_ROW_INFO {
00048   ///
00049   /// The index of the first character in the string which is displayed on the line.
00050   ///
00051   UINTN   StartIndex;
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   ///
00056   UINTN   EndIndex;
00057   UINTN   LineHeight; ///< The height of the line, in pixels.
00058   UINTN   LineWidth;  ///< 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   ///
00063   UINTN   BaselineOffset;
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 ///
00070 typedef UINT32  EFI_FONT_INFO_MASK;
00071 
00072 #define EFI_FONT_INFO_SYS_FONT        0x00000001
00073 #define EFI_FONT_INFO_SYS_SIZE        0x00000002
00074 #define EFI_FONT_INFO_SYS_STYLE       0x00000004
00075 #define EFI_FONT_INFO_SYS_FORE_COLOR  0x00000010
00076 #define EFI_FONT_INFO_SYS_BACK_COLOR  0x00000020
00077 #define EFI_FONT_INFO_RESIZE          0x00001000
00078 #define EFI_FONT_INFO_RESTYLE         0x00002000
00079 #define EFI_FONT_INFO_ANY_FONT        0x00010000
00080 #define EFI_FONT_INFO_ANY_SIZE        0x00020000
00081 #define EFI_FONT_INFO_ANY_STYLE       0x00040000
00082 
00083 //
00084 // EFI_FONT_INFO
00085 //
00086 typedef struct {
00087   EFI_HII_FONT_STYLE FontStyle;
00088   UINT16             FontSize;      ///< character cell height in pixels
00089   CHAR16             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 string
00096   should be rendered in a particular font. FontInfo specifies the
00097   basic font information and ForegroundColor and BackgroundColor
00098   specify the color in which they should be displayed. The flags
00099   in FontInfoMask describe where the system default should be
00100   supplied instead of the specified information. The flags also
00101   describe what options can be used to make a match between the
00102   font requested and the font available.
00103 **/
00104 typedef struct _EFI_FONT_DISPLAY_INFO {
00105   EFI_GRAPHICS_OUTPUT_BLT_PIXEL ForegroundColor;
00106   EFI_GRAPHICS_OUTPUT_BLT_PIXEL BackgroundColor;
00107   EFI_FONT_INFO_MASK            FontInfoMask;
00108   EFI_FONT_INFO                 FontInfo;
00109 } EFI_FONT_DISPLAY_INFO;
00110 
00111 /**
00112 
00113   This function renders a string to a bitmap or the screen using
00114   the specified font, color and options. It either draws the
00115   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 each
00118   row and the character position on that row. If
00119   EFI_HII_OUT_FLAG_CLIP is set, then text will be formatted only
00120   based on explicit line breaks and all pixels which would lie
00121   outside the bounding box specified by Width and Height are
00122   ignored. The information in the RowInfoArray only describes
00123   characters which are at least partially displayed. For the final
00124   row, the LineHeight and BaseLine may describe pixels that are
00125   outside the limit specified by Height (unless
00126   EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is specified) even though those
00127   pixels were not drawn. The LineWidth may describe pixels which
00128   are outside the limit specified by Width (unless
00129   EFI_HII_OUT_FLAG_CLIP_CLEAN_X is specified) even though those
00130   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 that
00132   if a character's right-most on pixel cannot fit, then it will
00133   not be drawn at all. This flag requires that
00134   EFI_HII_OUT_FLAG_CLIP be set. If EFI_HII_OUT_FLAG_CLIP_CLEAN_Y
00135   is set, then it modifies the behavior of EFI_HII_OUT_FLAG_CLIP
00136   so that if a row's bottom-most pixel cannot fit, then it will
00137   not be drawn at all. This flag requires that
00138   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-break
00140   opportunity prior to a character whose right-most extent would
00141   exceed Width. If no line-break opportunity can be found, then
00142   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. If
00144   EFI_HII_OUT_FLAG_TRANSPARENT is set, then BackgroundColor is
00145   ignored and all 'off' pixels in the character's drawn
00146   will use the pixel value from Blt. This flag cannot be used if
00147   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 (REPLACEMENT
00150   CHARACTER). If EFI_HII_IGNORE_LINE_BREAK is set, then explicit
00151   line break characters will be ignored. If
00152   EFI_HII_DIRECT_TO_SCREEN is set, then the string will be written
00153   directly to the output device specified by Screen. Otherwise the
00154   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 be
00161 
00162   @param StringInfo       Points to the string output information,
00163                           including the color and font. If NULL, then
00164                           the string will be output in the default
00165                           system font and color.
00166 
00167   @param Blt              If this points to a non-NULL on entry, this points
00168                           to the image, which is Width pixels wide and
00169                           Height pixels high. The string will be drawn onto
00170                           this image and EFI_HII_OUT_FLAG_CLIP is implied.
00171                           If this points to a NULL on entry, then a buffer
00172                           will be allocated to hold the generated image and
00173                           the pointer updated on exit. It is the caller's
00174                           responsibility to free this buffer.
00175 
00176   @param BltX, BltY       Specifies the offset from the left and top
00177                           edge of the image of the first character
00178                           cell in the image.
00179 
00180   @param RowInfoArray     If this is non-NULL on entry, then on
00181                           exit, this will point to an allocated buffer
00182                           containing row information and
00183                           RowInfoArraySize will be updated to contain
00184                           the number of elements. This array describes
00185                           the characters that were at least partially
00186                           drawn and the heights of the rows. It is the
00187                           caller's responsibility to free this buffer.
00188 
00189   @param RowInfoArraySize If this is non-NULL on entry, then on
00190                           exit it contains the number of
00191                           elements in RowInfoArray.
00192 
00193   @param ColumnInfoArray  If this is non-NULL, then on return it
00194                           will be filled with the horizontal
00195                           offset for each character in the
00196                           string on the row where it is
00197                           displayed. Non-printing characters
00198                           will have the offset ~0. The caller is
00199                           responsible for allocating a buffer large
00200                           enough so that there is one entry for
00201                           each character in the string, not
00202                           including the null-terminator. It is
00203                           possible when character display is
00204                           normalized that some character cells
00205                           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 typedef
00216 EFI_STATUS
00217 (EFIAPI *EFI_HII_STRING_TO_IMAGE)(
00218   IN CONST  EFI_HII_FONT_PROTOCOL *This,
00219   IN        EFI_HII_OUT_FLAGS     Flags,
00220   IN CONST  EFI_STRING            String,
00221   IN CONST  EFI_FONT_DISPLAY_INFO *StringInfo,
00222   IN OUT    EFI_IMAGE_OUTPUT      **Blt,
00223   IN        UINTN                 BltX,
00224   IN        UINTN                 BltY,
00225   OUT       EFI_HII_ROW_INFO      **RowInfoArray OPTIONAL,
00226   OUT       UINTN                 *RowInfoArraySize OPTIONAL,
00227   OUT       UINTN                 *ColumnInfoArray OPTIONAL
00228 );
00229 
00230 
00231 
00232 /**
00233 
00234   This function renders a string as a bitmap or to the screen
00235   and can clip or wrap the string. The bitmap is either supplied
00236   by the caller or allocated by the function. The
00237   strings are drawn with the font, size and style specified and
00238   can be drawn transparently or opaquely. The function can also
00239   return information about each row and each character's
00240   position on the row. If EFI_HII_OUT_FLAG_CLIP is set, then
00241   text will be formatted based only on explicit line breaks, and
00242   all pixels that would lie outside the bounding box specified
00243   by Width and Height are ignored. The information in the
00244   RowInfoArray only describes characters which are at least
00245   partially displayed. For the final row, the LineHeight and
00246   BaseLine may describe pixels which are outside the limit
00247   specified by Height (unless EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is
00248   specified) even though those pixels were not drawn. If
00249   EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set, then it modifies the
00250   behavior of EFI_HII_OUT_FLAG_CLIP so that if a character's
00251   right-most on pixel cannot fit, then it will not be drawn at
00252   all. This flag requires that EFI_HII_OUT_FLAG_CLIP be set. If
00253   EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is set, then it modifies the
00254   behavior of EFI_HII_OUT_FLAG_CLIP so that if a row's bottom
00255   most pixel cannot fit, then it will not be drawn at all. This
00256   flag requires that EFI_HII_OUT_FLAG_CLIP be set. If
00257   EFI_HII_OUT_FLAG_WRAP is set, then text will be wrapped at the
00258   right-most line-break opportunity prior to a character whose
00259   right-most extent would exceed Width. If no line-break
00260   opportunity can be found, then the text will behave as if
00261   EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set. This flag cannot be used
00262   with EFI_HII_OUT_FLAG_CLIP_CLEAN_X. If
00263   EFI_HII_OUT_FLAG_TRANSPARENT is set, then BackgroundColor is
00264   ignored and all off" pixels in the character's glyph will
00265   use the pixel value from Blt. This flag cannot be used if Blt
00266   is NULL upon entry. If EFI_HII_IGNORE_IF_NO_GLYPH is set, then
00267   characters which have no glyphs are not drawn. Otherwise, they
00268   are replaced with Unicode character code 0xFFFD (REPLACEMENT
00269   CHARACTER). If EFI_HII_IGNORE_LINE_BREAK is set, then explicit
00270   line break characters will be ignored. If
00271   EFI_HII_DIRECT_TO_SCREEN is set, then the string will be
00272   written directly to the output device specified by Screen.
00273   Otherwise the string will be rendered to the bitmap specified
00274   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 PackageList
00282                     The package list in the HII database to
00283                     search for the specified string.
00284 
00285   @param StringId   The string's id, which is unique within
00286                     PackageList.
00287 
00288   @param Language   Points to the language for the retrieved
00289                     string. If NULL, then the current system
00290                     language is used.
00291 
00292   @param StringInfo Points to the string output information,
00293                     including the color and font. If NULL, then
00294                     the string will be output in the default
00295                     system font and color.
00296 
00297   @param Blt        If this points to a non-NULL on entry, this points
00298                     to the image, which is Width pixels wide and
00299                     Height pixels high. The string will be drawn onto
00300                     this image and EFI_HII_OUT_FLAG_CLIP is implied.
00301                     If this points to a NULL on entry, then a buffer
00302                     will be allocated to hold the generated image and
00303                     the pointer updated on exit. It is the caller's
00304                     responsibility to free this buffer.
00305 
00306   @param BltX, BltY Specifies the offset from the left and top
00307                     edge of the output image of the first
00308                     character cell in the image.
00309 
00310   @param RowInfoArray     If this is non-NULL on entry, then on
00311                           exit, this will point to an allocated
00312                           buffer containing row information and
00313                           RowInfoArraySize will be updated to
00314                           contain the number of elements. This array
00315                           describes the characters which were at
00316                           least partially drawn and the heights of
00317                           the rows. It is the caller's
00318                           responsibility to free this buffer.
00319 
00320   @param RowInfoArraySize If this is non-NULL on entry, then on
00321                           exit it contains the number of
00322                           elements in RowInfoArray.
00323 
00324   @param ColumnInfoArray  If non-NULL, on return it is filled
00325                           with the horizontal offset for each
00326                           character in the string on the row
00327                           where it is displayed. Non-printing
00328                           characters will have the offset ~0.
00329                           The caller is responsible to allocate
00330                           a buffer large enough so that there is
00331                           one entry for each character in the
00332                           string, not including the
00333                           null-terminator. It is possible when
00334                           character display is normalized that
00335                           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 output
00341                                 buffer for RowInfoArray or Blt.
00342 
00343   @retval EFI_INVALID_PARAMETER The String, or Blt, or Height, or
00344                                 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 typedef
00352 EFI_STATUS
00353 (EFIAPI *EFI_HII_STRING_ID_TO_IMAGE)(
00354   IN CONST  EFI_HII_FONT_PROTOCOL *This,
00355   IN        EFI_HII_OUT_FLAGS     Flags,
00356   IN        EFI_HII_HANDLE        PackageList,
00357   IN        EFI_STRING_ID         StringId,
00358   IN CONST  CHAR8                 *Language,
00359   IN CONST  EFI_FONT_DISPLAY_INFO *StringInfo       OPTIONAL,
00360   IN OUT    EFI_IMAGE_OUTPUT      **Blt,
00361   IN        UINTN                 BltX,
00362   IN        UINTN                 BltY,
00363   OUT       EFI_HII_ROW_INFO      **RowInfoArray    OPTIONAL,
00364   OUT       UINTN                 *RowInfoArraySize OPTIONAL,
00365   OUT       UINTN                 *ColumnInfoArray  OPTIONAL
00366 );
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 color
00378                     information or NULL if the string should use
00379                     the default system font and color.
00380 
00381   @param Blt        This must point to a NULL on entry. A buffer will
00382                     be allocated to hold the output and the pointer
00383                     updated on exit. It is the caller's responsibility
00384                     to free this buffer.
00385 
00386   @param Baseline   The number of pixels from the bottom of the bitmap
00387                     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 was
00395                                   replaced with the glyph for
00396                                   Unicode character code 0xFFFD.
00397 
00398   @retval EFI_INVALID_PARAMETER   Blt is NULL, or Width is NULL, or
00399                                   Height is NULL
00400 
00401 
00402 **/
00403 typedef
00404 EFI_STATUS
00405 (EFIAPI *EFI_HII_GET_GLYPH)(
00406   IN CONST  EFI_HII_FONT_PROTOCOL *This,
00407   IN CONST  CHAR16                Char,
00408   IN CONST  EFI_FONT_DISPLAY_INFO *StringInfo,
00409   OUT       EFI_IMAGE_OUTPUT      **Blt,
00410   OUT       UINTN                 *Baseline OPTIONAL
00411 );
00412 
00413 /**
00414 
00415   This function iterates through fonts which match the specified
00416   font, using the specified criteria. If String is non-NULL, then
00417   all of the characters in the string must exist in order for a
00418   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 returned
00423                         by a previous call to GetFontInfo() or NULL
00424                         to start with the first font. On return,
00425                         points to the returned font handle or points
00426                         to NULL if there are no more matching fonts.
00427 
00428   @param StringInfoIn   Upon entry, points to the font to return
00429                         information about. If NULL, then the information
00430                         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 buffer
00434                         is allocated with a call to the Boot Service AllocatePool().
00435                         It is the caller's responsibility to call the Boot
00436                         Service FreePool() when the caller no longer requires
00437                         the contents of StringInfoOut.
00438 
00439   @param String         Points to the string which will be tested to
00440                         determine if all characters are available. If
00441                         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 typedef
00451 EFI_STATUS
00452 (EFIAPI *EFI_HII_GET_FONT_INFO)(
00453   IN CONST  EFI_HII_FONT_PROTOCOL *This,
00454   IN OUT    EFI_FONT_HANDLE       *FontHandle,
00455   IN CONST  EFI_FONT_DISPLAY_INFO *StringInfoIn, OPTIONAL
00456   OUT       EFI_FONT_DISPLAY_INFO **StringInfoOut,
00457   IN CONST  EFI_STRING            String OPTIONAL
00458 );
00459 
00460 ///
00461 /// The protocol provides the service to retrieve the font informations.
00462 ///
00463 struct _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 extern EFI_GUID gEfiHiiFontProtocolGuid;
00471 
00472 
00473 #endif
00474