Reorganize system font APIs
This CL reorganizes the system font related APIs with following things:
- Move match function from system_fonts.h to new header file.
The matching logic is not only for system fonts. The custom font or
custom fallback Typeface can be a target of this matcher.
- Introduce new struct AFontMatcher for keeping matching rules.
This is for future extensibility. We may add another parameter for
querying fonts in future.
- Renamce ASystemFont to AFont and moved to new header file.
This is mainly because for future improvements.
Currently we don't have any plan for doing this in Q timeline, but the
matcher object can be used for Java Typeface object via JNI. For
example, build Typeface in Java and pass down to JNI and query the font
for the passed Typeface.
Bug: 129559385
Test: TEMPORARY_DISABLE_PATH_RESTRICTIONS=true m ndk-docs
Test: atest CtsGraphicsTestCases:android.graphics.fonts
Change-Id: I6c593d9597b1f1ff71eaea6ecf7992890d635480
diff --git a/include/android/system_fonts.h b/include/android/system_fonts.h
index 38f036e..3facf82 100644
--- a/include/android/system_fonts.h
+++ b/include/android/system_fonts.h
@@ -62,6 +62,8 @@
#include <stddef.h>
#include <sys/cdefs.h>
+#include <android/font.h>
+
/******************************************************************
*
* IMPORTANT NOTICE:
@@ -82,41 +84,6 @@
#if __ANDROID_API__ >= 29
-enum {
- /** The minimum value fot the font weight value. */
- ASYSTEM_FONT_WEIGHT_MIN = 0,
-
- /** A font weight value for the thin weight. */
- ASYSTEM_FONT_WEIGHT_THIN = 100,
-
- /** A font weight value for the extra-light weight. */
- ASYSTEM_FONT_WEIGHT_EXTRA_LIGHT = 200,
-
- /** A font weight value for the light weight. */
- ASYSTEM_FONT_WEIGHT_LIGHT = 300,
-
- /** A font weight value for the normal weight. */
- ASYSTEM_FONT_WEIGHT_NORMAL = 400,
-
- /** A font weight value for the medium weight. */
- ASYSTEM_FONT_WEIGHT_MEDIUM = 500,
-
- /** A font weight value for the semi-bold weight. */
- ASYSTEM_FONT_WEIGHT_SEMI_BOLD = 600,
-
- /** A font weight value for the bold weight. */
- ASYSTEM_FONT_WEIGHT_BOLD = 700,
-
- /** A font weight value for the extra-bold weight. */
- ASYSTEM_FONT_WEIGHT_EXTRA_BOLD = 800,
-
- /** A font weight value for the black weight. */
- ASYSTEM_FONT_WEIGHT_BLACK = 900,
-
- /** The maximum value for the font weight value. */
- ASYSTEM_FONT_WEIGHT_MAX = 1000
-};
-
/**
* ASystemFontIterator provides access to the system font configuration.
*
@@ -126,11 +93,6 @@
struct ASystemFontIterator;
/**
- * ASystemFont provides information of the single system font configuration.
- */
-struct ASystemFont;
-
-/**
* Create a system font iterator.
*
* Use ASystemFont_close() to close the iterator.
@@ -153,254 +115,7 @@
* \return a font. If no more font is available, returns nullptr. You need to release the returned
* font by ASystemFont_close when it is no longer needed.
*/
-ASystemFont* _Nullable ASystemFontIterator_next(ASystemFontIterator* _Nonnull iterator) __INTRODUCED_IN(29);
-
-/**
- * Close an ASystemFont returned by ASystemFontIterator_next.
- *
- * \param font a font returned by ASystemFontIterator_next or ASystemFont_matchFamilyStyleCharacter.
- * Do nothing if NULL is passed.
- */
-void ASystemFont_close(ASystemFont* _Nullable font) __INTRODUCED_IN(29);
-
-
-/**
- * Select the best font from given parameters.
- *
- * Only generic font families are supported.
- * For more information about generic font families, read [W3C spec](https://www.w3.org/TR/css-fonts-4/#generic-font-families)
- *
- * Even if no font can render the given text, this function will return a non-null result for
- * drawing Tofu character.
- *
- * Examples:
- * \code{.cpp}
- * // Simple font query for the ASCII character.
- * std::vector<uint16_t> text = { 'A' };
- * ASystemFont font = ASystemFont_matchFamilyStyleCharacter(
- * "sans", 400, false, "en-US", text.data(), text.length(), &runLength);
- * // runLength will be 1 and the font will points a valid font file.
- *
- * // Querying font for CJK characters
- * std::vector<uint16_t> text = { 0x9AA8 };
- * ASystemFont font = ASystemFont_matchFamilyStyleCharacter(
- * "sans", 400, false, "zh-CN,ja-JP", text.data(), text.length(), &runLength);
- * // runLength will be 1 and the font will points a Simplified Chinese font.
- * ASystemFont font = ASystemFont_matchFamilyStyleCharacter(
- * "sans", 400, false, "ja-JP,zh-CN", text.data(), text.length(), &runLength);
- * // runLength will be 1 and the font will points a Japanese font.
- *
- * // Querying font for text/color emoji
- * std::vector<uint16_t> text = { 0xD83D, 0xDC68, 0x200D, 0x2764, 0xFE0F, 0x200D, 0xD83D, 0xDC68 };
- * ASystemFont font = ASystemFont_matchFamilyStyleCharacter(
- * "sans", 400, false, "en-US", text.data(), text.length(), &runLength);
- * // runLength will be 8 and the font will points a color emoji font.
- *
- * // Mixture of multiple script of characters.
- * // 0x05D0 is a Hebrew character and 0x0E01 is a Thai character.
- * std::vector<uint16_t> text = { 0x05D0, 0x0E01 };
- * ASystemFont font = ASystemFont_matchFamilyStyleCharacter(
- * "sans", 400, false, "en-US", text.data(), text.length(), &runLength);
- * // runLength will be 1 and the font will points a Hebrew font.
- * \endcode
- *
- * \param familyName a null character terminated font family name
- * \param weight a font weight value. Only from 0 to 1000 value is valid
- * \param italic true if italic, otherwise false.
- * \param languageTags a null character terminated comma separated IETF BCP47 compliant language
- * tags.
- * \param text a UTF-16 encoded text buffer to be rendered. Do not pass empty string.
- * \param textLength a length of the given text buffer. This must not be zero.
- * \param runLengthOut if not null, the font run length will be filled.
- * \return a font to be used for given text and params. You need to release the returned font by
- * ASystemFont_close when it is no longer needed.
- */
-ASystemFont* _Nonnull ASystemFont_matchFamilyStyleCharacter(
- const char* _Nonnull familyName,
- uint16_t weight,
- bool italic,
- const char* _Nonnull languageTags,
- const uint16_t* _Nonnull text,
- uint32_t textLength,
- uint32_t* _Nullable runLengthOut) __INTRODUCED_IN(29);
-
-/**
- * Return an absolute path to the current font file.
- *
- * Here is a list of font formats returned by this method:
- * <ul>
- * <li>OpenType</li>
- * <li>OpenType Font Collection</li>
- * <li>TrueType</li>
- * <li>TrueType Collection</li>
- * </ul>
- * The file extension could be one of *.otf, *.ttf, *.otc or *.ttc.
- *
- * The font file returned is guaranteed to be opend with O_RDONLY.
- * Note that the returned pointer is valid until ASystemFont_close() is called for the given font.
- *
- * \param font a font object. Passing NULL is not allowed.
- * \return a string of the font file path.
- */
-const char* _Nonnull ASystemFont_getFontFilePath(const ASystemFont* _Nonnull font) __INTRODUCED_IN(29);
-
-/**
- * Return a weight value associated with the current font.
- *
- * The weight values are positive and less than or equal to 1000.
- * Here are pairs of the common names and their values.
- * <p>
- * <table>
- * <tr>
- * <th align="center">Value</th>
- * <th align="center">Name</th>
- * <th align="center">NDK Definition</th>
- * </tr>
- * <tr>
- * <td align="center">100</td>
- * <td align="center">Thin</td>
- * <td align="center">{@link ASYSTEM_FONT_WEIGHT_THIN}</td>
- * </tr>
- * <tr>
- * <td align="center">200</td>
- * <td align="center">Extra Light (Ultra Light)</td>
- * <td align="center">{@link ASYSTEM_FONT_WEIGHT_EXTRA_LIGHT}</td>
- * </tr>
- * <tr>
- * <td align="center">300</td>
- * <td align="center">Light</td>
- * <td align="center">{@link ASYSTEM_FONT_WEIGHT_LIGHT}</td>
- * </tr>
- * <tr>
- * <td align="center">400</td>
- * <td align="center">Normal (Regular)</td>
- * <td align="center">{@link ASYSTEM_FONT_WEIGHT_NORMAL}</td>
- * </tr>
- * <tr>
- * <td align="center">500</td>
- * <td align="center">Medium</td>
- * <td align="center">{@link ASYSTEM_FONT_WEIGHT_MEDIUM}</td>
- * </tr>
- * <tr>
- * <td align="center">600</td>
- * <td align="center">Semi Bold (Demi Bold)</td>
- * <td align="center">{@link ASYSTEM_FONT_WEIGHT_SEMI_BOLD}</td>
- * </tr>
- * <tr>
- * <td align="center">700</td>
- * <td align="center">Bold</td>
- * <td align="center">{@link ASYSTEM_FONT_WEIGHT_BOLD}</td>
- * </tr>
- * <tr>
- * <td align="center">800</td>
- * <td align="center">Extra Bold (Ultra Bold)</td>
- * <td align="center">{@link ASYSTEM_FONT_WEIGHT_EXTRA_BOLD}</td>
- * </tr>
- * <tr>
- * <td align="center">900</td>
- * <td align="center">Black (Heavy)</td>
- * <td align="center">{@link ASYSTEM_FONT_WEIGHT_BLACK}</td>
- * </tr>
- * </table>
- * </p>
- * Note that the weight value may fall in between above values, e.g. 250 weight.
- *
- * For more information about font weight, read [OpenType usWeightClass](https://docs.microsoft.com/en-us/typography/opentype/spec/os2#usweightclass)
- *
- * \param font a font object. Passing NULL is not allowed.
- * \return a positive integer less than or equal to {@link ASYSTEM_FONT_MAX_WEIGHT} is returned.
- */
-uint16_t ASystemFont_getWeight(const ASystemFont* _Nonnull font) __INTRODUCED_IN(29);
-
-/**
- * Return true if the current font is italic, otherwise returns false.
- *
- * \param font a font object. Passing NULL is not allowed.
- * \return true if italic, otherwise false.
- */
-bool ASystemFont_isItalic(const ASystemFont* _Nonnull font) __INTRODUCED_IN(29);
-
-/**
- * Return a IETF BCP47 compliant language tag associated with the current font.
- *
- * For information about IETF BCP47, read [Locale.forLanguageTag(java.lang.String)](https://developer.android.com/reference/java/util/Locale.html#forLanguageTag(java.lang.String)")
- *
- * Note that the returned pointer is valid until ASystemFont_close() is called.
- *
- * \param font a font object. Passing NULL is not allowed.
- * \return a IETF BCP47 compliant langauge tag or nullptr if not available.
- */
-const char* _Nullable ASystemFont_getLocale(const ASystemFont* _Nonnull font) __INTRODUCED_IN(29);
-
-/**
- * Return a font collection index value associated with the current font.
- *
- * In case the target font file is a font collection (e.g. .ttc or .otc), this
- * returns a non-negative value as an font offset in the collection. This
- * always returns 0 if the target font file is a regular font.
- *
- * \param font a font object. Passing NULL is not allowed.
- * \return a font collection index.
- */
-size_t ASystemFont_getCollectionIndex(const ASystemFont* _Nonnull font) __INTRODUCED_IN(29);
-
-/**
- * Return a count of font variation settings associated with the current font
- *
- * The font variation settings are provided as multiple tag-values pairs.
- *
- * For example, bold italic font may have following font variation settings:
- * 'wght' 700, 'slnt' -12
- * In this case, ASystemFont_getAxisCount returns 2 and ASystemFont_getAxisTag
- * and ASystemFont_getAxisValue will return following values.
- * \code{.cpp}
- * ASystemFont* font = ASystemFontIterator_next(ite);
- *
- * // Returns the number of axes
- * ASystemFont_getAxisCount(font); // Returns 2
- *
- * // Returns the tag-value pair for the first axis.
- * ASystemFont_getAxisTag(font, 0); // Returns 'wght'(0x77676874)
- * ASystemFont_getAxisValue(font, 0); // Returns 700.0
- *
- * // Returns the tag-value pair for the second axis.
- * ASystemFont_getAxisTag(font, 1); // Returns 'slnt'(0x736c6e74)
- * ASystemFont_getAxisValue(font, 1); // Returns -12.0
- * \endcode
- *
- * For more information about font variation settings, read [Font Variations Table](https://docs.microsoft.com/en-us/typography/opentype/spec/fvar)
- *
- * \param font a font object. Passing NULL is not allowed.
- * \return a number of font variation settings.
- */
-size_t ASystemFont_getAxisCount(const ASystemFont* _Nonnull font) __INTRODUCED_IN(29);
-
-
-/**
- * Return an OpenType axis tag associated with the current font.
- *
- * See ASystemFont_getAxisCount for more details.
- *
- * \param font a font object. Passing NULL is not allowed.
- * \param axisIndex an index to the font variation settings. Passing value larger than or
- * equal to {@link ASystemFont_getAxisCount} is not allowed.
- * \return an OpenType axis tag value for the given font variation setting.
- */
-uint32_t ASystemFont_getAxisTag(const ASystemFont* _Nonnull font, uint32_t axisIndex)
- __INTRODUCED_IN(29);
-
-/**
- * Return an OpenType axis value associated with the current font.
- *
- * See ASystemFont_getAxisCount for more details.
- *
- * \param font a font object. Passing NULL is not allowed.
- * \param axisIndex an index to the font variation settings. Passing value larger than or
- * equal to {@link ASYstemFont_getAxisCount} is not allwed.
- * \return a float value for the given font variation setting.
- */
-float ASystemFont_getAxisValue(const ASystemFont* _Nonnull font, uint32_t axisIndex)
- __INTRODUCED_IN(29);
+AFont* _Nullable ASystemFontIterator_next(ASystemFontIterator* _Nonnull iterator) __INTRODUCED_IN(29);
#endif // __ANDROID_API__ >= 29