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