diff options
author | Guo Mang <mang.guo@intel.com> | 2016-12-22 15:57:14 +0800 |
---|---|---|
committer | Guo Mang <mang.guo@intel.com> | 2016-12-26 19:14:41 +0800 |
commit | 1760cf81e4b1847c6823ea3514a78dd120e19b6e (patch) | |
tree | 64a874b14050fe24d3bbc1bc13cd293abf8ae018 /Core/MdePkg/Include/Protocol/HiiFont.h | |
parent | 7f05fa00f73038b425002566d3afe6c3ade2ccdb (diff) | |
download | edk2-platforms-1760cf81e4b1847c6823ea3514a78dd120e19b6e.tar.xz |
MdePkg: Move to new location
Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Guo Mang <mang.guo@intel.com>
Diffstat (limited to 'Core/MdePkg/Include/Protocol/HiiFont.h')
-rw-r--r-- | Core/MdePkg/Include/Protocol/HiiFont.h | 472 |
1 files changed, 472 insertions, 0 deletions
diff --git a/Core/MdePkg/Include/Protocol/HiiFont.h b/Core/MdePkg/Include/Protocol/HiiFont.h new file mode 100644 index 0000000000..6314df8e37 --- /dev/null +++ b/Core/MdePkg/Include/Protocol/HiiFont.h @@ -0,0 +1,472 @@ +/** @file
+ The file provides services to retrieve font information.
+
+Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR>
+This program and the accompanying materials are licensed and made available under
+the terms and conditions of the BSD License that 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.
+
+**/
+
+#ifndef __HII_FONT_H__
+#define __HII_FONT_H__
+
+#include <Protocol/GraphicsOutput.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;
+
+typedef VOID *EFI_FONT_HANDLE;
+
+///
+/// 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_CLIP_CLEAN_Y 0x00000004
+#define EFI_HII_OUT_FLAG_CLIP_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.
+**/
+typedef struct _EFI_HII_ROW_INFO {
+ ///
+ /// The index of the first character in the string which is displayed on the line.
+ ///
+ UINTN StartIndex;
+ ///
+ /// 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.
+ ///
+ UINTN EndIndex;
+ UINTN LineHeight; ///< The height of the line, in pixels.
+ UINTN LineWidth; ///< The width of the text on the line, in pixels.
+
+ ///
+ /// The font baseline offset in pixels from the bottom of the row, or 0 if none.
+ ///
+ UINTN BaselineOffset;
+} EFI_HII_ROW_INFO;
+
+///
+/// Font info flag. All flags (FONT, SIZE, STYLE, and COLOR) are defined.
+/// They are defined as EFI_FONT_INFO_***
+///
+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 {
+ EFI_HII_FONT_STYLE FontStyle;
+ UINT16 FontSize; ///< character cell height in pixels
+ CHAR16 FontName[1];
+} EFI_FONT_INFO;
+
+/**
+ Describes font output-related information.
+
+ 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.
+**/
+typedef struct _EFI_FONT_DISPLAY_INFO {
+ EFI_GRAPHICS_OUTPUT_BLT_PIXEL ForegroundColor;
+ EFI_GRAPHICS_OUTPUT_BLT_PIXEL BackgroundColor;
+ EFI_FONT_INFO_MASK FontInfoMask;
+ EFI_FONT_INFO FontInfo;
+} 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 that 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 code 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
+
+ @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 that 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 for allocating 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 was NULL.
+
+ @retval EFI_INVALID_PARAMETER Flags were invalid combination.
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_HII_STRING_TO_IMAGE)(
+ IN CONST EFI_HII_FONT_PROTOCOL *This,
+ IN EFI_HII_OUT_FLAGS Flags,
+ IN CONST EFI_STRING String,
+ IN CONST EFI_FONT_DISPLAY_INFO *StringInfo,
+ IN OUT EFI_IMAGE_OUTPUT **Blt,
+ IN UINTN BltX,
+ IN 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 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 based only on explicit line breaks, and
+ all pixels that 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. 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 code 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.
+ @retval EFI_INVALID_PARAMETER The Blt or PackageList was NULL.
+ @retval EFI_INVALID_PARAMETER Flags were invalid combination.
+ @retval EFI_NOT_FOUND The specified PackageList is not in the Database,
+ or the stringid is not in the specified PackageList.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_HII_STRING_ID_TO_IMAGE)(
+ IN CONST EFI_HII_FONT_PROTOCOL *This,
+ IN EFI_HII_OUT_FLAGS Flags,
+ IN EFI_HII_HANDLE PackageList,
+ IN EFI_STRING_ID StringId,
+ IN CONST CHAR8 *Language,
+ IN CONST EFI_FONT_DISPLAY_INFO *StringInfo OPTIONAL,
+ IN OUT EFI_IMAGE_OUTPUT **Blt,
+ IN UINTN BltX,
+ IN 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 The 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 This 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 The number of pixels from the bottom of the bitmap
+ to the baseline.
+
+
+ @retval EFI_SUCCESS The 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 code 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. If NULL, then the information
+ about the system default font will be returned.
+
+ @param StringInfoOut Upon return, contains the matching font's information.
+ If NULL, then no information is returned. This buffer
+ is allocated with a call to the Boot Service AllocatePool().
+ It is the caller's responsibility to call the Boot
+ Service FreePool() when the caller no longer requires
+ the contents of StringInfoOut.
+
+ @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_OUT_OF_RESOURCES There were insufficient resources to complete the request.
+
+**/
+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, OPTIONAL
+ OUT EFI_FONT_DISPLAY_INFO **StringInfoOut,
+ IN CONST EFI_STRING String OPTIONAL
+);
+
+///
+/// The protocol provides the service to retrieve the font informations.
+///
+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
+
|