From 4025ad804383dc8d5ace9654ae21d4d726d0dbc4 Mon Sep 17 00:00:00 2001 From: Behdad Esfahbod Date: Sat, 27 Oct 2018 02:35:06 -0700 Subject: [PATCH] Document new API --- src/hb-common.h | 30 +++++++++++++++++++++- src/hb-ot-color.cc | 16 ++++++------ src/hb-ot-layout.cc | 2 +- src/hb-ot-name.cc | 61 ++++++++++++++++++++++++++++++++++++++++++++- src/hb-ot-name.h | 15 +++++++++++ 5 files changed, 113 insertions(+), 11 deletions(-) diff --git a/src/hb-common.h b/src/hb-common.h index 0858c0e29..2532d69fe 100644 --- a/src/hb-common.h +++ b/src/hb-common.h @@ -449,15 +449,43 @@ hb_variation_to_string (hb_variation_t *variation, * * Data type for holding color values. * - * Since: REPLACEME + * Since: 2.1.0 */ typedef uint32_t hb_color_t; #define HB_COLOR(b,g,r,a) ((hb_color_t) HB_TAG ((b),(g),(r),(a))) +/** + * hb_color_get_alpha: + * + * + * + * Since: 2.1.0 + */ #define hb_color_get_alpha(color) ((color) & 0xFF) +/** + * hb_color_get_red: + * + * + * + * Since: 2.1.0 + */ #define hb_color_get_red(color) (((color) >> 8) & 0xFF) +/** + * hb_color_get_green: + * + * + * + * Since: 2.1.0 + */ #define hb_color_get_green(color) (((color) >> 16) & 0xFF) +/** + * hb_color_get_blue: + * + * + * + * Since: 2.1.0 + */ #define hb_color_get_blue(color) (((color) >> 24) & 0xFF) diff --git a/src/hb-ot-color.cc b/src/hb-ot-color.cc index 3f492cc1f..58f5a0709 100644 --- a/src/hb-ot-color.cc +++ b/src/hb-ot-color.cc @@ -89,7 +89,7 @@ _get_svg (hb_face_t *face) * * Returns: whether CPAL table is available. * - * Since: REPLACEME + * Since: 2.1.0 */ hb_bool_t hb_ot_color_has_palettes (hb_face_t *face) @@ -104,7 +104,7 @@ hb_ot_color_has_palettes (hb_face_t *face) * Returns: the number of color palettes in @face, or zero if @face has * no colors. * - * Since: REPLACEME + * Since: 2.1.0 */ unsigned int hb_ot_color_palette_get_count (hb_face_t *face) @@ -123,7 +123,7 @@ hb_ot_color_palette_get_count (hb_face_t *face) * Returns: an identifier within @face's `name` table. * If the requested palette has no name the result is #HB_NAME_ID_INVALID. * - * Since: REPLACEME + * Since: 2.1.0 */ hb_name_id_t hb_ot_color_palette_get_name_id (hb_face_t *face, @@ -139,7 +139,7 @@ hb_ot_color_palette_get_name_id (hb_face_t *face, * * Returns: Name ID associated with a palette entry, e.g. eye color * - * Since: REPLACEME + * Since: 2.1.0 */ hb_name_id_t hb_ot_color_palette_color_get_name_id (hb_face_t *face, @@ -155,7 +155,7 @@ hb_ot_color_palette_color_get_name_id (hb_face_t *face, * * Returns: the flags for the requested color palette. * - * Since: REPLACEME + * Since: 2.1.0 */ hb_ot_color_palette_flags_t hb_ot_color_palette_get_flags (hb_face_t *face, @@ -186,7 +186,7 @@ hb_ot_color_palette_get_flags (hb_face_t *face, * * Returns: the total number of colors in the palette. * - * Since: REPLACEME + * Since: 2.1.0 */ unsigned int hb_ot_color_palette_get_colors (hb_face_t *face, @@ -209,7 +209,7 @@ hb_ot_color_palette_get_colors (hb_face_t *face, * * Returns: whether COLR table is available. * - * Since: REPLACEME + * Since: 2.1.0 */ hb_bool_t hb_ot_color_has_layers (hb_face_t *face) @@ -227,7 +227,7 @@ hb_ot_color_has_layers (hb_face_t *face) * * Returns: * - * Since: REPLACEME + * Since: 2.1.0 */ unsigned int hb_ot_color_glyph_get_layers (hb_face_t *face, diff --git a/src/hb-ot-layout.cc b/src/hb-ot-layout.cc index 096fda207..27c49df7d 100644 --- a/src/hb-ot-layout.cc +++ b/src/hb-ot-layout.cc @@ -1174,7 +1174,7 @@ hb_ot_layout_feature_get_name_ids (hb_face_t *face, * one shot copying). * @char_count: (inout) (allow-none): The count of characters for which this feature * provides glyph variants. (May be zero.) - * @characters: (out) (allow-none): A buffer pointer. The Unicode Scalar Value + * @characters: (out caller-allocates) (array length=char_count): A buffer pointer. The Unicode codepoints * of the characters for which this feature provides glyph variants. * * Fetches characters listed by designer under feature parameters for "Character diff --git a/src/hb-ot-name.cc b/src/hb-ot-name.cc index f1c1f76e8..650d99ab0 100644 --- a/src/hb-ot-name.cc +++ b/src/hb-ot-name.cc @@ -39,7 +39,18 @@ _get_name (hb_face_t *face) return *(hb_ot_face_data (face)->name.get ()); } - +/** + * hb_ot_name_get_names: + * @face: font face. + * @entries: (out) (transfer none) (array): + * + * Enumerates all available name IDs and language combinations. Returned + * array is owned by the @face and should not be modified. It can be + * used as long as @face is alive. + * + * Returns: Number of entries returned. + * Since: 2.1.0 + **/ unsigned int hb_ot_name_get_names (hb_face_t *face, const hb_ot_name_entry_t **entries /* OUT */) @@ -131,6 +142,22 @@ hb_ot_name_get_utf (hb_face_t *face, return 0; } +/** + * hb_ot_name_get_utf8: + * @face: font face. + * @name_id: OpenType name identifier to fetch. + * @language: language to fetch the name for. + * @text_size: (inout) (allow-none): input size of @text buffer, and output size of + * text written to buffer. + * @text: (out caller-allocates) (array length=text_size): buffer to write fetched name into. + * + * Fetches a font name from the OpenType 'name' table. + * If @language is #HB_LANGUAGE_INVALID, English ("en") is assumed. + * Returns string in UTF-8 encoding. + * + * Returns: full length of the requested string, or 0 if not found. + * Since: 2.1.0 + **/ unsigned int hb_ot_name_get_utf8 (hb_face_t *face, hb_name_id_t name_id, @@ -142,6 +169,22 @@ hb_ot_name_get_utf8 (hb_face_t *face, (hb_utf8_t::codepoint_t *) text); } +/** + * hb_ot_name_get_utf16: + * @face: font face. + * @name_id: OpenType name identifier to fetch. + * @language: language to fetch the name for. + * @text_size: (inout) (allow-none): input size of @text buffer, and output size of + * text written to buffer. + * @text: (out caller-allocates) (array length=text_size): buffer to write fetched name into. + * + * Fetches a font name from the OpenType 'name' table. + * If @language is #HB_LANGUAGE_INVALID, English ("en") is assumed. + * Returns string in UTF-16 encoding. + * + * Returns: full length of the requested string, or 0 if not found. + * Since: 2.1.0 + **/ unsigned int hb_ot_name_get_utf16 (hb_face_t *face, hb_name_id_t name_id, @@ -152,6 +195,22 @@ hb_ot_name_get_utf16 (hb_face_t *face, return hb_ot_name_get_utf (face, name_id, language, text_size, text); } +/** + * hb_ot_name_get_utf32: + * @face: font face. + * @name_id: OpenType name identifier to fetch. + * @language: language to fetch the name for. + * @text_size: (inout) (allow-none): input size of @text buffer, and output size of + * text written to buffer. + * @text: (out caller-allocates) (array length=text_size): buffer to write fetched name into. + * + * Fetches a font name from the OpenType 'name' table. + * If @language is #HB_LANGUAGE_INVALID, English ("en") is assumed. + * Returns string in UTF-32 encoding. + * + * Returns: full length of the requested string, or 0 if not found. + * Since: 2.1.0 + **/ unsigned int hb_ot_name_get_utf32 (hb_face_t *face, hb_name_id_t name_id, diff --git a/src/hb-ot-name.h b/src/hb-ot-name.h index 66af5b646..18476553b 100644 --- a/src/hb-ot-name.h +++ b/src/hb-ot-name.h @@ -66,6 +66,10 @@ enum { /** * hb_name_id_t: * + * An integral type representing an OpenType 'name' table name identifier. + * There are predefined name IDs, as well as name IDs return from other + * API. These can be used to fetch name strings from a font face. + * * Since: 2.0.0 */ typedef unsigned int hb_name_id_t; @@ -73,6 +77,8 @@ typedef unsigned int hb_name_id_t; /** * HB_NAME_ID_INVALID * + * Value to represent a nonexistent name ID. + * * Since: 2.0.0 **/ #define HB_NAME_ID_INVALID 0xFFFF @@ -100,6 +106,15 @@ hb_ot_name_get_utf32 (hb_face_t *face, uint32_t *text /* OUT */); +/** + * hb_ot_name_entry_t: + * @name_id: name ID + * @language: language + * + * Structure representing a name ID in a particular language. + * + * Since: 2.1.0 + **/ typedef struct hb_ot_name_entry_t { hb_name_id_t name_id;