[mirror_edk2.git] / MdePkg / Include / Protocol / HiiFont.h

/** @file\r
  The file provides services to retrieve font information.\r
  \r
  Copyright (c) 2006 - 2007, Intel Corporation\r
  All rights reserved. This program and the accompanying materials                          \r
  are licensed and made available under the terms and conditions of the BSD License         \r
  which accompanies this distribution.  The full text of the license may be found at        \r
  http://opensource.org/licenses/bsd-license.php                                            \r
\r
  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,                     \r
  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.             \r
\r
**/\r
\r
#ifndef __HII_FONT_H__\r
#define __HII_FONT_H__\r
\r
#include <Protocol/GraphicsOutput.h>\r
#include <Protocol/HiiImage.h>\r
\r
#error "UEFI 2.1 HII is not fully implemented for now, Please don't include this file now."\r
\r
#define EFI_HII_FONT_PROTOCOL_GUID \\r
{ 0xe9ca4775, 0x8657, 0x47fc, { 0x97, 0xe7, 0x7e, 0xd6, 0x5a, 0x8, 0x43, 0x24 } }\r
\r
typedef struct _EFI_HII_FONT_PROTOCOL EFI_HII_FONT_PROTOCOL;\r
\r
typedef VOID    *EFI_FONT_HANDLE;\r
\r
//\r
// EFI_HII_OUT_FLAGS\r
// \r
typedef UINT32  EFI_HII_OUT_FLAGS;\r
#define EFI_HII_OUT_FLAG_CLIP         0x00000001\r
#define EFI_HII_OUT_FLAG_WRAP         0x00000002\r
#define EFI_HII_OUT_FLAG_CLEAN_Y      0x00000004\r
#define EFI_HII_OUT_FLAG_CLEAN_X      0x00000008\r
#define EFI_HII_OUT_FLAG_TRANSPARENT  0x00000010\r
#define EFI_HII_IGNORE_IF_NO_GLYPH    0x00000020\r
#define EFI_HII_IGNORE_LINE_BREAK     0x00000040\r
#define EFI_HII_DIRECT_TO_SCREEN      0x00000080\r
\r
/**\r
\r
  Definition of EFI_HII_ROW_INFO.\r
\r
  @param StartIndex The index of the first character in the\r
                    string which is displayed on the line.\r
\r
  @param EndIndex The index of the last character in the string\r
                  which is displayed on the line. If this is the\r
                  same as StartIndex, then no characters are\r
                  displayed.\r
\r
  @param LineHeight The height of the line, in pixels.\r
\r
  @param LineWidth  The width of the text on the line, in\r
                    pixels.\r
\r
  @param BaselineOffset The number of pixels above the bottom of\r
                        the row of the font baseline or 0 if\r
                        none.\r
\r
**/\r
typedef struct _EFI_HII_ROW_INFO {\r
  UINTN   StartIndex;\r
  UINTN   EndIndex;\r
  UINTN   LineHeight;\r
  UINTN   LineWidth;\r
  UINTN   BaselineOffset;\r
} EFI_HII_ROW_INFO;\r
\r
//\r
// EFI_FONT_INFO_MASK\r
// \r
typedef UINT32  EFI_FONT_INFO_MASK;\r
#define EFI_FONT_INFO_SYS_FONT        0x00000001\r
#define EFI_FONT_INFO_SYS_SIZE        0x00000002\r
#define EFI_FONT_INFO_SYS_STYLE       0x00000004\r
#define EFI_FONT_INFO_SYS_FORE_COLOR  0x00000010\r
#define EFI_FONT_INFO_SYS_BACK_COLOR  0x00000020\r
#define EFI_FONT_INFO_RESIZE          0x00001000\r
#define EFI_FONT_INFO_RESTYLE         0x00002000\r
#define EFI_FONT_INFO_ANY_FONT        0x00010000\r
#define EFI_FONT_INFO_ANY_SIZE        0x00020000\r
#define EFI_FONT_INFO_ANY_STYLE       0x00040000\r
\r
//\r
// EFI_FONT_INFO\r
// \r
typedef struct {\r
  UINT32  FontStyle;\r
  UINT16  FontSize;\r
  CHAR16  FontName[1];\r
} EFI_FONT_INFO;\r
\r
/**\r
  This structure is used for describing the way in which a string\r
  should be rendered in a particular font. FontInfo specifies the\r
  basic font information and ForegroundColor and BackgroundColor\r
  specify the color in which they should be displayed. The flags\r
  in FontInfoMask describe where the system default should be\r
  supplied instead of the specified information. The flags also\r
  describe what options can be used to make a match between the\r
  font requested and the font available. If EFI_FONT_INFO_SYS_FONT\r
  is specified, then the font name in FontInfo is ignored and the\r
  system font name is used. This flag cannot be used with\r
  EFI_FONT_INFO_ANY_FONT. If EFI_FONT_INFO_SYS_SIZE is specified,\r
  then the font height specified in FontInfo is ignored and the\r
  system font height is used instead. This flag cannot be used\r
  with EFI_FONT_INFO_ANY_SIZE. If EFI_FONT_INFO_SYS_STYLE is\r
  specified, then the font style in FontInfo is ignored and the\r
  system font style is used. This flag cannot be used with\r
  EFI_FONT_INFO_ANY_STYLE. If EFI_FONT_INFO_SYS_FORE_COLOR is\r
  specified, then ForegroundColor is ignored and the system\r
  foreground color is used. If EFI_FONT_INFO_SYS_BACK_COLOR is\r
  specified, then BackgroundColor is ignored and the system\r
  background color is used. If EFI_FONT_INFO_RESIZE is specified,\r
  then the system may attempt to stretch or shrink a font to meet\r
  the size requested. This flag cannot be used with\r
  EFI_FONT_INFO_ANY_SIZE. If EFI_FONT_INFO_RESTYLE is specified,\r
  then the system may attempt to remove some of the specified\r
  styles in order to meet the style requested. This flag cannot be\r
  used with EFI_FONT_INFO_ANY_STYLE. If EFI_FONT_INFO_ANY_FONT is\r
  specified, then the system may attempt to match with any font.\r
  This flag cannot be used with EFI_FONT_INFO_SYS_FONT. If\r
  EFI_FONT_INFO_ANY_SIZE is specified, then the system may attempt\r
  to match with any font size. This flag cannot be used with\r
  EFI_FONT_INFO_SYS_SIZE or EFI_FONT_INFO_RESIZE. If\r
  EFI_FONT_INFO_ANY_STYLE is specified, then the system may\r
  attempt to match with any font style. This flag cannot be used\r
  with EFI_FONT_INFO_SYS_STYLE or EFI_FONT_INFO_RESTYLE.\r
\r
  @param FontInfo Points to the font information or NULL if the\r
                  string should use the default system font.\r
  \r
  @param ForegroundColor  The color of the "on" pixels in the\r
                          glyph in the bitmap.\r
  \r
  @param BackgroundColor  The color of the "off" pixels in the\r
                          glyph in the bitmap.\r
  \r
  @param FontInfoMask   The font information mask determines\r
                        which portion of the font information\r
                        will be used and what to do if the\r
                        specific font is not available.\r
  \r
**/\r
typedef struct _EFI_FONT_DISPLAY_INFO {\r
  EFI_GRAPHICS_OUTPUT_BLT_PIXEL ForegroundColor;\r
  EFI_GRAPHICS_OUTPUT_BLT_PIXEL BackgroundColor;\r
  EFI_FONT_INFO_MASK            FontInfoMask;\r
  EFI_FONT_INFO                 FontInfo;  \r
} EFI_FONT_DISPLAY_INFO;\r
\r
/**\r
\r
  This function renders a string to a bitmap or the screen using\r
  the specified font, color and options. It either draws the\r
  string and glyphs on an existing bitmap, allocates a new bitmap\r
  or uses the screen. The strings can be clipped or wrapped.\r
  Optionally, the function also returns the information about each\r
  row and the character position on that row. If\r
  EFI_HII_OUT_FLAG_CLIP is set, then text will be formatted only\r
  based on explicit line breaks and all pixels which would lie\r
  outside the bounding box specified by Width and Height are\r
  ignored. The information in the RowInfoArray only describes\r
  characters which are at least partially displayed. For the final\r
  row, the LineHeight and BaseLine may describe pixels which are\r
  outside the limit specified by Height (unless\r
  EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is specified) even though those\r
  pixels were not drawn. The LineWidth may describe pixels which\r
  are outside the limit specified by Width (unless\r
  EFI_HII_OUT_FLAG_CLIP_CLEAN_X is specified) even though those\r
  pixels were not drawn. If EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set,\r
  then it modifies the behavior of EFI_HII_OUT_FLAG_CLIP so that\r
  if a character????s right-most on pixel cannot fit, then it will\r
  not be drawn at all. This flag requires that\r
  EFI_HII_OUT_FLAG_CLIP be set. If EFI_HII_OUT_FLAG_CLIP_CLEAN_Y\r
  is set, then it modifies the behavior of EFI_HII_OUT_FLAG_CLIP\r
  so that if a row????s bottom-most pixel cannot fit, then it will\r
  not be drawn at all. This flag requires that\r
  EFI_HII_OUT_FLAG_CLIP be set. If EFI_HII_OUT_FLAG_WRAP is set,\r
  then text will be wrapped at the right-most line-break\r
  opportunity prior to a character whose right-most extent would\r
  exceed Width. If no line-break opportunity can be found, then\r
  the text will behave as if EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set.\r
  This flag cannot be used with EFI_HII_OUT_FLAG_CLIP_CLEAN_X. If\r
  EFI_HII_OUT_FLAG_TRANSPARENT is set, then BackgroundColor is\r
  ignored and all ????off???? pixels in the character????s drawn\r
  will use the pixel value from Blt. This flag cannot be used if\r
  Blt is NULL upon entry. If EFI_HII_IGNORE_IF_NO_GLYPH is set,\r
  then characters which have no glyphs are not drawn. Otherwise,\r
  they are replaced with Unicode character 0xFFFD (REPLACEMENT\r
  CHARACTER). If EFI_HII_IGNORE_LINE_BREAK is set, then explicit\r
  line break characters will be ignored. If\r
  EFI_HII_DIRECT_TO_SCREEN is set, then the string will be written\r
  directly to the output device specified by Screen. Otherwise the\r
  string will be rendered to the bitmap specified by Bitmap.\r
\r
  @param This A pointer to the EFI_HII_FONT_PROTOCOL instance.\r
\r
  @param Flags  Describes how the string is to be drawn.\r
\r
  @param String Points to the null-terminated string to be\r
                displayed.\r
\r
  @param StringInfo Points to the string output information,\r
                    including the color and font. If NULL, then\r
                    the string will be output in the default\r
                    system font and color.\r
\r
  @param Blt  If this points to a non-NULL on entry, this points\r
              to the image, which is Width pixels wide and\r
              Height pixels high. The string will be drawn onto\r
              this image and EFI_HII_OUT_FLAG_CLIP is implied.\r
              If this points to a NULL on entry, then a buffer\r
              will be allocated to hold the generated image and\r
              the pointer updated on exit. It is the caller's\r
              responsibility to free this buffer.\r
\r
  @param BltX, BltY Specifies the offset from the left and top\r
                    edge of the image of the first character\r
                    cell in the image.\r
\r
  @param RowInfoArray If this is non-NULL on entry, then on\r
                    exit, this will point to an allocated buffer\r
                    containing row information and\r
                    RowInfoArraySize will be updated to contain\r
                    the number of elements. This array describes\r
                    the characters which were at least partially\r
                    drawn and the heights of the rows. It is the\r
                    caller's responsibility to free this buffer.\r
\r
  @param RowInfoArraySize If this is non-NULL on entry, then on\r
                          exit it contains the number of\r
                          elements in RowInfoArray.\r
\r
  @param ColumnInfoArray If this is non-NULL, then on return it\r
                          will be filled with the horizontal\r
                          offset for each character in the\r
                          string on the row where it is\r
                          displayed. Non-printing characters\r
                          will have the offset ~0. The caller is\r
                          responsible to allocate a buffer large\r
                          enough so that there is one entry for\r
                          each character in the string, not\r
                          including the null-terminator. It is\r
                          possible when character display is\r
                          normalized that some character cells\r
                          overlap.\r
\r
  @retval EFI_SUCCESS The string was successfully updated.\r
  \r
  @retval EFI_OUT_OF_RESOURCES  Unable to allocate an output\r
                                buffer for RowInfoArray or Blt.\r
  \r
  @retval EFI_INVALID_PARAMETER The String or Blt or Height or\r
                                Width was NULL.\r
\r
  \r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_HII_STRING_TO_IMAGE) (\r
  IN CONST  EFI_HII_FONT_PROTOCOL *This,\r
  IN CONST  EFI_HII_OUT_FLAGS     Flags,\r
  IN CONST  EFI_STRING            String,\r
  IN CONST  EFI_FONT_DISPLAY_INFO *StringInfo,\r
  IN OUT    EFI_IMAGE_OUTPUT      **Blt,\r
  IN CONST  UINTN                 BltX,\r
  IN CONST  UINTN                 BltY,\r
  OUT       EFI_HII_ROW_INFO      **RowInfoArray OPTIONAL,\r
  OUT       UINTN                 *RowInfoArraySize OPTIONAL,\r
  OUT       UINTN                 *ColumnInfoArray OPTIONAL\r
);\r
\r
\r
\r
/**\r
\r
  This function renders a string as a bitmap or to the screen\r
  and can clip or wrap the string. The bitmap is either supplied\r
  by the caller or else is allocated by the function. The\r
  strings are drawn with the font, size and style specified and\r
  can be drawn transparently or opaquely. The function can also\r
  return information about each row and each character's\r
  position on the row. If EFI_HII_OUT_FLAG_CLIP is set, then\r
  text will be formatted only based on explicit line breaks and\r
  all pixels which would lie outside the bounding box specified\r
  by Width and Height are ignored. The information in the\r
  RowInfoArray only describes characters which are at least\r
  partially displayed. For the final row, the LineHeight and\r
  BaseLine may describe pixels which are outside the limit\r
  specified by Height (unless EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is\r
  specified) even though those pixels were not drawn. If\r
  EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set, then it modifies the\r
  behavior of EFI_HII_OUT_FLAG_CLIP so that if a character????s\r
  right-most on pixel cannot fit, then it will not be drawn at\r
  all. This flag requires that EFI_HII_OUT_FLAG_CLIP be set. If\r
  EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is set, then it modifies the\r
  behavior of EFI_HII_OUT_FLAG_CLIP so that if a row????s bottom\r
  most pixel cannot fit, then it will not be drawn at all. This\r
  flag requires that EFI_HII_OUT_FLAG_CLIP be set. Draft for\r
  Review HII Protocols Version 2.1 November 3, 2006 1285 If\r
  EFI_HII_OUT_FLAG_WRAP is set, then text will be wrapped at the\r
  right-most line-break opportunity prior to a character whose\r
  right-most extent would exceed Width. If no line-break\r
  opportunity can be found, then the text will behave as if\r
  EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set. This flag cannot be used\r
  with EFI_HII_OUT_FLAG_CLIP_CLEAN_X. If\r
  EFI_HII_OUT_FLAG_TRANSPARENT is set, then BackgroundColor is\r
Commit	Line	Data
d1f95000	1	/** @file\r
	2	The file provides services to retrieve font information.\r
	3	\r
	4	Copyright (c) 2006 - 2007, Intel Corporation\r
	5	All rights reserved. This program and the accompanying materials \r
	6	are licensed and made available under the terms and conditions of the BSD License \r
	7	which accompanies this distribution. The full text of the license may be found at \r
	8	http://opensource.org/licenses/bsd-license.php \r
	9	\r
	10	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
	11	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
	12	\r
d1f95000	13	**/\r
	14	\r
	15	#ifndef __HII_FONT_H__\r
	16	#define __HII_FONT_H__\r
	17	\r
