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 /**
 228
 229   This function renders a string as a bitmap or to the screen
 230   and can clip or wrap the string. The bitmap is either supplied
 231   by the caller or allocated by the function. The
 232   strings are drawn with the font, size and style specified and
 233   can be drawn transparently or opaquely. The function can also
 234   return information about each row and each character's
 235   position on the row. If EFI_HII_OUT_FLAG_CLIP is set, then
 236   text will be formatted based only on explicit line breaks, and
 237   all pixels that would lie outside the bounding box specified
 238   by Width and Height are ignored. The information in the
 239   RowInfoArray only describes characters which are at least
 240   partially displayed. For the final row, the LineHeight and
 241   BaseLine may describe pixels which are outside the limit
 242   specified by Height (unless EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is
 243   specified) even though those pixels were not drawn. If
 244   EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set, then it modifies the
 245   behavior of EFI_HII_OUT_FLAG_CLIP so that if a character's
 246   right-most on pixel cannot fit, then it will not be drawn at
 247   all. This flag requires that EFI_HII_OUT_FLAG_CLIP be set. If
 248   EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is set, then it modifies the
 249   behavior of EFI_HII_OUT_FLAG_CLIP so that if a row's bottom
 250   most pixel cannot fit, then it will not be drawn at all. This
 251   flag requires that EFI_HII_OUT_FLAG_CLIP be set. If
 252   EFI_HII_OUT_FLAG_WRAP is set, then text will be wrapped at the
 253   right-most line-break opportunity prior to a character whose
 254   right-most extent would exceed Width. If no line-break
 255   opportunity can be found, then the text will behave as if
 256   EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set. This flag cannot be used
 257   with EFI_HII_OUT_FLAG_CLIP_CLEAN_X. If
 258   EFI_HII_OUT_FLAG_TRANSPARENT is set, then BackgroundColor is
 259   ignored and all off" pixels in the character's glyph will
 260   use the pixel value from Blt. This flag cannot be used if Blt
 261   is NULL upon entry. If EFI_HII_IGNORE_IF_NO_GLYPH is set, then
 262   characters which have no glyphs are not drawn. Otherwise, they
 263   are replaced with Unicode character code 0xFFFD (REPLACEMENT
 264   CHARACTER). If EFI_HII_IGNORE_LINE_BREAK is set, then explicit
 265   line break characters will be ignored. If
 266   EFI_HII_DIRECT_TO_SCREEN is set, then the string will be
 267   written directly to the output device specified by Screen.
 268   Otherwise the string will be rendered to the bitmap specified
 269   by Bitmap.
 270
 271
 272   @param This       A pointer to the EFI_HII_FONT_PROTOCOL instance.
 273
 274   @param Flags      Describes how the string is to be drawn.
 275
 276   @param PackageList
 277                     The package list in the HII database to
 278                     search for the specified string.
 279
 280   @param StringId   The string's id, which is unique within
 281                     PackageList.
 282
 283   @param Language   Points to the language for the retrieved
 284                     string. If NULL, then the current system
 285                     language is used.
 286
 287   @param StringInfo Points to the string output information,
 288                     including the color and font. If NULL, then
 289                     the string will be output in the default
 290                     system font and color.
 291
 292   @param Blt        If this points to a non-NULL on entry, this points
 293                     to the image, which is Width pixels wide and
 294                     Height pixels high. The string will be drawn onto
 295                     this image and EFI_HII_OUT_FLAG_CLIP is implied.
 296                     If this points to a NULL on entry, then a buffer
 297                     will be allocated to hold the generated image and
 298                     the pointer updated on exit. It is the caller's
 299                     responsibility to free this buffer.
 300
 301   @param BltX, BltY Specifies the offset from the left and top
 302                     edge of the output image of the first
 303                     character cell in the image.
 304
 305   @param RowInfoArray     If this is non-NULL on entry, then on
 306                           exit, this will point to an allocated
 307                           buffer containing row information and
 308                           RowInfoArraySize will be updated to
 309                           contain the number of elements. This array
 310                           describes the characters which were at
 311                           least partially drawn and the heights of
 312                           the rows. It is the caller's
 313                           responsibility to free this buffer.
 314
 315   @param RowInfoArraySize If this is non-NULL on entry, then on
 316                           exit it contains the number of
 317                           elements in RowInfoArray.
 318
 319   @param ColumnInfoArray  If non-NULL, on return it is filled
 320                           with the horizontal offset for each
 321                           character in the string on the row
 322                           where it is displayed. Non-printing
 323                           characters will have the offset ~0.
 324                           The caller is responsible to allocate
 325                           a buffer large enough so that there is
 326                           one entry for each character in the
 327                           string, not including the
 328                           null-terminator. It is possible when
 329                           character display is normalized that
 330                           some character cells overlap.
 331
 332
 333   @retval EFI_SUCCESS           The string was successfully updated.
 334
 335   @retval EFI_OUT_OF_RESOURCES  Unable to allocate an output
 336                                 buffer for RowInfoArray or Blt.
 337
 338   @retval EFI_INVALID_PARAMETER The String, or Blt, or Height, or
 339                                 Width was NULL.
 340   @retval EFI_INVALID_PARAMETER The Blt or PackageList was NULL.
 341   @retval EFI_INVALID_PARAMETER Flags were invalid combination.
 342   @retval EFI_NOT_FOUND         The specified PackageList is not in the Database,
 343                                 or the stringid is not in the specified PackageList.
 344
 345 **/
 346 typedef
 347 EFI_STATUS
 348 (EFIAPI *EFI_HII_STRING_ID_TO_IMAGE)(
 349   IN CONST  EFI_HII_FONT_PROTOCOL *This,
 350   IN        EFI_HII_OUT_FLAGS     Flags,
 351   IN        EFI_HII_HANDLE        PackageList,
 352   IN        EFI_STRING_ID         StringId,
 353   IN CONST  CHAR8                 *Language,
 354   IN CONST  EFI_FONT_DISPLAY_INFO *StringInfo       OPTIONAL,
 355   IN OUT    EFI_IMAGE_OUTPUT      **Blt,
 356   IN        UINTN                 BltX,
 357   IN        UINTN                 BltY,
 358   OUT       EFI_HII_ROW_INFO      **RowInfoArray    OPTIONAL,
 359   OUT       UINTN                 *RowInfoArraySize OPTIONAL,
 360   OUT       UINTN                 *ColumnInfoArray  OPTIONAL
 361 );
 362
 363
 364 /**
 365
 366   Convert the glyph for a single character into a bitmap.
 367
 368   @param This       A pointer to the EFI_HII_FONT_PROTOCOL instance.
 369
 370   @param Char       The character to retrieve.
 371
 372   @param StringInfo Points to the string font and color
 373                     information or NULL if the string should use
 374                     the default system font and color.
 375
 376   @param Blt        This must point to a NULL on entry. A buffer will
 377                     be allocated to hold the output and the pointer
 378                     updated on exit. It is the caller's responsibility
 379                     to free this buffer.
 380
 381   @param Baseline   The number of pixels from the bottom of the bitmap
 382                     to the baseline.
 383
 384
 385   @retval EFI_SUCCESS             The glyph bitmap created.
 386
 387   @retval EFI_OUT_OF_RESOURCES    Unable to allocate the output buffer Blt.
 388
 389   @retval EFI_WARN_UNKNOWN_GLYPH  The glyph was unknown and was
 390                                   replaced with the glyph for
 391                                   Unicode character code 0xFFFD.
 392
 393   @retval EFI_INVALID_PARAMETER   Blt is NULL, or Width is NULL, or
 394                                   Height is NULL
 395
 396
 397 **/
 398 typedef
 399 EFI_STATUS
 400 (EFIAPI *EFI_HII_GET_GLYPH)(
 401   IN CONST  EFI_HII_FONT_PROTOCOL *This,
 402   IN CONST  CHAR16                Char,
 403   IN CONST  EFI_FONT_DISPLAY_INFO *StringInfo,
 404   OUT       EFI_IMAGE_OUTPUT      **Blt,
 405   OUT       UINTN                 *Baseline OPTIONAL
 406 );
 407
 408 /**
 409
 410   This function iterates through fonts which match the specified
 411   font, using the specified criteria. If String is non-NULL, then
 412   all of the characters in the string must exist in order for a
 413   candidate font to be returned.
 414
 415   @param This           A pointer to the EFI_HII_FONT_PROTOCOL instance.
 416
 417   @param FontHandle     On entry, points to the font handle returned
 418                         by a previous call to GetFontInfo() or NULL
 419                         to start with the first font. On return,
 420                         points to the returned font handle or points
 421                         to NULL if there are no more matching fonts.
 422
 423   @param StringInfoIn   Upon entry, points to the font to return
 424                         information about. If NULL, then the information
 425                         about the system default font will be returned.
 426
 427   @param  StringInfoOut Upon return, contains the matching font's information.
 428                         If NULL, then no information is returned. This buffer
 429                         is allocated with a call to the Boot Service AllocatePool().
 430                         It is the caller's responsibility to call the Boot
 431                         Service FreePool() when the caller no longer requires
 432                         the contents of StringInfoOut.
 433
 434   @param String         Points to the string which will be tested to
 435                         determine if all characters are available. If
 436                         NULL, then any font is acceptable.
 437
 438   @retval EFI_SUCCESS            Matching font returned successfully.
 439
 440   @retval EFI_NOT_FOUND          No matching font was found.
 441
 442   @retval EFI_OUT_OF_RESOURCES   There were insufficient resources to complete the request.
 443
 444 **/
 445 typedef
 446 EFI_STATUS
 447 (EFIAPI *EFI_HII_GET_FONT_INFO)(
 448   IN CONST  EFI_HII_FONT_PROTOCOL *This,
 449   IN OUT    EFI_FONT_HANDLE       *FontHandle,
 450   IN CONST  EFI_FONT_DISPLAY_INFO *StringInfoIn, OPTIONAL
 451   OUT       EFI_FONT_DISPLAY_INFO **StringInfoOut,
 452   IN CONST  EFI_STRING            String OPTIONAL
 453 );
 454
 455 ///
 456 /// The protocol provides the service to retrieve the font informations.
 457 ///
 458 struct _EFI_HII_FONT_PROTOCOL {
 459   EFI_HII_STRING_TO_IMAGE     StringToImage;
 460   EFI_HII_STRING_ID_TO_IMAGE  StringIdToImage;
 461   EFI_HII_GET_GLYPH           GetGlyph;
 462   EFI_HII_GET_FONT_INFO       GetFontInfo;
 463 };
 464
 465 extern EFI_GUID gEfiHiiFontProtocolGuid;
 466
 467
 468 #endif
 469