// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

library fuchsia.fonts;

using fuchsia.intl;
using fuchsia.mem;

/// The maximum length of a font family name.
const uint32 MAX_FAMILY_NAME_LENGTH = 128;

/// The maximum number of code points allowed in a typeface query.
const uint32 MAX_FACE_QUERY_CODE_POINTS = 128;

/// The maximum number of preferred languages allowed in a typeface query.
const uint32 MAX_FACE_QUERY_LANGUAGES = 8;

/// The maximum number of styles that will be returned for a font family.
const uint32 MAX_FAMILY_STYLES = 300;

/// The name of a family of fonts.
///
/// Examples: "Roboto", "Noto Serif".
struct FamilyName {
    /// The characters that make up the name.
    string:MAX_FAMILY_NAME_LENGTH name;
};

/// Boolean flags for `TypefaceRequest`.
bits TypefaceRequestFlags : uint32 {
    /// Disables font family fallback. The service won't try to search the fallback font set if the
    /// requested font family doesn't exist or if it doesn't contain the requested code point.
    EXACT_FAMILY = 0x00000001;

    /// Disables approximate style matching. The service will only return a face that matches the
    /// requested style exactly. For example, there will be no substitutions of "medium" for a
    /// requested "semi-bold" weight, or "oblique" for a requested "italic" slant.
    EXACT_STYLE = 0x00000002;
};

/// Options for what the font server should do if the client requests a typeface that is not yet
/// cached.
enum CacheMissPolicy {
    /// The server will attempt to load the uncached typeface before providing a response. This is
    /// the *default* behavior.
    ///
    /// This option is not recommended for synchronous clients that block rendering while waiting
    /// for a font.
    BLOCK_UNTIL_DOWNLOADED = 1;

    /// The server will tell the client that the uncached typeface is unavailable, by returning an
    /// empty [`fuchsia.fonts/TypefaceResponse`]. The uncached typeface may be downloaded
    /// asynchronously to be available for future requests.
    ///
    /// This is similar to `font-display: block` in CSS.
    RETURN_EMPTY_RESPONSE = 2;

    /// The server will attempt to provide a cached fallback typeface (if allowed by the fallback
    /// restrictions in [`fuchsia.fonts/TypefaceRequestFlags`]). The uncached typeface may be
    /// downloaded asynchronously to be available for future requests.
    ///
    /// This is similar to `font-display: swap` in CSS.
    RETURN_FALLBACK = 3;
};

/// Parameters for requesting a typeface.
table TypefaceRequest {
    /// Parameters for looking up a typeface.
    1: TypefaceQuery query;

    /// Flags for how to process the request, such as which kinds of substitutions are permitted.
    2: TypefaceRequestFlags flags;

    /// Setting for what to do if the requested typeface exists but is not cached, and therefore
    /// cannot be served immediately.
    ///
    /// If this field is empty, the default policy is
    /// [`fuchsia.fonts/CacheMissPolicy.BLOCK_UNTIL_DOWNLOADED`].
    ///
    /// If the client needs an immediate response, it can choose one of the non-blocking policies.
    /// In this case, clients can also register to be notified when new fonts have been added to the
    /// cache by calling [`fuchsia.fonts/Provider.RegisterFontSetEventListener`].
    3: CacheMissPolicy cache_miss_policy;
};

/// Parameters for looking up a typeface.
table TypefaceQuery {
    /// Desired font family name, e.g. "Roboto". Font family search is case-insensitive.
    ///
    /// Note: In cases where the specified family doesn't exist, or the specified family doesn't
    /// have a glyph for the requested `code_point`, a face from another family may be returned.
    /// This behavior can be disabled using `TypefaceRequestFlags.EXACT_FAMILY`.
    1: FamilyName family;

    /// Style properties of the desired typeface.
    2: Style2 style;

    /// Language tags in order of preference. This allows disambiguating code points that map
    /// to different glyphs in different languages (e.g. CJK code points).
    ///
    /// See `fuchsia.intl.LocaleId`.
    3: vector<fuchsia.intl.LocaleId>:MAX_FACE_QUERY_LANGUAGES languages;

    /// Optional code points for which glyphs must be present in the returned face.
    ///
    /// Callers that specify this field are expected to extract the character set from the result
    /// and cache it in order to avoid calling the API more than necessary.
    4: vector<uint32>:MAX_FACE_QUERY_CODE_POINTS code_points;

    /// A generic font family to fall back to if an exact match is unavailable or does not contain
    /// the requested code point.
    ///
    /// Every font family belongs to a generic family (configured in the font manifest). If a
    /// particular font family doesn't contain a requested code point, the provider can search for
    /// the code point in other font families _in the same generic family_ as a fallback.
    ///
    /// Specifying `fallback_family` in a query allows the client to override the generic family
    /// that would be used as a fallback.
    5: GenericFontFamily fallback_family;
};

/// Response to a TypefaceRequest. Contains the digital font file and metadata corresponding to a
/// returned typeface. Clients are expected to cache the results if they plan to reuse them.
///
/// If a matching typeface cannot be found, the table will be empty.
table TypefaceResponse {
    /// A memory buffer containing the bytes of a digital font file.
    /// It is the client's responsibility to identify the type of file and to parse it (usually by
    /// delegating to FreeType or a similar library).
    1: fuchsia.mem.Buffer buffer;

    /// Identifier for the buffer. Responses with the same `buffer_id` are guaranteed to contain the
    /// same data in the buffer. Clients may use this value to detect if they already have the font
    /// cached in parsed form.
    2: uint32 buffer_id;

    /// Index of the returned typeface within `buffer`. Used for digital font formats that may
    /// contain more than one typeface per file, e.g. TTC (TrueType Collection).
    3: uint32 font_index;
};

/// Information about a font family that can be requested using `Provider.GetFontFamilyInfo()`.
///
/// If a matching font family is not found, the table will be empty.
table FontFamilyInfo {
    /// Canonical font family name. Note that this may be different from the value passed to
    /// `GetFontFamilyInfo()` due to the resolution of font aliases, and/or differences in
    /// whitespace and capitalization.
    1: FamilyName name;

    /// Unordered list of all available styles in the family.
    2: vector<Style2>:MAX_FAMILY_STYLES styles;
};