MdePkg/Include/Protocol/HiiFont.h

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