Merge branch 'documentation-updates' into 'master'

Documentation updates

See merge request cairo/cairo!431

doc/public/cairo-sections.txt

@@ -515,6 +515,14 @@ cairo_font_options_set_hint_metrics
 cairo_font_options_get_hint_metrics
 cairo_font_options_get_variations
 cairo_font_options_set_variations
+cairo_color_mode_t
+cairo_font_options_set_color_mode
+cairo_font_options_get_color_mode
+CAIRO_COLOR_PALETTE_DEFAULT
+cairo_font_options_set_color_palette
+cairo_font_options_get_color_palette
+cairo_font_options_set_custom_palette_color
+cairo_font_options_get_custom_palette_color
 </SECTION>
 
 <SECTION>

src/cairo-font-options.c

@@ -700,6 +700,14 @@ cairo_font_options_get_color_mode (const cairo_font_options_t *options)
     return options->color_mode;
 }
 
+/**
+ * CAIRO_COLOR_PALETTE_DEFAULT:
+ *
+ * The default color palette index.
+ *
+ * Since: 1.18
+ **/
+
 /**
  * cairo_font_options_set_color_palette:
  * @options: a #cairo_font_options_t
@@ -709,11 +717,11 @@ cairo_font_options_get_color_mode (const cairo_font_options_t *options)
  * object. OpenType color fonts with a CPAL table may contain multiple
  * palettes. The default color palette index is %CAIRO_COLOR_PALETTE_DEFAULT.
  *
- * #cairo_font_options_t can also contain a custom palette, which will
- * be used if @palette_index is %CAIRO_COLOR_PALETTE_CUSTOM.
- *
  * If @palette_index is invalid, the default palette is used.
  *
+ * Individual colors within the palette may be overriden with
+ * cairo_font_options_set_custom_palette_color().
+ *
  * Since: 1.18
  **/
 void
@@ -730,7 +738,7 @@ cairo_font_options_set_color_palette (cairo_font_options_t *options,
  * cairo_font_options_get_color_palette:
  * @options: a #cairo_font_options_t
  *
- * Gets the OpenType color font palette for the font options object.
+ * Gets the current OpenType color font palette for the font options object.
  *
  * Return value: the palette index
  *
@@ -754,11 +762,14 @@ cairo_font_options_get_color_palette (const cairo_font_options_t *options)
  * @blue: blue component of color
  * @alpha: alpha component of color
  *
- * Sets a custom palette color for the font options object.
+ * Sets a custom palette color for the font options object. This
+ * overrides the palette color at the specified color index. This override is
+ * independent of the selected palette index and will remain in place
+ * even if cairo_font_options_set_color_palette() is called to change
+ * the palette index.
  *
- * The custom colors will be used in preference to the selected
- * color palette from the font (see cairo_font_options_set_color_palette()).
- * It is possible to override only selected colors from the font palette.
+ * It is only possible to override color indexes already in the font
+ * palette.
  *
  * Since: 1.18
  */
@@ -803,10 +814,11 @@ cairo_font_options_set_custom_palette_color (cairo_font_options_t *options,
  * @blue: return location for blue component of color
  * @alpha: return location for alpha component of color
  *
- * Gets a custom palette color for the font options object.
+ * Gets the custom palette color for the color index for the font options object.
  *
- * Returns: `CAIRO_STATUS_SUCCESS` if a custom palette color is returned,
- *     `CAIRO_STATUS_INVALID_INDEX` otherwise.
+ * Returns: `CAIRO_STATUS_SUCCESS` if a custom palette color is
+ * returned, `CAIRO_STATUS_INVALID_INDEX` if no custom color exists
+ * for the color index.
  *
  * Since: 1.18
  */

src/cairo-pdf-surface.c

@@ -133,10 +133,10 @@
  * The PDF surface is used to render cairo graphics to Adobe
  * PDF files and is a multi-page vector surface backend.
  *
- * The following mime types are supported: %CAIRO_MIME_TYPE_JPEG,
- * %CAIRO_MIME_TYPE_JP2, %CAIRO_MIME_TYPE_UNIQUE_ID,
- * %CAIRO_MIME_TYPE_JBIG2, %CAIRO_MIME_TYPE_JBIG2_GLOBAL,
- * %CAIRO_MIME_TYPE_JBIG2_GLOBAL_ID,
+ * The following mime types are supported on source patterns:
+ * %CAIRO_MIME_TYPE_JPEG, %CAIRO_MIME_TYPE_JP2,
+ * %CAIRO_MIME_TYPE_UNIQUE_ID, %CAIRO_MIME_TYPE_JBIG2,
+ * %CAIRO_MIME_TYPE_JBIG2_GLOBAL, %CAIRO_MIME_TYPE_JBIG2_GLOBAL_ID,
  * %CAIRO_MIME_TYPE_CCITT_FAX, %CAIRO_MIME_TYPE_CCITT_FAX_PARAMS.
  *
  * # JBIG2 Images #

src/cairo-ps-surface.c

@@ -119,9 +119,8 @@ static char *ctime_r(const time_t *timep, char *buf)
  * The PostScript surface is used to render cairo graphics to Adobe
  * PostScript files and is a multi-page vector surface backend.
  *
- * The following mime types are supported: %CAIRO_MIME_TYPE_JPEG,
- * %CAIRO_MIME_TYPE_UNIQUE_ID,
- * %CAIRO_MIME_TYPE_CCITT_FAX, %CAIRO_MIME_TYPE_CCITT_FAX_PARAMS,
+ * The following mime types are supported on source patterns:
+ * %CAIRO_MIME_TYPE_JPEG, %CAIRO_MIME_TYPE_UNIQUE_ID,
  * %CAIRO_MIME_TYPE_CCITT_FAX, %CAIRO_MIME_TYPE_CCITT_FAX_PARAMS,
  * %CAIRO_MIME_TYPE_EPS, %CAIRO_MIME_TYPE_EPS_PARAMS.
  *
@@ -219,8 +218,11 @@ static const char * _cairo_ps_level_strings[CAIRO_PS_LEVEL_LAST] =
 static const char *_cairo_ps_supported_mime_types[] =
 {
     CAIRO_MIME_TYPE_JPEG,
+    CAIRO_MIME_TYPE_UNIQUE_ID,
     CAIRO_MIME_TYPE_CCITT_FAX,
     CAIRO_MIME_TYPE_CCITT_FAX_PARAMS,
+    CAIRO_MIME_TYPE_EPS,
+    CAIRO_MIME_TYPE_EPS_PARAMS,
     NULL
 };
 

src/win32/cairo-win32-printing-surface.c

@@ -2154,6 +2154,9 @@ _cairo_win32_printing_surface_supports_fine_grained_fallbacks (void *abstract_su
  * provide correct complex rendering behaviour; cairo_surface_show_page() and
  * associated methods must be used for correct output.
  *
+ * The following mime types are supported on source patterns:
+ * %CAIRO_MIME_TYPE_JPEG, %CAIRO_MIME_TYPE_PNG.
+ *
  * Return value: the newly created surface
  *
  * Since: 1.6