iPXE
HiiFont.h
Go to the documentation of this file.
1 /** @file
2  The file provides services to retrieve font information.
3 
4 Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR>
5 This program and the accompanying materials are licensed and made available under
6 the terms and conditions of the BSD License that accompanies this distribution.
7 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 FILE_LICENCE ( BSD3 );
19 
22 
23 #define EFI_HII_FONT_PROTOCOL_GUID \
24 { 0xe9ca4775, 0x8657, 0x47fc, { 0x97, 0xe7, 0x7e, 0xd6, 0x5a, 0x8, 0x43, 0x24 } }
25 
27 
29 
30 ///
31 /// EFI_HII_OUT_FLAGS.
32 ///
34 
35 #define EFI_HII_OUT_FLAG_CLIP 0x00000001
36 #define EFI_HII_OUT_FLAG_WRAP 0x00000002
37 #define EFI_HII_OUT_FLAG_CLIP_CLEAN_Y 0x00000004
38 #define EFI_HII_OUT_FLAG_CLIP_CLEAN_X 0x00000008
39 #define EFI_HII_OUT_FLAG_TRANSPARENT 0x00000010
40 #define EFI_HII_IGNORE_IF_NO_GLYPH 0x00000020
41 #define EFI_HII_IGNORE_LINE_BREAK 0x00000040
42 #define EFI_HII_DIRECT_TO_SCREEN 0x00000080
43 
44 /**
45  Definition of EFI_HII_ROW_INFO.
46 **/
47 typedef struct _EFI_HII_ROW_INFO {
48  ///
49  /// The index of the first character in the string which is displayed on the line.
50  ///
52  ///
53  /// The index of the last character in the string which is displayed on the line.
54  /// If this is the same as StartIndex, then no characters are displayed.
55  ///
57  UINTN LineHeight; ///< The height of the line, in pixels.
58  UINTN LineWidth; ///< The width of the text on the line, in pixels.
59 
60  ///
61  /// The font baseline offset in pixels from the bottom of the row, or 0 if none.
62  ///
65 
66 ///
67 /// Font info flag. All flags (FONT, SIZE, STYLE, and COLOR) are defined.
68 /// They are defined as EFI_FONT_INFO_***
69 ///
71 
72 #define EFI_FONT_INFO_SYS_FONT 0x00000001
73 #define EFI_FONT_INFO_SYS_SIZE 0x00000002
74 #define EFI_FONT_INFO_SYS_STYLE 0x00000004
75 #define EFI_FONT_INFO_SYS_FORE_COLOR 0x00000010
76 #define EFI_FONT_INFO_SYS_BACK_COLOR 0x00000020
77 #define EFI_FONT_INFO_RESIZE 0x00001000
78 #define EFI_FONT_INFO_RESTYLE 0x00002000
79 #define EFI_FONT_INFO_ANY_FONT 0x00010000
80 #define EFI_FONT_INFO_ANY_SIZE 0x00020000
81 #define EFI_FONT_INFO_ANY_STYLE 0x00040000
82 
83 //
84 // EFI_FONT_INFO
85 //
86 typedef struct {
88  UINT16 FontSize; ///< character cell height in pixels
89  CHAR16 FontName[1];
91 
92 /**
93  Describes font output-related information.
94 
95  This structure is used for describing the way in which a string
96  should be rendered in a particular font. FontInfo specifies the
97  basic font information and ForegroundColor and BackgroundColor
98  specify the color in which they should be displayed. The flags
99  in FontInfoMask describe where the system default should be
100  supplied instead of the specified information. The flags also
101  describe what options can be used to make a match between the
102  font requested and the font available.
103 **/
104 typedef struct _EFI_FONT_DISPLAY_INFO {
110 
111 /**
112 
113  This function renders a string to a bitmap or the screen using
114  the specified font, color and options. It either draws the
115  string and glyphs on an existing bitmap, allocates a new bitmap,
116  or uses the screen. The strings can be clipped or wrapped.
117  Optionally, the function also returns the information about each
118  row and the character position on that row. If
119  EFI_HII_OUT_FLAG_CLIP is set, then text will be formatted only
120  based on explicit line breaks and all pixels which would lie
121  outside the bounding box specified by Width and Height are
122  ignored. The information in the RowInfoArray only describes
123  characters which are at least partially displayed. For the final
124  row, the LineHeight and BaseLine may describe pixels that are
125  outside the limit specified by Height (unless
126  EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is specified) even though those
127  pixels were not drawn. The LineWidth may describe pixels which
128  are outside the limit specified by Width (unless
129  EFI_HII_OUT_FLAG_CLIP_CLEAN_X is specified) even though those
130  pixels were not drawn. If EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set,
131  then it modifies the behavior of EFI_HII_OUT_FLAG_CLIP so that
132  if a character's right-most on pixel cannot fit, then it will
133  not be drawn at all. This flag requires that
134  EFI_HII_OUT_FLAG_CLIP be set. If EFI_HII_OUT_FLAG_CLIP_CLEAN_Y
135  is set, then it modifies the behavior of EFI_HII_OUT_FLAG_CLIP
136  so that if a row's bottom-most pixel cannot fit, then it will
137  not be drawn at all. This flag requires that
138  EFI_HII_OUT_FLAG_CLIP be set. If EFI_HII_OUT_FLAG_WRAP is set,
139  then text will be wrapped at the right-most line-break
140  opportunity prior to a character whose right-most extent would
141  exceed Width. If no line-break opportunity can be found, then
142  the text will behave as if EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set.
143  This flag cannot be used with EFI_HII_OUT_FLAG_CLIP_CLEAN_X. If
144  EFI_HII_OUT_FLAG_TRANSPARENT is set, then BackgroundColor is
145  ignored and all 'off' pixels in the character's drawn
146  will use the pixel value from Blt. This flag cannot be used if
147  Blt is NULL upon entry. If EFI_HII_IGNORE_IF_NO_GLYPH is set,
148  then characters which have no glyphs are not drawn. Otherwise,
149  they are replaced with Unicode character code 0xFFFD (REPLACEMENT
150  CHARACTER). If EFI_HII_IGNORE_LINE_BREAK is set, then explicit
151  line break characters will be ignored. If
152  EFI_HII_DIRECT_TO_SCREEN is set, then the string will be written
153  directly to the output device specified by Screen. Otherwise the
154  string will be rendered to the bitmap specified by Bitmap.
155 
156  @param This A pointer to the EFI_HII_FONT_PROTOCOL instance.
157 
158  @param Flags Describes how the string is to be drawn.
159 
160  @param String Points to the null-terminated string to be
161 
162  @param StringInfo Points to the string output information,
163  including the color and font. If NULL, then
164  the string will be output in the default
165  system font and color.
166 
167  @param Blt If this points to a non-NULL on entry, this points
168  to the image, which is Width pixels wide and
169  Height pixels high. The string will be drawn onto
170  this image and EFI_HII_OUT_FLAG_CLIP is implied.
171  If this points to a NULL on entry, then a buffer
172  will be allocated to hold the generated image and
173  the pointer updated on exit. It is the caller's
174  responsibility to free this buffer.
175 
176  @param BltX, BltY Specifies the offset from the left and top
177  edge of the image of the first character
178  cell in the image.
179 
180  @param RowInfoArray If this is non-NULL on entry, then on
181  exit, this will point to an allocated buffer
182  containing row information and
183  RowInfoArraySize will be updated to contain
184  the number of elements. This array describes
185  the characters that were at least partially
186  drawn and the heights of the rows. It is the
187  caller's responsibility to free this buffer.
188 
189  @param RowInfoArraySize If this is non-NULL on entry, then on
190  exit it contains the number of
191  elements in RowInfoArray.
192 
193  @param ColumnInfoArray If this is non-NULL, then on return it
194  will be filled with the horizontal
195  offset for each character in the
196  string on the row where it is
197  displayed. Non-printing characters
198  will have the offset ~0. The caller is
199  responsible for allocating a buffer large
200  enough so that there is one entry for
201  each character in the string, not
202  including the null-terminator. It is
203  possible when character display is
204  normalized that some character cells
205  overlap.
206 
207  @retval EFI_SUCCESS The string was successfully updated.
208 
209  @retval EFI_OUT_OF_RESOURCES Unable to allocate an output buffer for RowInfoArray or Blt.
210 
211  @retval EFI_INVALID_PARAMETER The String or Blt was NULL.
212 
213  @retval EFI_INVALID_PARAMETER Flags were invalid combination.
214 **/
215 typedef
220  IN CONST EFI_STRING String,
221  IN CONST EFI_FONT_DISPLAY_INFO *StringInfo,
222  IN OUT EFI_IMAGE_OUTPUT **Blt,
223  IN UINTN BltX,
224  IN UINTN BltY,
225  OUT EFI_HII_ROW_INFO **RowInfoArray OPTIONAL,
226  OUT UINTN *RowInfoArraySize OPTIONAL,
227  OUT UINTN *ColumnInfoArray OPTIONAL
228 );
229 
230 
231 
232 /**
233 
234  This function renders a string as a bitmap or to the screen
235  and can clip or wrap the string. The bitmap is either supplied
236  by the caller or allocated by the function. The
237  strings are drawn with the font, size and style specified and
238  can be drawn transparently or opaquely. The function can also
239  return information about each row and each character's
240  position on the row. If EFI_HII_OUT_FLAG_CLIP is set, then
241  text will be formatted based only on explicit line breaks, and
242  all pixels that would lie outside the bounding box specified
243  by Width and Height are ignored. The information in the
244  RowInfoArray only describes characters which are at least
245  partially displayed. For the final row, the LineHeight and
246  BaseLine may describe pixels which are outside the limit
247  specified by Height (unless EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is
248  specified) even though those pixels were not drawn. If
249  EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set, then it modifies the
250  behavior of EFI_HII_OUT_FLAG_CLIP so that if a character's
251  right-most on pixel cannot fit, then it will not be drawn at
252  all. This flag requires that EFI_HII_OUT_FLAG_CLIP be set. If
253  EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is set, then it modifies the
254  behavior of EFI_HII_OUT_FLAG_CLIP so that if a row's bottom
255  most pixel cannot fit, then it will not be drawn at all. This
256  flag requires that EFI_HII_OUT_FLAG_CLIP be set. If
257  EFI_HII_OUT_FLAG_WRAP is set, then text will be wrapped at the
258  right-most line-break opportunity prior to a character whose
259  right-most extent would exceed Width. If no line-break
260  opportunity can be found, then the text will behave as if
261  EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set. This flag cannot be used
262  with EFI_HII_OUT_FLAG_CLIP_CLEAN_X. If
263  EFI_HII_OUT_FLAG_TRANSPARENT is set, then BackgroundColor is
264  ignored and all off" pixels in the character's glyph will
265  use the pixel value from Blt. This flag cannot be used if Blt
266  is NULL upon entry. If EFI_HII_IGNORE_IF_NO_GLYPH is set, then
267  characters which have no glyphs are not drawn. Otherwise, they
268  are replaced with Unicode character code 0xFFFD (REPLACEMENT
269  CHARACTER). If EFI_HII_IGNORE_LINE_BREAK is set, then explicit
270  line break characters will be ignored. If
271  EFI_HII_DIRECT_TO_SCREEN is set, then the string will be
272  written directly to the output device specified by Screen.
273  Otherwise the string will be rendered to the bitmap specified
274  by Bitmap.
275 
276 
277  @param This A pointer to the EFI_HII_FONT_PROTOCOL instance.
278 
279  @param Flags Describes how the string is to be drawn.
280 
281  @param PackageList
282  The package list in the HII database to
283  search for the specified string.
284 
285  @param StringId The string's id, which is unique within
286  PackageList.
287 
288  @param Language Points to the language for the retrieved
289  string. If NULL, then the current system
290  language is used.
291 
292  @param StringInfo Points to the string output information,
293  including the color and font. If NULL, then
294  the string will be output in the default
295  system font and color.
296 
297  @param Blt If this points to a non-NULL on entry, this points
298  to the image, which is Width pixels wide and
299  Height pixels high. The string will be drawn onto
300  this image and EFI_HII_OUT_FLAG_CLIP is implied.
301  If this points to a NULL on entry, then a buffer
302  will be allocated to hold the generated image and
303  the pointer updated on exit. It is the caller's
304  responsibility to free this buffer.
305 
306  @param BltX, BltY Specifies the offset from the left and top
307  edge of the output image of the first
308  character cell in the image.
309 
310  @param RowInfoArray If this is non-NULL on entry, then on
311  exit, this will point to an allocated
312  buffer containing row information and
313  RowInfoArraySize will be updated to
314  contain the number of elements. This array
315  describes the characters which were at
316  least partially drawn and the heights of
317  the rows. It is the caller's
318  responsibility to free this buffer.
319 
320  @param RowInfoArraySize If this is non-NULL on entry, then on
321  exit it contains the number of
322  elements in RowInfoArray.
323 
324  @param ColumnInfoArray If non-NULL, on return it is filled
325  with the horizontal offset for each
326  character in the string on the row
327  where it is displayed. Non-printing
328  characters will have the offset ~0.
329  The caller is responsible to allocate
330  a buffer large enough so that there is
331  one entry for each character in the
332  string, not including the
333  null-terminator. It is possible when
334  character display is normalized that
335  some character cells overlap.
336 
337 
338  @retval EFI_SUCCESS The string was successfully updated.
339 
340  @retval EFI_OUT_OF_RESOURCES Unable to allocate an output
341  buffer for RowInfoArray or Blt.
342 
343  @retval EFI_INVALID_PARAMETER The String, or Blt, or Height, or
344  Width was NULL.
345  @retval EFI_INVALID_PARAMETER The Blt or PackageList was NULL.
346  @retval EFI_INVALID_PARAMETER Flags were invalid combination.
347  @retval EFI_NOT_FOUND The specified PackageList is not in the Database,
348  or the stringid is not in the specified PackageList.
349 
350 **/
351 typedef
356  IN EFI_HII_HANDLE PackageList,
357  IN EFI_STRING_ID StringId,
358  IN CONST CHAR8 *Language,
360  IN OUT EFI_IMAGE_OUTPUT **Blt,
361  IN UINTN BltX,
362  IN UINTN BltY,
363  OUT EFI_HII_ROW_INFO **RowInfoArray OPTIONAL,
364  OUT UINTN *RowInfoArraySize OPTIONAL,
365  OUT UINTN *ColumnInfoArray OPTIONAL
366 );
367 
368 
369 /**
370 
371  Convert the glyph for a single character into a bitmap.
372 
373  @param This A pointer to the EFI_HII_FONT_PROTOCOL instance.
374 
375  @param Char The character to retrieve.
376 
377  @param StringInfo Points to the string font and color
378  information or NULL if the string should use
379  the default system font and color.
380 
381  @param Blt This must point to a NULL on entry. A buffer will
382  be allocated to hold the output and the pointer
383  updated on exit. It is the caller's responsibility
384  to free this buffer.
385 
386  @param Baseline The number of pixels from the bottom of the bitmap
387  to the baseline.
388 
389 
390  @retval EFI_SUCCESS The glyph bitmap created.
391 
392  @retval EFI_OUT_OF_RESOURCES Unable to allocate the output buffer Blt.
393 
394  @retval EFI_WARN_UNKNOWN_GLYPH The glyph was unknown and was
395  replaced with the glyph for
396  Unicode character code 0xFFFD.
397 
398  @retval EFI_INVALID_PARAMETER Blt is NULL, or Width is NULL, or
399  Height is NULL
400 
401 
402 **/
403 typedef
407  IN CONST CHAR16 Char,
408  IN CONST EFI_FONT_DISPLAY_INFO *StringInfo,
409  OUT EFI_IMAGE_OUTPUT **Blt,
410  OUT UINTN *Baseline OPTIONAL
411 );
412 
413 /**
414 
415  This function iterates through fonts which match the specified
416  font, using the specified criteria. If String is non-NULL, then
417  all of the characters in the string must exist in order for a
418  candidate font to be returned.
419 
420  @param This A pointer to the EFI_HII_FONT_PROTOCOL instance.
421 
422  @param FontHandle On entry, points to the font handle returned
423  by a previous call to GetFontInfo() or NULL
424  to start with the first font. On return,
425  points to the returned font handle or points
426  to NULL if there are no more matching fonts.
427 
428  @param StringInfoIn Upon entry, points to the font to return
429  information about. If NULL, then the information
430  about the system default font will be returned.
431 
432  @param StringInfoOut Upon return, contains the matching font's information.
433  If NULL, then no information is returned. This buffer
434  is allocated with a call to the Boot Service AllocatePool().
435  It is the caller's responsibility to call the Boot
436  Service FreePool() when the caller no longer requires
437  the contents of StringInfoOut.
438 
439  @param String Points to the string which will be tested to
440  determine if all characters are available. If
441  NULL, then any font is acceptable.
442 
443  @retval EFI_SUCCESS Matching font returned successfully.
444 
445  @retval EFI_NOT_FOUND No matching font was found.
446 
447  @retval EFI_OUT_OF_RESOURCES There were insufficient resources to complete the request.
448 
449 **/
450 typedef
454  IN OUT EFI_FONT_HANDLE *FontHandle,
455  IN CONST EFI_FONT_DISPLAY_INFO *StringInfoIn, OPTIONAL
456  OUT EFI_FONT_DISPLAY_INFO **StringInfoOut,
457  IN CONST EFI_STRING String OPTIONAL
458 );
459 
460 ///
461 /// The protocol provides the service to retrieve the font informations.
462 ///
468 };
469 
471 
472 
473 #endif
474 
#define OPTIONAL
Passing the datum to the function is optional, and a NULL is passed if the value is not supplied.
Definition: Base.h:340
EFI_HII_STRING_TO_IMAGE StringToImage
Definition: HiiFont.h:464
UINTN BaselineOffset
The font baseline offset in pixels from the bottom of the row, or 0 if none.
Definition: HiiFont.h:63
UINT32 EFI_FONT_INFO_MASK
Font info flag.
Definition: HiiFont.h:70
EFI_FONT_INFO_MASK FontInfoMask
Definition: HiiFont.h:107
EFI_HII_STRING_ID_TO_IMAGE StringIdToImage
Definition: HiiFont.h:465
UINTN StartIndex
The index of the first character in the string which is displayed on the line.
Definition: HiiFont.h:51
128 bit buffer containing a unique identifier value.
Definition: Base.h:263
EFI_HII_GET_GLYPH GetGlyph
Definition: HiiFont.h:466
EFI_STATUS(EFIAPI * EFI_HII_GET_FONT_INFO)(IN CONST EFI_HII_FONT_PROTOCOL *This, IN OUT EFI_FONT_HANDLE *FontHandle, IN CONST EFI_FONT_DISPLAY_INFO *StringInfoIn, OPTIONAL OUT EFI_FONT_DISPLAY_INFO **StringInfoOut, IN CONST EFI_STRING String OPTIONAL)
This function iterates through fonts which match the specified font, using the specified criteria.
Definition: HiiFont.h:452
UINT16 FontSize
character cell height in pixels
Definition: HiiFont.h:88
EFI_HII_GET_FONT_INFO GetFontInfo
Definition: HiiFont.h:467
EFI_STATUS(EFIAPI * EFI_HII_STRING_TO_IMAGE)(IN CONST EFI_HII_FONT_PROTOCOL *This, IN EFI_HII_OUT_FLAGS Flags, IN CONST EFI_STRING String, IN CONST EFI_FONT_DISPLAY_INFO *StringInfo, IN OUT EFI_IMAGE_OUTPUT **Blt, IN UINTN BltX, IN UINTN BltY, OUT EFI_HII_ROW_INFO **RowInfoArray OPTIONAL, OUT UINTN *RowInfoArraySize OPTIONAL, OUT UINTN *ColumnInfoArray OPTIONAL)
This function renders a string to a bitmap or the screen using the specified font,...
Definition: HiiFont.h:217
unsigned int UINT32
Definition: ProcessorBind.h:56
struct _EFI_FONT_DISPLAY_INFO EFI_FONT_DISPLAY_INFO
Describes font output-related information.
unsigned short CHAR16
Definition: ProcessorBind.h:59
CHAR16 * EFI_STRING
UINTN EndIndex
The index of the last character in the string which is displayed on the line.
Definition: HiiFont.h:56
EFI_GUID gEfiHiiFontProtocolGuid
EFI_HII_FONT_STYLE FontStyle
Definition: HiiFont.h:87
UINT32 EFI_HII_OUT_FLAGS
EFI_HII_OUT_FLAGS.
Definition: HiiFont.h:33
UINT16_t Flags
Flags.
Definition: pxe_api.h:87
struct _EFI_HII_ROW_INFO EFI_HII_ROW_INFO
Definition of EFI_HII_ROW_INFO.
Definition of EFI_HII_ROW_INFO.
Definition: HiiFont.h:47
UINT32 EFI_HII_FONT_STYLE
UINTN LineWidth
The width of the text on the line, in pixels.
Definition: HiiFont.h:58
#define OUT
Definition: mlx_utils.h:29
unsigned short UINT16
Definition: ProcessorBind.h:58
#define EFIAPI
Describes font output-related information.
Definition: HiiFont.h:104
VOID * EFI_FONT_HANDLE
Definition: HiiFont.h:28
UINT64 UINTN
Unsigned value of native width.
Definition: ProcessorBind.h:71
EFI_STATUS(EFIAPI * EFI_HII_GET_GLYPH)(IN CONST EFI_HII_FONT_PROTOCOL *This, IN CONST CHAR16 Char, IN CONST EFI_FONT_DISPLAY_INFO *StringInfo, OUT EFI_IMAGE_OUTPUT **Blt, OUT UINTN *Baseline OPTIONAL)
Convert the glyph for a single character into a bitmap.
Definition: HiiFont.h:405
FILE_LICENCE(BSD3)
#define VOID
Undeclared type.
Definition: Base.h:319
#define IN
Definition: mlx_utils.h:28
Graphics Output Protocol from the UEFI 2.0 specification.
EFI_GRAPHICS_OUTPUT_BLT_PIXEL BackgroundColor
Definition: HiiFont.h:106
#define CONST
Datum is read-only.
Definition: Base.h:309
char CHAR8
Definition: ProcessorBind.h:63
The protocol provides the service to retrieve the font informations.
Definition: HiiFont.h:463
RETURN_STATUS EFI_STATUS
Function return status for EFI API.
Definition: UefiBaseType.h:35
UINT16 EFI_STRING_ID
EFI_STATUS(EFIAPI * EFI_HII_STRING_ID_TO_IMAGE)(IN CONST EFI_HII_FONT_PROTOCOL *This, IN EFI_HII_OUT_FLAGS Flags, IN EFI_HII_HANDLE PackageList, IN EFI_STRING_ID StringId, IN CONST CHAR8 *Language, IN CONST EFI_FONT_DISPLAY_INFO *StringInfo OPTIONAL, IN OUT EFI_IMAGE_OUTPUT **Blt, IN UINTN BltX, IN UINTN BltY, OUT EFI_HII_ROW_INFO **RowInfoArray OPTIONAL, OUT UINTN *RowInfoArraySize OPTIONAL, OUT UINTN *ColumnInfoArray OPTIONAL)
This function renders a string as a bitmap or to the screen and can clip or wrap the string.
Definition: HiiFont.h:353
UINTN LineHeight
The height of the line, in pixels.
Definition: HiiFont.h:57
EFI_GRAPHICS_OUTPUT_BLT_PIXEL ForegroundColor
Definition: HiiFont.h:105
Definition of EFI_IMAGE_OUTPUT.
Definition: HiiImage.h:195
VOID * EFI_HII_HANDLE
The following types are currently defined:
EFI_FONT_INFO FontInfo
Definition: HiiFont.h:108
The file provides services to access to images in the images database.