walkero
/
harfbuzz
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Docs: Regularize GTK-Doc comments for hb-ot-color.

This commit is contained in:
Nathan Willis 2019-04-14 15:20:56 +01:00
parent 35f3b97fac
commit 3f74b7a14b
2 changed files with 78 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

132
src/hb-ot-color.cc
View File

@ -47,6 +47,8 @@
* @include: hb-ot.h * @include: hb-ot.h
* *
* Functions for fetching color-font information from OpenType font faces. * Functions for fetching color-font information from OpenType font faces.
*
* HarfBuzz supports COLR/CPAL, sbix, CBDT, and SVG color fonts.
**/ **/
@ -57,9 +59,11 @@
/** /**
* hb_ot_color_has_palettes: * hb_ot_color_has_palettes:
* @face: a font face. * @face: #hb_face_t to work upon
* *
* Returns: whether CPAL table is available. * Tests whether a face includes a CPAL color-palette table.
*
* Return value: true if data found, false otherwise
* *
* Since: 2.1.0 * Since: 2.1.0
*/ */
@ -71,10 +75,11 @@ hb_ot_color_has_palettes (hb_face_t *face)
/** /**
* hb_ot_color_palette_get_count: * hb_ot_color_palette_get_count:
* @face: a font face. * @face: #hb_face_t to work upon
* *
* Returns: the number of color palettes in @face, or zero if @face has * Fetches the number of color palettes in a face.
* no colors. *
* Return value: the number of palettes found
* *
* Since: 2.1.0 * Since: 2.1.0
*/ */
@ -86,13 +91,16 @@ hb_ot_color_palette_get_count (hb_face_t *face)
/** /**
* hb_ot_color_palette_get_name_id: * hb_ot_color_palette_get_name_id:
* @face: a font face. * @face: #hb_face_t to work upon
* @palette_index: the index of the color palette whose name is being requested. * @palette_index: The index of the color palette
* *
* Retrieves the name id of a color palette. For example, a color font can * Fetches the 'name' table Name ID that provides display names for
* have themed palettes like "Spring", "Summer", "Fall", and "Winter". * a CPAL color palette.
* *
* Returns: an identifier within @face's `name` table. * Palette display names can be generic (e.g., "Default") or provide
* specific, themed names (e.g., "Spring", "Summer", "Fall", and "Winter").
*
* Return value: the Named ID found for the palette.
* If the requested palette has no name the result is #HB_OT_NAME_ID_INVALID. * If the requested palette has no name the result is #HB_OT_NAME_ID_INVALID.
* *
* Since: 2.1.0 * Since: 2.1.0
@ -106,10 +114,16 @@ hb_ot_color_palette_get_name_id (hb_face_t *face,
/** /**
* hb_ot_color_palette_color_get_name_id: * hb_ot_color_palette_color_get_name_id:
* @face: a font face. * @face: #hb_face_t to work upon
* @color_index: palette entry index. * @color_index: The index of the color
* *
* Returns: Name ID associated with a palette entry, e.g. eye color * Fetches the 'name' table Name ID that provides display names for
* the specificed color in a face's CPAL color palette.
*
* Display names can be generic (e.g., "Background") or specific
* (e.g., "Eye color").
*
* Return value: the Name ID found for the color.
* *
* Since: 2.1.0 * Since: 2.1.0
*/ */
@ -122,10 +136,12 @@ hb_ot_color_palette_color_get_name_id (hb_face_t *face,
/** /**
* hb_ot_color_palette_get_flags: * hb_ot_color_palette_get_flags:
* @face: a font face * @face: #hb_face_t to work upon
* @palette_index: the index of the color palette whose flags are being requested * @palette_index: The index of the color palette
* *
* Returns: the flags for the requested color palette. * Fetches the flags defined for a color palette.
*
* Return value: the #hb_ot_color_palette_flags_t of the requested color palette
* *
* Since: 2.1.0 * Since: 2.1.0
*/ */
@ -138,25 +154,22 @@ hb_ot_color_palette_get_flags (hb_face_t *face,
/** /**
* hb_ot_color_palette_get_colors: * hb_ot_color_palette_get_colors:
* @face: a font face. * @face: #hb_face_t to work upon
* @palette_index:the index of the color palette whose colors * @palette_index: the index of the color palette to query
* are being requested. * @start_offset: offset of the first color to retrieve
* @start_offset: the index of the first color being requested. * @color_count: (inout) (optional): Input = the maximum number of colors to return;
* @color_count: (inout) (optional): on input, how many colors * Output = the actual number of colors returned (may be zero)
* can be maximally stored into the @colors array; * @colors: (array length=color_count) (out) (optional): The array of #hb_color_t records found
* on output, how many colors were actually stored. *
* @colors: (array length=color_count) (out) (optional): * Fetches a list of the colors in a color palette.
* an array of #hb_color_t records. After calling *
* this function, @colors will be filled with * After calling this function, @colors will be filled with the palette
* the palette colors. If @colors is NULL, the function * colors. If @colors is NULL, the function will just return the number
* will just return the number of total colors * of total colors without storing any actual colors; this can be used
* without storing any actual colors; this can be used
* for allocating a buffer of suitable size before calling * for allocating a buffer of suitable size before calling
* hb_ot_color_palette_get_colors() a second time. * #hb_ot_color_palette_get_colors() a second time.
* *
* Retrieves the colors in a color palette. * Return value: the total number of colors in the palette
*
* Returns: the total number of colors in the palette.
* *
* Since: 2.1.0 * Since: 2.1.0
*/ */
@ -177,9 +190,11 @@ hb_ot_color_palette_get_colors (hb_face_t *face,
/** /**
* hb_ot_color_has_layers: * hb_ot_color_has_layers:
* @face: a font face. * @face: #hb_face_t to work upon
* *
* Returns: whether COLR table is available. * Tests whether a face includes any COLR color layers.
*
* Return value: true if data found, false otherwise
* *
* Since: 2.1.0 * Since: 2.1.0
*/ */
@ -191,14 +206,17 @@ hb_ot_color_has_layers (hb_face_t *face)
/** /**
* hb_ot_color_glyph_get_layers: * hb_ot_color_glyph_get_layers:
* @face: a font face. * @face: #hb_face_t to work upon
* @glyph: a layered color glyph id. * @glyph: The glyph index to query
* @start_offset: starting offset of layers. * @start_offset: offset of the first layer to retrieve
* @count: (inout) (optional): gets number of layers available to be written on buffer * @count: (inout) (optional): Input = the maximum number of layers to return;
* and returns number of written layers. * Output = the actual number of layers returned (may be zero)
* @layers: (array length=count) (out) (optional): layers buffer to buffer. * @layers: (array length=count) (out) (optional): The array of layers found
* *
* Returns: Total number of layers a layered color glyph have. * Fetches a list of all color layers for the specified glyph index in the specified
* face. The list returned will begin at the offset provided.
*
* Return value: Total number of layers available for the glyph index queried
* *
* Since: 2.1.0 * Since: 2.1.0
*/ */
@ -219,11 +237,11 @@ hb_ot_color_glyph_get_layers (hb_face_t *face,
/** /**
* hb_ot_color_has_svg: * hb_ot_color_has_svg:
* @face: a font face. * @face: #hb_face_t to work upon.
* *
* Check whether @face has SVG glyph images. * Tests whether a face includes any SVG glyph images.
* *
* Returns true if available, false otherwise. * Return value: true if data found, false otherwise.
* *
* Since: 2.1.0 * Since: 2.1.0
*/ */
@ -235,12 +253,12 @@ hb_ot_color_has_svg (hb_face_t *face)
/** /**
* hb_ot_color_glyph_reference_svg: * hb_ot_color_glyph_reference_svg:
* @face: a font face. * @face: #hb_face_t to work upon
* @glyph: a svg glyph index. * @glyph: a svg glyph index
* *
* Get SVG document for a glyph. The blob may be either plain text or gzip-encoded. * Fetches the SVG document for a glyph. The blob may be either plain text or gzip-encoded.
* *
* Returns: (transfer full): respective svg blob of the glyph, if available. * Return value: (transfer full): An #hb_blob_t containing the SVG document of the glyph, if available
* *
* Since: 2.1.0 * Since: 2.1.0
*/ */
@ -257,11 +275,11 @@ hb_ot_color_glyph_reference_svg (hb_face_t *face, hb_codepoint_t glyph)
/** /**
* hb_ot_color_has_png: * hb_ot_color_has_png:
* @face: a font face. * @face: #hb_face_t to work upon
* *
* Check whether @face has PNG glyph images (either CBDT or sbix tables). * Tests whether a face has PNG glyph images (either in CBDT or sbix tables).
* *
* Returns true if available, false otherwise. * Return value: true if data found, false otherwise
* *
* Since: 2.1.0 * Since: 2.1.0
*/ */
@ -273,14 +291,14 @@ hb_ot_color_has_png (hb_face_t *face)
/** /**
* hb_ot_color_glyph_reference_png: * hb_ot_color_glyph_reference_png:
* @font: a font object, not face. upem should be set on * @font: #hb_font_t to work upon
* that font object if one wants to get optimal png blob, otherwise
* return the biggest one
* @glyph: a glyph index. * @glyph: a glyph index.
* *
* Get PNG image for a glyph. * Fetches the PNG image for a glyph. This function takes a font object, not a face object,
* as input. To get an optimally sized PNG blob, the UPEM value must be set on the @font
* object. If UPEM is unset, the blob returned will be the largest PNG available.
* *
* Returns: (transfer full): respective PNG blob of the glyph, if available. * Return value: (transfer full): An #hb_blob_t containing the PNG image for the glyph, if available
* *
* Since: 2.1.0 * Since: 2.1.0
*/ */

6
src/hb-ot-color.h
View File

@ -59,11 +59,11 @@ hb_ot_color_palette_color_get_name_id (hb_face_t *face,
/** /**
* hb_ot_color_palette_flags_t: * hb_ot_color_palette_flags_t:
* @HB_OT_COLOR_PALETTE_FLAG_DEFAULT: default indicating that there is nothing special * @HB_OT_COLOR_PALETTE_FLAG_DEFAULT: Default indicating that there is nothing special
* to note about a color palette. * to note about a color palette.
* @HB_OT_COLOR_PALETTE_FLAG_USABLE_WITH_LIGHT_BACKGROUND: flag indicating that the color * @HB_OT_COLOR_PALETTE_FLAG_USABLE_WITH_LIGHT_BACKGROUND: Flag indicating that the color
* palette is appropriate to use when displaying the font on a light background such as white. * palette is appropriate to use when displaying the font on a light background such as white.
* @HB_OT_COLOR_PALETTE_FLAG_USABLE_WITH_DARK_BACKGROUND: flag indicating that the color * @HB_OT_COLOR_PALETTE_FLAG_USABLE_WITH_DARK_BACKGROUND: Flag indicating that the color
* palette is appropriate to use when displaying the font on a dark background such as black. * palette is appropriate to use when displaying the font on a dark background such as black.
* *
* Since: 2.1.0 * Since: 2.1.0