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