MdePkg/Include/Protocol/HiiFont.h

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