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