Merge branch 'doc-fixes' into 'master'

More random doc fixes

See merge request cairo/cairo!437
This commit is contained in:
Adrian Johnson 2023-02-08 09:53:29 +00:00
commit cae2376dd0
15 changed files with 90 additions and 49 deletions

View file

@ -43,11 +43,11 @@
<xi:include href="xml/cairo-win32.xml"/>
<xi:include href="xml/cairo-svg.xml"/>
<xi:include href="xml/cairo-quartz.xml" />
<!--xi:include href="xml/cairo-quartz-image.xml"/-->
<xi:include href="xml/cairo-xcb.xml"/>
<xi:include href="xml/cairo-xlib.xml"/>
<xi:include href="xml/cairo-xlib-xrender.xml"/>
<xi:include href="xml/cairo-script.xml"/>
<xi:include href="xml/cairo-surface-observer.xml"/>
</chapter>
<chapter id="cairo-support">
<title>Utilities</title>

View file

@ -166,6 +166,8 @@ CAIRO_HAS_QUARTZ_SURFACE
cairo_quartz_surface_create
cairo_quartz_surface_create_for_cg_context
cairo_quartz_surface_get_cg_context
cairo_quartz_image_surface_create
cairo_quartz_image_surface_get_image
</SECTION>
<SECTION>

View file

