Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit cb88a651 authored by Seigo Nonaka's avatar Seigo Nonaka
Browse files

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
parent 2d84dddc

include/android/font.h

0 → 100644
+281 −0
Original line number Diff line number Diff line 
/*

 * Copyright (C) 2019 The Android Open Source Project

 *

 * Licensed under the Apache License, Version 2.0 (the "License");

 * you may not use this file except in compliance with the License.

 * You may obtain a copy of the License at

 *

 *      http://www.apache.org/licenses/LICENSE-2.0

 *

 * Unless required by applicable law or agreed to in writing, software

 * distributed under the License is distributed on an "AS IS" BASIS,

 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

 * See the License for the specific language governing permissions and

 * limitations under the License.

 */



/**

 * @file font.h

 * @brief Provides some constants used in system_fonts.h or fonts_matcher.h

 *

 * Available since API level 29.

 */



#ifndef ANDROID_FONT_H

#define ANDROID_FONT_H



#include <stdbool.h>

#include <stddef.h>

#include <sys/cdefs.h>



/******************************************************************

 *

 * IMPORTANT NOTICE:

 *

 *   This file is part of Android's set of stable system headers

 *   exposed by the Android NDK (Native Development Kit).

 *

 *   Third-party source AND binary code relies on the definitions

 *   here to be FROZEN ON ALL UPCOMING PLATFORM RELEASES.

 *

 *   - DO NOT MODIFY ENUMS (EXCEPT IF YOU ADD NEW 32-BIT VALUES)

 *   - DO NOT MODIFY CONSTANTS OR FUNCTIONAL MACROS

 *   - DO NOT CHANGE THE SIGNATURE OF FUNCTIONS IN ANY WAY

 *   - DO NOT CHANGE THE LAYOUT OR SIZE OF STRUCTURES

 */



__BEGIN_DECLS



#if __ANDROID_API__ >= 29



enum {

    /** The minimum value fot the font weight value. */

    AFONT_WEIGHT_MIN = 0,



    /** A font weight value for the thin weight. */

    AFONT_WEIGHT_THIN = 100,



    /** A font weight value for the extra-light weight. */

    AFONT_WEIGHT_EXTRA_LIGHT = 200,



    /** A font weight value for the light weight. */

    AFONT_WEIGHT_LIGHT = 300,



    /** A font weight value for the normal weight. */

    AFONT_WEIGHT_NORMAL = 400,



    /** A font weight value for the medium weight. */

    AFONT_WEIGHT_MEDIUM = 500,



    /** A font weight value for the semi-bold weight. */

    AFONT_WEIGHT_SEMI_BOLD = 600,



    /** A font weight value for the bold weight. */

    AFONT_WEIGHT_BOLD = 700,



    /** A font weight value for the extra-bold weight. */

    AFONT_WEIGHT_EXTRA_BOLD = 800,



    /** A font weight value for the black weight. */

    AFONT_WEIGHT_BLACK = 900,



    /** The maximum value for the font weight value. */

    AFONT_WEIGHT_MAX = 1000

};



/**

 * AFont provides information of the single font configuration.

 */

struct AFont;



/**

 * Close an AFont.

 *

 * \param font a font returned by ASystemFontIterator_next or AFontMatchert_match.

 *        Do nothing if NULL is passed.

 */

