blob: 339f280c07cae339afd026fda56c80947c0253ff [file] [log] [blame]
// 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.
/// 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.
/// 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.
/// 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.
/// 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;