@ -143,7 +143,6 @@ _cairo_array_truncate (cairo_array_t *array, unsigned int num_elements)
/**
* _cairo_array_index:
* @array: a #cairo_array_t
* Returns: A pointer to the object stored at @index.
*
* If the resulting value is assigned to a pointer to an object of the same
* element_size as initially passed to _cairo_array_init() then that
@ -161,6 +160,8 @@ _cairo_array_truncate (cairo_array_t *array, unsigned int num_elements)
* for (i = 0; i < _cairo_array_num_elements (&array); i++)
* ... use values[i] here ...
* </programlisting></informalexample>
*
* Returns: A pointer to the object stored at @index.
**/
void *
_cairo_array_index (cairo_array_t *array, unsigned int index)
@ -187,7 +188,6 @@ _cairo_array_index (cairo_array_t *array, unsigned int index)
/**
* _cairo_array_index_const:
* @array: a #cairo_array_t
* Returns: A pointer to the object stored at @index.
*
* If the resulting value is assigned to a pointer to an object of the same
* element_size as initially passed to _cairo_array_init() then that
@ -205,6 +205,8 @@ _cairo_array_index (cairo_array_t *array, unsigned int index)
* for (i = 0; i < _cairo_array_num_elements (&array); i++)
* ... read values[i] here ...
* </programlisting></informalexample>
*
* Returns: A pointer to the object stored at @index.
**/
const void *
_cairo_array_index_const (const cairo_array_t *array, unsigned int index)
@ -330,9 +332,10 @@ _cairo_array_allocate (cairo_array_t *array,
/**
* _cairo_array_num_elements:
* @array: a #cairo_array_t
* Returns: The number of elements stored in @array.
*
* This space was left intentionally blank, but gtk-doc filled it.
*
* Returns: The number of elements stored in @array.
**/
unsigned int
_cairo_array_num_elements (const cairo_array_t *array)
@ -343,10 +346,11 @@ _cairo_array_num_elements (const cairo_array_t *array)
/**
* _cairo_array_size:
* @array: a #cairo_array_t
* Returns: The number of elements for which there is currently space
* allocated in @array.
*
* This space was left intentionally blank, but gtk-doc filled it.
*
* Returns: The number of elements for which there is currently space
* allocated in @array.
**/
unsigned int
_cairo_array_size (const cairo_array_t *array)

View file

@ -56,7 +56,6 @@ _cairo_cache_entry_is_non_zero (const void *entry)
* @keys_equal: a function to return %TRUE if two keys are equal
* @entry_destroy: destroy notifier for cache entries
* @max_size: the maximum size for this cache
* Returns: the newly created #cairo_cache_t
*
* Creates a new cache using the keys_equal() function to determine
* the equality of entries.
@ -84,6 +83,8 @@ _cairo_cache_entry_is_non_zero (const void *entry)
* _cairo_cache_freeze() and _cairo_cache_thaw() calls can be
* used to establish a window during which no automatic removal of
* entries will occur.
*
* Returns: the newly created #cairo_cache_t
**/
cairo_status_t
_cairo_cache_init (cairo_cache_t *cache,

View file

@ -51,7 +51,7 @@ cairo_public IDWriteRenderingParams *
cairo_dwrite_font_face_get_rendering_params (cairo_font_face_t *font_face);
cairo_public void
cairo_dwrite_font_face_set_rendering_params (cairo_font_face_t *font_face, IDWriteRenderingParams *param);
cairo_dwrite_font_face_set_rendering_params (cairo_font_face_t *font_face, IDWriteRenderingParams *params);
cairo_public DWRITE_MEASURING_MODE
cairo_dwrite_font_face_get_measuring_mode (cairo_font_face_t *font_face);

View file

@ -662,7 +662,7 @@ cairo_font_options_get_variations (cairo_font_options_t *options)
/**
* cairo_font_options_set_color_mode:
* @options: a #cairo_font_options_t
* @font_color: the new color mode
* @color_mode: the new color mode
*
* Sets the color mode for the font options object. This controls
* whether color fonts are to be rendered in color or as outlines.

View file

@ -3439,9 +3439,10 @@ use_bilinear(double x, double y, double t)
/**
* _cairo_pattern_analyze_filter:
* @pattern: surface pattern
* Returns: the optimized #cairo_filter_t to use with @pattern.
*
* Possibly optimize the filter to a simpler value depending on transformation
*
* Returns: the optimized #cairo_filter_t to use with @pattern.
**/
cairo_filter_t
_cairo_pattern_analyze_filter (const cairo_pattern_t *pattern)

View file

@ -148,7 +148,7 @@ static char *ctime_r(const time_t *timep, char *buf)
* ury]" that specifies the bounding box (in PS coordinates) of the
* EPS graphics. The parameters are: lower left x, lower left y, upper
* right x, upper right y. Normally the bbox data is identical to the
* %%%BoundingBox data in the EPS file.
* \%\%\%BoundingBox data in the EPS file.
*
**/

View file

@ -377,15 +377,27 @@ cairo_quartz_image_surface_create (cairo_surface_t *surface)
}
/**
* cairo_quartz_image_surface_get_image:
* @surface: a #cairo_surface_t
*
* Returns a #cairo_surface_t image surface that refers to the same bits
* as the image of the quartz surface.
*
* Return value: a #cairo_surface_t (owned by the quartz #cairo_surface_t),
* or %NULL if the quartz surface is not an image surface.
*
* Since: 1.6
*/
cairo_surface_t *
cairo_quartz_image_surface_get_image (cairo_surface_t *asurface)
cairo_quartz_image_surface_get_image (cairo_surface_t *surface)
{
cairo_quartz_image_surface_t *surface = (cairo_quartz_image_surface_t*) asurface;
cairo_quartz_image_surface_t *qsurface = (cairo_quartz_image_surface_t*) surface;
/* Throw an error for a non-quartz surface */
if (! _cairo_surface_is_quartz (asurface)) {
if (! _cairo_surface_is_quartz (surface)) {
return SURFACE_ERROR_TYPE_MISMATCH;
}
return (cairo_surface_t*) surface->imageSurface;
return (cairo_surface_t*) qsurface->imageSurface;
}

View file

@ -2660,6 +2660,8 @@ _cairo_scaled_glyph_set_path (cairo_scaled_glyph_t *scaled_glyph,
* @recording_surface: The recording surface
* @foreground_color: The foreground color that was used to record the
* glyph, or NULL if foreground color not required.
*
* Sets the surface that was used to record the glyph.
*/
void
_cairo_scaled_glyph_set_recording_surface (cairo_scaled_glyph_t *scaled_glyph,
@ -2691,6 +2693,8 @@ _cairo_scaled_glyph_set_recording_surface (cairo_scaled_glyph_t *scaled_glyph,
* @foreground_marker_color: The foreground color that was used to
* substitute the foreground_marker, or NULL if foreground_marker not
* used when rendering the surface color.
*
* Sets the color surface of the glyph.
*/
void
_cairo_scaled_glyph_set_color_surface (cairo_scaled_glyph_t *scaled_glyph,

View file

@ -54,6 +54,15 @@
#include "cairo-script-private.h"
#endif
/**
* SECTION:cairo-surface-observer
* @Title: Surface Observer
* @Short_Description: Observing other surfaces
* @See_Also: #cairo_surface_t
*
* A surface that exists solely to watch another is doing.
*/
static const cairo_surface_backend_t _cairo_surface_observer_backend;
/* observation/stats */

View file

@ -73,9 +73,9 @@ typedef enum _cairo_svg_version {
* lengths in the SVG specification.
*
* See also:
* https://www.w3.org/TR/SVG/coords.html#Units
* https://www.w3.org/TR/SVG/types.html#DataTypeLength
* https://www.w3.org/TR/css-values-3/#lengths
* - [SVG Units](https://www.w3.org/TR/SVG/coords.html#Units)
* - [SVG Types](https://www.w3.org/TR/SVG/types.html#DataTypeLength)
* - [CSS Length](https://www.w3.org/TR/css-values-3/#lengths)
*
* Since: 1.16
**/

View file

@ -1166,9 +1166,8 @@ cairo_set_fill_rule (cairo_t *cr, cairo_fill_rule_t fill_rule)
* cairo_set_line_width() and ignore this note.
*
* As with the other stroke parameters, the current line width is
* examined by cairo_stroke(), cairo_stroke_extents(), and
* cairo_stroke_to_path(), but does not have any effect during path
* construction.
* examined by cairo_stroke(), and cairo_stroke_extents(), but does not have
* any effect during path construction.
*
* The default line width value is 2.0.
*
@ -1242,9 +1241,8 @@ slim_hidden_def (cairo_set_hairline);
* styles are drawn.
*
* As with the other stroke parameters, the current line cap style is
* examined by cairo_stroke(), cairo_stroke_extents(), and
* cairo_stroke_to_path(), but does not have any effect during path
* construction.
* examined by cairo_stroke(), and cairo_stroke_extents(), but does not have
* any effect during path construction.
*
* The default line cap style is %CAIRO_LINE_CAP_BUTT.
*
@ -1274,9 +1272,8 @@ slim_hidden_def (cairo_set_line_cap);
* styles are drawn.
*
* As with the other stroke parameters, the current line join style is
* examined by cairo_stroke(), cairo_stroke_extents(), and
* cairo_stroke_to_path(), but does not have any effect during path
* construction.
* examined by cairo_stroke(), and cairo_stroke_extents(), but does not have
* any effect during path construction.
*
* The default line join style is %CAIRO_LINE_JOIN_MITER.
*
@ -1411,9 +1408,8 @@ cairo_get_dash (cairo_t *cr,
* converted to a bevel.
*
* As with the other stroke parameters, the current line miter limit is
* examined by cairo_stroke(), cairo_stroke_extents(), and
* cairo_stroke_to_path(), but does not have any effect during path
* construction.
* examined by cairo_stroke(), and cairo_stroke_extents(), but does not have
* any effect during path construction.
*
* The default miter limit value is 10.0, which will convert joins
* with interior angles less than 11 degrees to bevels instead of
@ -2941,7 +2937,7 @@ cairo_copy_clip_rectangle_list (cairo_t *cr)
* CAIRO_TAG_DEST:
*
* Create a destination for a hyperlink. Destination tag attributes
* are detailed at [Destinations][dests].
* are detailed at [Destinations][dest].
*
* Since: 1.16
**/
@ -2950,7 +2946,7 @@ cairo_copy_clip_rectangle_list (cairo_t *cr)
* CAIRO_TAG_LINK:
*
* Create hyperlink. Link tag attributes are detailed at
* [Links][links].
* [Links][link].
*
* Since: 1.16
**/
@ -4044,7 +4040,7 @@ slim_hidden_def (cairo_has_current_point);
* cairo_move_to(), cairo_line_to(), cairo_curve_to(),
* cairo_rel_move_to(), cairo_rel_line_to(), cairo_rel_curve_to(),
* cairo_arc(), cairo_arc_negative(), cairo_rectangle(),
* cairo_text_path(), cairo_glyph_path(), cairo_stroke_to_path().
* cairo_text_path(), cairo_glyph_path().
*
* Some functions use and alter the current point but do not
* otherwise change current path:

View file

@ -295,6 +295,7 @@ typedef struct _cairo_user_data_key {
* @CAIRO_STATUS_WIN32_GDI_ERROR: error occurred in the Windows Graphics Device Interface (Since 1.16)
* @CAIRO_STATUS_TAG_ERROR: invalid tag name, attributes, or nesting (Since 1.16)
* @CAIRO_STATUS_DWRITE_ERROR: error occurred in the Windows Direct Write API (Since 1.18)
* @CAIRO_STATUS_SVG_FONT_ERROR: error occurred in OpenType-SVG font rendering (Since 1.18)
* @CAIRO_STATUS_LAST_STATUS: this is a special value indicating the number of
* status values defined in this enumeration. When using this value, note
* that the version of cairo at run-time may have additional status values
@ -2448,26 +2449,37 @@ cairo_surface_status (cairo_surface_t *surface);
* @CAIRO_SURFACE_TYPE_PS: The surface is of type ps, since 1.2
* @CAIRO_SURFACE_TYPE_XLIB: The surface is of type xlib, since 1.2
* @CAIRO_SURFACE_TYPE_XCB: The surface is of type xcb, since 1.2
* @CAIRO_SURFACE_TYPE_GLITZ: The surface is of type glitz, since 1.2
* @CAIRO_SURFACE_TYPE_GLITZ: The surface is of type glitz, since 1.2, deprecated 1.18
* (glitz support have been removed, this surface type will never be set by cairo)
* @CAIRO_SURFACE_TYPE_QUARTZ: The surface is of type quartz, since 1.2
* @CAIRO_SURFACE_TYPE_WIN32: The surface is of type win32, since 1.2
* @CAIRO_SURFACE_TYPE_BEOS: The surface is of type beos, since 1.2
* @CAIRO_SURFACE_TYPE_DIRECTFB: The surface is of type directfb, since 1.2
* @CAIRO_SURFACE_TYPE_BEOS: The surface is of type beos, since 1.2, deprecated 1.18
* (beos support have been removed, this surface type will never be set by cairo)
* @CAIRO_SURFACE_TYPE_DIRECTFB: The surface is of type directfb, since 1.2, deprecated 1.18
* (directfb support have been removed, this surface type will never be set by cairo)
* @CAIRO_SURFACE_TYPE_SVG: The surface is of type svg, since 1.2
* @CAIRO_SURFACE_TYPE_OS2: The surface is of type os2, since 1.4
* @CAIRO_SURFACE_TYPE_OS2: The surface is of type os2, since 1.4, deprecated 1.18
* (os2 support have been removed, this surface type will never be set by cairo)
* @CAIRO_SURFACE_TYPE_WIN32_PRINTING: The surface is a win32 printing surface, since 1.6
* @CAIRO_SURFACE_TYPE_QUARTZ_IMAGE: The surface is of type quartz_image, since 1.6
* @CAIRO_SURFACE_TYPE_SCRIPT: The surface is of type script, since 1.10
* @CAIRO_SURFACE_TYPE_QT: The surface is of type Qt, since 1.10
* @CAIRO_SURFACE_TYPE_QT: The surface is of type Qt, since 1.10, deprecated 1.18
* (Ot support have been removed, this surface type will never be set by cairo)
* @CAIRO_SURFACE_TYPE_RECORDING: The surface is of type recording, since 1.10
* @CAIRO_SURFACE_TYPE_VG: The surface is a OpenVG surface, since 1.10
* @CAIRO_SURFACE_TYPE_GL: The surface is of type OpenGL, since 1.10
* @CAIRO_SURFACE_TYPE_DRM: The surface is of type Direct Render Manager, since 1.10
* @CAIRO_SURFACE_TYPE_VG: The surface is a OpenVG surface, since 1.10, deprecated 1.18
* (OpenVG support have been removed, this surface type will never be set by cairo)
* @CAIRO_SURFACE_TYPE_GL: The surface is of type OpenGL, since 1.10, deprecated 1.18
* (OpenGL support have been removed, this surface type will never be set by cairo)
* @CAIRO_SURFACE_TYPE_DRM: The surface is of type Direct Render Manager, since 1.10, deprecated 1.18
* (DRM support have been removed, this surface type will never be set by cairo)
* @CAIRO_SURFACE_TYPE_TEE: The surface is of type 'tee' (a multiplexing surface), since 1.10
* @CAIRO_SURFACE_TYPE_XML: The surface is of type XML (for debugging), since 1.10
* @CAIRO_SURFACE_TYPE_SKIA: The surface is of type Skia, since 1.10, deprecated 1.18
* (Skia support have been removed, this surface type will never be set by cairo)
* @CAIRO_SURFACE_TYPE_SUBSURFACE: The surface is a subsurface created with
* cairo_surface_create_for_rectangle(), since 1.10
* @CAIRO_SURFACE_TYPE_COGL: This surface is of type Cogl, since 1.12
* @CAIRO_SURFACE_TYPE_COGL: This surface is of type Cogl, since 1.12, deprecated 1.18
* (Cogl support have been removed, this surface type will never be set by cairo)
*
* #cairo_surface_type_t is used to describe the type of a given
* surface. The surface types are also known as "backends" or "surface

View file

@ -923,7 +923,7 @@ _cairo_dwrite_scaled_font_init_glyph_color_surface(cairo_dwrite_scaled_font_t *s
RefPtr<IDWriteColorGlyphRunEnumerator1> run_enumerator;
HRESULT hr;
/**
/*
* We transform by the inverse transformation here. This will put our glyph
* locations in the space in which we draw. Which is later transformed by
* the transformation matrix that we use. This will transform the
@ -932,7 +932,7 @@ _cairo_dwrite_scaled_font_init_glyph_color_surface(cairo_dwrite_scaled_font_t *s
*/
cairo_matrix_transform_point(&scaled_font->mat_inverse, &x, &y);
offset.advanceOffset = (FLOAT)x;
/** Y-axis is inverted */
/* Y-axis is inverted */
offset.ascenderOffset = -(FLOAT)y;
run.fontFace = dwrite_font_face->dwriteface;
@ -1205,7 +1205,7 @@ _cairo_dwrite_scaled_font_init_glyph_surface(cairo_dwrite_scaled_font_t *scaled_
if (status)
goto FAIL;
/**
/*
* We transform by the inverse transformation here. This will put our glyph
* locations in the space in which we draw. Which is later transformed by
* the transformation matrix that we use. This will transform the
@ -1214,7 +1214,7 @@ _cairo_dwrite_scaled_font_init_glyph_surface(cairo_dwrite_scaled_font_t *scaled_
*/
cairo_matrix_transform_point(&scaled_font->mat_inverse, &x, &y);
offset.advanceOffset = (FLOAT)x;
/** Y-axis is inverted */
/* Y-axis is inverted */
offset.ascenderOffset = -(FLOAT)y;
area.top = 0;
@ -1573,7 +1573,7 @@ _dwrite_draw_glyphs_to_gdi_surface_gdi(cairo_win32_surface_t *surface,
else
params = DWriteFactory::DefaultRenderingParams();
/**
/*
* We set the number of pixels per DIP to 1.0. This is because we always want
* to draw in device pixels, and not device independent pixels. On high DPI
* systems this value will be higher than 1.0 and automatically upscale
@ -1716,7 +1716,7 @@ _cairo_dwrite_show_glyphs_on_surface(void *surface,
largestY = (INT32)glyphs[i].y;
}
}
/**
/*
* Here we try to get a rough estimate of the area that this glyph run will
* cover on the surface. Since we use GDI interop to draw we will be copying
* data around the size of the area of the surface that we map. We will want
@ -1776,7 +1776,7 @@ _cairo_dwrite_show_glyphs_on_surface(void *surface,
double x = glyphs[i].x - fontArea.left + EPSILON;
double y = glyphs[i].y - fontArea.top;
cairo_matrix_transform_point(&dwritesf->mat_inverse, &x, &y);
/**
/*
* Since we will multiply by our ctm matrix later for rotation effects
* and such, adjust positions by the inverse matrix now. The Y-axis
* is inverted so the offset becomes negative.