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
1 /** @file
2 The file provides services to retrieve font information.
3
4 Copyright (c) 2006 - 2007, Intel Corporation
5 All rights reserved. This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
9
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
12
13 **/
14
15 #ifndef __HII_FONT_H__
16 #define __HII_FONT_H__
17
18 #include <Protocol/HiiImage.h>
19
20 #error "UEFI 2.1 HII is not fully implemented for now, Please don't include this file now."
21
22 #define EFI_HII_FONT_PROTOCOL_GUID \
23 { 0xe9ca4775, 0x8657, 0x47fc, { 0x97, 0xe7, 0x7e, 0xd6, 0x5a, 0x8, 0x43, 0x24 } }
24
25 typedef struct _EFI_HII_FONT_PROTOCOL EFI_HII_FONT_PROTOCOL;
26
27
28 //
29 // EFI_HII_OUT_FLAGS
30 //
31 typedef UINT32 EFI_HII_OUT_FLAGS;
32 #define EFI_HII_OUT_FLAG_CLIP 0x00000001
33 #define EFI_HII_OUT_FLAG_WRAP 0x00000002
34 #define EFI_HII_OUT_FLAG_CLEAN_Y 0x00000004
35 #define EFI_HII_OUT_FLAG_CLEAN_X 0x00000008
36 #define EFI_HII_OUT_FLAG_TRANSPARENT 0x00000010
37 #define EFI_HII_IGNORE_IF_NO_GLYPH 0x00000020
38 #define EFI_HII_IGNORE_LINE_BREAK 0x00000040
39 #define EFI_HII_DIRECT_TO_SCREEN 0x00000080
40
41 /**
42
43 Definition of EFI_HII_ROW_INFO.
44
45 @param StartIndex The index of the first character in the
46 string which is displayed on the line.
47
48 @param EndIndex The index of the last character in the string
49 which is displayed on the line. If this is the
50 same as StartIndex, then no characters are
51 displayed.
52
53 @param LineHeight The height of the line, in pixels.
54
55 @param LineWidth The width of the text on the line, in
56 pixels.
57
58 @param BaselineOffset The number of pixels above the bottom of
59 the row of the font baseline or 0 if
60 none.
61
62 **/
63 typedef struct _EFI_HII_ROW_INFO {
64 UINTN StartIndex;
65 UINTN EndIndex;
66 UINTN LineHeight;
67 UINTN LineWidth;
68 UINTN BaselineOffset;
69 } EFI_HII_ROW_INFO;
70
71 //
72 // EFI_FONT_INFO_MASK
73 //
74 typedef UINT32 EFI_FONT_INFO_MASK;
75 #define EFI_FONT_INFO_SYS_FONT 0x00000001
76 #define EFI_FONT_INFO_SYS_SIZE 0x00000002
77 #define EFI_FONT_INFO_SYS_STYLE 0x00000004
78 #define EFI_FONT_INFO_SYS_FORE_COLOR 0x00000010
79 #define EFI_FONT_INFO_SYS_BACK_COLOR 0x00000020
80 #define EFI_FONT_INFO_RESIZE 0x00001000
81 #define EFI_FONT_INFO_RESTYLE 0x00002000
82 #define EFI_FONT_INFO_ANY_FONT 0x00010000
83 #define EFI_FONT_INFO_ANY_SIZE 0x00020000
84 #define EFI_FONT_INFO_ANY_STYLE 0x00040000
85
86 //
87 // EFI_FONT_INFO
88 //
89 typedef struct {
90 UINT32 FontStyle;
91 UINT16 FontSize;
92 CHAR16 FontName[1];
93 } EFI_FONT_INFO;
94
95 /**
96 This structure is used for describing the way in which a string
97 should be rendered in a particular font. FontInfo specifies the
98 basic font information and ForegroundColor and BackgroundColor
99 specify the color in which they should be displayed. The flags
100 in FontInfoMask describe where the system default should be
101 supplied instead of the specified information. The flags also
102 describe what options can be used to make a match between the
103 font requested and the font available. If EFI_FONT_INFO_SYS_FONT
104 is specified, then the font name in FontInfo is ignored and the
105 system font name is used. This flag cannot be used with
106 EFI_FONT_INFO_ANY_FONT. If EFI_FONT_INFO_SYS_SIZE is specified,
107 then the font height specified in FontInfo is ignored and the
108 system font height is used instead. This flag cannot be used
109 with EFI_FONT_INFO_ANY_SIZE. If EFI_FONT_INFO_SYS_STYLE is
110 specified, then the font style in FontInfo is ignored and the
111 system font style is used. This flag cannot be used with
112 EFI_FONT_INFO_ANY_STYLE. If EFI_FONT_INFO_SYS_FORE_COLOR is
113 specified, then ForegroundColor is ignored and the system
114 foreground color is used. If EFI_FONT_INFO_SYS_BACK_COLOR is
115 specified, then BackgroundColor is ignored and the system
116 background color is used. If EFI_FONT_INFO_RESIZE is specified,
117 then the system may attempt to stretch or shrink a font to meet
118 the size requested. This flag cannot be used with
119 EFI_FONT_INFO_ANY_SIZE. If EFI_FONT_INFO_RESTYLE is specified,
120 then the system may attempt to remove some of the specified
121 styles in order to meet the style requested. This flag cannot be
122 used with EFI_FONT_INFO_ANY_STYLE. If EFI_FONT_INFO_ANY_FONT is
123 specified, then the system may attempt to match with any font.
124 This flag cannot be used with EFI_FONT_INFO_SYS_FONT. If
125 EFI_FONT_INFO_ANY_SIZE is specified, then the system may attempt
126 to match with any font size. This flag cannot be used with
127 EFI_FONT_INFO_SYS_SIZE or EFI_FONT_INFO_RESIZE. If
128 EFI_FONT_INFO_ANY_STYLE is specified, then the system may
129 attempt to match with any font style. This flag cannot be used
130 with EFI_FONT_INFO_SYS_STYLE or EFI_FONT_INFO_RESTYLE.
131
132 @param FontInfo Points to the font information or NULL if the
133 string should use the default system font.
134
135 @param ForegroundColor The color of the "on" pixels in the
136 glyph in the bitmap.
137
138 @param BackgroundColor The color of the "off" pixels in the
139 glyph in the bitmap.
140
141 @param FontInfoMask The font information mask determines
142 which portion of the font information
143 will be used and what to do if the
144 specific font is not available.
145
146 **/
147 typedef struct _EFI_FONT_DISPLAY_INFO {
148 EFI_FONT_INFO FontInfo;
149 EFI_GRAPHICS_OUTPUT_BLT_PIXEL ForegroundColor;
150 EFI_GRAPHICS_OUTPUT_BLT_PIXEL BackgroundColor;
151 EFI_FONT_INFO_MASK FontInfoMask;
152 } EFI_FONT_DISPLAY_INFO;
153
154 /**
155
156 This function renders a string to a bitmap or the screen using
157 the specified font, color and options. It either draws the
158 string and glyphs on an existing bitmap, allocates a new bitmap
159 or uses the screen. The strings can be clipped or wrapped.
160 Optionally, the function also returns the information about each
161 row and the character position on that row. If
162 EFI_HII_OUT_FLAG_CLIP is set, then text will be formatted only
163 based on explicit line breaks and all pixels which would lie
164 outside the bounding box specified by Width and Height are
165 ignored. The information in the RowInfoArray only describes
166 characters which are at least partially displayed. For the final
167 row, the LineHeight and BaseLine may describe pixels which are
168 outside the limit specified by Height (unless
169 EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is specified) even though those
170 pixels were not drawn. The LineWidth may describe pixels which
171 are outside the limit specified by Width (unless
172 EFI_HII_OUT_FLAG_CLIP_CLEAN_X is specified) even though those
173 pixels were not drawn. If EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set,
174 then it modifies the behavior of EFI_HII_OUT_FLAG_CLIP so that
175 if a character????s right-most on pixel cannot fit, then it will
176 not be drawn at all. This flag requires that
177 EFI_HII_OUT_FLAG_CLIP be set. If EFI_HII_OUT_FLAG_CLIP_CLEAN_Y
178 is set, then it modifies the behavior of EFI_HII_OUT_FLAG_CLIP
179 so that if a row????s bottom-most pixel cannot fit, then it will
180 not be drawn at all. This flag requires that
181 EFI_HII_OUT_FLAG_CLIP be set. If EFI_HII_OUT_FLAG_WRAP is set,
182 then text will be wrapped at the right-most line-break
183 opportunity prior to a character whose right-most extent would
184 exceed Width. If no line-break opportunity can be found, then
185 the text will behave as if EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set.
186 This flag cannot be used with EFI_HII_OUT_FLAG_CLIP_CLEAN_X. If
187 EFI_HII_OUT_FLAG_TRANSPARENT is set, then BackgroundColor is
188 ignored and all ????off???? pixels in the character????s drawn
189 will use the pixel value from Blt. This flag cannot be used if
190 Blt is NULL upon entry. If EFI_HII_IGNORE_IF_NO_GLYPH is set,
191 then characters which have no glyphs are not drawn. Otherwise,
192 they are replaced with Unicode character 0xFFFD (REPLACEMENT
193 CHARACTER). If EFI_HII_IGNORE_LINE_BREAK is set, then explicit
194 line break characters will be ignored. If
195 EFI_HII_DIRECT_TO_SCREEN is set, then the string will be written
196 directly to the output device specified by Screen. Otherwise the
197 string will be rendered to the bitmap specified by Bitmap.
198
199 @param This A pointer to the EFI_HII_FONT_PROTOCOL instance.
200
201 @param Flags Describes how the string is to be drawn.
202
203 @param String Points to the null-terminated string to be
204 displayed.
205
206 @param StringInfo Points to the string output information,
207 including the color and font. If NULL, then
208 the string will be output in the default
209 system font and color.
210
211 @param Blt If this points to a non-NULL on entry, this points
212 to the image, which is Width pixels wide and
213 Height pixels high. The string will be drawn onto
214 this image and EFI_HII_OUT_FLAG_CLIP is implied.
215 If this points to a NULL on entry, then a buffer
216 will be allocated to hold the generated image and
217 the pointer updated on exit. It is the caller's
218 responsibility to free this buffer.
219
220 @param BltX, BltY Specifies the offset from the left and top
221 edge of the image of the first character
222 cell in the image.
223
224 @param RowInfoArray If this is non-NULL on entry, then on
225 exit, this will point to an allocated buffer
226 containing row information and
227 RowInfoArraySize will be updated to contain
228 the number of elements. This array describes
229 the characters which were at least partially
230 drawn and the heights of the rows. It is the
231 caller's responsibility to free this buffer.
232
233 @param RowInfoArraySize If this is non-NULL on entry, then on
234 exit it contains the number of
235 elements in RowInfoArray.
236
237 @param ColumnInfoArray If this is non-NULL, then on return it
238 will be filled with the horizontal
239 offset for each character in the
240 string on the row where it is
241 displayed. Non-printing characters
242 will have the offset ~0. The caller is
243 responsible to allocate a buffer large
244 enough so that there is one entry for
245 each character in the string, not
246 including the null-terminator. It is
247 possible when character display is
248 normalized that some character cells
249 overlap.
250
251 @retval EFI_SUCCESS The string was successfully updated.
252
253 @retval EFI_OUT_OF_RESOURCES Unable to allocate an output
254 buffer for RowInfoArray or Blt.
255
256 @retval EFI_INVALID_PARAMETER The String or Blt or Height or
257 Width was NULL.
258
259
260 **/
261 typedef
262 EFI_STATUS
263 (EFIAPI *EFI_HII_STRING_TO_IMAGE) (
264 IN CONST EFI_HII_FONT_PROTOCOL *This,
265 IN CONST EFI_HII_OUT_FLAGS Flags,
266 IN CONST EFI_STRING String,
267 IN CONST EFI_FONT_DISPLAY_INFO *StringInfo,
268 IN OUT EFI_IMAGE_OUTPUT **Blt,
269 IN CONST UINTN BltX,
270 IN CONST UINTN BltY,
271 OUT EFI_HII_ROW_INFO **RowInfoArray OPTIONAL,
272 OUT UINTN *RowInfoArraySize OPTIONAL,
273 OUT UINTN *ColumnInfoArray OPTIONAL
274 );
275
276
277
278 /**
279
280 This function renders a string as a bitmap or to the screen
281 and can clip or wrap the string. The bitmap is either supplied
282 by the caller or else is allocated by the function. The
283 strings are drawn with the font, size and style specified and
284 can be drawn transparently or opaquely. The function can also
285 return information about each row and each character's
286 position on the row. If EFI_HII_OUT_FLAG_CLIP is set, then
287 text will be formatted only based on explicit line breaks and
288 all pixels which would lie outside the bounding box specified
289 by Width and Height are ignored. The information in the
290 RowInfoArray only describes characters which are at least
291 partially displayed. For the final row, the LineHeight and
292 BaseLine may describe pixels which are outside the limit
293 specified by Height (unless EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is
294 specified) even though those pixels were not drawn. If
295 EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set, then it modifies the
296 behavior of EFI_HII_OUT_FLAG_CLIP so that if a character????s
297 right-most on pixel cannot fit, then it will not be drawn at
298 all. This flag requires that EFI_HII_OUT_FLAG_CLIP be set. If
299 EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is set, then it modifies the
300 behavior of EFI_HII_OUT_FLAG_CLIP so that if a row????s bottom
301 most pixel cannot fit, then it will not be drawn at all. This
302 flag requires that EFI_HII_OUT_FLAG_CLIP be set. Draft for
303 Review HII Protocols Version 2.1 November 3, 2006 1285 If
304 EFI_HII_OUT_FLAG_WRAP is set, then text will be wrapped at the
305 right-most line-break opportunity prior to a character whose
306 right-most extent would exceed Width. If no line-break
307 opportunity can be found, then the text will behave as if
308 EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set. This flag cannot be used
309 with EFI_HII_OUT_FLAG_CLIP_CLEAN_X. If
310 EFI_HII_OUT_FLAG_TRANSPARENT is set, then BackgroundColor is
311 ignored and all off¡± pixels in the character¡¯s glyph will
312 use the pixel value from Blt. This flag cannot be used if Blt
313 is NULL upon entry. If EFI_HII_IGNORE_IF_NO_GLYPH is set, then
314 characters which have no glyphs are not drawn. Otherwise, they
315 are replaced with Unicode character 0xFFFD (REPLACEMENT
316 CHARACTER). If EFI_HII_IGNORE_LINE_BREAK is set, then explicit
317 line break characters will be ignored. If
318 EFI_HII_DIRECT_TO_SCREEN is set, then the string will be
319 written directly to the output device specified by Screen.
320 Otherwise the string will be rendered to the bitmap specified
321 by Bitmap.
322
323
324 @param This A pointer to the EFI_HII_FONT_PROTOCOL instance.
325
326 @param Flags Describes how the string is to be drawn.
327
328 @param PackageList The package list in the HII database to
329 search for the specified string.
330
331 @param StringId The string's id, which is unique within
332 PackageList.
333
334 @param Language Points to the language for the retrieved
335 string. If NULL, then the current system
336 language is used.
337
338 @param StringInfo Points to the string output information,
339 including the color and font. If NULL, then
340 the string will be output in the default
341 system font and color.
342
343 @param Blt If this points to a non-NULL on entry, this points
344 to the image, which is Width pixels wide and
345 Height pixels high. The string will be drawn onto
346 this image and EFI_HII_OUT_FLAG_CLIP is implied.
347 If this points to a NULL on entry, then a buffer
348 will be allocated to hold the generated image and
349 the pointer updated on exit. It is the caller's
350 responsibility to free this buffer.
351
352 @param BltX, BltY Specifies the offset from the left and top
353 edge of the output image of the first
354 character cell in the image.
355
356 @param RowInfoArray If this is non-NULL on entry, then on
357 exit, this will point to an allocated
358 buffer containing row information and
359 RowInfoArraySize will be updated to
360 contain the number of elements. This array
361 describes the characters which were at
362 least partially drawn and the heights of
363 the rows. It is the caller's
364 responsibility to free this buffer.
365
366 @param RowInfoArraySize If this is non-NULL on entry, then on
367 exit it contains the number of
368 elements in RowInfoArray.
369
370 @param ColumnInfoArray If non-NULL, on return it is filled
371 with the horizontal offset for each
372 character in the string on the row
373 where it is displayed. Non-printing
374 characters will have the offset ~0.
375 The caller is responsible to allocate
376 a buffer large enough so that there is
377 one entry for each character in the
378 string, not including the
379 null-terminator. It is possible when
380 character display is normalized that
381 some character cells overlap.
382
383
384 @retval EFI_SUCCESS The string was successfully updated.
385
386 @retval EFI_OUT_OF_RESOURCES Unable to allocate an output
387 buffer for RowInfoArray or Blt.
388
389 @retval EFI_INVALID_PARAMETER The String or Blt or Height or
390 Width was NULL.
391
392 **/
393 typedef
394 EFI_STATUS
395 (EFIAPI *EFI_HII_STRING_ID_TO_IMAGE) (
396 IN CONST EFI_HII_FONT_PROTOCOL *This,
397 IN CONST EFI_HII_OUT_FLAGS Flags,
398 IN CONST EFI_HII_HANDLE PackageList,
399 IN CONST EFI_STRING_ID StringId,
400 IN CONST CHAR8 *Language,
401 IN CONST EFI_FONT_DISPLAY_INFO *StringInfo OPTIONAL,
402 IN OUT EFI_IMAGE_OUTPUT **Blt,
403 IN CONST UINTN BltX,
404 IN CONST UINTN BltY,
405 OUT EFI_HII_ROW_INFO **RowInfoArray OPTIONAL,
406 OUT UINTN *RowInfoArraySize OPTIONAL,
407 OUT UINTN *ColumnInfoArray OPTIONAL
408 );
409
410
411 /**
412
413 Convert the glyph for a single character into a bitmap.
414
415 @param This A pointer to the EFI_HII_FONT_PROTOCOL instance.
416
417 @param Char Character to retrieve.
418
419 @param StringInfo Points to the string font and color
420 information or NULL if the string should use
421 the default system font and color.
422
423 @param Blt Thus must point to a NULL on entry. A buffer will
424 be allocated to hold the output and the pointer
425 updated on exit. It is the caller's responsibility
426 to free this buffer.
427
428 @param Baseline Number of pixels from the bottom of the bitmap
429 to the baseline.
430
431
432 @retval EFI_SUCCESS Glyph bitmap created.
433
434 @retval EFI_OUT_OF_RESOURCES Unable to allocate the output
435 buffer Blt.
436
437 @retval EFI_WARN_UNKNOWN_GLYPH The glyph was unknown and was
438 replaced with the glyph for
439 Unicode character 0xFFFD.
440
441 @retval EFI_INVALID_PARAMETER Blt is NULL or Width is NULL or
442 Height is NULL
443
444
445 **/
446 typedef
447 EFI_STATUS
448 (EFIAPI *EFI_HII_GET_GLYPH) (
449 IN CONST EFI_HII_FONT_PROTOCOL *This,
450 IN CONST CHAR16 Char,
451 IN CONST EFI_FONT_DISPLAY_INFO *StringInfo,
452 OUT EFI_IMAGE_OUTPUT **Blt,
453 OUT UINTN *Baseline OPTIONAL
454 );
455
456 /**
457
458 This function iterates through fonts which match the specified
459 font, using the specified criteria. If String is non-NULL, then
460 all of the characters in the string must exist in order for a
461 candidate font to be returned.
462
463 @param This A pointer to the EFI_HII_FONT_PROTOCOL instance.
464
465 @param FontHandle On entry, points to the font handle returned
466 by a previous call to GetFontInfo() or NULL
467 to start with the first font. On return,
468 points to the returned font handle or points
469 to NULL if there are no more matching fonts.
470
471 @param StringInfoIn Upon entry, points to the font to return
472 information about.
473
474 @param StringInfoOut Upon return, contains the matching
475 font's information. If NULL, then no
476 information is returned.
477
478 @param String Points to the string which will be tested to
479 determine if all characters are available. If
480 NULL, then any font is acceptable.
481
482 @retval EFI_SUCCESS Matching font returned successfully.
483
484 @retval EFI_NOT_FOUND No matching font was found.
485
486 @retval EFI_INVALID_PARAMETER FontHandle is NULL or
487 StringInfoIn is NULL
488
489 **/
490 typedef
491 EFI_STATUS
492 (EFIAPI *EFI_HII_GET_FONT_INFO) (
493 IN CONST EFI_HII_FONT_PROTOCOL *This,
494 IN OUT EFI_FONT_HANDLE *FontHandle,
495 IN CONST EFI_FONT_DISPLAY_INFO *StringInfoIn,
496 OUT EFI_FONT_DISPLAY_INFO *StringInfoOut,
497 IN CONST EFI_STRING *String OPTIONAL
498 );
499
500 /**
501
502 The protocol provides the service to retrieve the font
503 informations;
504
505 @param StringToImage Render a string to a bitmap or to the
506 display.
507
508 @param StringIdToImage Render a string to a bitmap or to the
509 display.
510 @param GetGlyph Return a specific glyph in a specific font.
511
512 @param GetFontInfo Return font information for a specific
513 font.
514
515 **/
516 struct _EFI_HII_FONT_PROTOCOL {
517 EFI_HII_STRING_TO_IMAGE StringToImage;
518 EFI_HII_STRING_ID_TO_IMAGE StringIdToImage;
519 EFI_HII_GET_GLYPH GetGlyph;
520 EFI_HII_GET_FONT_INFO GetFontInfo;
521 };
522
523 extern EFI_GUID gEfiHiiFontProtocolGuid;
524
525
526 #endif
527