2 The file provides services to retrieve font information.
4 Copyright (c) 2006 - 2008, 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/GraphicsOutput.h>
19 #include <Protocol/HiiImage.h>
21 #define EFI_HII_FONT_PROTOCOL_GUID \
22 { 0xe9ca4775, 0x8657, 0x47fc, { 0x97, 0xe7, 0x7e, 0xd6, 0x5a, 0x8, 0x43, 0x24 } }
24 typedef struct _EFI_HII_FONT_PROTOCOL EFI_HII_FONT_PROTOCOL
;
26 typedef VOID
*EFI_FONT_HANDLE
;
31 typedef UINT32 EFI_HII_OUT_FLAGS
;
33 #define EFI_HII_OUT_FLAG_CLIP 0x00000001
34 #define EFI_HII_OUT_FLAG_WRAP 0x00000002
35 #define EFI_HII_OUT_FLAG_CLIP_CLEAN_Y 0x00000004
36 #define EFI_HII_OUT_FLAG_CLIP_CLEAN_X 0x00000008
37 #define EFI_HII_OUT_FLAG_TRANSPARENT 0x00000010
38 #define EFI_HII_IGNORE_IF_NO_GLYPH 0x00000020
39 #define EFI_HII_IGNORE_LINE_BREAK 0x00000040
40 #define EFI_HII_DIRECT_TO_SCREEN 0x00000080
43 Definition of EFI_HII_ROW_INFO.
45 typedef struct _EFI_HII_ROW_INFO
{
47 /// The index of the first character in the string which is displayed on the line.
51 /// The index of the last character in the string which is displayed on the line.
52 /// If this is the same as StartIndex, then no characters are displayed.
55 UINTN LineHeight
; ///< The height of the line, in pixels.
56 UINTN LineWidth
; ///< The width of the text on the line, in pixels.
59 /// The number of pixels above the bottom of the row of the font baseline or 0 if none.
65 /// Font info flag. All flags (FONT, SIZE, STYLE, and COLOR) are defined.
66 /// They are defined as EFI_FONT_INFO_***
68 typedef UINT32 EFI_FONT_INFO_MASK
;
70 #define EFI_FONT_INFO_SYS_FONT 0x00000001
71 #define EFI_FONT_INFO_SYS_SIZE 0x00000002
72 #define EFI_FONT_INFO_SYS_STYLE 0x00000004
73 #define EFI_FONT_INFO_SYS_FORE_COLOR 0x00000010
74 #define EFI_FONT_INFO_SYS_BACK_COLOR 0x00000020
75 #define EFI_FONT_INFO_RESIZE 0x00001000
76 #define EFI_FONT_INFO_RESTYLE 0x00002000
77 #define EFI_FONT_INFO_ANY_FONT 0x00010000
78 #define EFI_FONT_INFO_ANY_SIZE 0x00020000
79 #define EFI_FONT_INFO_ANY_STYLE 0x00040000
85 EFI_HII_FONT_STYLE FontStyle
;
86 UINT16 FontSize
; ///< character cell height in pixels
91 Describes font output-related information.
93 This structure is used for describing the way in which a string
94 should be rendered in a particular font. FontInfo specifies the
95 basic font information and ForegroundColor and BackgroundColor
96 specify the color in which they should be displayed. The flags
97 in FontInfoMask describe where the system default should be
98 supplied instead of the specified information. The flags also
99 describe what options can be used to make a match between the
100 font requested and the font available.
102 typedef struct _EFI_FONT_DISPLAY_INFO
{
103 EFI_GRAPHICS_OUTPUT_BLT_PIXEL ForegroundColor
;
104 EFI_GRAPHICS_OUTPUT_BLT_PIXEL BackgroundColor
;
105 EFI_FONT_INFO_MASK FontInfoMask
;
106 EFI_FONT_INFO FontInfo
;
107 } EFI_FONT_DISPLAY_INFO
;
111 This function renders a string to a bitmap or the screen using
112 the specified font, color and options. It either draws the
113 string and glyphs on an existing bitmap, allocates a new bitmap
114 or uses the screen. The strings can be clipped or wrapped.
115 Optionally, the function also returns the information about each
116 row and the character position on that row. If
117 EFI_HII_OUT_FLAG_CLIP is set, then text will be formatted only
118 based on explicit line breaks and all pixels which would lie
119 outside the bounding box specified by Width and Height are
120 ignored. The information in the RowInfoArray only describes
121 characters which are at least partially displayed. For the final
122 row, the LineHeight and BaseLine may describe pixels which are
123 outside the limit specified by Height (unless
124 EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is specified) even though those
125 pixels were not drawn. The LineWidth may describe pixels which
126 are outside the limit specified by Width (unless
127 EFI_HII_OUT_FLAG_CLIP_CLEAN_X is specified) even though those
128 pixels were not drawn. If EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set,
129 then it modifies the behavior of EFI_HII_OUT_FLAG_CLIP so that
130 if a character's right-most on pixel cannot fit, then it will
131 not be drawn at all. This flag requires that
132 EFI_HII_OUT_FLAG_CLIP be set. If EFI_HII_OUT_FLAG_CLIP_CLEAN_Y
133 is set, then it modifies the behavior of EFI_HII_OUT_FLAG_CLIP
134 so that if a row's bottom-most pixel cannot fit, then it will
135 not be drawn at all. This flag requires that
136 EFI_HII_OUT_FLAG_CLIP be set. If EFI_HII_OUT_FLAG_WRAP is set,
137 then text will be wrapped at the right-most line-break
138 opportunity prior to a character whose right-most extent would
139 exceed Width. If no line-break opportunity can be found, then
140 the text will behave as if EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set.
141 This flag cannot be used with EFI_HII_OUT_FLAG_CLIP_CLEAN_X. If
142 EFI_HII_OUT_FLAG_TRANSPARENT is set, then BackgroundColor is
143 ignored and all 'off' pixels in the character's drawn
144 will use the pixel value from Blt. This flag cannot be used if
145 Blt is NULL upon entry. If EFI_HII_IGNORE_IF_NO_GLYPH is set,
146 then characters which have no glyphs are not drawn. Otherwise,
147 they are replaced with Unicode character 0xFFFD (REPLACEMENT
148 CHARACTER). If EFI_HII_IGNORE_LINE_BREAK is set, then explicit
149 line break characters will be ignored. If
150 EFI_HII_DIRECT_TO_SCREEN is set, then the string will be written
151 directly to the output device specified by Screen. Otherwise the
152 string will be rendered to the bitmap specified by Bitmap.
154 @param This A pointer to the EFI_HII_FONT_PROTOCOL instance.
156 @param Flags Describes how the string is to be drawn.
158 @param String Points to the null-terminated string to be
160 @param StringInfo Points to the string output information,
161 including the color and font. If NULL, then
162 the string will be output in the default
163 system font and color.
165 @param Blt If this points to a non-NULL on entry, this points
166 to the image, which is Width pixels wide and
167 Height pixels high. The string will be drawn onto
168 this image and EFI_HII_OUT_FLAG_CLIP is implied.
169 If this points to a NULL on entry, then a buffer
170 will be allocated to hold the generated image and
171 the pointer updated on exit. It is the caller's
172 responsibility to free this buffer.
174 @param BltX, BltY Specifies the offset from the left and top
175 edge of the image of the first character
178 @param RowInfoArray If this is non-NULL on entry, then on
179 exit, this will point to an allocated buffer
180 containing row information and
181 RowInfoArraySize will be updated to contain
182 the number of elements. This array describes
183 the characters which were at least partially
184 drawn and the heights of the rows. It is the
185 caller's responsibility to free this buffer.
187 @param RowInfoArraySize If this is non-NULL on entry, then on
188 exit it contains the number of
189 elements in RowInfoArray.
191 @param ColumnInfoArray If this is non-NULL, then on return it
192 will be filled with the horizontal
193 offset for each character in the
194 string on the row where it is
195 displayed. Non-printing characters
196 will have the offset ~0. The caller is
197 responsible to allocate a buffer large
198 enough so that there is one entry for
199 each character in the string, not
200 including the null-terminator. It is
201 possible when character display is
202 normalized that some character cells
205 @retval EFI_SUCCESS The string was successfully updated.
207 @retval EFI_OUT_OF_RESOURCES Unable to allocate an output buffer for RowInfoArray or Blt.
209 @retval EFI_INVALID_PARAMETER The String or Blt was NULL.
211 @retval EFI_INVALID_PARAMETER Flags were invalid combination.
215 (EFIAPI
*EFI_HII_STRING_TO_IMAGE
)(
216 IN CONST EFI_HII_FONT_PROTOCOL
*This
,
217 IN EFI_HII_OUT_FLAGS Flags
,
218 IN CONST EFI_STRING String
,
219 IN CONST EFI_FONT_DISPLAY_INFO
*StringInfo
,
220 IN OUT EFI_IMAGE_OUTPUT
**Blt
,
223 OUT EFI_HII_ROW_INFO
**RowInfoArray OPTIONAL
,
224 OUT UINTN
*RowInfoArraySize OPTIONAL
,
225 OUT UINTN
*ColumnInfoArray OPTIONAL
232 This function renders a string as a bitmap or to the screen
233 and can clip or wrap the string. The bitmap is either supplied
234 by the caller or else is allocated by the function. The
235 strings are drawn with the font, size and style specified and
236 can be drawn transparently or opaquely. The function can also
237 return information about each row and each character's
238 position on the row. If EFI_HII_OUT_FLAG_CLIP is set, then
239 text will be formatted only based on explicit line breaks and
240 all pixels which would lie outside the bounding box specified
241 by Width and Height are ignored. The information in the
242 RowInfoArray only describes characters which are at least
243 partially displayed. For the final row, the LineHeight and
244 BaseLine may describe pixels which are outside the limit
245 specified by Height (unless EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is
246 specified) even though those pixels were not drawn. If
247 EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set, then it modifies the
248 behavior of EFI_HII_OUT_FLAG_CLIP so that if a character's
249 right-most on pixel cannot fit, then it will not be drawn at
250 all. This flag requires that EFI_HII_OUT_FLAG_CLIP be set. If
251 EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is set, then it modifies the
252 behavior of EFI_HII_OUT_FLAG_CLIP so that if a row's bottom
253 most pixel cannot fit, then it will not be drawn at all. This
254 flag requires that EFI_HII_OUT_FLAG_CLIP be set. Draft for
255 Review HII Protocols Version 2.1 November 3, 2006 1285 If
256 EFI_HII_OUT_FLAG_WRAP is set, then text will be wrapped at the
257 right-most line-break opportunity prior to a character whose
258 right-most extent would exceed Width. If no line-break
259 opportunity can be found, then the text will behave as if
260 EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set. This flag cannot be used
261 with EFI_HII_OUT_FLAG_CLIP_CLEAN_X. If
262 EFI_HII_OUT_FLAG_TRANSPARENT is set, then BackgroundColor is
263 ignored and all off" pixels in the character's glyph will
264 use the pixel value from Blt. This flag cannot be used if Blt
265 is NULL upon entry. If EFI_HII_IGNORE_IF_NO_GLYPH is set, then
266 characters which have no glyphs are not drawn. Otherwise, they
267 are replaced with Unicode character 0xFFFD (REPLACEMENT
268 CHARACTER). If EFI_HII_IGNORE_LINE_BREAK is set, then explicit
269 line break characters will be ignored. If
270 EFI_HII_DIRECT_TO_SCREEN is set, then the string will be
271 written directly to the output device specified by Screen.
272 Otherwise the string will be rendered to the bitmap specified
276 @param This A pointer to the EFI_HII_FONT_PROTOCOL instance.
278 @param Flags Describes how the string is to be drawn.
281 The package list in the HII database to
282 search for the specified string.
284 @param StringId The string's id, which is unique within
287 @param Language Points to the language for the retrieved
288 string. If NULL, then the current system
291 @param StringInfo Points to the string output information,
292 including the color and font. If NULL, then
293 the string will be output in the default
294 system font and color.
296 @param Blt If this points to a non-NULL on entry, this points
297 to the image, which is Width pixels wide and
298 Height pixels high. The string will be drawn onto
299 this image and EFI_HII_OUT_FLAG_CLIP is implied.
300 If this points to a NULL on entry, then a buffer
301 will be allocated to hold the generated image and
302 the pointer updated on exit. It is the caller's
303 responsibility to free this buffer.
305 @param BltX, BltY Specifies the offset from the left and top
306 edge of the output image of the first
307 character cell in the image.
309 @param RowInfoArray If this is non-NULL on entry, then on
310 exit, this will point to an allocated
311 buffer containing row information and
312 RowInfoArraySize will be updated to
313 contain the number of elements. This array
314 describes the characters which were at
315 least partially drawn and the heights of
316 the rows. It is the caller's
317 responsibility to free this buffer.
319 @param RowInfoArraySize If this is non-NULL on entry, then on
320 exit it contains the number of
321 elements in RowInfoArray.
323 @param ColumnInfoArray If non-NULL, on return it is filled
324 with the horizontal offset for each
325 character in the string on the row
326 where it is displayed. Non-printing
327 characters will have the offset ~0.
328 The caller is responsible to allocate
329 a buffer large enough so that there is
330 one entry for each character in the
331 string, not including the
332 null-terminator. It is possible when
333 character display is normalized that
334 some character cells overlap.
337 @retval EFI_SUCCESS The string was successfully updated.
339 @retval EFI_OUT_OF_RESOURCES Unable to allocate an output
340 buffer for RowInfoArray or Blt.
342 @retval EFI_INVALID_PARAMETER The String or Blt or Height or
344 @retval EFI_INVALID_PARAMETER The Blt or PackageList was NULL.
345 @retval EFI_INVALID_PARAMETER Flags were invalid combination.
346 @retval EFI_NOT_FOUND The specified PackageList is not in the Database
347 or the stringid is not in the specified PackageList.
352 (EFIAPI
*EFI_HII_STRING_ID_TO_IMAGE
)(
353 IN CONST EFI_HII_FONT_PROTOCOL
*This
,
354 IN EFI_HII_OUT_FLAGS Flags
,
355 IN EFI_HII_HANDLE PackageList
,
356 IN EFI_STRING_ID StringId
,
357 IN CONST CHAR8
*Language
,
358 IN CONST EFI_FONT_DISPLAY_INFO
*StringInfo OPTIONAL
,
359 IN OUT EFI_IMAGE_OUTPUT
**Blt
,
362 OUT EFI_HII_ROW_INFO
**RowInfoArray OPTIONAL
,
363 OUT UINTN
*RowInfoArraySize OPTIONAL
,
364 OUT UINTN
*ColumnInfoArray OPTIONAL
370 Convert the glyph for a single character into a bitmap.
372 @param This A pointer to the EFI_HII_FONT_PROTOCOL instance.
374 @param Char Character to retrieve.
376 @param StringInfo Points to the string font and color
377 information or NULL if the string should use
378 the default system font and color.
380 @param Blt Thus must point to a NULL on entry. A buffer will
381 be allocated to hold the output and the pointer
382 updated on exit. It is the caller's responsibility
385 @param Baseline Number of pixels from the bottom of the bitmap
389 @retval EFI_SUCCESS Glyph bitmap created.
391 @retval EFI_OUT_OF_RESOURCES Unable to allocate the output buffer Blt.
393 @retval EFI_WARN_UNKNOWN_GLYPH The glyph was unknown and was
394 replaced with the glyph for
395 Unicode character 0xFFFD.
397 @retval EFI_INVALID_PARAMETER Blt is NULL or Width is NULL or
404 (EFIAPI
*EFI_HII_GET_GLYPH
)(
405 IN CONST EFI_HII_FONT_PROTOCOL
*This
,
406 IN CONST CHAR16 Char
,
407 IN CONST EFI_FONT_DISPLAY_INFO
*StringInfo
,
408 OUT EFI_IMAGE_OUTPUT
**Blt
,
409 OUT UINTN
*Baseline OPTIONAL
414 This function iterates through fonts which match the specified
415 font, using the specified criteria. If String is non-NULL, then
416 all of the characters in the string must exist in order for a
417 candidate font to be returned.
419 @param This A pointer to the EFI_HII_FONT_PROTOCOL instance.
421 @param FontHandle On entry, points to the font handle returned
422 by a previous call to GetFontInfo() or NULL
423 to start with the first font. On return,
424 points to the returned font handle or points
425 to NULL if there are no more matching fonts.
427 @param StringInfoIn Upon entry, points to the font to return
428 information about. If NULL, then the information about the system default
429 font will be returned.
431 @param StringInfoOut Upon return, contains the matching
432 font's information. If NULL, then no
433 information is returned.
435 @param String Points to the string which will be tested to
436 determine if all characters are available. If
437 NULL, then any font is acceptable.
439 @retval EFI_SUCCESS Matching font returned successfully.
441 @retval EFI_NOT_FOUND No matching font was found.
443 @retval EFI_INVALID_PARAMETER StringInfoIn->FontInfoMask is an invalid combination.
445 @retval EFI_OUT_OF_RESOURCES There were insufficient resources to complete the request.
450 (EFIAPI
*EFI_HII_GET_FONT_INFO
)(
451 IN CONST EFI_HII_FONT_PROTOCOL
*This
,
452 IN OUT EFI_FONT_HANDLE
*FontHandle
,
453 IN CONST EFI_FONT_DISPLAY_INFO
*StringInfoIn
, OPTIONAL
454 OUT EFI_FONT_DISPLAY_INFO
**StringInfoOut
,
455 IN CONST EFI_STRING String OPTIONAL
459 /// The protocol provides the service to retrieve the font informations.
461 struct _EFI_HII_FONT_PROTOCOL
{
462 EFI_HII_STRING_TO_IMAGE StringToImage
;
463 EFI_HII_STRING_ID_TO_IMAGE StringIdToImage
;
464 EFI_HII_GET_GLYPH GetGlyph
;
465 EFI_HII_GET_FONT_INFO GetFontInfo
;
468 extern EFI_GUID gEfiHiiFontProtocolGuid
;