diff options
Diffstat (limited to 'thirdparty/harfbuzz/src/hb-face.cc')
-rw-r--r-- | thirdparty/harfbuzz/src/hb-face.cc | 179 |
1 files changed, 106 insertions, 73 deletions
diff --git a/thirdparty/harfbuzz/src/hb-face.cc b/thirdparty/harfbuzz/src/hb-face.cc index 7bde50df5b..33a788e7c5 100644 --- a/thirdparty/harfbuzz/src/hb-face.cc +++ b/thirdparty/harfbuzz/src/hb-face.cc @@ -41,8 +41,10 @@ * @short_description: Font face objects * @include: hb.h * - * Font face is objects represent a single face in a font family. - * More exactly, a font face represents a single face in a binary font file. + * A font face is an object that represents a single face from within a + * font family. + * + * More precisely, a font face represents a single face in a binary font file. * Font faces are typically built from a binary blob and a face index. * Font faces are used to create fonts. **/ @@ -52,7 +54,7 @@ * hb_face_count: * @blob: a blob. * - * Get number of faces in a blob. + * Fetches the number of faces in a blob. * * Return value: Number of faces in @blob * @@ -96,13 +98,19 @@ DEFINE_NULL_INSTANCE (hb_face_t) = /** * hb_face_create_for_tables: - * @reference_table_func: (closure user_data) (destroy destroy) (scope notified): - * @user_data: - * @destroy: - * + * @reference_table_func: (closure user_data) (destroy destroy) (scope notified): Table-referencing function + * @user_data: A pointer to the user data + * @destroy: (optional): A callback to call when @data is not needed anymore * + * Variant of hb_face_create(), built for those cases where it is more + * convenient to provide data for individual tables instead of the whole font + * data. With the caveat that hb_face_get_table_tags() does not currently work + * with faces created this way. + * + * Creates a new face object from the specified @user_data and @reference_table_func, + * with the @destroy callback. * - * Return value: (transfer full) + * Return value: (transfer full): The new face object * * Since: 0.9.2 **/ @@ -182,12 +190,15 @@ _hb_face_for_data_reference_table (hb_face_t *face HB_UNUSED, hb_tag_t tag, void /** * hb_face_create: (Xconstructor) - * @blob: - * @index: - * + * @blob: #hb_blob_t to work upon + * @index: The index of the face within @blob * + * Constructs a new face object from the specified blob and + * a face index into that blob. This is used for blobs of + * file formats such as Dfont and TTC that can contain more + * than one face. * - * Return value: (transfer full): + * Return value: (transfer full): The new face object * * Since: 0.9.2 **/ @@ -222,9 +233,9 @@ hb_face_create (hb_blob_t *blob, /** * hb_face_get_empty: * + * Fetches the singleton empty face object. * - * - * Return value: (transfer full) + * Return value: (transfer full) The empty face object * * Since: 0.9.2 **/ @@ -237,11 +248,11 @@ hb_face_get_empty () /** * hb_face_reference: (skip) - * @face: a face. - * + * @face: A face object * + * Increases the reference count on a face object. * - * Return value: + * Return value: The @face object * * Since: 0.9.2 **/ @@ -253,9 +264,11 @@ hb_face_reference (hb_face_t *face) /** * hb_face_destroy: (skip) - * @face: a face. - * - * + * @face: A face object + * + * Decreases the reference count on a face object. When the + * reference count reaches zero, the face is destroyed, + * freeing all memory. * * Since: 0.9.2 **/ @@ -283,15 +296,15 @@ hb_face_destroy (hb_face_t *face) /** * hb_face_set_user_data: (skip) - * @face: a face. - * @key: - * @data: - * @destroy: - * @replace: - * + * @face: A face object + * @key: The user-data key to set + * @data: A pointer to the user data + * @destroy: (optional): A callback to call when @data is not needed anymore + * @replace: Whether to replace an existing data with the same key * + * Attaches a user-data key/data pair to the given face object. * - * Return value: + * Return value: %true if success, %false otherwise * * Since: 0.9.2 **/ @@ -307,12 +320,13 @@ hb_face_set_user_data (hb_face_t *face, /** * hb_face_get_user_data: (skip) - * @face: a face. - * @key: + * @face: A face object + * @key: The user-data key to query * + * Fetches the user data associated with the specified key, + * attached to the specified face object. * - * - * Return value: (transfer none): + * Return value: (transfer none): A pointer to the user data * * Since: 0.9.2 **/ @@ -325,9 +339,9 @@ hb_face_get_user_data (const hb_face_t *face, /** * hb_face_make_immutable: - * @face: a face. - * + * @face: A face object * + * Makes the given face object immutable. * * Since: 0.9.2 **/ @@ -342,11 +356,11 @@ hb_face_make_immutable (hb_face_t *face) /** * hb_face_is_immutable: - * @face: a face. + * @face: A face object * + * Tests whether the given face object is immutable. * - * - * Return value: + * Return value: True is @face is immutable, false otherwise * * Since: 0.9.2 **/ @@ -359,12 +373,13 @@ hb_face_is_immutable (const hb_face_t *face) /** * hb_face_reference_table: - * @face: a face. - * @tag: - * + * @face: A face object + * @tag: The #hb_tag_t of the table to query * + * Fetches a reference to the specified table within + * the specified face. * - * Return value: (transfer full): + * Return value: (transfer full): A pointer to the @tag table within @face * * Since: 0.9.2 **/ @@ -380,11 +395,13 @@ hb_face_reference_table (const hb_face_t *face, /** * hb_face_reference_blob: - * @face: a face. - * + * @face: A face object * + * Fetches a pointer to the binary blob that contains the + * specified face. Returns an empty blob if referencing face data is not + * possible. * - * Return value: (transfer full): + * Return value: (transfer full): A pointer to the blob for @face * * Since: 0.9.2 **/ @@ -396,10 +413,13 @@ hb_face_reference_blob (hb_face_t *face) /** * hb_face_set_index: - * @face: a face. - * @index: + * @face: A face object + * @index: The index to assign * + * Assigns the specified face-index to @face. Fails if the + * face is immutable. * + * <note>Note: face indices within a collection are zero-based.</note> * * Since: 0.9.2 **/ @@ -415,11 +435,13 @@ hb_face_set_index (hb_face_t *face, /** * hb_face_get_index: - * @face: a face. + * @face: A face object * + * Fetches the face-index corresponding to the given face. * + * <note>Note: face indices within a collection are zero-based.</note> * - * Return value: + * Return value: The index of @face. * * Since: 0.9.2 **/ @@ -431,10 +453,10 @@ hb_face_get_index (const hb_face_t *face) /** * hb_face_set_upem: - * @face: a face. - * @upem: - * + * @face: A face object + * @upem: The units-per-em value to assign * + * Sets the units-per-em (upem) for a face object to the specified value. * * Since: 0.9.2 **/ @@ -450,11 +472,11 @@ hb_face_set_upem (hb_face_t *face, /** * hb_face_get_upem: - * @face: a face. - * + * @face: A face object * + * Fetches the units-per-em (upem) value of the specified face object. * - * Return value: + * Return value: The upem value of @face * * Since: 0.9.2 **/ @@ -466,10 +488,10 @@ hb_face_get_upem (const hb_face_t *face) /** * hb_face_set_glyph_count: - * @face: a face. - * @glyph_count: - * + * @face: A face object + * @glyph_count: The glyph-count value to assign * + * Sets the glyph count for a face object to the specified value. * * Since: 0.9.7 **/ @@ -485,11 +507,11 @@ hb_face_set_glyph_count (hb_face_t *face, /** * hb_face_get_glyph_count: - * @face: a face. - * + * @face: A face object * + * Fetches the glyph-count value of the specified face object. * - * Return value: + * Return value: The glyph-count value of @face * * Since: 0.9.7 **/ @@ -501,14 +523,16 @@ hb_face_get_glyph_count (const hb_face_t *face) /** * hb_face_get_table_tags: - * @face: a face. - * @start_offset: index of first tag to return. - * @table_count: input length of @table_tags array, output number of items written. - * @table_tags: array to write tags into. + * @face: A face object + * @start_offset: The index of first table tag to retrieve + * @table_count: (inout): Input = the maximum number of table tags to return; + * Output = the actual number of table tags returned (may be zero) + * @table_tags: (out) (array length=table_count): The array of table tags found * - * Retrieves table tags for a face, if possible. + * Fetches a list of all table tags for a face, if possible. The list returned will + * begin at the offset provided * - * Return value: total number of tables, or 0 if not possible to list. + * Return value: Total number of tables, or zero if it is not possible to list * * Since: 1.6.0 **/ @@ -542,8 +566,11 @@ hb_face_get_table_tags (const hb_face_t *face, #ifndef HB_NO_FACE_COLLECT_UNICODES /** * hb_face_collect_unicodes: - * @face: font face. - * @out: set to add Unicode characters covered by @face to. + * @face: A face object + * @out: The set to add Unicode characters to + * + * Collects all of the Unicode characters covered by @face and adds + * them to the #hb_set_t set @out. * * Since: 1.9.0 */ @@ -555,10 +582,11 @@ hb_face_collect_unicodes (hb_face_t *face, } /** * hb_face_collect_variation_selectors: - * @face: font face. - * @out: set to add Variation Selector characters covered by @face to. - * + * @face: A face object + * @out: The set to add Variation Selector characters to * + * Collects all Unicode "Variation Selector" characters covered by @face and adds + * them to the #hb_set_t set @out. * * Since: 1.9.0 */ @@ -570,10 +598,12 @@ hb_face_collect_variation_selectors (hb_face_t *face, } /** * hb_face_collect_variation_unicodes: - * @face: font face. - * @out: set to add Unicode characters for @variation_selector covered by @face to. - * + * @face: A face object + * @variation_selector: The Variation Selector to query + * @out: The set to add Unicode characters to * + * Collects all Unicode characters for @variation_selector covered by @face and adds + * them to the #hb_set_t set @out. * * Since: 1.9.0 */ @@ -708,6 +738,9 @@ hb_face_builder_create () /** * hb_face_builder_add_table: + * @face: A face object created with hb_face_builder_create() + * @tag: The #hb_tag_t of the table to add + * @blob: The blob containing the table data to add * * Add table for @tag with data provided by @blob to the face. @face must * be created using hb_face_builder_create(). |