EdkCompatibilityPkg/Foundation/Efi/Protocol/HiiFont/HiiFont.h

   1 /*++
   2
   3 Copyright (c) 2007 - 2010, Intel Corporation. All rights reserved.<BR>
   4 This program and the accompanying materials
   5 are licensed and made available under the terms and conditions of the BSD License
   6 which accompanies this distribution.  The full text of the license may be found at
   7 http://opensource.org/licenses/bsd-license.php
   8
   9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  11
  12 Module Name:
  13
  14     HiiFont.h
  15
  16 Abstract:
  17
  18     EFI_HII_FONT_PROTOCOL from UEFI 2.1 specification.
  19
  20     This protocol provides interfaces to retrieve font information.
  21
  22 Revision History
  23
  24 --*/
  25
  26 #ifndef __EFI_HII_FONT_PROTOCOL_H__
  27 #define __EFI_HII_FONT_PROTOCOL_H__
  28
  29 #include EFI_PROTOCOL_DEFINITION (GraphicsOutput)
  30 #include EFI_PROTOCOL_DEFINITION (HiiImage)
  31
  32 //
  33 // Global ID for the Hii Font Protocol.
  34 //
  35
  36 #define EFI_HII_FONT_PROTOCOL_GUID \
  37   { \
  38     0xe9ca4775, 0x8657, 0x47fc, {0x97, 0xe7, 0x7e, 0xd6, 0x5a, 0x8, 0x43, 0x24} \
  39   }
  40
  41 EFI_FORWARD_DECLARATION (EFI_HII_FONT_PROTOCOL);
  42
  43 typedef UINT32  EFI_HII_OUT_FLAGS;
  44 typedef UINT32  EFI_FONT_INFO_MASK;
  45 typedef VOID*   EFI_FONT_HANDLE;
  46
  47 typedef struct _EFI_HII_ROW_INFO {
  48   UINTN StartIndex;
  49   UINTN EndIndex;
  50   UINTN LineHeight;
  51   UINTN LineWidth;
  52   UINTN BaselineOffset;
  53 } EFI_HII_ROW_INFO;
  54
  55 typedef struct {
  56   EFI_HII_FONT_STYLE FontStyle;
  57   UINT16             FontSize; // character cell height in pixels
  58   CHAR16             FontName[1];
  59 } EFI_FONT_INFO;
  60
  61 typedef struct _EFI_FONT_DISPLAY_INFO {
  62   EFI_GRAPHICS_OUTPUT_BLT_PIXEL ForegroundColor;
  63   EFI_GRAPHICS_OUTPUT_BLT_PIXEL BackgroundColor;
  64   EFI_FONT_INFO_MASK            FontInfoMask;
  65   EFI_FONT_INFO                 FontInfo;
  66 } EFI_FONT_DISPLAY_INFO;
  67
  68 #define EFI_HII_OUT_FLAG_CLIP         0x00000001
  69 #define EFI_HII_OUT_FLAG_WRAP         0x00000002
  70 #define EFI_HII_OUT_FLAG_CLIP_CLEAN_Y 0x00000004
  71 #define EFI_HII_OUT_FLAG_CLIP_CLEAN_X 0x00000008
  72 #define EFI_HII_OUT_FLAG_TRANSPARENT  0x00000010
  73 #define EFI_HII_IGNORE_IF_NO_GLYPH    0x00000020
  74 #define EFI_HII_IGNORE_LINE_BREAK     0x00000040
  75 #define EFI_HII_DIRECT_TO_SCREEN      0x00000080
  76
  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 typedef
  89 EFI_STATUS
  90 (EFIAPI *EFI_HII_STRING_TO_IMAGE) (
  91   IN  CONST EFI_HII_FONT_PROTOCOL    *This,
  92   IN  EFI_HII_OUT_FLAGS              Flags,
  93   IN  CONST EFI_STRING               String,
  94   IN  CONST EFI_FONT_DISPLAY_INFO    *StringInfo       OPTIONAL,
  95   IN  OUT EFI_IMAGE_OUTPUT           **Blt,
  96   IN  UINTN                          BltX,
  97   IN  UINTN                          BltY,
  98   OUT EFI_HII_ROW_INFO               **RowInfoArray    OPTIONAL,
  99   OUT UINTN                          *RowInfoArraySize OPTIONAL,
 100   OUT UINTN                          *ColumnInfoArray  OPTIONAL
 101   )
 102 /*++
 103
 104   Routine Description:
 105     Renders a string to a bitmap or to the display.
 106
 107   Arguments:
 108     This              - A pointer to the EFI_HII_FONT_PROTOCOL instance.
 109     Flags             - Describes how the string is to be drawn.
 110     String            - Points to the null-terminated string to be displayed.
 111     StringInfo        - Points to the string output information, including the color and font.
 112                         If NULL, then the string will be output in the default system font and color.
 113     Blt               - If this points to a non-NULL on entry, this points to the image, which is Width pixels
 114                         wide and Height pixels high. The string will be drawn onto this image and
 115                         EFI_HII_OUT_FLAG_CLIP is implied. If this points to a NULL on entry, then a
 116                         buffer will be allocated to hold the generated image and the pointer updated on exit. It
 117                         is the caller's responsibility to free this buffer.
 118     BltX,BLTY         - Specifies the offset from the left and top edge of the image of the first character cell in
 119                         the image.
 120     RowInfoArray      - If this is non-NULL on entry, then on exit, this will point to an allocated buffer
 121                         containing row information and RowInfoArraySize will be updated to contain the
 122                         number of elements. This array describes the characters which were at least partially
 123                         drawn and the heights of the rows. It is the caller's responsibility to free this buffer.
 124     RowInfoArraySize  - If this is non-NULL on entry, then on exit it contains the number of elements in
 125                         RowInfoArray.
 126     ColumnInfoArray   - If this is non-NULL, then on return it will be filled with the horizontal offset for each
 127                         character in the string on the row where it is displayed. Non-printing characters will
 128                         have the offset ~0. The caller is responsible to allocate a buffer large enough so that
 129                         there is one entry for each character in the string, not including the null-terminator. It
 130                         is possible when character display is normalized that some character cells overlap.
 131
 132   Returns:
 133     EFI_SUCCESS           - The string was successfully rendered.
 134     EFI_OUT_OF_RESOURCES  - Unable to allocate an output buffer for RowInfoArray or Blt.
 135     EFI_INVALID_PARAMETER - The String or Blt was NULL.
 136     EFI_INVALID_PARAMETER - Flags were invalid combination.
 137
 138 --*/
 139 ;
 140
 141 typedef
 142 EFI_STATUS
 143 (EFIAPI *EFI_HII_STRING_ID_TO_IMAGE) (
 144   IN  CONST EFI_HII_FONT_PROTOCOL    *This,
 145   IN  EFI_HII_OUT_FLAGS              Flags,
 146   IN  EFI_HII_HANDLE                 PackageList,
 147   IN  EFI_STRING_ID                  StringId,
 148   IN  CONST CHAR8*                   Language,
 149   IN  CONST EFI_FONT_DISPLAY_INFO    *StringInfo       OPTIONAL,
 150   IN  OUT EFI_IMAGE_OUTPUT           **Blt,
 151   IN  UINTN                          BltX,
 152   IN  UINTN                          BltY,
 153   OUT EFI_HII_ROW_INFO               **RowInfoArray    OPTIONAL,
 154   OUT UINTN                          *RowInfoArraySize OPTIONAL,
 155   OUT UINTN                          *ColumnInfoArray  OPTIONAL
 156   )
 157 /*++
 158
 159   Routine Description:
 160     Render a string to a bitmap or the screen containing the contents of the specified string.
 161
 162   Arguments:
 163     This              - A pointer to the EFI_HII_FONT_PROTOCOL instance.
 164     Flags             - Describes how the string is to be drawn.
 165     PackageList       - The package list in the HII database to search for the specified string.
 166     StringId          - The string's id, which is unique within PackageList.
 167     Language          - Points to the language for the retrieved string. If NULL, then the current system
 168                         language is used.
 169     StringInfo        - Points to the string output information, including the color and font.
 170                         If NULL, then the string will be output in the default system font and color.
 171     Blt               - If this points to a non-NULL on entry, this points to the image, which is Width pixels
 172                         wide and Height pixels high. The string will be drawn onto this image and
 173                         EFI_HII_OUT_FLAG_CLIP is implied. If this points to a NULL on entry, then a
 174                         buffer will be allocated to hold the generated image and the pointer updated on exit. It
 175                         is the caller's responsibility to free this buffer.
 176     BltX,BLTY         - Specifies the offset from the left and top edge of the image of the first character cell in
 177                         the image.
 178     RowInfoArray      - If this is non-NULL on entry, then on exit, this will point to an allocated buffer
 179                         containing row information and RowInfoArraySize will be updated to contain the
 180                         number of elements. This array describes the characters which were at least partially
 181                         drawn and the heights of the rows. It is the caller's responsibility to free this buffer.
 182     RowInfoArraySize  - If this is non-NULL on entry, then on exit it contains the number of elements in
 183                         RowInfoArray.
 184     ColumnInfoArray   - If this is non-NULL, then on return it will be filled with the horizontal offset for each
 185                         character in the string on the row where it is displayed. Non-printing characters will
 186                         have the offset ~0. The caller is responsible to allocate a buffer large enough so that
 187                         there is one entry for each character in the string, not including the null-terminator. It
 188                         is possible when character display is normalized that some character cells overlap.
 189
 190   Returns:
 191     EFI_SUCCESS           - The string was successfully rendered.
 192     EFI_OUT_OF_RESOURCES  - Unable to allocate an output buffer for RowInfoArray or Blt.
 193     EFI_INVALID_PARAMETER - The Blt or PackageList was NULL.
 194     EFI_INVALID_PARAMETER - Flags were invalid combination.
 195     EFI_NOT_FOUND         - The specified PackageList is not in the Database or the stringid is not
 196                             in the specified PackageList.
 197
 198 --*/
 199 ;
 200
 201 typedef
 202 EFI_STATUS
 203 (EFIAPI *EFI_HII_GET_GLYPH) (
 204   IN  CONST EFI_HII_FONT_PROTOCOL    *This,
 205   IN  CHAR16                         Char,
 206   IN  CONST EFI_FONT_DISPLAY_INFO    *StringInfo,
 207   OUT EFI_IMAGE_OUTPUT               **Blt,
 208   OUT UINTN                          *Baseline OPTIONAL
 209   )
 210 /*++
 211
 212   Routine Description:
 213     Convert the glyph for a single character into a bitmap.
 214
 215   Arguments:
 216     This              - A pointer to the EFI_HII_FONT_PROTOCOL instance.
 217     Char              - Character to retrieve.
 218     StringInfo        - Points to the string font and color information or NULL if the string should use the
 219                         default system font and color.
 220     Blt               - Thus must point to a NULL on entry. A buffer will be allocated to hold the output and
 221                         the pointer updated on exit. It is the caller's responsibility to free this buffer.
 222     Baseline          - Number of pixels from the bottom of the bitmap to the baseline.
 223
 224   Returns:
 225     EFI_SUCCESS            - Glyph bitmap created.
 226     EFI_OUT_OF_RESOURCES   - Unable to allocate the output buffer Blt.
 227     EFI_WARN_UNKNOWN_GLYPH - The glyph was unknown and was
 228                              replaced with the glyph for Unicode
 229                              character 0xFFFD.
 230     EFI_INVALID_PARAMETER  - Blt is NULL or *Blt is not NULL.
 231
 232 --*/
 233 ;
 234
 235 typedef
 236 EFI_STATUS
 237 (EFIAPI *EFI_HII_GET_FONT_INFO) (
 238   IN  CONST EFI_HII_FONT_PROTOCOL    *This,
 239   IN  OUT   EFI_FONT_HANDLE          *FontHandle,
 240   IN  CONST EFI_FONT_DISPLAY_INFO    *StringInfoIn, OPTIONAL
 241   OUT       EFI_FONT_DISPLAY_INFO    **StringInfoOut,
 242   IN  CONST EFI_STRING               String OPTIONAL
 243   )
 244 /*++
 245
 246   Routine Description:
 247     This function iterates through fonts which match the specified font, using
 248     the specified criteria. If String is non-NULL, then all of the characters in
 249     the string must exist in order for a candidate font to be returned.
 250
 251   Arguments:
 252     This              - A pointer to the EFI_HII_FONT_PROTOCOL instance.
 253     FontHandle        - On entry, points to the font handle returned by a previous
 254                         call to GetFontInfo() or points to NULL to start with the
 255                         first font. On return, points to the returned font handle or
 256                         points to NULL if there are no more matching fonts.
 257     StringInfoIn      - Upon entry, points to the font to return information about.
 258                         If NULL, then the information about the system default
 259                         font will be returned.
 260     StringInfoOut     - Upon return, contains the matching font's information.
 261                         If NULL, then no information is returned.
 262                         It's caller's responsibility to free this buffer.
 263     String            - Points to the string which will be tested to determine
 264                         if all characters are available. If NULL, then any font
 265                         is acceptable.
 266
 267   Returns:
 268     EFI_SUCCESS            - Matching font returned successfully.
 269     EFI_NOT_FOUND          - No matching font was found.
 270     EFI_INVALID_PARAMETER  - StringInfoIn->FontInfoMask is an invalid combination.
 271     EFI_OUT_OF_RESOURCES   - There were insufficient resources to complete the request.
 272
 273 --*/
 274 ;
 275
 276
 277 //
 278 // Interface structure for the EFI_HII_FONT_PROTOCOL
 279 //
 280 struct _EFI_HII_FONT_PROTOCOL {
 281   EFI_HII_STRING_TO_IMAGE       StringToImage;
 282   EFI_HII_STRING_ID_TO_IMAGE    StringIdToImage;
 283   EFI_HII_GET_GLYPH             GetGlyph;
 284   EFI_HII_GET_FONT_INFO         GetFontInfo;
 285 };
 286
 287 extern EFI_GUID gEfiHiiFontProtocolGuid;
 288
 289 #endif