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