include/android/system_fonts.h

/*
 * Copyright (C) 2018 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 system_fonts.h
 * @brief Provides the system font configurations.
 *
 * These APIs provides the list of system installed font files with additional metadata about the
 * font.
 *
 * The ASystemFontIterator_open method will give you an iterator which can iterate all system
 * installed font files as shown in the following example.
 *
 * \code{.cpp}
 *   ASystemFontIterator* iterator = ASystemFontIterator_open();
 *   ASystemFont* font = NULL;
 *
 *   while ((font = ASystemFontIterator_next(iterator)) != nullptr) {
 *       // Look if the font is your desired one.
 *       if (ASystemFont_getWeight(font) == 400 && !ASystemFont_isItalic(font)
 *           && ASystemFont_getLocale(font) == NULL) {
 *           break;
 *       }
 *       ASystemFont_close(font);
 *   }
 *   ASystemFontIterator_close(iterator);
 *
 *   int fd = open(ASystemFont_getFontFilePath(font), O_RDONLY);
 *   int collectionIndex = ASystemFont_getCollectionINdex(font);
 *   std::vector<std::pair<uint32_t, float>> variationSettings;
 *   for (size_t i = 0; i < ASystemFont_getAxisCount(font); ++i) {
 *       variationSettings.push_back(std::make_pair(
 *           ASystemFont_getAxisTag(font, i),
 *           ASystemFont_getAxisValue(font, i)));
 *   }
 *   ASystemFont_close(font);
 *
 *   // Use this font for your text rendering engine.
 *
 * \endcode
 *
 * Available since API level 29.
 */

#ifndef ANDROID_SYSTEM_FONTS_H
#define ANDROID_SYSTEM_FONTS_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. */
    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.
 *
 * ASystemFontIterator is an iterator for all available system font settings.
 * This iterator is not a thread-safe object. Do not pass this iterator to other threads.
 */
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.
 *
 * \return a pointer for a newly allocated iterator, nullptr on failure.
 */
ASystemFontIterator* _Nullable ASystemFontIterator_open() __INTRODUCED_IN(29);

/**
 * Close an opened system font iterator, freeing any related resources.
 *
 * \param iterator a pointer of an iterator for the system fonts. Do nothing if NULL is passed.
 */
void ASystemFontIterator_close(ASystemFontIterator* _Nullable iterator) __INTRODUCED_IN(29);

/**
 * Move to the next system font.
 *
 * \param iterator an iterator for the system fonts. Passing NULL is not allowed.
 * \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);

#endif // __ANDROID_API__ >= 29

__END_DECLS

#endif // ANDROID_SYSTEM_FONTS_H