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

   1 /*++
   2
   3 Copyright (c) 2007, 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   UINT32 FontStyle;
  57   UINT16 FontSize; // character cell size 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_CLEAN_Y     0x00000004
  71 #define EFI_HII_OUT_FLAG_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 was NULL.
 136
 137 --*/
 138 ;
 139
 140 typedef
 141 EFI_STATUS
 142 (EFIAPI *EFI_HII_STRING_ID_TO_IMAGE) (
 143   IN  CONST EFI_HII_FONT_PROTOCOL    *This,
 144   IN  EFI_HII_OUT_FLAGS              Flags,
 145   IN  EFI_HII_HANDLE                 PackageList,
 146   IN  EFI_STRING_ID                  StringId,
 147   IN  CONST CHAR8*                   Language,
 148   IN  CONST EFI_FONT_DISPLAY_INFO    *StringInfo       OPTIONAL,
 149   IN  OUT EFI_IMAGE_OUTPUT           **Blt,
 150   IN  UINTN                          BltX,
 151   IN  UINTN                          BltY,
 152   OUT EFI_HII_ROW_INFO               **RowInfoArray    OPTIONAL,
 153   OUT UINTN                          *RowInfoArraySize OPTIONAL,
 154   OUT UINTN                          *ColumnInfoArray  OPTIONAL
 155   )
 156 /*++
 157
 158   Routine Description:
 159     Render a string to a bitmap or the screen containing the contents of the specified string.
 160
 161   Arguments:
 162     This              - A pointer to the EFI_HII_FONT_PROTOCOL instance.
 163     Flags             - Describes how the string is to be drawn.
 164     PackageList       - The package list in the HII database to search for the specified string.
 165     StringId          - The string's id, which is unique within PackageList.
 166     Language          - Points to the language for the retrieved string. If NULL, then the current system
 167                         language is used.
 168     StringInfo        - Points to the string output information, including the color and font.
 169                         If NULL, then the string will be output in the default system font and color.
 170     Blt               - If this points to a non-NULL on entry, this points to the image, which is Width pixels
 171                         wide and Height pixels high. The string will be drawn onto this image and
 172                         EFI_HII_OUT_FLAG_CLIP is implied. If this points to a NULL on entry, then a
 173                         buffer will be allocated to hold the generated image and the pointer updated on exit. It
 174                         is the caller's responsibility to free this buffer.
 175     BltX,BLTY         - Specifies the offset from the left and top edge of the image of the first character cell in
 176                         the image.
 177     RowInfoArray      - If this is non-NULL on entry, then on exit, this will point to an allocated buffer
 178                         containing row information and RowInfoArraySize will be updated to contain the
 179                         number of elements. This array describes the characters which were at least partially
 180                         drawn and the heights of the rows. It is the caller's responsibility to free this buffer.
 181     RowInfoArraySize  - If this is non-NULL on entry, then on exit it contains the number of elements in
 182                         RowInfoArray.
 183     ColumnInfoArray   - If this is non-NULL, then on return it will be filled with the horizontal offset for each
 184                         character in the string on the row where it is displayed. Non-printing characters will
 185                         have the offset ~0. The caller is responsible to allocate a buffer large enough so that
 186                         there is one entry for each character in the string, not including the null-terminator. It
 187                         is possible when character display is normalized that some character cells overlap.
 188
 189   Returns:
 190     EFI_SUCCESS           - The string was successfully rendered.
 191     EFI_OUT_OF_RESOURCES  - Unable to allocate an output buffer for RowInfoArray or Blt.
 192     EFI_INVALID_PARAMETER - The String was NULL.
 193
 194 --*/
 195 ;
 196
 197 typedef
 198 EFI_STATUS
 199 (EFIAPI *EFI_HII_GET_GLYPH) (
 200   IN  CONST EFI_HII_FONT_PROTOCOL    *This,
 201   IN  CHAR16                         Char,
 202   IN  CONST EFI_FONT_DISPLAY_INFO    *StringInfo,
 203   OUT EFI_IMAGE_OUTPUT               **Blt,
 204   OUT UINTN                          *Baseline OPTIONAL
 205   )
 206 /*++
 207
 208   Routine Description:
 209     Convert the glyph for a single character into a bitmap.
 210
 211   Arguments:
 212     This              - A pointer to the EFI_HII_FONT_PROTOCOL instance.
 213     Char              - Character to retrieve.
 214     StringInfo        - Points to the string font and color information or NULL if the string should use the
 215                         default system font and color.
 216     Blt               - Thus must point to a NULL on entry. A buffer will be allocated to hold the output and
 217                         the pointer updated on exit. It is the caller's responsibility to free this buffer.
 218     Baseline          - Number of pixels from the bottom of the bitmap to the baseline.
 219
 220   Returns:
 221     EFI_SUCCESS            - Glyph bitmap created.
 222     EFI_OUT_OF_RESOURCES   - Unable to allocate the output buffer Blt.
 223     EFI_WARN_UNKNOWN_GLYPH - The glyph was unknown and was
 224                              replaced with the glyph for Unicode
 225                              character 0xFFFD.
 226     EFI_INVALID_PARAMETER  - Blt is NULL or *Blt is not NULL.
 227
 228 --*/
 229 ;
 230
 231 typedef
 232 EFI_STATUS
 233 (EFIAPI *EFI_HII_GET_FONT_INFO) (
 234   IN  CONST EFI_HII_FONT_PROTOCOL    *This,
 235   IN  OUT   EFI_FONT_HANDLE          *FontHandle,
 236   IN  CONST EFI_FONT_DISPLAY_INFO    *StringInfoIn,
 237   OUT       EFI_FONT_DISPLAY_INFO    **StringInfoOut,
 238   IN  CONST EFI_STRING               String OPTIONAL
 239   )
 240 /*++
 241
 242   Routine Description:
 243     This function iterates through fonts which match the specified font, using
 244     the specified criteria. If String is non-NULL, then all of the characters in
 245     the string must exist in order for a candidate font to be returned.
 246
 247   Arguments:
 248     This              - A pointer to the EFI_HII_FONT_PROTOCOL instance.
 249     FontHandle        - On entry, points to the font handle returned by a
 250                         previous call to GetFontInfo() or NULL to start with the
 251                         first font. On return, points to the returned font handle or
 252                         points to NULL if there are no more matching fonts.
 253     StringInfoIn      - Upon entry, points to the font to return information about.
 254     StringInfoOut     - Upon return, contains the matching font's information.
 255                         If NULL, then no information is returned.
 256                         It's caller's responsibility to free this buffer.
 257     String            - Points to the string which will be tested to determine
 258                         if all characters are available. If NULL, then any font
 259                         is acceptable.
 260
 261   Returns:
 262     EFI_SUCCESS            - Matching font returned successfully.
 263     EFI_NOT_FOUND          - No matching font was found.
 264     EFI_INVALID_PARAMETER  - StringInfoIn is NULL.
 265     EFI_OUT_OF_RESOURCES   - There were insufficient resources to complete the request.
 266
 267 --*/
 268 ;
 269
 270
 271 //
 272 // Interface structure for the EFI_HII_FONT_PROTOCOL
 273 //
 274 struct _EFI_HII_FONT_PROTOCOL {
 275   EFI_HII_STRING_TO_IMAGE       StringToImage;
 276   EFI_HII_STRING_ID_TO_IMAGE    StringIdToImage;
 277   EFI_HII_GET_GLYPH             GetGlyph;
 278   EFI_HII_GET_FONT_INFO         GetFontInfo;
 279 };
 280
 281 extern EFI_GUID gEfiHiiFontProtocolGuid;
 282
 283 #endif