2 The file provides services to retrieve font information.
4 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
5 SPDX-License-Identifier: BSD-2-Clause-Patent
7 @par Revision Reference:
8 This Protocol was introduced in UEFI Specification 2.1.
12 #ifndef __HII_FONT_H__
13 #define __HII_FONT_H__
15 #include <Protocol/GraphicsOutput.h>
16 #include <Protocol/HiiImage.h>
18 #define EFI_HII_FONT_PROTOCOL_GUID \
19 { 0xe9ca4775, 0x8657, 0x47fc, { 0x97, 0xe7, 0x7e, 0xd6, 0x5a, 0x8, 0x43, 0x24 } }
21 typedef struct _EFI_HII_FONT_PROTOCOL EFI_HII_FONT_PROTOCOL
;
23 typedef VOID
*EFI_FONT_HANDLE
;
26 /// EFI_HII_OUT_FLAGS.
28 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_CLIP_CLEAN_Y 0x00000004
33 #define EFI_HII_OUT_FLAG_CLIP_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
40 Definition of EFI_HII_ROW_INFO.
42 typedef struct _EFI_HII_ROW_INFO
{
44 /// The index of the first character in the string which is displayed on the line.
48 /// The index of the last character in the string which is displayed on the line.
49 /// If this is the same as StartIndex, then no characters are displayed.
52 UINTN LineHeight
; ///< The height of the line, in pixels.
53 UINTN LineWidth
; ///< The width of the text on the line, in pixels.
56 /// The font baseline offset in pixels from the bottom of the row, or 0 if none.
62 /// Font info flag. All flags (FONT, SIZE, STYLE, and COLOR) are defined.
63 /// They are defined as EFI_FONT_INFO_***
65 typedef UINT32 EFI_FONT_INFO_MASK
;
67 #define EFI_FONT_INFO_SYS_FONT 0x00000001
68 #define EFI_FONT_INFO_SYS_SIZE 0x00000002
69 #define EFI_FONT_INFO_SYS_STYLE 0x00000004
70 #define EFI_FONT_INFO_SYS_FORE_COLOR 0x00000010
71 #define EFI_FONT_INFO_SYS_BACK_COLOR 0x00000020
72 #define EFI_FONT_INFO_RESIZE 0x00001000
73 #define EFI_FONT_INFO_RESTYLE 0x00002000
74 #define EFI_FONT_INFO_ANY_FONT 0x00010000
75 #define EFI_FONT_INFO_ANY_SIZE 0x00020000
76 #define EFI_FONT_INFO_ANY_STYLE 0x00040000
82 EFI_HII_FONT_STYLE FontStyle
;
83 UINT16 FontSize
; ///< character cell height in pixels
88 Describes font output-related information.
90 This structure is used for describing the way in which a string
91 should be rendered in a particular font. FontInfo specifies the
92 basic font information and ForegroundColor and BackgroundColor
93 specify the color in which they should be displayed. The flags
94 in FontInfoMask describe where the system default should be
95 supplied instead of the specified information. The flags also
96 describe what options can be used to make a match between the
97 font requested and the font available.
99 typedef struct _EFI_FONT_DISPLAY_INFO
{
100 EFI_GRAPHICS_OUTPUT_BLT_PIXEL ForegroundColor
;
101 EFI_GRAPHICS_OUTPUT_BLT_PIXEL BackgroundColor
;
102 EFI_FONT_INFO_MASK FontInfoMask
;
103 EFI_FONT_INFO FontInfo
;
104 } EFI_FONT_DISPLAY_INFO
;
108 This function renders a string to a bitmap or the screen using
109 the specified font, color and options. It either draws the
110 string and glyphs on an existing bitmap, allocates a new bitmap,
111 or uses the screen. The strings can be clipped or wrapped.
112 Optionally, the function also returns the information about each
113 row and the character position on that row. If
114 EFI_HII_OUT_FLAG_CLIP is set, then text will be formatted only
115 based on explicit line breaks and all pixels which would lie
116 outside the bounding box specified by Width and Height are
117 ignored. The information in the RowInfoArray only describes
118 characters which are at least partially displayed. For the final
119 row, the LineHeight and BaseLine may describe pixels that are
120 outside the limit specified by Height (unless
121 EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is specified) even though those
122 pixels were not drawn. The LineWidth may describe pixels which
123 are outside the limit specified by Width (unless
124 EFI_HII_OUT_FLAG_CLIP_CLEAN_X is specified) even though those
125 pixels were not drawn. If EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set,
126 then it modifies the behavior of EFI_HII_OUT_FLAG_CLIP so that
127 if a character's right-most on pixel cannot fit, then it will
128 not be drawn at all. This flag requires that
129 EFI_HII_OUT_FLAG_CLIP be set. If EFI_HII_OUT_FLAG_CLIP_CLEAN_Y
130 is set, then it modifies the behavior of EFI_HII_OUT_FLAG_CLIP
131 so that if a row's bottom-most pixel cannot fit, then it will
132 not be drawn at all. This flag requires that
133 EFI_HII_OUT_FLAG_CLIP be set. If EFI_HII_OUT_FLAG_WRAP is set,
134 then text will be wrapped at the right-most line-break
135 opportunity prior to a character whose right-most extent would
136 exceed Width. If no line-break opportunity can be found, then
137 the text will behave as if EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set.
138 This flag cannot be used with EFI_HII_OUT_FLAG_CLIP_CLEAN_X. If
139 EFI_HII_OUT_FLAG_TRANSPARENT is set, then BackgroundColor is
140 ignored and all 'off' pixels in the character's drawn
141 will use the pixel value from Blt. This flag cannot be used if
142 Blt is NULL upon entry. If EFI_HII_IGNORE_IF_NO_GLYPH is set,
143 then characters which have no glyphs are not drawn. Otherwise,
144 they are replaced with Unicode character code 0xFFFD (REPLACEMENT
145 CHARACTER). If EFI_HII_IGNORE_LINE_BREAK is set, then explicit
146 line break characters will be ignored. If
147 EFI_HII_DIRECT_TO_SCREEN is set, then the string will be written
148 directly to the output device specified by Screen. Otherwise the
149 string will be rendered to the bitmap specified by Bitmap.
151 @param This A pointer to the EFI_HII_FONT_PROTOCOL instance.
153 @param Flags Describes how the string is to be drawn.
155 @param String Points to the null-terminated string to be
157 @param StringInfo Points to the string output information,
158 including the color and font. If NULL, then
159 the string will be output in the default
160 system font and color.
162 @param Blt If this points to a non-NULL on entry, this points
163 to the image, which is Width pixels wide and
164 Height pixels high. The string will be drawn onto
165 this image and EFI_HII_OUT_FLAG_CLIP is implied.
166 If this points to a NULL on entry, then a buffer
167 will be allocated to hold the generated image and
168 the pointer updated on exit. It is the caller's
169 responsibility to free this buffer.
171 @param BltX, BltY Specifies the offset from the left and top
172 edge of the image of the first character
175 @param RowInfoArray If this is non-NULL on entry, then on
176 exit, this will point to an allocated buffer
177 containing row information and
178 RowInfoArraySize will be updated to contain
179 the number of elements. This array describes
180 the characters that were at least partially
181 drawn and the heights of the rows. It is the
182 caller's responsibility to free this buffer.
184 @param RowInfoArraySize If this is non-NULL on entry, then on
185 exit it contains the number of
186 elements in RowInfoArray.
188 @param ColumnInfoArray If this is non-NULL, then on return it
189 will be filled with the horizontal
190 offset for each character in the
191 string on the row where it is
192 displayed. Non-printing characters
193 will have the offset ~0. The caller is
194 responsible for allocating a buffer large
195 enough so that there is one entry for
196 each character in the string, not
197 including the null-terminator. It is
198 possible when character display is
199 normalized that some character cells
202 @retval EFI_SUCCESS The string was successfully updated.
204 @retval EFI_OUT_OF_RESOURCES Unable to allocate an output buffer for RowInfoArray or Blt.
206 @retval EFI_INVALID_PARAMETER The String or Blt was NULL.
208 @retval EFI_INVALID_PARAMETER Flags were invalid combination.
212 (EFIAPI
*EFI_HII_STRING_TO_IMAGE
)(
213 IN CONST EFI_HII_FONT_PROTOCOL
*This
,
214 IN EFI_HII_OUT_FLAGS Flags
,
215 IN CONST EFI_STRING String
,
216 IN CONST EFI_FONT_DISPLAY_INFO
*StringInfo
,
217 IN OUT EFI_IMAGE_OUTPUT
**Blt
,
220 OUT EFI_HII_ROW_INFO
**RowInfoArray OPTIONAL
,
221 OUT UINTN
*RowInfoArraySize OPTIONAL
,
222 OUT UINTN
*ColumnInfoArray OPTIONAL
227 This function renders a string as a bitmap or to the screen
228 and can clip or wrap the string. The bitmap is either supplied
229 by the caller or allocated by the function. The
230 strings are drawn with the font, size and style specified and
231 can be drawn transparently or opaquely. The function can also
232 return information about each row and each character's
233 position on the row. If EFI_HII_OUT_FLAG_CLIP is set, then
234 text will be formatted based only on explicit line breaks, and
235 all pixels that would lie outside the bounding box specified
236 by Width and Height are ignored. The information in the
237 RowInfoArray only describes characters which are at least
238 partially displayed. For the final row, the LineHeight and
239 BaseLine may describe pixels which are outside the limit
240 specified by Height (unless EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is
241 specified) even though those pixels were not drawn. If
242 EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set, then it modifies the
243 behavior of EFI_HII_OUT_FLAG_CLIP so that if a character's
244 right-most on pixel cannot fit, then it will not be drawn at
245 all. This flag requires that EFI_HII_OUT_FLAG_CLIP be set. If
246 EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is set, then it modifies the
247 behavior of EFI_HII_OUT_FLAG_CLIP so that if a row's bottom
248 most pixel cannot fit, then it will not be drawn at all. This
249 flag requires that EFI_HII_OUT_FLAG_CLIP be set. If
250 EFI_HII_OUT_FLAG_WRAP is set, then text will be wrapped at the
251 right-most line-break opportunity prior to a character whose
252 right-most extent would exceed Width. If no line-break
253 opportunity can be found, then the text will behave as if
254 EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set. This flag cannot be used
255 with EFI_HII_OUT_FLAG_CLIP_CLEAN_X. If
256 EFI_HII_OUT_FLAG_TRANSPARENT is set, then BackgroundColor is
257 ignored and all off" pixels in the character's glyph will
258 use the pixel value from Blt. This flag cannot be used if Blt
259 is NULL upon entry. If EFI_HII_IGNORE_IF_NO_GLYPH is set, then
260 characters which have no glyphs are not drawn. Otherwise, they
261 are replaced with Unicode character code 0xFFFD (REPLACEMENT
262 CHARACTER). If EFI_HII_IGNORE_LINE_BREAK is set, then explicit
263 line break characters will be ignored. If
264 EFI_HII_DIRECT_TO_SCREEN is set, then the string will be
265 written directly to the output device specified by Screen.
266 Otherwise the string will be rendered to the bitmap specified
270 @param This A pointer to the EFI_HII_FONT_PROTOCOL instance.
272 @param Flags Describes how the string is to be drawn.
275 The package list in the HII database to
276 search for the specified string.
278 @param StringId The string's id, which is unique within
281 @param Language Points to the language for the retrieved
282 string. If NULL, then the current system
285 @param StringInfo Points to the string output information,
286 including the color and font. If NULL, then
287 the string will be output in the default
288 system font and color.
290 @param Blt If this points to a non-NULL on entry, this points
291 to the image, which is Width pixels wide and
292 Height pixels high. The string will be drawn onto
293 this image and EFI_HII_OUT_FLAG_CLIP is implied.
294 If this points to a NULL on entry, then a buffer
295 will be allocated to hold the generated image and
296 the pointer updated on exit. It is the caller's
297 responsibility to free this buffer.
299 @param BltX, BltY Specifies the offset from the left and top
300 edge of the output image of the first
301 character cell in the image.
303 @param RowInfoArray If this is non-NULL on entry, then on
304 exit, this will point to an allocated
305 buffer containing row information and
306 RowInfoArraySize will be updated to
307 contain the number of elements. This array
308 describes the characters which were at
309 least partially drawn and the heights of
310 the rows. It is the caller's
311 responsibility to free this buffer.
313 @param RowInfoArraySize If this is non-NULL on entry, then on
314 exit it contains the number of
315 elements in RowInfoArray.
317 @param ColumnInfoArray If non-NULL, on return it is filled
318 with the horizontal offset for each
319 character in the string on the row
320 where it is displayed. Non-printing
321 characters will have the offset ~0.
322 The caller is responsible to allocate
323 a buffer large enough so that there is
324 one entry for each character in the
325 string, not including the
326 null-terminator. It is possible when
327 character display is normalized that
328 some character cells overlap.
331 @retval EFI_SUCCESS The string was successfully updated.
333 @retval EFI_OUT_OF_RESOURCES Unable to allocate an output
334 buffer for RowInfoArray or Blt.
336 @retval EFI_INVALID_PARAMETER The String, or Blt, or Height, or
338 @retval EFI_INVALID_PARAMETER The Blt or PackageList was NULL.
339 @retval EFI_INVALID_PARAMETER Flags were invalid combination.
340 @retval EFI_NOT_FOUND The specified PackageList is not in the Database,
341 or the stringid is not in the specified PackageList.
346 (EFIAPI
*EFI_HII_STRING_ID_TO_IMAGE
)(
347 IN CONST EFI_HII_FONT_PROTOCOL
*This
,
348 IN EFI_HII_OUT_FLAGS Flags
,
349 IN EFI_HII_HANDLE PackageList
,
350 IN EFI_STRING_ID StringId
,
351 IN CONST CHAR8
*Language
,
352 IN CONST EFI_FONT_DISPLAY_INFO
*StringInfo OPTIONAL
,
353 IN OUT EFI_IMAGE_OUTPUT
**Blt
,
356 OUT EFI_HII_ROW_INFO
**RowInfoArray OPTIONAL
,
357 OUT UINTN
*RowInfoArraySize OPTIONAL
,
358 OUT UINTN
*ColumnInfoArray OPTIONAL
363 Convert the glyph for a single character into a bitmap.
365 @param This A pointer to the EFI_HII_FONT_PROTOCOL instance.
367 @param Char The character to retrieve.
369 @param StringInfo Points to the string font and color
370 information or NULL if the string should use
371 the default system font and color.
373 @param Blt This must point to a NULL on entry. A buffer will
374 be allocated to hold the output and the pointer
375 updated on exit. It is the caller's responsibility
378 @param Baseline The number of pixels from the bottom of the bitmap
382 @retval EFI_SUCCESS The glyph bitmap created.
384 @retval EFI_OUT_OF_RESOURCES Unable to allocate the output buffer Blt.
386 @retval EFI_WARN_UNKNOWN_GLYPH The glyph was unknown and was
387 replaced with the glyph for
388 Unicode character code 0xFFFD.
390 @retval EFI_INVALID_PARAMETER Blt is NULL, or Width is NULL, or
397 (EFIAPI
*EFI_HII_GET_GLYPH
)(
398 IN CONST EFI_HII_FONT_PROTOCOL
*This
,
399 IN CONST CHAR16 Char
,
400 IN CONST EFI_FONT_DISPLAY_INFO
*StringInfo
,
401 OUT EFI_IMAGE_OUTPUT
**Blt
,
402 OUT UINTN
*Baseline OPTIONAL
407 This function iterates through fonts which match the specified
408 font, using the specified criteria. If String is non-NULL, then
409 all of the characters in the string must exist in order for a
410 candidate font to be returned.
412 @param This A pointer to the EFI_HII_FONT_PROTOCOL instance.
414 @param FontHandle On entry, points to the font handle returned
415 by a previous call to GetFontInfo() or NULL
416 to start with the first font. On return,
417 points to the returned font handle or points
418 to NULL if there are no more matching fonts.
420 @param StringInfoIn Upon entry, points to the font to return
421 information about. If NULL, then the information
422 about the system default font will be returned.
424 @param StringInfoOut Upon return, contains the matching font's information.
425 If NULL, then no information is returned. This buffer
426 is allocated with a call to the Boot Service AllocatePool().
427 It is the caller's responsibility to call the Boot
428 Service FreePool() when the caller no longer requires
429 the contents of StringInfoOut.
431 @param String Points to the string which will be tested to
432 determine if all characters are available. If
433 NULL, then any font is acceptable.
435 @retval EFI_SUCCESS Matching font returned successfully.
437 @retval EFI_NOT_FOUND No matching font was found.
439 @retval EFI_OUT_OF_RESOURCES There were insufficient resources to complete the request.
444 (EFIAPI
*EFI_HII_GET_FONT_INFO
)(
445 IN CONST EFI_HII_FONT_PROTOCOL
*This
,
446 IN OUT EFI_FONT_HANDLE
*FontHandle
,
447 IN CONST EFI_FONT_DISPLAY_INFO
*StringInfoIn OPTIONAL
,
448 OUT EFI_FONT_DISPLAY_INFO
**StringInfoOut
,
449 IN CONST EFI_STRING String OPTIONAL
453 /// The protocol provides the service to retrieve the font informations.
455 struct _EFI_HII_FONT_PROTOCOL
{
456 EFI_HII_STRING_TO_IMAGE StringToImage
;
457 EFI_HII_STRING_ID_TO_IMAGE StringIdToImage
;
458 EFI_HII_GET_GLYPH GetGlyph
;
459 EFI_HII_GET_FONT_INFO GetFontInfo
;
462 extern EFI_GUID gEfiHiiFontProtocolGuid
;