[fonts] Font Provider API changes based on API review

- Introduce tables for existing structs
- Improve organization of definitions; add detailed documentation
- Place all new definitions in provider.fidl (and styles.fidl)
- Incorporate other changes and suggestions from
  https://fuchsia-review.googlesource.com/c/fuchsia/+/249522/

Implementation updates will be completed in subsequent CLs.

I18N-12 #comment

Change-Id: I177f5850b1c9eb91f59af1885005336121c0f1e0

garnet/bin/fonts/src/font_service.rs

@@ -313,6 +313,7 @@ impl FontService {
     fn handle_font_provider_request(
         &self, request: fonts::ProviderRequest,
     ) -> impl Future<Output = Result<(), fidl::Error>> {
+        #[allow(unused_variables)]
         match request {
             fonts::ProviderRequest::GetFont { request, responder } => {
                 let mut response = self.match_request(request);
@@ -322,6 +323,14 @@ impl FontService {
                 let mut font_info = self.get_font_info(family);
                 future::ready(responder.send(font_info.as_mut().map(OutOfLine)))
             }
+            fonts::ProviderRequest::GetTypeface { request, responder } => {
+                // TODO(I18N-12): Implement changes from API review
+                unimplemented!();
+            }
+            fonts::ProviderRequest::GetFontFamilyInfo { family, responder } => {
+                // TODO(I18N-12): Implement changes from API review
+                unimplemented!();
+            }
         }
     }
 }

sdk/fidl/fuchsia.fonts/BUILD.gn

@@ -9,9 +9,12 @@ fidl("fuchsia.fonts") {
 
   sources = [
     "font_provider.fidl",
+    "provider.fidl",
+    "styles.fidl",
   ]
 
   public_deps = [
+    "//sdk/fidl/fuchsia.intl",
     "//zircon/public/fidl/fuchsia-mem",
   ]
 }

sdk/fidl/fuchsia.fonts/font_provider.fidl

@@ -2,16 +2,14 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+// NOTE: This file is deprecated and will soon be removed in favor of provider.fidl.
+
 library fuchsia.fonts;
 
 using fuchsia.mem;
 
-enum Slant {
-    UPRIGHT = 1;
-    ITALIC = 2;
-    OBLIQUE = 3;
-};
-
+/// Deprecated. See |GenericFontFamily|.
+[Transitional]
 enum FallbackGroup {
     NONE = 0;
     SERIF = 1;
@@ -21,46 +19,49 @@ enum FallbackGroup {
     FANTASY = 5;
 };
 
-// Disables font fallback. The service won't try to search fallback font set if
-// there is no requested font family or if it doesn't contain requested
-// character.
+/// Deprecated. See |FaceRequestFlags|.
+/// Disables font fallback. The service won't try to search fallback font set if
+/// there is no requested font family or if it doesn't contain requested
+/// character.
 const uint32 REQUEST_FLAG_NO_FALLBACK = 1;
 
-// Disables approximate style matching. The service will only return font that
-// matches the requested style exactly.
+/// Deprecated. See |FaceRequestFlags|.
+/// Disables approximate style matching. The service will only return font that
+/// matches the requested style exactly.
 const uint32 REQUEST_FLAG_EXACT_MATCH = 2;
 
+/// Deprecated. See |FaceRequest|.
 struct Request {
-    // Desired font family name, e.g. "Roboto". Font family search is
-    // case-insensitive. In case when there is no specified family or the
-    // specified family doesn't have glyph for the requested |character| then
-    // a font from another family may be returned. This behavior can be disabled
-    // using REQUEST_FLAG_NO_FALLBACK.
-    string:128? family;
-
-    // For example, 400 is normal, 700 is bold.
+    /// Desired font family name, e.g. "Roboto". Font family search is
+    /// case-insensitive. In case when there is no specified family or the
+    /// specified family doesn't have glyph for the requested |character| then
+    /// a font from another family may be returned. This behavior can be disabled
+    /// using REQUEST_FLAG_NO_FALLBACK.
+    string:MAX_FAMILY_NAME_LENGTH? family;
+
+    /// For example, 400 is normal, 700 is bold.
     uint32 weight = 400;
 
-    // Numeric values matching OS/2 & Windows Metrics usWidthClass table.
-    // https://www.microsoft.com/typography/otspec/os2.htm
-    // For example, 5 is normal.
+    /// Numeric values matching OS/2 & Windows Metrics usWidthClass table.
+    /// https://www.microsoft.com/typography/otspec/os2.htm
+    /// For example, 5 is normal.
     uint32 width = 5;
 
     Slant slant = UPRIGHT;
 
-    // BCP47 language tags in order of preference. See
-    // https://tools.ietf.org/html/bcp47 .
+    /// BCP47 language tags in order of preference. See
+    /// https://tools.ietf.org/html/bcp47 .
     vector<string:35>:8? language;
 
-    // Codepoint for the character that must be present in the returned font or 0.
-    // Caller that specify this field are expected to extract character set from
-    // the result and cache it in order to avoid calling the API more than
-    // necessary.
+    /// Codepoint for the character that must be present in the returned font or 0.
+    /// Caller that specify this field are expected to extract character set from
+    /// the result and cache it in order to avoid calling the API more than
+    /// necessary.
     uint32 character = 0;
 
-    // Fallback group preference. Caller can leave this field set to NONE. In
-    // that case the font provider will use fallback group of the specified font
-    // family.
+    /// Fallback group preference. Caller can leave this field set to NONE. In
+    /// that case the font provider will use fallback group of the specified font
+    /// family.
     FallbackGroup fallback_group = NONE;
 
     uint32 flags = 0;
@@ -69,42 +70,67 @@ struct Request {
 struct Response {
     fuchsia.mem.Buffer 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.
+    /// 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.
     uint32 buffer_id;
 
-    // Font index within `buffer`. Used for font formats that may contain more
-    // than one font per file, e.g. TTC (TrueType Collection).
+    /// Font index within `buffer`. Used for font formats that may contain more
+    /// than one font per file, e.g. TTC (TrueType Collection).
     uint32 font_index;
 };
 
+/// Deprecated.
+/// See |Style2|.
 struct Style {
     uint32 weight;
     uint32 width;
     Slant slant;
 };
 
-// Information about font family that can be requested using GetFamilyInfo().
+/// Deprecated. See |FontFamilyInfo|.
+///
+/// Information about font family that can be requested using GetFamilyInfo().
 struct FamilyInfo {
-    // Canonical font family name. Note that this may be different from the
-    // value passed to GetFamilyInfo() because GetFamilyInfo() also resolves
-    // font aliases and ignores case. For example GetFamilyInfo("robotoslab")
-    // will FamilyInfo.name = "Robot Slab".
-    string:128 name;
-
-    // Unordered list of all available styles in the family.
-    vector<Style>:300 styles;
+    /// Canonical font family name. Note that this may be different from the
+    /// value passed to GetFamilyInfo() because GetFamilyInfo() also resolves
+    /// font aliases and ignores case. For example GetFamilyInfo("robotoslab")
+    /// will FamilyInfo.name = "Robot Slab".
+    string:MAX_FAMILY_NAME_LENGTH name;
+
+    /// Unordered list of all available styles in the family.
+    vector<Style>:MAX_FAMILY_STYLES styles;
 };
 
+/// Provider of digital font files and metadata.
+///
+/// TODO(I18N-12): Remove deprecated methods and move to provider.fidl.
 [Discoverable]
 protocol Provider {
-    // Returns font that matches specified |request|.
+
+    /// Deprecated. See |GetTypeface|.
+    ///
+    /// Returns font that matches specified |request|.
     GetFont(Request request) -> (Response? response);
 
-    // Returns information for the specified font family or null if there is
-    // no family with the specified name. This function respects family name
-    // aliases and ignores case, so request for "robotoSLAB" will return
-    // FamilyInfo for "Roboto Slab".
-    GetFamilyInfo(string:128 family) -> (FamilyInfo? family_info);
+    /// Deprecated. See |GetFontFamilyInfo|.
+    ///
+    /// Returns information for the specified font family or null if there is
+    /// no family with the specified name. This function respects family name
+    /// aliases and ignores case, so request for "robotoSLAB" will return
+    /// FamilyInfo for "Roboto Slab".
+    GetFamilyInfo(string:MAX_FAMILY_NAME_LENGTH family) -> (FamilyInfo? family_info);
+
+    /// Returns a typeface that matches the specified |request|, or an empty table if no matching
+    /// face is found. (The latter is more likely to happen if |TypefaceRequestFlags.EXACT_FAMILY|
+    /// is used to disable fallbacks.)
+    GetTypeface(TypefaceRequest request) -> (TypefaceResponse response);
+
+    /// Returns information for the specified font family, or an empty table if there is no family
+    /// with the specified name.
+    ///
+    /// This function respects family name aliases and ignores case. For example, "RobotoSlab" is an
+    /// alias for the canonical name "Roboto Slab". A request for "robotoSLAB" would return the
+    /// |FontFamilyInfo| for "Roboto Slab" due to the case-insensitivity and alias resolution.
+    GetFontFamilyInfo(FamilyName family) -> (FontFamilyInfo family_info);
 };

sdk/fidl/fuchsia.fonts/fuchsia.fonts.api

 {
-  "fidl/fuchsia.fonts/font_provider.fidl": "235173cb08d4421d53c8905c0e351455"
+  "fidl/fuchsia.fonts/font_provider.fidl": "2d8e7878bd19c1dcb72d523d82a5db3c",
+  "fidl/fuchsia.fonts/provider.fidl": "442eac20007bd397686255d215d074dd",
+  "fidl/fuchsia.fonts/styles.fidl": "ce2944f0316e3138e7356a5659f46acd"
 }
\ No newline at end of file

sdk/fidl/fuchsia.fonts/provider.fidl

+// 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;
+};

sdk/fidl/fuchsia.fonts/styles.fidl

+// 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 Weight = uint16;
+
+// Commonly used constants for font weight.
+const uint16 WEIGHT_THIN = 100;
+const uint16 WEIGHT_EXTRA_LIGHT = 200;
+const uint16 WEIGHT_LIGHT = 300;
+const uint16 WEIGHT_NORMAL = 400;
+const uint16 WEIGHT_MEDIUM = 500;
+const uint16 WEIGHT_SEMI_BOLD = 600;
+const uint16 WEIGHT_BOLD = 700;
+const uint16 WEIGHT_EXTRA_BOLD = 800;
+const uint16 WEIGHT_BLACK = 900;
+
+/// The type of slant of a type face.
+enum Slant {
+    /// The default; upright glyphs.
+    UPRIGHT = 1;
+    /// Specially designed, slanted and slightly calligraphic glyphs.
+    ITALIC = 2;
+    /// Skewed glyphs. Oblique usually means an geometric transformation of the upright variant,
+    /// rather than a custom-designed variant.
+    OBLIQUE = 3;
+};
+
+/// Horizontal width class of the glyphs.
+///
+/// See https://docs.microsoft.com/en-us/typography/opentype/spec/os2#uswidthclass.
+enum Width {
+    /// 50% of normal width
+    ULTRA_CONDENSED = 1;
+    /// 62.5% of normal width
+    EXTRA_CONDENSED = 2;
+    /// 75% of normal width
+    CONDENSED = 3;
+    /// 87.5% of normal width
+    SEMI_CONDENSED = 4;
+    /// Normal width
+    NORMAL = 5;
+    /// 112.5% of normal width
+    SEMI_EXPANDED = 6;
+    /// 125% of normal width
+    EXPANDED = 7;
+    /// 150% of normal width
+    EXTRA_EXPANDED = 8;
+    /// 200% of normal width
+    ULTRA_EXPANDED = 9;
+};
+
+/// Style properties that can be used when requesting or describing a type face.
+table Style2 {
+    /// See |Slant|.
+    1: Slant slant;
+    /// Weight or thickness of the glyphs. Allowed values are integers in the range [1, 1000], but
+    /// most real-world font families only support some integer multiples of 100:
+    /// {100, 200, ..., 900}. Normal text (|WEIGHT_NORMAL|) is 400; |WEIGHT_BOLD| is 700.
+    ///
+    /// See:
+    /// https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight#Common_weight_name_mapping
+    /// https://docs.microsoft.com/en-us/typography/opentype/spec/os2#usweightclass
+    2: Weight weight;
+    /// See |Width|.
+    3: Width width;
+};
+
+/// Generic groups of font families that can serve as fallbacks for a specific family.
+///
+/// Every font family belongs to some _generic_ font family (see examples below).
+///
+/// If an exact requested family is unavailable but a fallback group is specified in the request,
+/// the provider may return some other family that belongs to the fallback group. For example, if
+/// the client requests the "Arial" family with a |SANS_SERIF| fallback, and "Arial" is unavailable,
+/// the provider may return another available sans serif family, such as "Roboto Regular", instead.
+///
+/// See also:
+/// https://www.w3.org/Style/Examples/007/fonts.en.html
+/// https://developer.mozilla.org/en-US/docs/Web/CSS/font-family#Values
+enum GenericFontFamily {
+    /// Glyphs have little "serifs", hooks, or notches at the ends of most strokes.
+    /// Examples: Georgia, Noto Serif, Times New Roman.
+    SERIF = 1;
+    /// Glyphs that have no serifs at the ends of most strokes.
+    /// Examples: Arial, Noto Sans, Roboto, Tahoma.
+    SANS_SERIF = 2;
+    /// Fixed-width fonts.
+    /// Examples: Consolas, Courier New, Inconsolata.
+    MONOSPACE = 3;
+    /// Handwritten or cursive fonts.
+    /// Examples: Brush Script, Comic Sans, Lucida Calligraphy.
+    CURSIVE = 4;
+    /// Decorative fonts.
+    /// Examples: Impact, Papyrus.
+    FANTASY = 5;
+};