xref: /illumos-gate/usr/src/boot/efi/include/Protocol/HiiFont.h (revision f334afcfaebea1b7dc3430015651d8d748fa8a3e)
1 /** @file
2   The file provides services to retrieve font information.
3 
4 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
5 SPDX-License-Identifier: BSD-2-Clause-Patent
6 
7   @par Revision Reference:
8   This Protocol was introduced in UEFI Specification 2.1.
9 
10 **/
11 
12 #ifndef __HII_FONT_H__
13 #define __HII_FONT_H__
14 
15 #include <Protocol/GraphicsOutput.h>
16 #include <Protocol/HiiImage.h>
17 
18 #define EFI_HII_FONT_PROTOCOL_GUID \
19 { 0xe9ca4775, 0x8657, 0x47fc, { 0x97, 0xe7, 0x7e, 0xd6, 0x5a, 0x8, 0x43, 0x24 } }
20 
21 typedef struct _EFI_HII_FONT_PROTOCOL EFI_HII_FONT_PROTOCOL;
22 
23 typedef VOID *EFI_FONT_HANDLE;
24 
25 ///
26 /// EFI_HII_OUT_FLAGS.
27 ///
28 typedef UINT32 EFI_HII_OUT_FLAGS;
29 
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
38 
39 /**
40   Definition of EFI_HII_ROW_INFO.
41 **/
42 typedef struct _EFI_HII_ROW_INFO {
43   ///
44   /// The index of the first character in the string which is displayed on the line.
45   ///
46   UINTN    StartIndex;
47   ///
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.
50   ///
51   UINTN    EndIndex;
52   UINTN    LineHeight; ///< The height of the line, in pixels.
53   UINTN    LineWidth;  ///< The width of the text on the line, in pixels.
54 
55   ///
56   /// The font baseline offset in pixels from the bottom of the row, or 0 if none.
57   ///
58   UINTN    BaselineOffset;
59 } EFI_HII_ROW_INFO;
60 
61 ///
62 /// Font info flag. All flags (FONT, SIZE, STYLE, and COLOR) are defined.
63 /// They are defined as EFI_FONT_INFO_***
64 ///
65 typedef UINT32 EFI_FONT_INFO_MASK;
66 
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
77 
78 //
79 // EFI_FONT_INFO
80 //
81 typedef struct {
82   EFI_HII_FONT_STYLE    FontStyle;
83   UINT16                FontSize;   ///< character cell height in pixels
84   CHAR16                FontName[1];
85 } EFI_FONT_INFO;
86 
87 /**
88   Describes font output-related information.
89 
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.
98 **/
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;
105 
106 /**
107 
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.
150 
151   @param This             A pointer to the EFI_HII_FONT_PROTOCOL instance.
152 
153   @param Flags            Describes how the string is to be drawn.
154 
155   @param String           Points to the null-terminated string to be
156 
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.
161 
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.
170 
171   @param BltX, BltY       Specifies the offset from the left and top
172                           edge of the image of the first character
173                           cell in the image.
174 
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.
183 
184   @param RowInfoArraySize If this is non-NULL on entry, then on
185                           exit it contains the number of
186                           elements in RowInfoArray.
187 
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
200                           overlap.
201 
202   @retval EFI_SUCCESS           The string was successfully updated.
203 
204   @retval EFI_OUT_OF_RESOURCES  Unable to allocate an output buffer for RowInfoArray or Blt.
205 
206   @retval EFI_INVALID_PARAMETER The String or Blt was NULL.
207 
208   @retval EFI_INVALID_PARAMETER Flags were invalid combination.
209 **/
210 typedef
211 EFI_STATUS
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,
218   IN        UINTN                 BltX,
219   IN        UINTN                 BltY,
220   OUT       EFI_HII_ROW_INFO      **RowInfoArray OPTIONAL,
221   OUT       UINTN                 *RowInfoArraySize OPTIONAL,
222   OUT       UINTN                 *ColumnInfoArray OPTIONAL
223   );
224 
225 /**
226 
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
267   by Bitmap.
268 
269 
270   @param This       A pointer to the EFI_HII_FONT_PROTOCOL instance.
271 
272   @param Flags      Describes how the string is to be drawn.
273 
274   @param PackageList
275                     The package list in the HII database to
276                     search for the specified string.
277 
278   @param StringId   The string's id, which is unique within
279                     PackageList.
280 
281   @param Language   Points to the language for the retrieved
282                     string. If NULL, then the current system
283                     language is used.
284 
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.
289 
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.
298 
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.
302 
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.
312 
313   @param RowInfoArraySize If this is non-NULL on entry, then on
314                           exit it contains the number of
315                           elements in RowInfoArray.
316 
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.
329 
330 
331   @retval EFI_SUCCESS           The string was successfully updated.
332 
333   @retval EFI_OUT_OF_RESOURCES  Unable to allocate an output
334                                 buffer for RowInfoArray or Blt.
335 
336   @retval EFI_INVALID_PARAMETER The String, or Blt, or Height, or
337                                 Width was NULL.
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.
342 
343 **/
344 typedef
345 EFI_STATUS
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,
354   IN        UINTN                 BltX,
355   IN        UINTN                 BltY,
356   OUT       EFI_HII_ROW_INFO      **RowInfoArray    OPTIONAL,
357   OUT       UINTN                 *RowInfoArraySize OPTIONAL,
358   OUT       UINTN                 *ColumnInfoArray  OPTIONAL
359   );
360 
361 /**
362 
363   Convert the glyph for a single character into a bitmap.
364 
365   @param This       A pointer to the EFI_HII_FONT_PROTOCOL instance.
366 
367   @param Char       The character to retrieve.
368 
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.
372 
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
376                     to free this buffer.
377 
378   @param Baseline   The number of pixels from the bottom of the bitmap
379                     to the baseline.
380 
381 
382   @retval EFI_SUCCESS             The glyph bitmap created.
383 
384   @retval EFI_OUT_OF_RESOURCES    Unable to allocate the output buffer Blt.
385 
386   @retval EFI_WARN_UNKNOWN_GLYPH  The glyph was unknown and was
387                                   replaced with the glyph for
388                                   Unicode character code 0xFFFD.
389 
390   @retval EFI_INVALID_PARAMETER   Blt is NULL, or Width is NULL, or
391                                   Height is NULL
392 
393 
394 **/
395 typedef
396 EFI_STATUS
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
403   );
404 
405 /**
406 
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.
411 
412   @param This           A pointer to the EFI_HII_FONT_PROTOCOL instance.
413 
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.
419 
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.
423 
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.
430 
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.
434 
435   @retval EFI_SUCCESS            Matching font returned successfully.
436 
437   @retval EFI_NOT_FOUND          No matching font was found.
438 
439   @retval EFI_OUT_OF_RESOURCES   There were insufficient resources to complete the request.
440 
441 **/
442 typedef
443 EFI_STATUS
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
450   );
451 
452 ///
453 /// The protocol provides the service to retrieve the font informations.
454 ///
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;
460 };
461 
462 extern EFI_GUID  gEfiHiiFontProtocolGuid;
463 
464 #endif
465