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