2 The file provides services to retrieve font information.
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
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.
15 #ifndef __HII_FONT_H__
16 #define __HII_FONT_H__
18 #include <Protocol/HiiImage.h>
20 #define EFI_HII_FONT_PROTOCOL_GUID \
21 { 0xe9ca4775, 0x8657, 0x47fc, { 0x97, 0xe7, 0x7e, 0xd6, 0x5a, 0x8, 0x43, 0x24 } }
23 typedef struct _EFI_HII_FONT_PROTOCOL EFI_HII_FONT_PROTOCOL
;
29 typedef UINT32 EFI_HII_OUT_FLAGS
;
30 #define EFI_HII_OUT_FLAG_CLIP 0x00000001
31 #define EFI_HII_OUT_FLAG_WRAP 0x00000002
32 #define EFI_HII_OUT_FLAG_CLEAN_Y 0x00000004
33 #define EFI_HII_OUT_FLAG_CLEAN_X 0x00000008
34 #define EFI_HII_OUT_FLAG_TRANSPARENT 0x00000010
35 #define EFI_HII_IGNORE_IF_NO_GLYPH 0x00000020
36 #define EFI_HII_IGNORE_LINE_BREAK 0x00000040
37 #define EFI_HII_DIRECT_TO_SCREEN 0x00000080
41 Definition of EFI_HII_ROW_INFO.
43 @param StartIndex The index of the first character in the
44 string which is displayed on the line.
46 @param EndIndex The index of the last character in the string
47 which is displayed on the line. If this is the
48 same as StartIndex, then no characters are
51 @param LineHeight The height of the line, in pixels.
53 @param LineWidth The width of the text on the line, in
56 @param BaselineOffset The number of pixels above the bottom of
57 the row of the font baseline or 0 if
61 typedef struct _EFI_HII_ROW_INFO
{
72 typedef UINT32 EFI_FONT_INFO_MASK
;
73 #define EFI_FONT_INFO_SYS_FONT 0x00000001
74 #define EFI_FONT_INFO_SYS_SIZE 0x00000002
75 #define EFI_FONT_INFO_SYS_STYLE 0x00000004
76 #define EFI_FONT_INFO_SYS_FORE_COLOR 0x00000010
77 #define EFI_FONT_INFO_SYS_BACK_COLOR 0x00000020
78 #define EFI_FONT_INFO_RESIZE 0x00001000
79 #define EFI_FONT_INFO_RESTYLE 0x00002000
80 #define EFI_FONT_INFO_ANY_FONT 0x00010000
81 #define EFI_FONT_INFO_ANY_SIZE 0x00020000
82 #define EFI_FONT_INFO_ANY_STYLE 0x00040000
94 This structure is used for describing the way in which a string
95 should be rendered in a particular font. FontInfo specifies the
96 basic font information and ForegroundColor and BackgroundColor
97 specify the color in which they should be displayed. The flags
98 in FontInfoMask describe where the system default should be
99 supplied instead of the specified information. The flags also
100 describe what options can be used to make a match between the
101 font requested and the font available. If EFI_FONT_INFO_SYS_FONT
102 is specified, then the font name in FontInfo is ignored and the
103 system font name is used. This flag cannot be used with
104 EFI_FONT_INFO_ANY_FONT. If EFI_FONT_INFO_SYS_SIZE is specified,
105 then the font height specified in FontInfo is ignored and the
106 system font height is used instead. This flag cannot be used
107 with EFI_FONT_INFO_ANY_SIZE. If EFI_FONT_INFO_SYS_STYLE is
108 specified, then the font style in FontInfo is ignored and the
109 system font style is used. This flag cannot be used with
110 EFI_FONT_INFO_ANY_STYLE. If EFI_FONT_INFO_SYS_FORE_COLOR is
111 specified, then ForegroundColor is ignored and the system
112 foreground color is used. If EFI_FONT_INFO_SYS_BACK_COLOR is
113 specified, then BackgroundColor is ignored and the system
114 background color is used. If EFI_FONT_INFO_RESIZE is specified,
115 then the system may attempt to stretch or shrink a font to meet
116 the size requested. This flag cannot be used with
117 EFI_FONT_INFO_ANY_SIZE. If EFI_FONT_INFO_RESTYLE is specified,
118 then the system may attempt to remove some of the specified
119 styles in order to meet the style requested. This flag cannot be
120 used with EFI_FONT_INFO_ANY_STYLE. If EFI_FONT_INFO_ANY_FONT is
121 specified, then the system may attempt to match with any font.
122 This flag cannot be used with EFI_FONT_INFO_SYS_FONT. If
123 EFI_FONT_INFO_ANY_SIZE is specified, then the system may attempt
124 to match with any font size. This flag cannot be used with
125 EFI_FONT_INFO_SYS_SIZE or EFI_FONT_INFO_RESIZE. If
126 EFI_FONT_INFO_ANY_STYLE is specified, then the system may
127 attempt to match with any font style. This flag cannot be used
128 with EFI_FONT_INFO_SYS_STYLE or EFI_FONT_INFO_RESTYLE.
130 @param FontInfo Points to the font information or NULL if the
131 string should use the default system font.
133 @param ForegroundColor The color of the "on" pixels in the
136 @param BackgroundColor The color of the "off" pixels in the
139 @param FontInfoMask The font information mask determines
140 which portion of the font information
141 will be used and what to do if the
142 specific font is not available.
145 typedef struct _EFI_FONT_DISPLAY_INFO
{
146 EFI_FONT_INFO FontInfo
;
147 EFI_GRAPHICS_OUTPUT_BLT_PIXEL ForegroundColor
;
148 EFI_GRAPHICS_OUTPUT_BLT_PIXEL BackgroundColor
;
149 EFI_FONT_INFO_MASK FontInfoMask
;
150 } EFI_FONT_DISPLAY_INFO
;
154 This function renders a string to a bitmap or the screen using
155 the specified font, color and options. It either draws the
156 string and glyphs on an existing bitmap, allocates a new bitmap
157 or uses the screen. The strings can be clipped or wrapped.
158 Optionally, the function also returns the information about each
159 row and the character position on that row. If
160 EFI_HII_OUT_FLAG_CLIP is set, then text will be formatted only
161 based on explicit line breaks and all pixels which would lie
162 outside the bounding box specified by Width and Height are
163 ignored. The information in the RowInfoArray only describes
164 characters which are at least partially displayed. For the final
165 row, the LineHeight and BaseLine may describe pixels which are
166 outside the limit specified by Height (unless
167 EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is specified) even though those
168 pixels were not drawn. The LineWidth may describe pixels which
169 are outside the limit specified by Width (unless
170 EFI_HII_OUT_FLAG_CLIP_CLEAN_X is specified) even though those
171 pixels were not drawn. If EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set,
172 then it modifies the behavior of EFI_HII_OUT_FLAG_CLIP so that
173 if a character????s right-most on pixel cannot fit, then it will
174 not be drawn at all. This flag requires that
175 EFI_HII_OUT_FLAG_CLIP be set. If EFI_HII_OUT_FLAG_CLIP_CLEAN_Y
176 is set, then it modifies the behavior of EFI_HII_OUT_FLAG_CLIP
177 so that if a row????s bottom-most pixel cannot fit, then it will
178 not be drawn at all. This flag requires that
179 EFI_HII_OUT_FLAG_CLIP be set. If EFI_HII_OUT_FLAG_WRAP is set,
180 then text will be wrapped at the right-most line-break
181 opportunity prior to a character whose right-most extent would
182 exceed Width. If no line-break opportunity can be found, then
183 the text will behave as if EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set.
184 This flag cannot be used with EFI_HII_OUT_FLAG_CLIP_CLEAN_X. If
185 EFI_HII_OUT_FLAG_TRANSPARENT is set, then BackgroundColor is
186 ignored and all ????off???? pixels in the character????s drawn
187 will use the pixel value from Blt. This flag cannot be used if
188 Blt is NULL upon entry. If EFI_HII_IGNORE_IF_NO_GLYPH is set,
189 then characters which have no glyphs are not drawn. Otherwise,
190 they are replaced with Unicode character 0xFFFD (REPLACEMENT
191 CHARACTER). If EFI_HII_IGNORE_LINE_BREAK is set, then explicit
192 line break characters will be ignored. If
193 EFI_HII_DIRECT_TO_SCREEN is set, then the string will be written
194 directly to the output device specified by Screen. Otherwise the
195 string will be rendered to the bitmap specified by Bitmap.
197 @param This A pointer to the EFI_HII_FONT_PROTOCOL instance.
199 @param Flags Describes how the string is to be drawn.
201 @param String Points to the null-terminated string to be
204 @param StringInfo Points to the string output information,
205 including the color and font. If NULL, then
206 the string will be output in the default
207 system font and color.
209 @param Blt If this points to a non-NULL on entry, this points
210 to the image, which is Width pixels wide and
211 Height pixels high. The string will be drawn onto
212 this image and EFI_HII_OUT_FLAG_CLIP is implied.
213 If this points to a NULL on entry, then a buffer
214 will be allocated to hold the generated image and
215 the pointer updated on exit. It is the caller's
216 responsibility to free this buffer.
218 @param BltX, BltY Specifies the offset from the left and top
219 edge of the image of the first character
222 @param RowInfoArray If this is non-NULL on entry, then on
223 exit, this will point to an allocated buffer
224 containing row information and
225 RowInfoArraySize will be updated to contain
226 the number of elements. This array describes
227 the characters which were at least partially
228 drawn and the heights of the rows. It is the
229 caller's responsibility to free this buffer.
231 @param RowInfoArraySize If this is non-NULL on entry, then on
232 exit it contains the number of
233 elements in RowInfoArray.
235 @param ColumnInfoArray If this is non-NULL, then on return it
236 will be filled with the horizontal
237 offset for each character in the
238 string on the row where it is
239 displayed. Non-printing characters
240 will have the offset ~0. The caller is
241 responsible to allocate a buffer large
242 enough so that there is one entry for
243 each character in the string, not
244 including the null-terminator. It is
245 possible when character display is
246 normalized that some character cells
249 @retval EFI_SUCCESS The string was successfully updated.
251 @retval EFI_OUT_OF_RESOURCES Unable to allocate an output
252 buffer for RowInfoArray or Blt.
254 @retval EFI_INVALID_PARAMETER The String or Blt or Height or
261 (EFIAPI
*EFI_HII_STRING_TO_IMAGE
) (
262 IN CONST EFI_HII_FONT_PROTOCOL
*This
,
263 IN CONST EFI_HII_OUT_FLAGS Flags
,
264 IN CONST EFI_STRING String
,
265 IN CONST EFI_FONT_DISPLAY_INFO
*StringInfo
,
266 IN OUT EFI_IMAGE_OUTPUT
**Blt
,
269 OUT EFI_HII_ROW_INFO
**RowInfoArray OPTIONAL
,
270 OUT UINTN
*RowInfoArraySize OPTIONAL
,
271 OUT UINTN
*ColumnInfoArray OPTIONAL
278 This function renders a string as a bitmap or to the screen
279 and can clip or wrap the string. The bitmap is either supplied
280 by the caller or else is allocated by the function. The
281 strings are drawn with the font, size and style specified and
282 can be drawn transparently or opaquely. The function can also
283 return information about each row and each character's
284 position on the row. If EFI_HII_OUT_FLAG_CLIP is set, then
285 text will be formatted only based on explicit line breaks and
286 all pixels which would lie outside the bounding box specified
287 by Width and Height are ignored. The information in the
288 RowInfoArray only describes characters which are at least
289 partially displayed. For the final row, the LineHeight and
290 BaseLine may describe pixels which are outside the limit
291 specified by Height (unless EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is
292 specified) even though those pixels were not drawn. If
293 EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set, then it modifies the
294 behavior of EFI_HII_OUT_FLAG_CLIP so that if a character????s
295 right-most on pixel cannot fit, then it will not be drawn at
296 all. This flag requires that EFI_HII_OUT_FLAG_CLIP be set. If
297 EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is set, then it modifies the
298 behavior of EFI_HII_OUT_FLAG_CLIP so that if a row????s bottom
299 most pixel cannot fit, then it will not be drawn at all. This
300 flag requires that EFI_HII_OUT_FLAG_CLIP be set. Draft for
301 Review HII Protocols Version 2.1 November 3, 2006 1285 If
302 EFI_HII_OUT_FLAG_WRAP is set, then text will be wrapped at the
303 right-most line-break opportunity prior to a character whose
304 right-most extent would exceed Width. If no line-break
305 opportunity can be found, then the text will behave as if
306 EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set. This flag cannot be used
307 with EFI_HII_OUT_FLAG_CLIP_CLEAN_X. If
308 EFI_HII_OUT_FLAG_TRANSPARENT is set, then BackgroundColor is
309 ignored and all off¡± pixels in the character¡¯s glyph will
310 use the pixel value from Blt. This flag cannot be used if Blt
311 is NULL upon entry. If EFI_HII_IGNORE_IF_NO_GLYPH is set, then
312 characters which have no glyphs are not drawn. Otherwise, they
313 are replaced with Unicode character 0xFFFD (REPLACEMENT
314 CHARACTER). If EFI_HII_IGNORE_LINE_BREAK is set, then explicit
315 line break characters will be ignored. If
316 EFI_HII_DIRECT_TO_SCREEN is set, then the string will be
317 written directly to the output device specified by Screen.
318 Otherwise the string will be rendered to the bitmap specified
322 @param This A pointer to the EFI_HII_FONT_PROTOCOL instance.
324 @param Flags Describes how the string is to be drawn.
326 @param PackageList The package list in the HII database to
327 search for the specified string.
329 @param StringId The string's id, which is unique within
332 @param Language Points to the language for the retrieved
333 string. If NULL, then the current system
336 @param StringInfo Points to the string output information,
337 including the color and font. If NULL, then
338 the string will be output in the default
339 system font and color.
341 @param Blt If this points to a non-NULL on entry, this points
342 to the image, which is Width pixels wide and
343 Height pixels high. The string will be drawn onto
344 this image and EFI_HII_OUT_FLAG_CLIP is implied.
345 If this points to a NULL on entry, then a buffer
346 will be allocated to hold the generated image and
347 the pointer updated on exit. It is the caller's
348 responsibility to free this buffer.
350 @param BltX, BltY Specifies the offset from the left and top
351 edge of the output image of the first
352 character cell in the image.
354 @param RowInfoArray If this is non-NULL on entry, then on
355 exit, this will point to an allocated
356 buffer containing row information and
357 RowInfoArraySize will be updated to
358 contain the number of elements. This array
359 describes the characters which were at
360 least partially drawn and the heights of
361 the rows. It is the caller's
362 responsibility to free this buffer.
364 @param RowInfoArraySize If this is non-NULL on entry, then on
365 exit it contains the number of
366 elements in RowInfoArray.
368 @param ColumnInfoArray If non-NULL, on return it is filled
369 with the horizontal offset for each
370 character in the string on the row
371 where it is displayed. Non-printing
372 characters will have the offset ~0.
373 The caller is responsible to allocate
374 a buffer large enough so that there is
375 one entry for each character in the
376 string, not including the
377 null-terminator. It is possible when
378 character display is normalized that
379 some character cells overlap.
382 @retval EFI_SUCCESS The string was successfully updated.
384 @retval EFI_OUT_OF_RESOURCES Unable to allocate an output
385 buffer for RowInfoArray or Blt.
387 @retval EFI_INVALID_PARAMETER The String or Blt or Height or
393 (EFIAPI
*EFI_HII_STRING_ID_TO_IMAGE
) (
394 IN CONST EFI_HII_FONT_PROTOCOL
*This
,
395 IN CONST EFI_HII_OUT_FLAGS Flags
,
396 IN CONST EFI_HII_HANDLE PackageList
,
397 IN CONST EFI_STRING_ID StringId
,
398 IN CONST CHAR8
*Language
,
399 IN CONST EFI_FONT_DISPLAY_INFO
*StringInfo OPTIONAL
,
400 IN OUT EFI_IMAGE_OUTPUT
**Blt
,
403 OUT EFI_HII_ROW_INFO
**RowInfoArray OPTIONAL
,
404 OUT UINTN
*RowInfoArraySize OPTIONAL
,
405 OUT UINTN
*ColumnInfoArray OPTIONAL
411 Convert the glyph for a single character into a bitmap.
413 @param This A pointer to the EFI_HII_FONT_PROTOCOL instance.
415 @param Char Character to retrieve.
417 @param StringInfo Points to the string font and color
418 information or NULL if the string should use
419 the default system font and color.
421 @param Blt Thus must point to a NULL on entry. A buffer will
422 be allocated to hold the output and the pointer
423 updated on exit. It is the caller's responsibility
426 @param Baseline Number of pixels from the bottom of the bitmap
430 @retval EFI_SUCCESS Glyph bitmap created.
432 @retval EFI_OUT_OF_RESOURCES Unable to allocate the output
435 @retval EFI_WARN_UNKNOWN_GLYPH The glyph was unknown and was
436 replaced with the glyph for
437 Unicode character 0xFFFD.
439 @retval EFI_INVALID_PARAMETER Blt is NULL or Width is NULL or
446 (EFIAPI
*EFI_HII_GET_GLYPH
) (
447 IN CONST EFI_HII_FONT_PROTOCOL
*This
,
448 IN CONST CHAR16 Char
,
449 IN CONST EFI_FONT_DISPLAY_INFO
*StringInfo
,
450 OUT EFI_IMAGE_OUTPUT
**Blt
,
451 OUT UINTN
*Baseline OPTIONAL
456 This function iterates through fonts which match the specified
457 font, using the specified criteria. If String is non-NULL, then
458 all of the characters in the string must exist in order for a
459 candidate font to be returned.
461 @param This A pointer to the EFI_HII_FONT_PROTOCOL instance.
463 @param FontHandle On entry, points to the font handle returned
464 by a previous call to GetFontInfo() or NULL
465 to start with the first font. On return,
466 points to the returned font handle or points
467 to NULL if there are no more matching fonts.
469 @param StringInfoIn Upon entry, points to the font to return
472 @param StringInfoOut Upon return, contains the matching
473 font's information. If NULL, then no
474 information is returned.
476 @param String Points to the string which will be tested to
477 determine if all characters are available. If
478 NULL, then any font is acceptable.
480 @retval EFI_SUCCESS Matching font returned successfully.
482 @retval EFI_NOT_FOUND No matching font was found.
484 @retval EFI_INVALID_PARAMETER FontHandle is NULL or
490 (EFIAPI
*EFI_HII_GET_FONT_INFO
) (
491 IN CONST EFI_HII_FONT_PROTOCOL
*This
,
492 IN OUT EFI_FONT_HANDLE
*FontHandle
,
493 IN CONST EFI_FONT_DISPLAY_INFO
*StringInfoIn
,
494 OUT EFI_FONT_DISPLAY_INFO
*StringInfoOut
,
495 IN CONST EFI_STRING
*String OPTIONAL
500 The protocol provides the service to retrieve the font
503 @param StringToImage Render a string to a bitmap or to the
506 @param StringIdToImage Render a string to a bitmap or to the
508 @param GetGlyph Return a specific glyph in a specific font.
510 @param GetFontInfo Return font information for a specific
514 struct _EFI_HII_FONT_PROTOCOL
{
515 EFI_HII_STRING_TO_IMAGE StringToImage
;
516 EFI_HII_STRING_ID_TO_IMAGE StringIdToImage
;
517 EFI_HII_GET_GLYPH GetGlyph
;
518 EFI_HII_GET_FONT_INFO GetFontInfo
;
521 extern EFI_GUID gEfiHiiFontProtocolGuid
;