/** @file\r
The file provides services to retrieve font information.\r
- \r
- Copyright (c) 2006 - 2008, Intel Corporation\r
- All rights reserved. This program and the accompanying materials \r
- are licensed and made available under the terms and conditions of the BSD License \r
- which accompanies this distribution. The full text of the license may be found at \r
- http://opensource.org/licenses/bsd-license.php \r
\r
- THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
- WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
+Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
+SPDX-License-Identifier: BSD-2-Clause-Patent\r
+\r
+ @par Revision Reference:\r
+ This Protocol was introduced in UEFI Specification 2.1.\r
\r
**/\r
\r
\r
typedef struct _EFI_HII_FONT_PROTOCOL EFI_HII_FONT_PROTOCOL;\r
\r
-typedef VOID *EFI_FONT_HANDLE;\r
+typedef VOID *EFI_FONT_HANDLE;\r
\r
///\r
-/// EFI_HII_OUT_FLAGS\r
-/// \r
-typedef UINT32 EFI_HII_OUT_FLAGS;\r
-\r
-#define EFI_HII_OUT_FLAG_CLIP 0x00000001\r
-#define EFI_HII_OUT_FLAG_WRAP 0x00000002\r
-#define EFI_HII_OUT_FLAG_CLIP_CLEAN_Y 0x00000004\r
-#define EFI_HII_OUT_FLAG_CLIP_CLEAN_X 0x00000008\r
-#define EFI_HII_OUT_FLAG_TRANSPARENT 0x00000010\r
-#define EFI_HII_IGNORE_IF_NO_GLYPH 0x00000020\r
-#define EFI_HII_IGNORE_LINE_BREAK 0x00000040\r
-#define EFI_HII_DIRECT_TO_SCREEN 0x00000080\r
+/// EFI_HII_OUT_FLAGS.\r
+///\r
+typedef UINT32 EFI_HII_OUT_FLAGS;\r
+\r
+#define EFI_HII_OUT_FLAG_CLIP 0x00000001\r
+#define EFI_HII_OUT_FLAG_WRAP 0x00000002\r
+#define EFI_HII_OUT_FLAG_CLIP_CLEAN_Y 0x00000004\r
+#define EFI_HII_OUT_FLAG_CLIP_CLEAN_X 0x00000008\r
+#define EFI_HII_OUT_FLAG_TRANSPARENT 0x00000010\r
+#define EFI_HII_IGNORE_IF_NO_GLYPH 0x00000020\r
+#define EFI_HII_IGNORE_LINE_BREAK 0x00000040\r
+#define EFI_HII_DIRECT_TO_SCREEN 0x00000080\r
\r
/**\r
Definition of EFI_HII_ROW_INFO.\r
///\r
/// The index of the first character in the string which is displayed on the line.\r
///\r
- UINTN StartIndex;\r
+ UINTN StartIndex;\r
///\r
/// The index of the last character in the string which is displayed on the line.\r
- /// If this is the same as StartIndex, then no characters are displayed. \r
+ /// If this is the same as StartIndex, then no characters are displayed.\r
///\r
- UINTN EndIndex;\r
- UINTN LineHeight; ///< The height of the line, in pixels.\r
- UINTN LineWidth; ///< The width of the text on the line, in pixels.\r
- \r
+ UINTN EndIndex;\r
+ UINTN LineHeight; ///< The height of the line, in pixels.\r
+ UINTN LineWidth; ///< The width of the text on the line, in pixels.\r
+\r
///\r
- /// The number of pixels above the bottom of the row of the font baseline or 0 if none. \r
+ /// The font baseline offset in pixels from the bottom of the row, or 0 if none.\r
///\r
- UINTN BaselineOffset;\r
+ UINTN BaselineOffset;\r
} EFI_HII_ROW_INFO;\r
\r
///\r
/// Font info flag. All flags (FONT, SIZE, STYLE, and COLOR) are defined.\r
/// They are defined as EFI_FONT_INFO_***\r
///\r
-typedef UINT32 EFI_FONT_INFO_MASK;\r
+typedef UINT32 EFI_FONT_INFO_MASK;\r
\r
#define EFI_FONT_INFO_SYS_FONT 0x00000001\r
#define EFI_FONT_INFO_SYS_SIZE 0x00000002\r
\r
//\r
// EFI_FONT_INFO\r
-// \r
+//\r
typedef struct {\r
- EFI_HII_FONT_STYLE FontStyle;\r
- UINT16 FontSize; ///< character cell height in pixels\r
- CHAR16 FontName[1];\r
+ EFI_HII_FONT_STYLE FontStyle;\r
+ UINT16 FontSize; ///< character cell height in pixels\r
+ CHAR16 FontName[1];\r
} EFI_FONT_INFO;\r
\r
/**\r
Describes font output-related information.\r
\r
- This structure is used for describing the way a string\r
+ This structure is used for describing the way in which a string\r
should be rendered in a particular font. FontInfo specifies the\r
- basic font information, and ForegroundColor and BackgroundColor\r
- specify the color in which the characters should be displayed. The flags\r
+ basic font information and ForegroundColor and BackgroundColor\r
+ specify the color in which they should be displayed. The flags\r
in FontInfoMask describe where the system default should be\r
supplied instead of the specified information. The flags also\r
describe what options can be used to make a match between the\r
font requested and the font available.\r
**/\r
typedef struct _EFI_FONT_DISPLAY_INFO {\r
- EFI_GRAPHICS_OUTPUT_BLT_PIXEL ForegroundColor;\r
- EFI_GRAPHICS_OUTPUT_BLT_PIXEL BackgroundColor;\r
- EFI_FONT_INFO_MASK FontInfoMask;\r
- EFI_FONT_INFO FontInfo; \r
+ EFI_GRAPHICS_OUTPUT_BLT_PIXEL ForegroundColor;\r
+ EFI_GRAPHICS_OUTPUT_BLT_PIXEL BackgroundColor;\r
+ EFI_FONT_INFO_MASK FontInfoMask;\r
+ EFI_FONT_INFO FontInfo;\r
} EFI_FONT_DISPLAY_INFO;\r
\r
/**\r
\r
This function renders a string to a bitmap or the screen using\r
the specified font, color and options. It either draws the\r
- string and glyphs on an existing bitmap, allocates a new bitmap\r
+ string and glyphs on an existing bitmap, allocates a new bitmap,\r
or uses the screen. The strings can be clipped or wrapped.\r
Optionally, the function also returns the information about each\r
row and the character position on that row. If\r
outside the bounding box specified by Width and Height are\r
ignored. The information in the RowInfoArray only describes\r
characters which are at least partially displayed. For the final\r
- row, the LineHeight and BaseLine may describe pixels which are\r
+ row, the LineHeight and BaseLine may describe pixels that are\r
outside the limit specified by Height (unless\r
EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is specified) even though those\r
pixels were not drawn. The LineWidth may describe pixels which\r
will use the pixel value from Blt. This flag cannot be used if\r
Blt is NULL upon entry. If EFI_HII_IGNORE_IF_NO_GLYPH is set,\r
then characters which have no glyphs are not drawn. Otherwise,\r
- they are replaced with Unicode character 0xFFFD (REPLACEMENT\r
+ they are replaced with Unicode character code 0xFFFD (REPLACEMENT\r
CHARACTER). If EFI_HII_IGNORE_LINE_BREAK is set, then explicit\r
line break characters will be ignored. If\r
EFI_HII_DIRECT_TO_SCREEN is set, then the string will be written\r
\r
@param Flags Describes how the string is to be drawn.\r
\r
- @param String Points to the null-terminated string to be \r
+ @param String Points to the null-terminated string to be\r
\r
@param StringInfo Points to the string output information,\r
including the color and font. If NULL, then\r
containing row information and\r
RowInfoArraySize will be updated to contain\r
the number of elements. This array describes\r
- the characters which were at least partially\r
+ the characters that were at least partially\r
drawn and the heights of the rows. It is the\r
caller's responsibility to free this buffer.\r
\r
overlap.\r
\r
@retval EFI_SUCCESS The string was successfully updated.\r
- \r
+\r
@retval EFI_OUT_OF_RESOURCES Unable to allocate an output buffer for RowInfoArray or Blt.\r
- \r
+\r
@retval EFI_INVALID_PARAMETER The String or Blt was NULL.\r
\r
@retval EFI_INVALID_PARAMETER Flags were invalid combination.\r
OUT EFI_HII_ROW_INFO **RowInfoArray OPTIONAL,\r
OUT UINTN *RowInfoArraySize OPTIONAL,\r
OUT UINTN *ColumnInfoArray OPTIONAL\r
-);\r
-\r
-\r
+ );\r
\r
/**\r
\r
can be drawn transparently or opaquely. The function can also\r
return information about each row and each character's\r
position on the row. If EFI_HII_OUT_FLAG_CLIP is set, then\r
- text will be formatted only based on explicit line breaks and\r
- all pixels which would lie outside the bounding box specified\r
+ text will be formatted based only on explicit line breaks, and\r
+ all pixels that would lie outside the bounding box specified\r
by Width and Height are ignored. The information in the\r
RowInfoArray only describes characters which are at least\r
partially displayed. For the final row, the LineHeight and\r
EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is set, then it modifies the\r
behavior of EFI_HII_OUT_FLAG_CLIP so that if a row's bottom\r
most pixel cannot fit, then it will not be drawn at all. This\r
- flag requires that EFI_HII_OUT_FLAG_CLIP be set. Draft for\r
- Review HII Protocols Version 2.1 November 3, 2006 1285 If\r
+ flag requires that EFI_HII_OUT_FLAG_CLIP be set. If\r
EFI_HII_OUT_FLAG_WRAP is set, then text will be wrapped at the\r
right-most line-break opportunity prior to a character whose\r
right-most extent would exceed Width. If no line-break\r
use the pixel value from Blt. This flag cannot be used if Blt\r
is NULL upon entry. If EFI_HII_IGNORE_IF_NO_GLYPH is set, then\r
characters which have no glyphs are not drawn. Otherwise, they\r
- are replaced with Unicode character 0xFFFD (REPLACEMENT\r
+ are replaced with Unicode character code 0xFFFD (REPLACEMENT\r
CHARACTER). If EFI_HII_IGNORE_LINE_BREAK is set, then explicit\r
line break characters will be ignored. If\r
EFI_HII_DIRECT_TO_SCREEN is set, then the string will be\r
\r
@param Flags Describes how the string is to be drawn.\r
\r
- @param PackageList \r
+ @param PackageList\r
The package list in the HII database to\r
search for the specified string.\r
\r
@retval EFI_OUT_OF_RESOURCES Unable to allocate an output\r
buffer for RowInfoArray or Blt.\r
\r
- @retval EFI_INVALID_PARAMETER The String or Blt or Height or\r
+ @retval EFI_INVALID_PARAMETER The String, or Blt, or Height, or\r
Width was NULL.\r
@retval EFI_INVALID_PARAMETER The Blt or PackageList was NULL.\r
@retval EFI_INVALID_PARAMETER Flags were invalid combination.\r
- @retval EFI_NOT_FOUND The specified PackageList is not in the Database \r
- or the stringid is not in the specified PackageList. \r
+ @retval EFI_NOT_FOUND The specified PackageList is not in the Database,\r
+ or the stringid is not in the specified PackageList.\r
\r
**/\r
typedef\r
OUT EFI_HII_ROW_INFO **RowInfoArray OPTIONAL,\r
OUT UINTN *RowInfoArraySize OPTIONAL,\r
OUT UINTN *ColumnInfoArray OPTIONAL\r
-);\r
-\r
+ );\r
\r
/**\r
\r
\r
@param This A pointer to the EFI_HII_FONT_PROTOCOL instance.\r
\r
- @param Char Character to retrieve.\r
+ @param Char The character to retrieve.\r
\r
@param StringInfo Points to the string font and color\r
information or NULL if the string should use\r
the default system font and color.\r
\r
- @param Blt Thus must point to a NULL on entry. A buffer will\r
+ @param Blt This must point to a NULL on entry. A buffer will\r
be allocated to hold the output and the pointer\r
updated on exit. It is the caller's responsibility\r
to free this buffer.\r
\r
- @param Baseline Number of pixels from the bottom of the bitmap\r
+ @param Baseline The number of pixels from the bottom of the bitmap\r
to the baseline.\r
\r
\r
- @retval EFI_SUCCESS Glyph bitmap created.\r
+ @retval EFI_SUCCESS The glyph bitmap created.\r
\r
@retval EFI_OUT_OF_RESOURCES Unable to allocate the output buffer Blt.\r
\r
@retval EFI_WARN_UNKNOWN_GLYPH The glyph was unknown and was\r
replaced with the glyph for\r
- Unicode character 0xFFFD.\r
+ Unicode character code 0xFFFD.\r
\r
- @retval EFI_INVALID_PARAMETER Blt is NULL or Width is NULL or\r
+ @retval EFI_INVALID_PARAMETER Blt is NULL, or Width is NULL, or\r
Height is NULL\r
\r
\r
IN CONST EFI_FONT_DISPLAY_INFO *StringInfo,\r
OUT EFI_IMAGE_OUTPUT **Blt,\r
OUT UINTN *Baseline OPTIONAL\r
-);\r
+ );\r
\r
/**\r
\r
to NULL if there are no more matching fonts.\r
\r
@param StringInfoIn Upon entry, points to the font to return\r
- information about. If NULL, then the information about the system default \r
- font will be returned.\r
+ information about. If NULL, then the information\r
+ about the system default font will be returned.\r
\r
- @param StringInfoOut Upon return, contains the matching\r
- font's information. If NULL, then no\r
- information is returned.\r
+ @param StringInfoOut Upon return, contains the matching font's information.\r
+ If NULL, then no information is returned. This buffer\r
+ is allocated with a call to the Boot Service AllocatePool().\r
+ It is the caller's responsibility to call the Boot\r
+ Service FreePool() when the caller no longer requires\r
+ the contents of StringInfoOut.\r
\r
@param String Points to the string which will be tested to\r
determine if all characters are available. If\r
NULL, then any font is acceptable.\r
- \r
+\r
@retval EFI_SUCCESS Matching font returned successfully.\r
- \r
+\r
@retval EFI_NOT_FOUND No matching font was found.\r
\r
@retval EFI_OUT_OF_RESOURCES There were insufficient resources to complete the request.\r
- \r
+\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_HII_GET_FONT_INFO)(\r
IN CONST EFI_HII_FONT_PROTOCOL *This,\r
IN OUT EFI_FONT_HANDLE *FontHandle,\r
- IN CONST EFI_FONT_DISPLAY_INFO *StringInfoIn, OPTIONAL\r
+ IN CONST EFI_FONT_DISPLAY_INFO *StringInfoIn OPTIONAL,\r
OUT EFI_FONT_DISPLAY_INFO **StringInfoOut,\r
IN CONST EFI_STRING String OPTIONAL\r
-);\r
+ );\r
\r
///\r
/// The protocol provides the service to retrieve the font informations.\r
///\r
struct _EFI_HII_FONT_PROTOCOL {\r
- EFI_HII_STRING_TO_IMAGE StringToImage;\r
- EFI_HII_STRING_ID_TO_IMAGE StringIdToImage;\r
- EFI_HII_GET_GLYPH GetGlyph;\r
- EFI_HII_GET_FONT_INFO GetFontInfo;\r
+ EFI_HII_STRING_TO_IMAGE StringToImage;\r
+ EFI_HII_STRING_ID_TO_IMAGE StringIdToImage;\r
+ EFI_HII_GET_GLYPH GetGlyph;\r
+ EFI_HII_GET_FONT_INFO GetFontInfo;\r
};\r
\r
-extern EFI_GUID gEfiHiiFontProtocolGuid;\r
-\r
+extern EFI_GUID gEfiHiiFontProtocolGuid;\r
\r
#endif\r
-\r