blob: b06cb5bfc33ce69e26618a576dd6ce9a462955f7 [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 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;
};
/// 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;
};
/// Parameters for looking up a typeface.
table TypefaceQuery {
/// Desired font family name, e.g. "Roboto". Font family search ignores differences in case and
/// whitespace.
///
/// 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 point for which a glyph 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: uint32 code_point;
/// 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<Style>:MAX_FAMILY_STYLES styles;
};