5a1fc221	18	#include <Protocol/GraphicsOutput.h>\r
d1f95000	19	#include <Protocol/HiiImage.h>\r
d1f95000	20	\r
1528fae8	21	#error "UEFI 2.1 HII is not fully implemented for now, Please don't include this file now."\r
1528fae8	22	\r
d1f95000	23	#define EFI_HII_FONT_PROTOCOL_GUID \\r
	24	{ 0xe9ca4775, 0x8657, 0x47fc, { 0x97, 0xe7, 0x7e, 0xd6, 0x5a, 0x8, 0x43, 0x24 } }\r
	25	\r
	26	typedef struct _EFI_HII_FONT_PROTOCOL EFI_HII_FONT_PROTOCOL;\r
	27	\r
5a1fc221	28	typedef VOID *EFI_FONT_HANDLE;\r
d1f95000	29	\r
	30	//\r
	31	// EFI_HII_OUT_FLAGS\r
	32	// \r
	33	typedef UINT32 EFI_HII_OUT_FLAGS;\r
	34	#define EFI_HII_OUT_FLAG_CLIP 0x00000001\r
	35	#define EFI_HII_OUT_FLAG_WRAP 0x00000002\r
	36	#define EFI_HII_OUT_FLAG_CLEAN_Y 0x00000004\r
	37	#define EFI_HII_OUT_FLAG_CLEAN_X 0x00000008\r
	38	#define EFI_HII_OUT_FLAG_TRANSPARENT 0x00000010\r
	39	#define EFI_HII_IGNORE_IF_NO_GLYPH 0x00000020\r
	40	#define EFI_HII_IGNORE_LINE_BREAK 0x00000040\r
	41	#define EFI_HII_DIRECT_TO_SCREEN 0x00000080\r
	42	\r
	43	/**\r
	44	\r
	45	Definition of EFI_HII_ROW_INFO.\r
	46	\r
	47	@param StartIndex The index of the first character in the\r
	48	string which is displayed on the line.\r
	49	\r
	50	@param EndIndex The index of the last character in the string\r
	51	which is displayed on the line. If this is the\r
	52	same as StartIndex, then no characters are\r
	53	displayed.\r
	54	\r
	55	@param LineHeight The height of the line, in pixels.\r
	56	\r
	57	@param LineWidth The width of the text on the line, in\r
	58	pixels.\r
	59	\r
	60	@param BaselineOffset The number of pixels above the bottom of\r
	61	the row of the font baseline or 0 if\r
	62	none.\r
	63	\r
	64	**/\r
	65	typedef struct _EFI_HII_ROW_INFO {\r
	66	UINTN StartIndex;\r
	67	UINTN EndIndex;\r
	68	UINTN LineHeight;\r
	69	UINTN LineWidth;\r
	70	UINTN BaselineOffset;\r
	71	} EFI_HII_ROW_INFO;\r
	72	\r
	73	//\r
	74	// EFI_FONT_INFO_MASK\r
	75	// \r
	76	typedef UINT32 EFI_FONT_INFO_MASK;\r
	77	#define EFI_FONT_INFO_SYS_FONT 0x00000001\r
	78	#define EFI_FONT_INFO_SYS_SIZE 0x00000002\r
	79	#define EFI_FONT_INFO_SYS_STYLE 0x00000004\r
	80	#define EFI_FONT_INFO_SYS_FORE_COLOR 0x00000010\r
	81	#define EFI_FONT_INFO_SYS_BACK_COLOR 0x00000020\r
	82	#define EFI_FONT_INFO_RESIZE 0x00001000\r
	83	#define EFI_FONT_INFO_RESTYLE 0x00002000\r
	84	#define EFI_FONT_INFO_ANY_FONT 0x00010000\r
	85	#define EFI_FONT_INFO_ANY_SIZE 0x00020000\r
	86	#define EFI_FONT_INFO_ANY_STYLE 0x00040000\r
	87	\r
	88	//\r
	89	// EFI_FONT_INFO\r
	90	// \r
	91	typedef struct {\r
	92	UINT32 FontStyle;\r
93	UINT16 FontSize;\r
94	CHAR16 FontName[1];\r
95	} EFI_FONT_INFO;\r
96	\r
97	/**\r
98	This structure is used for describing the way in which a string\r
99	should be rendered in a particular font. FontInfo specifies the\r
100	basic font information and ForegroundColor and BackgroundColor\r
101	specify the color in which they should be displayed. The flags\r
102	in FontInfoMask describe where the system default should be\r
103	supplied instead of the specified information. The flags also\r
104	describe what options can be used to make a match between the\r
105	font requested and the font available. If EFI_FONT_INFO_SYS_FONT\r
106	is specified, then the font name in FontInfo is ignored and the\r
107	system font name is used. This flag cannot be used with\r
108	EFI_FONT_INFO_ANY_FONT. If EFI_FONT_INFO_SYS_SIZE is specified,\r
109	then the font height specified in FontInfo is ignored and the\r
110	system font height is used instead. This flag cannot be used\r
111	with EFI_FONT_INFO_ANY_SIZE. If EFI_FONT_INFO_SYS_STYLE is\r
112	specified, then the font style in FontInfo is ignored and the\r
113	system font style is used. This flag cannot be used with\r
114	EFI_FONT_INFO_ANY_STYLE. If EFI_FONT_INFO_SYS_FORE_COLOR is\r
115	specified, then ForegroundColor is ignored and the system\r
116	foreground color is used. If EFI_FONT_INFO_SYS_BACK_COLOR is\r
117	specified, then BackgroundColor is ignored and the system\r
118	background color is used. If EFI_FONT_INFO_RESIZE is specified,\r
119	then the system may attempt to stretch or shrink a font to meet\r
120	the size requested. This flag cannot be used with\r
121	EFI_FONT_INFO_ANY_SIZE. If EFI_FONT_INFO_RESTYLE is specified,\r
122	then the system may attempt to remove some of the specified\r
123	styles in order to meet the style requested. This flag cannot be\r
124	used with EFI_FONT_INFO_ANY_STYLE. If EFI_FONT_INFO_ANY_FONT is\r
125	specified, then the system may attempt to match with any font.\r
126	This flag cannot be used with EFI_FONT_INFO_SYS_FONT. If\r
127	EFI_FONT_INFO_ANY_SIZE is specified, then the system may attempt\r
128	to match with any font size. This flag cannot be used with\r
129	EFI_FONT_INFO_SYS_SIZE or EFI_FONT_INFO_RESIZE. If\r
130	EFI_FONT_INFO_ANY_STYLE is specified, then the system may\r
131	attempt to match with any font style. This flag cannot be used\r
132	with EFI_FONT_INFO_SYS_STYLE or EFI_FONT_INFO_RESTYLE.\r
133	\r
134	@param FontInfo Points to the font information or NULL if the\r
135	string should use the default system font.\r
136	\r
137	@param ForegroundColor The color of the "on" pixels in the\r
138	glyph in the bitmap.\r
139	\r
140	@param BackgroundColor The color of the "off" pixels in the\r
141	glyph in the bitmap.\r
142	\r
143	@param FontInfoMask The font information mask determines\r
144	which portion of the font information\r
145	will be used and what to do if the\r
146	specific font is not available.\r
147	\r
148	**/\r
149	typedef struct _EFI_FONT_DISPLAY_INFO {\r
d1f95000	150	EFI_GRAPHICS_OUTPUT_BLT_PIXEL ForegroundColor;\r
	151	EFI_GRAPHICS_OUTPUT_BLT_PIXEL BackgroundColor;\r
	152	EFI_FONT_INFO_MASK FontInfoMask;\r
5a1fc221	153	EFI_FONT_INFO FontInfo; \r
d1f95000	154	} EFI_FONT_DISPLAY_INFO;\r
	155	\r
	156	/**\r
	157	\r
	158	This function renders a string to a bitmap or the screen using\r
	159	the specified font, color and options. It either draws the\r
	160	string and glyphs on an existing bitmap, allocates a new bitmap\r
	161	or uses the screen. The strings can be clipped or wrapped.\r
	162	Optionally, the function also returns the information about each\r
	163	row and the character position on that row. If\r
	164	EFI_HII_OUT_FLAG_CLIP is set, then text will be formatted only\r
	165	based on explicit line breaks and all pixels which would lie\r
	166	outside the bounding box specified by Width and Height are\r
	167	ignored. The information in the RowInfoArray only describes\r
	168	characters which are at least partially displayed. For the final\r
	169	row, the LineHeight and BaseLine may describe pixels which are\r
	170	outside the limit specified by Height (unless\r
	171	EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is specified) even though those\r
	172	pixels were not drawn. The LineWidth may describe pixels which\r
	173	are outside the limit specified by Width (unless\r
	174	EFI_HII_OUT_FLAG_CLIP_CLEAN_X is specified) even though those\r
	175	pixels were not drawn. If EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set,\r
	176	then it modifies the behavior of EFI_HII_OUT_FLAG_CLIP so that\r
	177	if a character????s right-most on pixel cannot fit, then it will\r
	178	not be drawn at all. This flag requires that\r
	179	EFI_HII_OUT_FLAG_CLIP be set. If EFI_HII_OUT_FLAG_CLIP_CLEAN_Y\r
	180	is set, then it modifies the behavior of EFI_HII_OUT_FLAG_CLIP\r
	181	so that if a row????s bottom-most pixel cannot fit, then it will\r
	182	not be drawn at all. This flag requires that\r
	183	EFI_HII_OUT_FLAG_CLIP be set. If EFI_HII_OUT_FLAG_WRAP is set,\r
	184	then text will be wrapped at the right-most line-break\r
	185	opportunity prior to a character whose right-most extent would\r
	186	exceed Width. If no line-break opportunity can be found, then\r
	187	the text will behave as if EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set.\r
	188	This flag cannot be used with EFI_HII_OUT_FLAG_CLIP_CLEAN_X. If\r
	189	EFI_HII_OUT_FLAG_TRANSPARENT is set, then BackgroundColor is\r
	190	ignored and all ????off???? pixels in the character????s drawn\r
	191	will use the pixel value from Blt. This flag cannot be used if\r
	192	Blt is NULL upon entry. If EFI_HII_IGNORE_IF_NO_GLYPH is set,\r
	193	then characters which have no glyphs are not drawn. Otherwise,\r
	194	they are replaced with Unicode character 0xFFFD (REPLACEMENT\r
	195	CHARACTER). If EFI_HII_IGNORE_LINE_BREAK is set, then explicit\r
	196	line break characters will be ignored. If\r
	197	EFI_HII_DIRECT_TO_SCREEN is set, then the string will be written\r
	198	directly to the output device specified by Screen. Otherwise the\r
	199	string will be rendered to the bitmap specified by Bitmap.\r
	200	\r
	201	@param This A pointer to the EFI_HII_FONT_PROTOCOL instance.\r
	202	\r
	203	@param Flags Describes how the string is to be drawn.\r
	204	\r
	205	@param String Points to the null-terminated string to be\r
	206	displayed.\r
	207	\r
	208	@param StringInfo Points to the string output information,\r
	209	including the color and font. If NULL, then\r
	210	the string will be output in the default\r
	211	system font and color.\r
	212	\r
	213	@param Blt If this points to a non-NULL on entry, this points\r
	214	to the image, which is Width pixels wide and\r
	215	Height pixels high. The string will be drawn onto\r
	216	this image and EFI_HII_OUT_FLAG_CLIP is implied.\r
	217	If this points to a NULL on entry, then a buffer\r
218	will be allocated to hold the generated image and\r
219	the pointer updated on exit. It is the caller's\r
220	responsibility to free this buffer.\r
221	\r
222	@param BltX, BltY Specifies the offset from the left and top\r
223	edge of the image of the first character\r
224	cell in the image.\r
225	\r
226	@param RowInfoArray If this is non-NULL on entry, then on\r
227	exit, this will point to an allocated buffer\r
228	containing row information and\r
229	RowInfoArraySize will be updated to contain\r
230	the number of elements. This array describes\r
231	the characters which were at least partially\r
232	drawn and the heights of the rows. It is the\r
233	caller's responsibility to free this buffer.\r
234	\r
235	@param RowInfoArraySize If this is non-NULL on entry, then on\r
236	exit it contains the number of\r
237	elements in RowInfoArray.\r
238	\r
239	@param ColumnInfoArray If this is non-NULL, then on return it\r
240	will be filled with the horizontal\r
241	offset for each character in the\r
242	string on the row where it is\r
243	displayed. Non-printing characters\r
244	will have the offset ~0. The caller is\r
245	responsible to allocate a buffer large\r
246	enough so that there is one entry for\r
247	each character in the string, not\r
248	including the null-terminator. It is\r
249	possible when character display is\r
250	normalized that some character cells\r
251	overlap.\r
252	\r
253	@retval EFI_SUCCESS The string was successfully updated.\r
254	\r
255	@retval EFI_OUT_OF_RESOURCES Unable to allocate an output\r
256	buffer for RowInfoArray or Blt.\r
257	\r
258	@retval EFI_INVALID_PARAMETER The String or Blt or Height or\r
259	Width was NULL.\r
260	\r
261	\r
262	**/\r
263	typedef\r
264	EFI_STATUS\r
265	(EFIAPI *EFI_HII_STRING_TO_IMAGE) (\r
266	IN CONST EFI_HII_FONT_PROTOCOL *This,\r
267	IN CONST EFI_HII_OUT_FLAGS Flags,\r
268	IN CONST EFI_STRING String,\r
269	IN CONST EFI_FONT_DISPLAY_INFO *StringInfo,\r
270	IN OUT EFI_IMAGE_OUTPUT **Blt,\r
271	IN CONST UINTN BltX,\r
272	IN CONST UINTN BltY,\r
273	OUT EFI_HII_ROW_INFO **RowInfoArray OPTIONAL,\r
274	OUT UINTN *RowInfoArraySize OPTIONAL,\r
275	OUT UINTN *ColumnInfoArray OPTIONAL\r
276	);\r
277	\r
278	\r
279	\r
280	/**\r
281	\r
282	This function renders a string as a bitmap or to the screen\r
283	and can clip or wrap the string. The bitmap is either supplied\r
284	by the caller or else is allocated by the function. The\r
285	strings are drawn with the font, size and style specified and\r
286	can be drawn transparently or opaquely. The function can also\r
287	return information about each row and each character's\r
288	position on the row. If EFI_HII_OUT_FLAG_CLIP is set, then\r
289	text will be formatted only based on explicit line breaks and\r
290	all pixels which would lie outside the bounding box specified\r
291	by Width and Height are ignored. The information in the\r
292	RowInfoArray only describes characters which are at least\r
293	partially displayed. For the final row, the LineHeight and\r
294	BaseLine may describe pixels which are outside the limit\r
295	specified by Height (unless EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is\r
296	specified) even though those pixels were not drawn. If\r
297	EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set, then it modifies the\r
298	behavior of EFI_HII_OUT_FLAG_CLIP so that if a character????s\r
299	right-most on pixel cannot fit, then it will not be drawn at\r
300	all. This flag requires that EFI_HII_OUT_FLAG_CLIP be set. If\r
301	EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is set, then it modifies the\r
302	behavior of EFI_HII_OUT_FLAG_CLIP so that if a row????s bottom\r
303	most pixel cannot fit, then it will not be drawn at all. This\r
304	flag requires that EFI_HII_OUT_FLAG_CLIP be set. Draft for\r
305	Review HII Protocols Version 2.1 November 3, 2006 1285 If\r
306	EFI_HII_OUT_FLAG_WRAP is set, then text will be wrapped at the\r
307	right-most line-break opportunity prior to a character whose\r
308	right-most extent would exceed Width. If no line-break\r
309	opportunity can be found, then the text will behave as if\r
310	EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set. This flag cannot be used\r
311	with EFI_HII_OUT_FLAG_CLIP_CLEAN_X. If\r
312	EFI_HII_OUT_FLAG_TRANSPARENT is set, then BackgroundColor is\r
313