void AFont_close(AFont* _Nullable font) __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 AFont_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 AFont_getFontFilePath(const AFont* _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 AFONT_WEIGHT_THIN}</td>

 *  </tr>

 *  <tr>

 *  <td align="center">200</td>

 *  <td align="center">Extra Light (Ultra Light)</td>

 *  <td align="center">{@link AFONT_WEIGHT_EXTRA_LIGHT}</td>

 *  </tr>

 *  <tr>

 *  <td align="center">300</td>

 *  <td align="center">Light</td>

 *  <td align="center">{@link AFONT_WEIGHT_LIGHT}</td>

 *  </tr>

 *  <tr>

 *  <td align="center">400</td>

 *  <td align="center">Normal (Regular)</td>

 *  <td align="center">{@link AFONT_WEIGHT_NORMAL}</td>

 *  </tr>

 *  <tr>

 *  <td align="center">500</td>

 *  <td align="center">Medium</td>

 *  <td align="center">{@link AFONT_WEIGHT_MEDIUM}</td>

 *  </tr>

 *  <tr>

 *  <td align="center">600</td>

 *  <td align="center">Semi Bold (Demi Bold)</td>

 *  <td align="center">{@link AFONT_WEIGHT_SEMI_BOLD}</td>

 *  </tr>

 *  <tr>

 *  <td align="center">700</td>

 *  <td align="center">Bold</td>

 *  <td align="center">{@link AFONT_WEIGHT_BOLD}</td>

 *  </tr>

 *  <tr>

 *  <td align="center">800</td>

 *  <td align="center">Extra Bold (Ultra Bold)</td>

 *  <td align="center">{@link AFONT_WEIGHT_EXTRA_BOLD}</td>

 *  </tr>

 *  <tr>

 *  <td align="center">900</td>

 *  <td align="center">Black (Heavy)</td>

 *  <td align="center">{@link AFONT_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 AFont_getWeight(const AFont* _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 AFont_isItalic(const AFont* _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 AFont_close() is called.

 *

 * \param font a font object. Passing NULL is not allowed.

 * \return a IETF BCP47 compliant language tag or nullptr if not available.

 */

const char* _Nullable AFont_getLocale(const AFont* _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 AFont_getCollectionIndex(const AFont* _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, AFont_getAxisCount returns 2 and AFont_getAxisTag

 * and AFont_getAxisValue will return following values.

 * \code{.cpp}

 *     AFont* font = AFontIterator_next(ite);

 *

 *     // Returns the number of axes

 *     AFont_getAxisCount(font);  // Returns 2

 *

 *     // Returns the tag-value pair for the first axis.

 *     AFont_getAxisTag(font, 0);  // Returns 'wght'(0x77676874)

 *     AFont_getAxisValue(font, 0);  // Returns 700.0

 *

 *     // Returns the tag-value pair for the second axis.

 *     AFont_getAxisTag(font, 1);  // Returns 'slnt'(0x736c6e74)

 *     AFont_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 AFont_getAxisCount(const AFont* _Nonnull font) __INTRODUCED_IN(29);





/**

 * Return an OpenType axis tag associated with the current font.

 *

 * See AFont_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 AFont_getAxisCount} is not allowed.

 * \return an OpenType axis tag value for the given font variation setting.

 */

uint32_t AFont_getAxisTag(const AFont* _Nonnull font, uint32_t axisIndex)

      __INTRODUCED_IN(29);



/**

 * Return an OpenType axis value associated with the current font.

 *

 * See AFont_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 AFont_getAxisValue(const AFont* _Nonnull font, uint32_t axisIndex)

      __INTRODUCED_IN(29);



#endif // __ANDROID_API__ >= 29



__END_DECLS



#endif // ANDROID_FONT_H

include/android/font_matcher.h

0 → 100644
+207 −0
Original line number Diff line number Diff line 
/*

 * Copyright (C) 2019 The Android Open Source Project

 *

 * Licensed under the Apache License, Version 2.0 (the "License");

 * you may not use this file except in compliance with the License.

 * You may obtain a copy of the License at

 *

 *      http://www.apache.org/licenses/LICENSE-2.0

 *

 * Unless required by applicable law or agreed to in writing, software

 * distributed under the License is distributed on an "AS IS" BASIS,

 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

 * See the License for the specific language governing permissions and

 * limitations under the License.

 */



/**

 * @file font_matcher.h

 * @brief Provides the font matching logic with various inputs.

 *

 * You can use this class for deciding what font is to be used for drawing text.

 *

 * A matcher is created from text style, locales and UI compatibility. The match function for

 * matcher object can be called multiple times until close function is called.

 *

 * Even if no font can render the given text, the match 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' };

 *  AFontMatcher* matcher = AFontMatcher_create("sans-serif");

 *  ASystemFont* font = AFontMatcher_match(text.data(), text.length(), &runLength);

 *  // runLength will be 1 and the font will points a valid font file.

 *  AFontMatcher_destroy(matcher);

 *

 *  // Querying font for CJK characters

 *  std::vector<uint16_t> text = { 0x9AA8 };

 *  AFontMatcher* matcher = AFontMatcher_create("sans-serif");

 *  AFontMatcher_setLocales(matcher, "zh-CN,ja-JP");

 *  ASystemFont* font = AFontMatcher_match(text.data(), text.length(), &runLength);

 *  // runLength will be 1 and the font will points a Simplified Chinese font.

 *  AFontMatcher_setLocales(matcher, "ja-JP,zh-CN");

 *  ASystemFont* font = AFontMatcher_match(text.data(), text.length(), &runLength);

 *  // runLength will be 1 and the font will points a Japanese font.

 *  AFontMatcher_destroy(matcher);

 *

 *  // Querying font for text/color emoji

 *  std::vector<uint16_t> text = { 0xD83D, 0xDC68, 0x200D, 0x2764, 0xFE0F, 0x200D, 0xD83D, 0xDC68 };

 *  AFontMatcher* matcher = AFontMatcher_create("sans-serif");

 *  ASystemFont* font = AFontMatcher_match(text.data(), text.length(), &runLength);

 *  // runLength will be 8 and the font will points a color emoji font.

 *  AFontMatcher_destroy(matcher);

 *

 *  // Mixture of multiple script of characters.

 *  // 0x05D0 is a Hebrew character and 0x0E01 is a Thai character.

 *  std::vector<uint16_t> text = { 0x05D0, 0x0E01 };

 *  AFontMatcher* matcher = AFontMatcher_create("sans-serif");

 *  ASystemFont* font = AFontMatcher_match(text.data(), text.length(), &runLength);

 *  // runLength will be 1 and the font will points a Hebrew font.

 *  AFontMatcher_destroy(matcher);

 * \endcode

 *

 * Available since API level 29.

 */



#ifndef ANDROID_FONT_MATCHER_H

#define ANDROID_FONT_MATCHER_H



#include <stdbool.h>

#include <stddef.h>

#include <sys/cdefs.h>



#include <android/font.h>



/******************************************************************

 *

 * IMPORTANT NOTICE:

 *

 *   This file is part of Android's set of stable system headers

 *   exposed by the Android NDK (Native Development Kit).

 *

 *   Third-party source AND binary code relies on the definitions

 *   here to be FROZEN ON ALL UPCOMING PLATFORM RELEASES.

 *

 *   - DO NOT MODIFY ENUMS (EXCEPT IF YOU ADD NEW 32-BIT VALUES)

 *   - DO NOT MODIFY CONSTANTS OR FUNCTIONAL MACROS

 *   - DO NOT CHANGE THE SIGNATURE OF FUNCTIONS IN ANY WAY

 *   - DO NOT CHANGE THE LAYOUT OR SIZE OF STRUCTURES

 */



__BEGIN_DECLS



#if __ANDROID_API__ >= 29



enum {

    /** A family variant value for the system default variant. */

    AFAMILY_VARIANT_DEFAULT = 0,



    /**

     * A family variant value for the compact font family variant.

     *

     * The compact font family has Latin-based vertical metrics.

     */

    AFAMILY_VARIANT_COMPACT = 1,



    /**

     * A family variant value for the elegant font family variant.

     *

     * The elegant font family may have larger vertical metrics than Latin font.

     */

    AFAMILY_VARIANT_ELEGANT = 2,

};



/**

 * AFontMatcher performs match operation on given parameters and available font files.

 * This matcher is not a thread-safe object. Do not pass this matcher to other threads.

 */

struct AFontMatcher;



/**

 * Select the best font from given parameters.

 *

 */



/**

 * Creates a new AFontMatcher object

 */

AFontMatcher* _Nonnull AFontMatcher_create() __INTRODUCED_IN(29);



/**

 * Destroy the matcher object.

 *

 * \param matcher a matcher object. Passing NULL is not allowed.

 */

void AFontMatcher_destroy(AFontMatcher* _Nonnull matcher) __INTRODUCED_IN(29);



/**

 * Set font style to matcher.

 *

 * If this function is not called, the matcher performs with {@link ASYSTEM_FONT_WEIGHT_NORMAL}

 * with non-italic style.

 *

 * \param matcher a matcher object. Passing NULL is not allowed.

 * \param weight a font weight value. Only from 0 to 1000 value is valid

 * \param italic true if italic, otherwise false.

 */

void AFontMatcher_setStyle(

        AFontMatcher* _Nonnull matcher,

        uint16_t weight,

        bool italic) __INTRODUCED_IN(29);



/**

 * Set font locales to matcher.

 *

 * If this function is not called, the matcher performs with empty locale list.

 *

 * \param matcher a matcher object. Passing NULL is not allowed.

 * \param languageTags a null character terminated comma separated IETF BCP47 compliant language

 *                     tags.

 */

void AFontMatcher_setLocales(

        AFontMatcher* _Nonnull matcher,

        const char* _Nonnull languageTags) __INTRODUCED_IN(29);



/**

 * Set family variant to matcher.

 *

 * If this function is not called, the matcher performs with {@link AFAMILY_VARIANT_DEFAULT}.

 *

 * \param matcher a matcher object. Passing NULL is not allowed.

 * \param familyVariant Must be one of {@link AFAMILY_VARIANT_DEFAULT},

 *                      {@link AFAMILY_VARIANT_COMPACT} or {@link AFAMILY_VARIANT_ELEGANT} is valid.

 */

void AFontMatcher_setFamilyVariant(

        AFontMatcher* _Nonnull matcher,

        uint32_t familyVariant) __INTRODUCED_IN(29);



/**

 * Performs the matching from the generic font family for the text and select one font.

 *

 * 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.

 *

 * \param matcher a matcher object. Passing NULL is not allowed.

 * \param familyName a null character terminated font family name

 * \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.

 */

AFont* _Nonnull AFontMatcher_match(

        const AFontMatcher* _Nonnull matcher,

        const char* _Nonnull familyName,

        const uint16_t* _Nonnull text,

        const uint32_t textLength,

        uint32_t* _Nullable runLengthOut) __INTRODUCED_IN(29);



#endif // __ANDROID_API__ >= 29



__END_DECLS



#endif // ANDROID_FONT_MATCHER_H

include/android/system_fonts.h

+3 −288

File changed.

Preview size limit exceeded, changes collapsed.