Reviewed the code comments in the Include/Protocol directory for typos, grammar issue...

[mirror_edk2.git] / MdePkg / Include / Protocol / HiiFont.h

/** @file\r
  The file provides services to retrieve font information.\r
  \r
  Copyright (c) 2006 - 2008, Intel Corporation\r
  All rights reserved. This program and the accompanying materials                          \r
  are licensed and made available under the terms and conditions of the BSD License         \r
  which accompanies this distribution.  The full text of the license may be found at        \r
  http://opensource.org/licenses/bsd-license.php                                            \r
\r
  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,                     \r
  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.             \r
\r
**/\r
\r
#ifndef __HII_FONT_H__\r
#define __HII_FONT_H__\r
\r
#include <Protocol/GraphicsOutput.h>\r
#include <Protocol/HiiImage.h>\r
\r
#define EFI_HII_FONT_PROTOCOL_GUID \\r
{ 0xe9ca4775, 0x8657, 0x47fc, { 0x97, 0xe7, 0x7e, 0xd6, 0x5a, 0x8, 0x43, 0x24 } }\r
\r
typedef struct _EFI_HII_FONT_PROTOCOL EFI_HII_FONT_PROTOCOL;\r
\r
typedef VOID    *EFI_FONT_HANDLE;\r
\r
///\r
/// EFI_HII_OUT_FLAGS\r
/// \r
typedef UINT32  EFI_HII_OUT_FLAGS;\r
\r
#define EFI_HII_OUT_FLAG_CLIP         0x00000001\r
#define EFI_HII_OUT_FLAG_WRAP         0x00000002\r
#define EFI_HII_OUT_FLAG_CLIP_CLEAN_Y 0x00000004\r
#define EFI_HII_OUT_FLAG_CLIP_CLEAN_X 0x00000008\r
#define EFI_HII_OUT_FLAG_TRANSPARENT  0x00000010\r
#define EFI_HII_IGNORE_IF_NO_GLYPH    0x00000020\r
#define EFI_HII_IGNORE_LINE_BREAK     0x00000040\r
#define EFI_HII_DIRECT_TO_SCREEN      0x00000080\r
\r
/**\r
  Definition of EFI_HII_ROW_INFO.\r
**/\r
typedef struct _EFI_HII_ROW_INFO {\r
  ///\r
  /// The index of the first character in the string which is displayed on the line.\r
  ///\r
  UINTN   StartIndex;\r
  ///\r
  /// The index of the last character in the string which is displayed on the line.\r
  /// If this is the same as StartIndex, then no characters are displayed.  \r
  ///\r
  UINTN   EndIndex;\r
  UINTN   LineHeight; ///< The height of the line, in pixels.\r
  UINTN   LineWidth;  ///< The width of the text on the line, in pixels.\r
  \r
  ///\r
  /// The number of pixels above the bottom of the row of the font baseline or 0 if none.  \r
  ///\r
  UINTN   BaselineOffset;\r
} EFI_HII_ROW_INFO;\r
\r
///\r
/// Font info flag. All flags (FONT, SIZE, STYLE, and COLOR) are defined.\r
/// They are defined as EFI_FONT_INFO_***\r
///\r
typedef UINT32  EFI_FONT_INFO_MASK;\r
\r
#define EFI_FONT_INFO_SYS_FONT        0x00000001\r
#define EFI_FONT_INFO_SYS_SIZE        0x00000002\r
#define EFI_FONT_INFO_SYS_STYLE       0x00000004\r
#define EFI_FONT_INFO_SYS_FORE_COLOR  0x00000010\r
#define EFI_FONT_INFO_SYS_BACK_COLOR  0x00000020\r
#define EFI_FONT_INFO_RESIZE          0x00001000\r
#define EFI_FONT_INFO_RESTYLE         0x00002000\r
#define EFI_FONT_INFO_ANY_FONT        0x00010000\r
#define EFI_FONT_INFO_ANY_SIZE        0x00020000\r
#define EFI_FONT_INFO_ANY_STYLE       0x00040000\r
\r
//\r
// EFI_FONT_INFO\r
// \r
typedef struct {\r
  EFI_HII_FONT_STYLE FontStyle;\r
  UINT16             FontSize;      ///< character cell height in pixels\r
  CHAR16             FontName[1];\r
} EFI_FONT_INFO;\r
\r
/**\r
  Describes font output-related information.\r
\r
  This structure is used for describing the way a string\r
  should be rendered in a particular font. FontInfo specifies the\r
  basic font information, and ForegroundColor and BackgroundColor\r
  specify the color in which the characters should be displayed. The flags\r
  in FontInfoMask describe where the system default should be\r
  supplied instead of the specified information. The flags also\r
  describe what options can be used to make a match between the\r
  font requested and the font available.\r
**/\r
typedef struct _EFI_FONT_DISPLAY_INFO {\r
  EFI_GRAPHICS_OUTPUT_BLT_PIXEL ForegroundColor;\r
  EFI_GRAPHICS_OUTPUT_BLT_PIXEL BackgroundColor;\r
  EFI_FONT_INFO_MASK            FontInfoMask;\r
  EFI_FONT_INFO                 FontInfo;  \r
} EFI_FONT_DISPLAY_INFO;\r
\r
/**\r
\r
  This function renders a string to a bitmap or the screen using\r
  the specified font, color and options. It either draws the\r
  string and glyphs on an existing bitmap, allocates a new bitmap\r
  or uses the screen. The strings can be clipped or wrapped.\r
  Optionally, the function also returns the information about each\r
  row and the character position on that row. If\r
  EFI_HII_OUT_FLAG_CLIP is set, then text will be formatted only\r
  based on explicit line breaks and all pixels which would lie\r
  outside the bounding box specified by Width and Height are\r
  ignored. The information in the RowInfoArray only describes\r
  characters which are at least partially displayed. For the final\r
  row, the LineHeight and BaseLine may describe pixels which are\r
  outside the limit specified by Height (unless\r
  EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is specified) even though those\r
  pixels were not drawn. The LineWidth may describe pixels which\r
  are outside the limit specified by Width (unless\r
  EFI_HII_OUT_FLAG_CLIP_CLEAN_X is specified) even though those\r
  pixels were not drawn. If EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set,\r
  then it modifies the behavior of EFI_HII_OUT_FLAG_CLIP so that\r
  if a character's right-most on pixel cannot fit, then it will\r
  not be drawn at all. This flag requires that\r
  EFI_HII_OUT_FLAG_CLIP be set. If EFI_HII_OUT_FLAG_CLIP_CLEAN_Y\r
  is set, then it modifies the behavior of EFI_HII_OUT_FLAG_CLIP\r
  so that if a row's bottom-most pixel cannot fit, then it will\r
  not be drawn at all. This flag requires that\r
  EFI_HII_OUT_FLAG_CLIP be set. If EFI_HII_OUT_FLAG_WRAP is set,\r
  then text will be wrapped at the right-most line-break\r
  opportunity prior to a character whose right-most extent would\r
  exceed Width. If no line-break opportunity can be found, then\r
  the text will behave as if EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set.\r
  This flag cannot be used with EFI_HII_OUT_FLAG_CLIP_CLEAN_X. If\r
  EFI_HII_OUT_FLAG_TRANSPARENT is set, then BackgroundColor is\r
  ignored and all 'off' pixels in the character's drawn\r
  will use the pixel value from Blt. This flag cannot be used if\r
  Blt is NULL upon entry. If EFI_HII_IGNORE_IF_NO_GLYPH is set,\r
  then characters which have no glyphs are not drawn. Otherwise,\r
  they are replaced with Unicode character 0xFFFD (REPLACEMENT\r
  CHARACTER). If EFI_HII_IGNORE_LINE_BREAK is set, then explicit\r
  line break characters will be ignored. If\r
  EFI_HII_DIRECT_TO_SCREEN is set, then the string will be written\r
  directly to the output device specified by Screen. Otherwise the\r
  string will be rendered to the bitmap specified by Bitmap.\r
\r
  @param This             A pointer to the EFI_HII_FONT_PROTOCOL instance.\r
\r
  @param Flags            Describes how the string is to be drawn.\r
\r
  @param String           Points to the null-terminated string to be \r
\r
  @param StringInfo       Points to the string output information,\r
                          including the color and font. If NULL, then\r
                          the string will be output in the default\r
                          system font and color.\r
\r
  @param Blt              If this points to a non-NULL on entry, this points\r
                          to the image, which is Width pixels wide and\r
                          Height pixels high. The string will be drawn onto\r
                          this image and EFI_HII_OUT_FLAG_CLIP is implied.\r
                          If this points to a NULL on entry, then a buffer\r
                          will be allocated to hold the generated image and\r
                          the pointer updated on exit. It is the caller's\r
                          responsibility to free this buffer.\r
\r
  @param BltX, BltY       Specifies the offset from the left and top\r
                          edge of the image of the first character\r
                          cell in the image.\r
\r
  @param RowInfoArray     If this is non-NULL on entry, then on\r
                          exit, this will point to an allocated buffer\r
                          containing row information and\r
                          RowInfoArraySize will be updated to contain\r
                          the number of elements. This array describes\r
                          the characters which were at least partially\r
                          drawn and the heights of the rows. It is the\r
                          caller's responsibility to free this buffer.\r
\r
  @param RowInfoArraySize If this is non-NULL on entry, then on\r
                          exit it contains the number of\r
                          elements in RowInfoArray.\r
\r
  @param ColumnInfoArray  If this is non-NULL, then on return it\r
                          will be filled with the horizontal\r
                          offset for each character in the\r
                          string on the row where it is\r
                          displayed. Non-printing characters\r
                          will have the offset ~0. The caller is\r
                          responsible for allocating a buffer large\r
                          enough so that there is one entry for\r
                          each character in the string, not\r
                          including the null-terminator. It is\r
                          possible when character display is\r
                          normalized that some character cells\r
                          overlap.\r
\r
  @retval EFI_SUCCESS           The string was successfully updated.\r
  \r
  @retval EFI_OUT_OF_RESOURCES  Unable to allocate an output buffer for RowInfoArray or Blt.\r
  \r
  @retval EFI_INVALID_PARAMETER The String or Blt was NULL.\r
\r
  @retval EFI_INVALID_PARAMETER Flags were invalid combination.\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_HII_STRING_TO_IMAGE)(\r
  IN CONST  EFI_HII_FONT_PROTOCOL *This,\r
  IN        EFI_HII_OUT_FLAGS     Flags,\r
  IN CONST  EFI_STRING            String,\r
  IN CONST  EFI_FONT_DISPLAY_INFO *StringInfo,\r
  IN OUT    EFI_IMAGE_OUTPUT      **Blt,\r
  IN        UINTN                 BltX,\r
  IN        UINTN                 BltY,\r
  OUT       EFI_HII_ROW_INFO      **RowInfoArray OPTIONAL,\r
  OUT       UINTN                 *RowInfoArraySize OPTIONAL,\r
  OUT       UINTN                 *ColumnInfoArray OPTIONAL\r
);\r
\r
\r
\r
/**\r
\r
  This function renders a string as a bitmap or to the screen\r
  and can clip or wrap the string. The bitmap is either supplied\r
  by the caller or allocated by the function. The\r
  strings are drawn with the font, size and style specified and\r
  can be drawn transparently or opaquely. The function can also\r
  return information about each row and each character's\r
  position on the row. If EFI_HII_OUT_FLAG_CLIP is set, then\r
  text will be formatted only based on explicit line breaks and\r
  all pixels which would lie outside the bounding box specified\r
  by Width and Height are ignored. The information in the\r
  RowInfoArray only describes characters which are at least\r
  partially displayed. For the final row, the LineHeight and\r
  BaseLine may describe pixels which are outside the limit\r
  specified by Height (unless EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is\r
  specified) even though those pixels were not drawn. If\r
  EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set, then it modifies the\r
  behavior of EFI_HII_OUT_FLAG_CLIP so that if a character's\r
  right-most on pixel cannot fit, then it will not be drawn at\r
  all. This flag requires that EFI_HII_OUT_FLAG_CLIP be set. If\r
  EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is set, then it modifies the\r
  behavior of EFI_HII_OUT_FLAG_CLIP so that if a row's bottom\r
  most pixel cannot fit, then it will not be drawn at all. This\r
  flag requires that EFI_HII_OUT_FLAG_CLIP be set. Draft for\r
  Review HII Protocols Version 2.1 November 3, 2006 1285 If\r
  EFI_HII_OUT_FLAG_WRAP is set, then text will be wrapped at the\r
  right-most line-break opportunity prior to a character whose\r
  right-most extent would exceed Width. If no line-break\r
  opportunity can be found, then the text will behave as if\r
  EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set. This flag cannot be used\r
  with EFI_HII_OUT_FLAG_CLIP_CLEAN_X. If\r
  EFI_HII_OUT_FLAG_TRANSPARENT is set, then BackgroundColor is\r
  ignored and all off" pixels in the character's glyph will\r
  use the pixel value from Blt. This flag cannot be used if Blt\r
  is NULL upon entry. If EFI_HII_IGNORE_IF_NO_GLYPH is set, then\r
  characters which have no glyphs are not drawn. Otherwise, they\r
  are replaced with Unicode character 0xFFFD (REPLACEMENT\r
  CHARACTER). If EFI_HII_IGNORE_LINE_BREAK is set, then explicit\r
  line break characters will be ignored. If\r
  EFI_HII_DIRECT_TO_SCREEN is set, then the string will be\r
  written directly to the output device specified by Screen.\r
  Otherwise the string will be rendered to the bitmap specified\r
  by Bitmap.\r
\r
\r
  @param This       A pointer to the EFI_HII_FONT_PROTOCOL instance.\r
\r
  @param Flags      Describes how the string is to be drawn.\r
\r
  @param PackageList  \r
                    The package list in the HII database to\r
                    search for the specified string.\r
\r
  @param StringId   The string's id, which is unique within\r
                    PackageList.\r
\r
  @param Language   Points to the language for the retrieved\r
                    string. If NULL, then the current system\r
                    language is used.\r
\r
  @param StringInfo Points to the string output information,\r
                    including the color and font. If NULL, then\r
                    the string will be output in the default\r
                    system font and color.\r
\r
  @param Blt        If this points to a non-NULL on entry, this points\r
                    to the image, which is Width pixels wide and\r
                    Height pixels high. The string will be drawn onto\r
                    this image and EFI_HII_OUT_FLAG_CLIP is implied.\r
                    If this points to a NULL on entry, then a buffer\r
                    will be allocated to hold the generated image and\r
                    the pointer updated on exit. It is the caller's\r
                    responsibility to free this buffer.\r
\r
  @param BltX, BltY Specifies the offset from the left and top\r
                    edge of the output image of the first\r
                    character cell in the image.\r
\r
  @param RowInfoArray     If this is non-NULL on entry, then on\r
                          exit, this will point to an allocated\r
                          buffer containing row information and\r
                          RowInfoArraySize will be updated to\r
                          contain the number of elements. This array\r
                          describes the characters which were at\r
                          least partially drawn and the heights of\r
                          the rows. It is the caller's\r
                          responsibility to free this buffer.\r
\r
  @param RowInfoArraySize If this is non-NULL on entry, then on\r
                          exit it contains the number of\r
                          elements in RowInfoArray.\r
\r
  @param ColumnInfoArray  If non-NULL, on return it is filled\r
                          with the horizontal offset for each\r
                          character in the string on the row\r
                          where it is displayed. Non-printing\r
                          characters will have the offset ~0.\r
                          The caller is responsible to allocate\r
                          a buffer large enough so that there is\r
                          one entry for each character in the\r
                          string, not including the\r
                          null-terminator. It is possible when\r
                          character display is normalized that\r
                          some character cells overlap.\r
\r
\r
  @retval EFI_SUCCESS           The string was successfully updated.\r
\r
  @retval EFI_OUT_OF_RESOURCES  Unable to allocate an output\r
                                buffer for RowInfoArray or Blt.\r
\r
  @retval EFI_INVALID_PARAMETER The String or Blt or Height or\r
                                Width was NULL.\r
  @retval EFI_INVALID_PARAMETER The Blt or PackageList was NULL.\r
  @retval EFI_INVALID_PARAMETER Flags were invalid combination.\r
  @retval EFI_NOT_FOUND         The specified PackageList is not in the Database \r
                                or the stringid is not in the specified PackageList. \r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_HII_STRING_ID_TO_IMAGE)(\r
  IN CONST  EFI_HII_FONT_PROTOCOL *This,\r
  IN        EFI_HII_OUT_FLAGS     Flags,\r
  IN        EFI_HII_HANDLE        PackageList,\r
  IN        EFI_STRING_ID         StringId,\r
  IN CONST  CHAR8                 *Language,\r
  IN CONST  EFI_FONT_DISPLAY_INFO *StringInfo       OPTIONAL,\r
  IN OUT    EFI_IMAGE_OUTPUT      **Blt,\r
  IN        UINTN                 BltX,\r
  IN        UINTN                 BltY,\r
  OUT       EFI_HII_ROW_INFO      **RowInfoArray    OPTIONAL,\r
  OUT       UINTN                 *RowInfoArraySize OPTIONAL,\r
  OUT       UINTN                 *ColumnInfoArray  OPTIONAL\r
);\r
\r
\r
/**\r
\r
  Convert the glyph for a single character into a bitmap.\r
\r
  @param This       A pointer to the EFI_HII_FONT_PROTOCOL instance.\r
\r
  @param Char       Character to retrieve.\r
\r
  @param StringInfo Points to the string font and color\r
                    information or NULL if the string should use\r
                    the default system font and color.\r
\r
  @param Blt        Thus must point to a NULL on entry. A buffer will\r
                    be allocated to hold the output and the pointer\r
                    updated on exit. It is the caller's responsibility\r
                    to free this buffer.\r
\r
  @param Baseline   Number of pixels from the bottom of the bitmap\r
                    to the baseline.\r
\r
\r
  @retval EFI_SUCCESS             Glyph bitmap created.\r
\r
  @retval EFI_OUT_OF_RESOURCES    Unable to allocate the output buffer Blt.\r
\r
  @retval EFI_WARN_UNKNOWN_GLYPH  The glyph was unknown and was\r
                                  replaced with the glyph for\r
                                  Unicode character 0xFFFD.\r
\r
  @retval EFI_INVALID_PARAMETER   Blt is NULL or Width is NULL or\r
                                  Height is NULL\r
\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_HII_GET_GLYPH)(\r
  IN CONST  EFI_HII_FONT_PROTOCOL *This,\r
  IN CONST  CHAR16                Char,\r
  IN CONST  EFI_FONT_DISPLAY_INFO *StringInfo,\r
  OUT       EFI_IMAGE_OUTPUT      **Blt,\r
  OUT       UINTN                 *Baseline OPTIONAL\r
);\r
\r
/**\r
\r
  This function iterates through fonts which match the specified\r
  font, using the specified criteria. If String is non-NULL, then\r
  all of the characters in the string must exist in order for a\r
  candidate font to be returned.\r
\r
  @param This           A pointer to the EFI_HII_FONT_PROTOCOL instance.\r
\r
  @param FontHandle     On entry, points to the font handle returned\r
                        by a previous call to GetFontInfo() or NULL\r
                        to start with the first font. On return,\r
                        points to the returned font handle or points\r
                        to NULL if there are no more matching fonts.\r
\r
  @param StringInfoIn   Upon entry, points to the font to return\r
                        information about. If NULL, then the information about the system default \r
                        font will be returned.\r
\r
  @param StringInfoOut  Upon return, contains the matching\r
                        font's information. If NULL, then no\r
                        information is returned.\r
\r
  @param String         Points to the string which will be tested to\r
                        determine if all characters are available. If\r
                        NULL, then any font is acceptable.\r
  \r
  @retval EFI_SUCCESS            Matching font returned successfully.\r
  \r
  @retval EFI_NOT_FOUND          No matching font was found.\r
\r
  @retval EFI_OUT_OF_RESOURCES   There were insufficient resources to complete the request.\r
  \r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_HII_GET_FONT_INFO)(\r
  IN CONST  EFI_HII_FONT_PROTOCOL *This,\r
  IN OUT    EFI_FONT_HANDLE       *FontHandle,\r
  IN CONST  EFI_FONT_DISPLAY_INFO *StringInfoIn, OPTIONAL\r
  OUT       EFI_FONT_DISPLAY_INFO **StringInfoOut,\r
  IN CONST  EFI_STRING            String OPTIONAL\r
);\r
\r
///\r
/// The protocol provides the service to retrieve the font informations.\r
///\r
struct _EFI_HII_FONT_PROTOCOL {\r
  EFI_HII_STRING_TO_IMAGE     StringToImage;\r
  EFI_HII_STRING_ID_TO_IMAGE  StringIdToImage;\r
  EFI_HII_GET_GLYPH           GetGlyph;\r
  EFI_HII_GET_FONT_INFO       GetFontInfo;\r
};\r
\r
extern EFI_GUID gEfiHiiFontProtocolGuid;\r
\r
\r
#endif\r
\r