MdePkg/Include/Protocol/HiiFont.h

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