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