MdePkg/Include/Protocol/HiiFont.h - edk2 - Git at Google

 /** @file
   The file provides services to retrieve font information.

 Copyright (c) 2006 - 2018, 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
	/** @file
	The file provides services to retrieve font information.

	Copyright (c) 2006 - 2018, 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