The file provides services to retrieve font information.
Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.
SPDX-License-Identifier: BSD-2-Clause-Patent
- Revision Reference:
- This Protocol was introduced in UEFI Specification 2.1.
Definition in file HiiFont.h.
This function renders a string to a bitmap or the screen using the specified font, color and options.
It either draws the string and glyphs on an existing bitmap, allocates a new bitmap, or uses the screen. The strings can be clipped or wrapped. Optionally, the function also returns the information about each row and the character position on that row. If EFI_HII_OUT_FLAG_CLIP is set, then text will be formatted only based on explicit line breaks and all pixels which would lie outside the bounding box specified by Width and Height are ignored. The information in the RowInfoArray only describes characters which are at least partially displayed. For the final row, the LineHeight and BaseLine may describe pixels that are outside the limit specified by Height (unless EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is specified) even though those pixels were not drawn. The LineWidth may describe pixels which are outside the limit specified by Width (unless EFI_HII_OUT_FLAG_CLIP_CLEAN_X is specified) even though those pixels were not drawn. If EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set, then it modifies the behavior of EFI_HII_OUT_FLAG_CLIP so that if a character's right-most on pixel cannot fit, then it will not be drawn at all. This flag requires that EFI_HII_OUT_FLAG_CLIP be set. If EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is set, then it modifies the behavior of EFI_HII_OUT_FLAG_CLIP so that if a row's bottom-most pixel cannot fit, then it will not be drawn at all. This flag requires that EFI_HII_OUT_FLAG_CLIP be set. If EFI_HII_OUT_FLAG_WRAP is set, then text will be wrapped at the right-most line-break opportunity prior to a character whose right-most extent would exceed Width. If no line-break opportunity can be found, then the text will behave as if EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set. This flag cannot be used with EFI_HII_OUT_FLAG_CLIP_CLEAN_X. If EFI_HII_OUT_FLAG_TRANSPARENT is set, then BackgroundColor is ignored and all 'off' pixels in the character's drawn will use the pixel value from Blt. This flag cannot be used if Blt is NULL upon entry. If EFI_HII_IGNORE_IF_NO_GLYPH is set, then characters which have no glyphs are not drawn. Otherwise, they are replaced with Unicode character code 0xFFFD (REPLACEMENT CHARACTER). If EFI_HII_IGNORE_LINE_BREAK is set, then explicit line break characters will be ignored. If EFI_HII_DIRECT_TO_SCREEN is set, then the string will be written directly to the output device specified by Screen. Otherwise the string will be rendered to the bitmap specified by Bitmap.
- Parameters
-
| This | A pointer to the EFI_HII_FONT_PROTOCOL instance. |
| Flags | Describes how the string is to be drawn. |
| String | Points to the null-terminated string to be |
| StringInfo | Points to the string output information, including the color and font. If NULL, then the string will be output in the default system font and color. |
| Blt | If this points to a non-NULL on entry, this points to the image, which is Width pixels wide and Height pixels high. The string will be drawn onto this image and EFI_HII_OUT_FLAG_CLIP is implied. If this points to a NULL on entry, then a buffer will be allocated to hold the generated image and the pointer updated on exit. It is the caller's responsibility to free this buffer. |
| BltX,BltY | Specifies the offset from the left and top edge of the image of the first character cell in the image. |
| RowInfoArray | If this is non-NULL on entry, then on exit, this will point to an allocated buffer containing row information and RowInfoArraySize will be updated to contain the number of elements. This array describes the characters that were at least partially drawn and the heights of the rows. It is the caller's responsibility to free this buffer. |
| RowInfoArraySize | If this is non-NULL on entry, then on exit it contains the number of elements in RowInfoArray. |
| ColumnInfoArray | If this is non-NULL, then on return it will be filled with the horizontal offset for each character in the string on the row where it is displayed. Non-printing characters will have the offset ~0. The caller is responsible for allocating a buffer large enough so that there is one entry for each character in the string, not including the null-terminator. It is possible when character display is normalized that some character cells overlap. |
- Return values
-
| EFI_SUCCESS | The string was successfully updated. |
| EFI_OUT_OF_RESOURCES | Unable to allocate an output buffer for RowInfoArray or Blt. |
| EFI_INVALID_PARAMETER | The String or Blt was NULL. |
| EFI_INVALID_PARAMETER | Flags were invalid combination. |
Definition at line 214 of file HiiFont.h.
| typedef 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.
The bitmap is either supplied by the caller or allocated by the function. The strings are drawn with the font, size and style specified and can be drawn transparently or opaquely. The function can also return information about each row and each character's position on the row. If EFI_HII_OUT_FLAG_CLIP is set, then text will be formatted based only on explicit line breaks, and all pixels that would lie outside the bounding box specified by Width and Height are ignored. The information in the RowInfoArray only describes characters which are at least partially displayed. For the final row, the LineHeight and BaseLine may describe pixels which are outside the limit specified by Height (unless EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is specified) even though those pixels were not drawn. If EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set, then it modifies the behavior of EFI_HII_OUT_FLAG_CLIP so that if a character's right-most on pixel cannot fit, then it will not be drawn at all. This flag requires that EFI_HII_OUT_FLAG_CLIP be set. If EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is set, then it modifies the behavior of EFI_HII_OUT_FLAG_CLIP so that if a row's bottom most pixel cannot fit, then it will not be drawn at all. This flag requires that EFI_HII_OUT_FLAG_CLIP be set. If EFI_HII_OUT_FLAG_WRAP is set, then text will be wrapped at the right-most line-break opportunity prior to a character whose right-most extent would exceed Width. If no line-break opportunity can be found, then the text will behave as if EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set. This flag cannot be used with EFI_HII_OUT_FLAG_CLIP_CLEAN_X. If EFI_HII_OUT_FLAG_TRANSPARENT is set, then BackgroundColor is ignored and all off" pixels in the character's glyph will use the pixel value from Blt. This flag cannot be used if Blt is NULL upon entry. If EFI_HII_IGNORE_IF_NO_GLYPH is set, then characters which have no glyphs are not drawn. Otherwise, they are replaced with Unicode character code 0xFFFD (REPLACEMENT CHARACTER). If EFI_HII_IGNORE_LINE_BREAK is set, then explicit line break characters will be ignored. If EFI_HII_DIRECT_TO_SCREEN is set, then the string will be written directly to the output device specified by Screen. Otherwise the string will be rendered to the bitmap specified by Bitmap.
- Parameters
-
| This | A pointer to the EFI_HII_FONT_PROTOCOL instance. |
| Flags | Describes how the string is to be drawn. |
| PackageList | The package list in the HII database to search for the specified string. |
| StringId | The string's id, which is unique within PackageList. |
| Language | Points to the language for the retrieved string. If NULL, then the current system language is used. |
| StringInfo | Points to the string output information, including the color and font. If NULL, then the string will be output in the default system font and color. |
| Blt | If this points to a non-NULL on entry, this points to the image, which is Width pixels wide and Height pixels high. The string will be drawn onto this image and EFI_HII_OUT_FLAG_CLIP is implied. If this points to a NULL on entry, then a buffer will be allocated to hold the generated image and the pointer updated on exit. It is the caller's responsibility to free this buffer. |
| BltX,BltY | Specifies the offset from the left and top edge of the output image of the first character cell in the image. |
| RowInfoArray | If this is non-NULL on entry, then on exit, this will point to an allocated buffer containing row information and RowInfoArraySize will be updated to contain the number of elements. This array describes the characters which were at least partially drawn and the heights of the rows. It is the caller's responsibility to free this buffer. |
| RowInfoArraySize | If this is non-NULL on entry, then on exit it contains the number of elements in RowInfoArray. |
| ColumnInfoArray | If non-NULL, on return it is filled with the horizontal offset for each character in the string on the row where it is displayed. Non-printing characters will have the offset ~0. The caller is responsible to allocate a buffer large enough so that there is one entry for each character in the string, not including the null-terminator. It is possible when character display is normalized that some character cells overlap. |
- Return values
-
| EFI_SUCCESS | The string was successfully updated. |
| EFI_OUT_OF_RESOURCES | Unable to allocate an output buffer for RowInfoArray or Blt. |
| EFI_INVALID_PARAMETER | The String, or Blt, or Height, or Width was NULL. |
| EFI_INVALID_PARAMETER | The Blt or PackageList was NULL. |
| EFI_INVALID_PARAMETER | Flags were invalid combination. |
| EFI_NOT_FOUND | The specified PackageList is not in the Database, or the stringid is not in the specified PackageList. |
Definition at line 348 of file HiiFont.h.
