[cairo-commit] 6 commits - doc/public NEWS src/cairo.c
src/cairo-font.c src/cairo.h src/cairo-pattern.c
src/cairo-scaled-font.c src/cairo-surface.c
src/cairo-win32-font.c src/cairo-win32-surface.c
Behdad Esfahbod
behdad at kemper.freedesktop.org
Fri Mar 2 19:53:02 PST 2007
NEWS | 7 +
doc/public/Headers.mk | 2
doc/public/tmpl/cairo-font.sgml | 33 ++++---
doc/public/tmpl/cairo-pattern.sgml | 37 +++++++
doc/public/tmpl/cairo-scaled-font.sgml | 31 ++++++
doc/public/tmpl/cairo-surface.sgml | 74 ++++++++-------
doc/public/tmpl/cairo-text.sgml | 33 ++++---
doc/public/tmpl/cairo.sgml | 40 ++++++++
src/cairo-font.c | 7 +
src/cairo-pattern.c | 22 ++++
src/cairo-scaled-font.c | 3
src/cairo-surface.c | 9 +
src/cairo-win32-font.c | 24 ++++-
src/cairo-win32-surface.c | 1
src/cairo.c | 79 +++++++++++++++-
src/cairo.h | 154 ++++++++++++++++++++++++++++-----
16 files changed, 458 insertions(+), 98 deletions(-)
New commits:
diff-tree 55d480612754dca652b5324d815e0429c745fec3 (from 77b27fd06b9f0e7ff5dedd4b41327e456d33e3cf)
Author: Behdad Esfahbod <behdad at behdad.org>
Date: Fri Mar 2 22:52:38 2007 -0500
[NEWS] Add note about documentation improvements
diff --git a/NEWS b/NEWS
index e2b77d1..19d8e9b 100644
--- a/NEWS
+++ b/NEWS
@@ -105,6 +105,13 @@ backend in previous snapshots, that impl
renamed from "nquartz" to "quartz" and has replaced the old quartz
backend.)
+Documentation improvements
+--------------------------
+We have added documentation for several functions and types that
+were previously undocumented, and improved documentation on other
+ones. As of this release, there remain only two undocumented
+symbols: cairo_filter_t and cairo_operator_t.
+
Other bug fixes
---------------
• cairo-svg: Fix bug that was preventing text from appearing in many
diff-tree 77b27fd06b9f0e7ff5dedd4b41327e456d33e3cf (from 1082fed6929a696455f27821819c6af4f575156d)
Author: Behdad Esfahbod <behdad at behdad.org>
Date: Fri Mar 2 22:45:50 2007 -0500
[doc] Update templates
diff --git a/doc/public/tmpl/cairo-font.sgml b/doc/public/tmpl/cairo-font.sgml
index 097b047..add99ec 100644
--- a/doc/public/tmpl/cairo-font.sgml
+++ b/doc/public/tmpl/cairo-font.sgml
@@ -49,44 +49,53 @@ Base class for fonts
@Returns:
-<!-- ##### FUNCTION cairo_font_face_get_user_data ##### -->
+<!-- ##### ENUM cairo_font_type_t ##### -->
+<para>
+
+</para>
+
+ at CAIRO_FONT_TYPE_TOY:
+ at CAIRO_FONT_TYPE_FT:
+ at CAIRO_FONT_TYPE_WIN32:
+ at CAIRO_FONT_TYPE_ATSUI:
+
+<!-- ##### FUNCTION cairo_font_face_get_type ##### -->
<para>
</para>
@font_face:
- at key:
@Returns:
-<!-- ##### FUNCTION cairo_font_face_set_user_data ##### -->
+<!-- ##### FUNCTION cairo_font_face_get_reference_count ##### -->
<para>
</para>
@font_face:
- at key:
- at user_data:
- at destroy:
@Returns:
-<!-- ##### ENUM cairo_font_type_t ##### -->
+<!-- ##### FUNCTION cairo_font_face_set_user_data ##### -->
<para>
</para>
- at CAIRO_FONT_TYPE_TOY:
- at CAIRO_FONT_TYPE_FT:
- at CAIRO_FONT_TYPE_WIN32:
- at CAIRO_FONT_TYPE_ATSUI:
+ at font_face:
+ at key:
+ at user_data:
+ at destroy:
+ at Returns:
-<!-- ##### FUNCTION cairo_font_face_get_type ##### -->
+
+<!-- ##### FUNCTION cairo_font_face_get_user_data ##### -->
<para>
</para>
@font_face:
+ at key:
@Returns:
diff --git a/doc/public/tmpl/cairo-pattern.sgml b/doc/public/tmpl/cairo-pattern.sgml
index 56b5a9d..8925b11 100644
--- a/doc/public/tmpl/cairo-pattern.sgml
+++ b/doc/public/tmpl/cairo-pattern.sgml
@@ -182,21 +182,21 @@ Gradients and filtered sources
@Returns:
-<!-- ##### FUNCTION cairo_pattern_destroy ##### -->
+<!-- ##### FUNCTION cairo_pattern_reference ##### -->
<para>
</para>
@pattern:
+ at Returns:
-<!-- ##### FUNCTION cairo_pattern_reference ##### -->
+<!-- ##### FUNCTION cairo_pattern_destroy ##### -->
<para>
</para>
@pattern:
- at Returns:
<!-- ##### FUNCTION cairo_pattern_status ##### -->
@@ -303,3 +303,34 @@ Gradients and filtered sources
@Returns:
+<!-- ##### FUNCTION cairo_pattern_get_reference_count ##### -->
+<para>
+
+</para>
+
+ at pattern:
+ at Returns:
+
+
+<!-- ##### FUNCTION cairo_pattern_set_user_data ##### -->
+<para>
+
+</para>
+
+ at pattern:
+ at key:
+ at user_data:
+ at destroy:
+ at Returns:
+
+
+<!-- ##### FUNCTION cairo_pattern_get_user_data ##### -->
+<para>
+
+</para>
+
+ at pattern:
+ at key:
+ at Returns:
+
+
diff --git a/doc/public/tmpl/cairo-scaled-font.sgml b/doc/public/tmpl/cairo-scaled-font.sgml
index 3e1ce48..4175d19 100644
--- a/doc/public/tmpl/cairo-scaled-font.sgml
+++ b/doc/public/tmpl/cairo-scaled-font.sgml
@@ -159,3 +159,34 @@ Caching metrics for a particular font si
@Returns:
+<!-- ##### FUNCTION cairo_scaled_font_get_reference_count ##### -->
+<para>
+
+</para>
+
+ at scaled_font:
+ at Returns:
+
+
+<!-- ##### FUNCTION cairo_scaled_font_set_user_data ##### -->
+<para>
+
+</para>
+
+ at scaled_font:
+ at key:
+ at user_data:
+ at destroy:
+ at Returns:
+
+
+<!-- ##### FUNCTION cairo_scaled_font_get_user_data ##### -->
+<para>
+
+</para>
+
+ at scaled_font:
+ at key:
+ at Returns:
+
+
diff --git a/doc/public/tmpl/cairo-surface.sgml b/doc/public/tmpl/cairo-surface.sgml
index 2f7d49e..15929f3 100644
--- a/doc/public/tmpl/cairo-surface.sgml
+++ b/doc/public/tmpl/cairo-surface.sgml
@@ -44,15 +44,16 @@ Base class for surfaces
@Returns:
-<!-- ##### FUNCTION cairo_surface_destroy ##### -->
+<!-- ##### FUNCTION cairo_surface_reference ##### -->
<para>
</para>
@surface:
+ at Returns:
-<!-- ##### FUNCTION cairo_surface_finish ##### -->
+<!-- ##### FUNCTION cairo_surface_destroy ##### -->
<para>
</para>
@@ -60,51 +61,46 @@ Base class for surfaces
@surface:
-<!-- ##### FUNCTION cairo_surface_flush ##### -->
+<!-- ##### FUNCTION cairo_surface_status ##### -->
<para>
</para>
@surface:
+ at Returns:
-<!-- ##### FUNCTION cairo_surface_get_font_options ##### -->
+<!-- ##### FUNCTION cairo_surface_finish ##### -->
<para>
</para>
@surface:
- at options:
-<!-- ##### FUNCTION cairo_surface_get_content ##### -->
+<!-- ##### FUNCTION cairo_surface_flush ##### -->
<para>
</para>
@surface:
- at Returns:
-<!-- ##### FUNCTION cairo_surface_set_user_data ##### -->
+<!-- ##### FUNCTION cairo_surface_get_font_options ##### -->
<para>
</para>
@surface:
- at key:
- at user_data:
- at destroy:
- at Returns:
+ at options:
-<!-- ##### FUNCTION cairo_surface_get_user_data ##### -->
+<!-- ##### FUNCTION cairo_surface_get_content ##### -->
<para>
</para>
@surface:
- at key:
@Returns:
@@ -128,15 +124,6 @@ Base class for surfaces
@height:
-<!-- ##### FUNCTION cairo_surface_reference ##### -->
-<para>
-
-</para>
-
- at surface:
- at Returns:
-
-
<!-- ##### FUNCTION cairo_surface_set_device_offset ##### -->
<para>
@@ -167,15 +154,6 @@ Base class for surfaces
@y_pixels_per_inch:
-<!-- ##### FUNCTION cairo_surface_status ##### -->
-<para>
-
-</para>
-
- at surface:
- at Returns:
-
-
<!-- ##### ENUM cairo_surface_type_t ##### -->
<para>
@@ -192,7 +170,6 @@ Base class for surfaces
@CAIRO_SURFACE_TYPE_BEOS:
@CAIRO_SURFACE_TYPE_DIRECTFB:
@CAIRO_SURFACE_TYPE_SVG:
- at CAIRO_SURFACE_TYPE_NQUARTZ:
@CAIRO_SURFACE_TYPE_OS2:
<!-- ##### FUNCTION cairo_surface_get_type ##### -->
@@ -204,3 +181,34 @@ Base class for surfaces
@Returns:
+<!-- ##### FUNCTION cairo_surface_get_reference_count ##### -->
+<para>
+
+</para>
+
+ at surface:
+ at Returns:
+
+
+<!-- ##### FUNCTION cairo_surface_set_user_data ##### -->
+<para>
+
+</para>
+
+ at surface:
+ at key:
+ at user_data:
+ at destroy:
+ at Returns:
+
+
+<!-- ##### FUNCTION cairo_surface_get_user_data ##### -->
+<para>
+
+</para>
+
+ at surface:
+ at key:
+ at Returns:
+
+
diff --git a/doc/public/tmpl/cairo-text.sgml b/doc/public/tmpl/cairo-text.sgml
index 87f626c..00366f2 100644
--- a/doc/public/tmpl/cairo-text.sgml
+++ b/doc/public/tmpl/cairo-text.sgml
@@ -98,26 +98,34 @@ Rendering text and sets of glyphs
@options:
-<!-- ##### FUNCTION cairo_show_text ##### -->
+<!-- ##### FUNCTION cairo_set_font_face ##### -->
<para>
</para>
@cr:
- at utf8:
+ at font_face:
-<!-- ##### FUNCTION cairo_show_glyphs ##### -->
+<!-- ##### FUNCTION cairo_get_font_face ##### -->
<para>
</para>
@cr:
- at glyphs:
- at num_glyphs:
+ at Returns:
-<!-- ##### FUNCTION cairo_get_font_face ##### -->
+<!-- ##### FUNCTION cairo_set_scaled_font ##### -->
+<para>
+
+</para>
+
+ at cr:
+ at scaled_font:
+
+
+<!-- ##### FUNCTION cairo_get_scaled_font ##### -->
<para>
</para>
@@ -126,31 +134,32 @@ Rendering text and sets of glyphs
@Returns:
-<!-- ##### FUNCTION cairo_font_extents ##### -->
+<!-- ##### FUNCTION cairo_show_text ##### -->
<para>
</para>
@cr:
- at extents:
+ at utf8:
-<!-- ##### FUNCTION cairo_set_font_face ##### -->
+<!-- ##### FUNCTION cairo_show_glyphs ##### -->
<para>
</para>
@cr:
- at font_face:
+ at glyphs:
+ at num_glyphs:
-<!-- ##### FUNCTION cairo_set_scaled_font ##### -->
+<!-- ##### FUNCTION cairo_font_extents ##### -->
<para>
</para>
@cr:
- at scaled_font:
+ at extents:
<!-- ##### FUNCTION cairo_text_extents ##### -->
diff --git a/doc/public/tmpl/cairo.sgml b/doc/public/tmpl/cairo.sgml
index 4b9dc0e..2f5c637 100644
--- a/doc/public/tmpl/cairo.sgml
+++ b/doc/public/tmpl/cairo.sgml
@@ -481,6 +481,15 @@ The cairo drawing context
@rectangle_list:
+<!-- ##### FUNCTION cairo_copy_clip_rectangle_list ##### -->
+<para>
+
+</para>
+
+ at cr:
+ at Returns:
+
+
<!-- ##### FUNCTION cairo_fill ##### -->
<para>
@@ -612,3 +621,34 @@ The cairo drawing context
@cr:
+<!-- ##### FUNCTION cairo_get_reference_count ##### -->
+<para>
+
+</para>
+
+ at cr:
+ at Returns:
+
+
+<!-- ##### FUNCTION cairo_set_user_data ##### -->
+<para>
+
+</para>
+
+ at cr:
+ at key:
+ at user_data:
+ at destroy:
+ at Returns:
+
+
+<!-- ##### FUNCTION cairo_get_user_data ##### -->
+<para>
+
+</para>
+
+ at cr:
+ at key:
+ at Returns:
+
+
diff-tree 1082fed6929a696455f27821819c6af4f575156d (from e37b6ca3e2c55256debf1fdfde83934fa9b28c1d)
Author: Behdad Esfahbod <behdad at behdad.org>
Date: Fri Mar 2 22:42:17 2007 -0500
[doc] Docuemnt all symbols but cairo_filter_t and cairo_operator_t
Lets see if this is enough to push Carl Worth document those two.
diff --git a/src/cairo-font.c b/src/cairo-font.c
index 0f72661..33e7041 100644
--- a/src/cairo-font.c
+++ b/src/cairo-font.c
@@ -72,13 +72,16 @@ CAIRO_MUTEX_DECLARE (cairo_font_face_mut
/**
* cairo_font_face_reference:
- * @font_face: a #cairo_font_face_t, (may be NULL in which case this
+ * @font_face: a #cairo_font_face_t, (may be %NULL in which case this
* function does nothing).
*
* Increases the reference count on @font_face by one. This prevents
* @font_face from being destroyed until a matching call to
* cairo_font_face_destroy() is made.
*
+ * The number of references to a #cairo_font_face_t can be get using
+ * cairo_font_face_get_reference_count().
+ *
* Return value: the referenced #cairo_font_face_t.
**/
cairo_font_face_t *
diff --git a/src/cairo-pattern.c b/src/cairo-pattern.c
index ebb56e3..a17107c 100644
--- a/src/cairo-pattern.c
+++ b/src/cairo-pattern.c
@@ -496,6 +496,9 @@ cairo_pattern_create_radial (double cx0,
* @pattern from being destroyed until a matching call to
* cairo_pattern_destroy() is made.
*
+ * The number of references to a #cairo_pattern_t can be get using
+ * cairo_pattern_get_reference_count().
+ *
* Return value: the referenced #cairo_pattern_t.
**/
cairo_pattern_t *
diff --git a/src/cairo-scaled-font.c b/src/cairo-scaled-font.c
index c792a4f..c34a0cf 100755
--- a/src/cairo-scaled-font.c
+++ b/src/cairo-scaled-font.c
@@ -536,6 +536,9 @@ slim_hidden_def (cairo_scaled_font_creat
* @scaled_font from being destroyed until a matching call to
* cairo_scaled_font_destroy() is made.
*
+ * The number of references to a #cairo_scaled_font_t can be get using
+ * cairo_scaled_font_get_reference_count().
+ *
* Returns: the referenced #cairo_scaled_font_t
**/
cairo_scaled_font_t *
diff --git a/src/cairo-surface.c b/src/cairo-surface.c
index 232b62a..1f5de8f 100644
--- a/src/cairo-surface.c
+++ b/src/cairo-surface.c
@@ -349,6 +349,9 @@ _cairo_surface_get_clip_mode (cairo_surf
* @surface from being destroyed until a matching call to
* cairo_surface_destroy() is made.
*
+ * The number of references to a #cairo_surface_t can be get using
+ * cairo_surface_get_reference_count().
+ *
* Return value: the referenced #cairo_surface_t.
**/
cairo_surface_t *
diff --git a/src/cairo.c b/src/cairo.c
index ef07828..fba24e7 100644
--- a/src/cairo.c
+++ b/src/cairo.c
@@ -222,6 +222,9 @@ slim_hidden_def (cairo_create);
* @cr from being destroyed until a matching call to cairo_destroy()
* is made.
*
+ * The number of references to a #cairo_t can be get using
+ * cairo_get_reference_count().
+ *
* Return value: the referenced #cairo_t.
**/
cairo_t *
diff --git a/src/cairo.h b/src/cairo.h
index 9091d54..a74871d 100644
--- a/src/cairo.h
+++ b/src/cairo.h
@@ -80,6 +80,13 @@ typedef int cairo_bool_t;
*
* A #cairo_t contains the current state of the rendering device,
* including coordinates of yet to be drawn shapes.
+ *
+ * Cairo contexts, as #cairo_t objects are named, are central to
+ * cairo and all drawing with cairo is always done to a #cairo_t
+ * object.
+ *
+ * Memory management of #cairo_t is done with
+ * cairo_reference() and cairo_destroy().
**/
typedef struct _cairo cairo_t;
@@ -88,9 +95,13 @@ typedef struct _cairo cairo_t;
*
* A #cairo_surface_t represents an image, either as the destination
* of a drawing operation or as source when drawing onto another
- * surface. There are different subtypes of cairo_surface_t for
+ * surface. To draw to a #cairo_surface_t, create a cairo context
+ * with the surface as the target, using cairo_create().
+ *
+ * There are different subtypes of #cairo_surface_t for
* different drawing backends; for example, cairo_image_surface_create()
* creates a bitmap image in memory.
+ * The type of a surface can be queried with cairo_surface_get_type().
*
* Memory management of #cairo_surface_t is done with
* cairo_surface_reference() and cairo_surface_destroy().
@@ -120,6 +131,25 @@ typedef struct _cairo_matrix {
double x0; double y0;
} cairo_matrix_t;
+/**
+ * cairo_pattern_t:
+ *
+ * A #cairo_pattern_t represents a source when drawing onto a
+ * surface. There are different subtypes of #cairo_pattern_t,
+ * for different types of sources; for example,
+ * cairo_pattern_create_rgb() creates a pattern for a solid
+ * opaque color.
+ *
+ * Other than various cairo_pattern_create_<emphasis>type</emphasis>
+ * functions, some of the pattern types can be implicitly created
+ * using vairous cairo_set_source_<emphasis>type</emphasis> functions;
+ * for example cairo_set_source_rgb().
+ *
+ * The type of a pattern can be queried with cairo_pattern_get_type().
+ *
+ * Memory management of #cairo_pattern_t is done with
+ * cairo_pattern_reference() and cairo_pattern_destroy().
+ **/
typedef struct _cairo_pattern cairo_pattern_t;
/**
@@ -415,7 +445,7 @@ cairo_set_line_width (cairo_t *cr, doubl
* @CAIRO_LINE_CAP_ROUND: use a round ending, the center of the circle is the end point
* @CAIRO_LINE_CAP_SQUARE: use squared ending, the center of the square is the end point
*
- * enumeration for style of line-endings
+ * Specifies how to render the endpoint of a line when stroking.
**/
typedef enum _cairo_line_cap {
CAIRO_LINE_CAP_BUTT,
@@ -426,6 +456,17 @@ typedef enum _cairo_line_cap {
cairo_public void
cairo_set_line_cap (cairo_t *cr, cairo_line_cap_t line_cap);
+/**
+ * cairo_line_join_t
+ * @CAIRO_LINE_JOIN_MITER: use a sharp (angled) corner, see
+ * cairo_set_miter_limit()
+ * @CAIRO_LINE_JOIN_ROUND: use a rounded join, the center of the circle is the
+ * joint point
+ * @CAIRO_LINE_JOIN_BEVEL: use a cut-off join, the join is cut off at half
+ * the line width from the joint point
+ *
+ * Specifies how to render the junction of two lines when stroking.
+ **/
typedef enum _cairo_line_join {
CAIRO_LINE_JOIN_MITER,
CAIRO_LINE_JOIN_ROUND,
@@ -656,6 +697,13 @@ cairo_rectangle_list_destroy (cairo_rect
* resolution. A cairo_scaled_font_t is most useful for low-level font
* usage where a library or application wants to cache a reference
* to a scaled font to speed up the computation of metrics.
+ *
+ * There are various types of scaled fonts, depending on the
+ * <firstterm>font backend</firstterm> they use. The type of a
+ * scaled font can be queried using cairo_scaled_font_get_type().
+ *
+ * Memory management of #cairo_scaled_font_t is done with
+ * cairo_scaled_font_reference() and cairo_scaled_font_destroy().
**/
typedef struct _cairo_scaled_font cairo_scaled_font_t;
@@ -668,6 +716,13 @@ typedef struct _cairo_scaled_font cairo_
* directions) . A font face can be set on a #cairo_t by using
* cairo_set_font_face(); the size and font matrix are set with
* cairo_set_font_size() and cairo_set_font_matrix().
+ *
+ * There are various types of font faces, depending on the
+ * <firstterm>font backend</firstterm> they use. The type of a
+ * font face can be queried using cairo_font_face_get_type().
+ *
+ * Memory management of #cairo_font_face_t is done with
+ * cairo_font_face_reference() and cairo_font_face_destroy().
**/
typedef struct _cairo_font_face cairo_font_face_t;
@@ -786,12 +841,27 @@ typedef struct {
double max_y_advance;
} cairo_font_extents_t;
+/**
+ * cairo_font_slant_t:
+ * @CAIRO_FONT_SLANT_NORMAL: Upright font style
+ * @CAIRO_FONT_SLANT_ITALIC: Italic font style
+ * @CAIRO_FONT_SLANT_OBLIQUE: Oblique font style
+ *
+ * Specifies variants of a font face based on their slant.
+ **/
typedef enum _cairo_font_slant {
CAIRO_FONT_SLANT_NORMAL,
CAIRO_FONT_SLANT_ITALIC,
CAIRO_FONT_SLANT_OBLIQUE
} cairo_font_slant_t;
+/**
+ * cairo_font_weight_t:
+ * @CAIRO_FONT_WEIGHT_NORMAL: Normal font weight
+ * @CAIRO_FONT_WEIGHT_BOLD: Bold font weight
+ *
+ * Specifies variants of a font face based on their weight.
+ **/
typedef enum _cairo_font_weight {
CAIRO_FONT_WEIGHT_NORMAL,
CAIRO_FONT_WEIGHT_BOLD
diff-tree e37b6ca3e2c55256debf1fdfde83934fa9b28c1d (from 9be961eb0c8c85b04287a5b85f7fd72dac160949)
Author: Behdad Esfahbod <behdad at behdad.org>
Date: Fri Mar 2 22:03:27 2007 -0500
Beautify cairo.h
diff --git a/src/cairo.h b/src/cairo.h
index 727ae39..9091d54 100644
--- a/src/cairo.h
+++ b/src/cairo.h
@@ -72,7 +72,7 @@ cairo_version_string (void);
* /<!-- -->* do something *<!-- -->/
* }
* </programlisting></informalexample>
- */
+ **/
typedef int cairo_bool_t;
/**
@@ -94,7 +94,7 @@ typedef struct _cairo cairo_t;
*
* Memory management of #cairo_surface_t is done with
* cairo_surface_reference() and cairo_surface_destroy().
- */
+ **/
typedef struct _cairo_surface cairo_surface_t;
/**
@@ -129,7 +129,7 @@ typedef struct _cairo_pattern cairo_patt
* #cairo_destroy_func_t the type of function which is called when a
* data element is destroyed. It is passed the pointer to the data
* element and should free any memory and resources allocated for it.
- */
+ **/
typedef void (*cairo_destroy_func_t) (void *data);
/**
@@ -141,7 +141,7 @@ typedef void (*cairo_destroy_func_t) (vo
* and there is no need to initialize the object; only the unique
* address of a #cairo_data_key_t object is used. Typically, you
* would just use the address of a static #cairo_data_key_t object.
- */
+ **/
typedef struct _cairo_user_data_key {
int unused;
} cairo_user_data_key_t;
@@ -219,7 +219,7 @@ typedef enum _cairo_status {
* Note: The large values here are designed to keep cairo_content_t
* values distinct from cairo_format_t values so that the
* implementation can detect the error if users confuse the two types.
- */
+ **/
typedef enum _cairo_content {
CAIRO_CONTENT_COLOR = 0x1000,
CAIRO_CONTENT_ALPHA = 0x2000,
@@ -241,7 +241,7 @@ typedef enum _cairo_content {
* CAIRO_STATUS_WRITE_ERROR otherwise.
*
* Returns: the status code of the write operation
- */
+ **/
typedef cairo_status_t (*cairo_write_func_t) (void *closure,
const unsigned char *data,
unsigned int length);
@@ -261,7 +261,7 @@ typedef cairo_status_t (*cairo_write_fun
* CAIRO_STATUS_READ_ERROR otherwise.
*
* Returns: the status code of the read operation
- */
+ **/
typedef cairo_status_t (*cairo_read_func_t) (void *closure,
unsigned char *data,
unsigned int length);
@@ -619,7 +619,7 @@ cairo_clip_extents (cairo_t *cr,
* A data structure for holding a rectangle.
*
* Since: 1.4
- */
+ **/
typedef struct _cairo_rectangle {
double x, y, width, height;
} cairo_rectangle_t;
@@ -634,7 +634,7 @@ typedef struct _cairo_rectangle {
* array of rectangles.
*
* Since: 1.4
- */
+ **/
typedef struct _cairo_rectangle_list {
cairo_status_t status;
cairo_rectangle_t *rectangles;
@@ -656,7 +656,7 @@ cairo_rectangle_list_destroy (cairo_rect
* resolution. A cairo_scaled_font_t is most useful for low-level font
* usage where a library or application wants to cache a reference
* to a scaled font to speed up the computation of metrics.
- */
+ **/
typedef struct _cairo_scaled_font cairo_scaled_font_t;
/**
@@ -668,7 +668,7 @@ typedef struct _cairo_scaled_font cairo_
* directions) . A font face can be set on a #cairo_t by using
* cairo_set_font_face(); the size and font matrix are set with
* cairo_set_font_size() and cairo_set_font_matrix().
- */
+ **/
typedef struct _cairo_font_face cairo_font_face_t;
/**
@@ -727,7 +727,7 @@ typedef struct {
* doubled. They will change slightly due to hinting (so you can't
* assume that metrics are independent of the transformation matrix),
* but otherwise will remain unchanged.
- */
+ **/
typedef struct {
double x_bearing;
double y_bearing;
@@ -777,7 +777,7 @@ typedef struct {
* not be doubled. They will change slightly due to hinting (so you
* can't assume that metrics are independent of the transformation
* matrix), but otherwise will remain unchanged.
- */
+ **/
typedef struct {
double ascent;
double descent;
@@ -843,7 +843,7 @@ typedef enum _cairo_subpixel_order {
* styles are supported by all font backends.
*
* New entries may be added in future versions.
- */
+ **/
typedef enum _cairo_hint_style {
CAIRO_HINT_STYLE_DEFAULT,
CAIRO_HINT_STYLE_NONE,
@@ -864,7 +864,7 @@ typedef enum _cairo_hint_style {
* device space. Doing this improves the consistency of
* letter and line spacing, however it also means that text
* will be laid out differently at different zoom factors.
- */
+ **/
typedef enum _cairo_hint_metrics {
CAIRO_HINT_METRICS_DEFAULT,
CAIRO_HINT_METRICS_OFF,
@@ -890,7 +890,7 @@ typedef enum _cairo_hint_metrics {
* cairo_font_options_hash() should be used to copy, check
* for equality, merge, or compute a hash value of
* #cairo_font_options_t objects.
- */
+ **/
typedef struct _cairo_font_options cairo_font_options_t;
cairo_public cairo_font_options_t *
@@ -1056,7 +1056,7 @@ cairo_font_face_status (cairo_font_face_
* New entries may be added in future versions.
*
* Since: 1.2
- */
+ **/
typedef enum _cairo_font_type {
CAIRO_FONT_TYPE_TOY,
CAIRO_FONT_TYPE_FT,
@@ -1381,7 +1381,7 @@ cairo_surface_status (cairo_surface_t *s
* New entries may be added in future versions.
*
* Since: 1.2
- */
+ **/
typedef enum _cairo_surface_type {
CAIRO_SURFACE_TYPE_IMAGE,
CAIRO_SURFACE_TYPE_PDF,
@@ -1486,7 +1486,7 @@ cairo_surface_set_fallback_resolution (c
* image data.
*
* New entries may be added in future versions.
- */
+ **/
typedef enum _cairo_format {
CAIRO_FORMAT_ARGB32,
CAIRO_FORMAT_RGB24,
@@ -1607,7 +1607,7 @@ cairo_pattern_set_user_data (cairo_patte
* New entries may be added in future versions.
*
* Since: 1.2
- */
+ **/
typedef enum _cairo_pattern_type {
CAIRO_PATTERN_TYPE_SOLID,
CAIRO_PATTERN_TYPE_SURFACE,
@@ -1652,7 +1652,7 @@ cairo_pattern_get_matrix (cairo_pattern_
* of a pattern will be drawn.
*
* New entries may be added in future versions.
- */
+ **/
typedef enum _cairo_extend {
CAIRO_EXTEND_NONE,
CAIRO_EXTEND_REPEAT,
diff-tree 9be961eb0c8c85b04287a5b85f7fd72dac160949 (from 8a6308e1448f402bd4f32b18ba2c60a4bcdbbe6f)
Author: Behdad Esfahbod <behdad at behdad.org>
Date: Fri Mar 2 22:01:15 2007 -0500
[doc] Some documentation love
diff --git a/src/cairo-font.c b/src/cairo-font.c
index 7fefea7..0f72661 100644
--- a/src/cairo-font.c
+++ b/src/cairo-font.c
@@ -149,7 +149,7 @@ slim_hidden_def (cairo_font_face_destroy
/**
* cairo_font_face_get_type:
- * @font_face: a #cairo_font_face_t
+ * @font_face: a font face
*
* This function returns the type of the backend used to create
* a font face. See #cairo_font_type_t for available types.
diff --git a/src/cairo-pattern.c b/src/cairo-pattern.c
index b7fb761..ebb56e3 100644
--- a/src/cairo-pattern.c
+++ b/src/cairo-pattern.c
@@ -846,6 +846,15 @@ cairo_pattern_get_matrix (cairo_pattern_
*matrix = pattern->matrix;
}
+/**
+ * cairo_pattern_set_filter:
+ * @pattern: a #cairo_pattern_t
+ * @filter: a #cairo_filter_t describing the filter to use for resizing
+ * the pattern
+ *
+ * Sets the filter to be used for resizing when using this pattern.
+ * See #cairo_filter_t for details on each filter.
+ **/
void
cairo_pattern_set_filter (cairo_pattern_t *pattern, cairo_filter_t filter)
{
@@ -855,6 +864,15 @@ cairo_pattern_set_filter (cairo_pattern_
pattern->filter = filter;
}
+/**
+ * cairo_pattern_get_filter:
+ * @pattern: a #cairo_pattern_t
+ *
+ * Gets the current filter for a pattern. See #cairo_filter_t
+ * for details on each filter.
+ *
+ * Return value: the current filter used for resizing the pattern.
+ **/
cairo_filter_t
cairo_pattern_get_filter (cairo_pattern_t *pattern)
{
@@ -1740,6 +1758,7 @@ cairo_pattern_get_surface (cairo_pattern
* cairo_pattern_get_color_stop_rgba
* @pattern: a #cairo_pattern_t
* @index: index of the stop to return data for
+ * @offset: return value for the offset of the stop, or %NULL
* @red: return value for red component of color, or %NULL
* @green: return value for green component of color, or %NULL
* @blue: return value for blue component of color, or %NULL
diff --git a/src/cairo-surface.c b/src/cairo-surface.c
index 19d2d08..232b62a 100644
--- a/src/cairo-surface.c
+++ b/src/cairo-surface.c
@@ -141,10 +141,12 @@ slim_hidden_def (cairo_surface_get_type)
* cairo_surface_get_content:
* @surface: a #cairo_surface_t
*
- * Return value: The content type of @surface which indicates whether
- * the surface contains color and/or alpha information. See
+ * This function returns the content type of @surface which indicates
+ * whether the surface contains color and/or alpha information. See
* #cairo_content_t.
*
+ * Return value: The content type of @surface.
+ *
* Since: 1.2
**/
cairo_content_t
diff --git a/src/cairo-win32-font.c b/src/cairo-win32-font.c
index 42a55b0..679d52d 100644
--- a/src/cairo-win32-font.c
+++ b/src/cairo-win32-font.c
@@ -1664,7 +1664,7 @@ cairo_win32_scaled_font_select_font (cai
/**
* cairo_win32_scaled_font_done_font:
- * @scaled_font: A #cairo_scaled_font_t from the Win32 font backend.
+ * @scaled_font: A scaled font from the Win32 font backend.
*
* Releases any resources allocated by cairo_win32_scaled_font_select_font()
**/
@@ -1675,7 +1675,7 @@ cairo_win32_scaled_font_done_font (cairo
/**
* cairo_win32_scaled_font_get_metrics_factor:
- * @scaled_font: a #cairo_scaled_font_t from the Win32 font backend
+ * @scaled_font: a scaled font from the Win32 font backend
*
* Gets a scale factor between logical coordinates in the coordinate
* space used by cairo_win32_scaled_font_select_font() (that is, the
@@ -1691,6 +1691,16 @@ cairo_win32_scaled_font_get_metrics_fact
return 1. / ((cairo_win32_scaled_font_t *)scaled_font)->logical_scale;
}
+/**
+ * cairo_win32_scaled_font_get_logical_to_device:
+ * @scaled_font: a scaled font from the Win32 font backend
+ * @logical_to_device: matrix to return
+ *
+ * Gets the transformation mapping the logical space used by @scaled_font
+ * to device space.
+ *
+ * Since: 1.4
+ **/
void
cairo_win32_scaled_font_get_logical_to_device (cairo_scaled_font_t *scaled_font,
cairo_matrix_t *logical_to_device)
@@ -1699,6 +1709,16 @@ cairo_win32_scaled_font_get_logical_to_d
*logical_to_device = win_font->logical_to_device;
}
+/**
+ * cairo_win32_scaled_font_get_device_to_logical:
+ * @scaled_font: a scaled font from the Win32 font backend
+ * @device_to_logical: matrix to return
+ *
+ * Gets the transformation mapping device space to the logical space
+ * used by @scaled_font.
+ *
+ * Since: 1.4
+ **/
void
cairo_win32_scaled_font_get_device_to_logical (cairo_scaled_font_t *scaled_font,
cairo_matrix_t *device_to_logical)
diff --git a/src/cairo-win32-surface.c b/src/cairo-win32-surface.c
index 20d75e7..dba6f6b 100644
--- a/src/cairo-win32-surface.c
+++ b/src/cairo-win32-surface.c
@@ -1732,6 +1732,7 @@ cairo_win32_surface_create_with_dib (cai
/**
* cairo_win32_surface_create_with_ddb:
+ * @hdc: the DC to create a surface for
* @format: format of pixels in the surface to create
* @width: width of the surface, in pixels
* @height: height of the surface, in pixels
diff --git a/src/cairo.c b/src/cairo.c
index fb799e1..ef07828 100644
--- a/src/cairo.c
+++ b/src/cairo.c
@@ -941,8 +941,8 @@ cairo_set_line_width (cairo_t *cr, doubl
/**
* cairo_set_line_cap:
- * @cr: a cairo context, as a #cairo_t
- * @line_cap: a line cap style, as a #cairo_line_cap_t
+ * @cr: a cairo context
+ * @line_cap: a line cap style
*
* Sets the current line cap style within the cairo context. See
* #cairo_line_cap_t for details about how the available line cap
@@ -966,8 +966,8 @@ cairo_set_line_cap (cairo_t *cr, cairo_l
/**
* cairo_set_line_join:
- * @cr: a cairo context, as a #cairo_t
- * @line_join: a line joint style, as a #cairo_line_join_t
+ * @cr: a cairo context
+ * @line_join: a line joint style
*
* Sets the current line join style within the cairo context. See
* #cairo_line_join_t for details about how the available line join
@@ -1040,11 +1040,13 @@ cairo_set_dash (cairo_t *cr,
* cairo_get_dash_count:
* @cr: a #cairo_t
*
- * Returns the length of the dash array in @cr (0 if dashing is not
- * currently in effect).
+ * This function returns the length of the dash array in @cr (0 if dashing
+ * is not currently in effect).
*
* See also cairo_set_dash() and cairo_get_dash().
*
+ * Return value: the length of the dash array, or 0 if no dash array set.
+ *
* Since: 1.4
*/
int
@@ -1079,6 +1081,25 @@ cairo_get_dash (cairo_t *cr,
*offset = cr->gstate->stroke_style.dash_offset;
}
+/**
+ * cairo_set_miter_limit:
+ * @cr: a cairo context
+ * @limit: miter limit to set
+ *
+ * Sets the current miter limit within the cairo context.
+ *
+ * If the current line join style is set to %CAIRO_LINE_JOIN_MITER
+ * (see cairo_set_line_join()), the miter limit is used to determine
+ * whether the lines should be joined with a bevel instead of a miter.
+ * Cairo divides the length of the miter by the line width.
+ * If the result is greater than the miter limit, the style is
+ * 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.
+ **/
void
cairo_set_miter_limit (cairo_t *cr, double limit)
{
@@ -2338,8 +2359,9 @@ _cairo_rectangle_list_create_in_error (c
/**
* cairo_copy_clip_rectangle_list:
+ * @cr: a cairo context
*
- * Returns the current clip region as a list of rectangles in user coordinates.
+ * Gets the current clip region as a list of rectangles in user coordinates.
* Never returns %NULL.
*
* The status in the list may be CAIRO_STATUS_CLIP_NOT_REPRESENTABLE to
@@ -2350,6 +2372,8 @@ _cairo_rectangle_list_create_in_error (c
* The caller must always call cairo_rectangle_list_destroy on the result of
* this function.
*
+ * Returns: the current clip region as a list of rectangles in user coordinates.
+ *
* Since: 1.4
**/
cairo_rectangle_list_t *
@@ -2818,6 +2842,16 @@ cairo_show_text (cairo_t *cr, const char
_cairo_set_error (cr, cr->status);
}
+/**
+ * cairo_show_glyphs:
+ * @cr: a cairo context
+ * @glyphs: array of glyphs to show
+ * @num_glyphs: number of glyphs to show
+ *
+ * A drawing operator that generates the shape from an array of glyphs,
+ * rendered according to the current font_face, font_size
+ * (font_matrix), and font_options.
+ **/
void
cairo_show_glyphs (cairo_t *cr, const cairo_glyph_t *glyphs, int num_glyphs)
{
@@ -2832,6 +2866,17 @@ cairo_show_glyphs (cairo_t *cr, const ca
_cairo_set_error (cr, cr->status);
}
+/**
+ * cairo_text_path:
+ * @cr: a cairo context
+ * @utf8: a string of text encoded in UTF-8
+ *
+ * Adds closed paths for text to the current path. The generated
+ * path if filled, achieves an effect similar to that of
+ * cairo_show_text().
+ *
+ * Text conversion and positioning is done similar to cairo_show_text().
+ **/
void
cairo_text_path (cairo_t *cr, const char *utf8)
{
@@ -2858,6 +2903,9 @@ cairo_text_path (cairo_t *cr, const cha
cr->status = _cairo_gstate_glyph_path (cr->gstate,
glyphs, num_glyphs,
&cr->path);
+
+ /* XXX: set current point like in cairo_show_text() */
+
if (glyphs)
free (glyphs);
@@ -2865,6 +2913,16 @@ cairo_text_path (cairo_t *cr, const cha
_cairo_set_error (cr, cr->status);
}
+/**
+ * cairo_glyph_path:
+ * @cr: a cairo context
+ * @glyphs: array of glyphs to show
+ * @num_glyphs: number of glyphs to show
+ *
+ * Adds closed paths for the glyphs to the current path. The generated
+ * path if filled, achieves an effect similar to that of
+ * cairo_show_glyphs().
+ **/
void
cairo_glyph_path (cairo_t *cr, const cairo_glyph_t *glyphs, int num_glyphs)
{
@@ -2984,10 +3042,12 @@ cairo_get_fill_rule (cairo_t *cr)
* cairo_get_line_width:
* @cr: a cairo context
*
- * Return value: the current line width value exactly as set by
+ * This function returns the current line width value exactly as set by
* cairo_set_line_width(). Note that the value is unchanged even if
* the CTM has changed between the calls to cairo_set_line_width() and
* cairo_get_line_width().
+ *
+ * Return value: the current line width.
**/
double
cairo_get_line_width (cairo_t *cr)
diff --git a/src/cairo.h b/src/cairo.h
index 430dcfe..727ae39 100644
--- a/src/cairo.h
+++ b/src/cairo.h
@@ -611,7 +611,11 @@ cairo_clip_extents (cairo_t *cr,
/**
* cairo_rectangle_t:
- *
+ * @x: X coordinate of the left side of the rectangle
+ * @y: Y coordinate of the the top side of the rectangle
+ * @width: width of the rectangle
+ * @height: height of the rectangle
+ *
* A data structure for holding a rectangle.
*
* Since: 1.4
@@ -622,6 +626,9 @@ typedef struct _cairo_rectangle {
/**
* cairo_rectangle_list_t:
+ * @status: Error status of the rectangle list
+ * @rectangles: Array containing the rectangles
+ * @num_rectangles: Number of rectangles in this list
*
* A data structure for holding a dynamically allocated
* array of rectangles.
@@ -864,6 +871,26 @@ typedef enum _cairo_hint_metrics {
CAIRO_HINT_METRICS_ON
} cairo_hint_metrics_t;
+/**
+ * cairo_font_options_t:
+ *
+ * An opaque structure holding all options that are used when
+ * rendering fonts.
+ *
+ * Individual features of a #cairo_font_options_t can be set or
+ * accessed using functions named
+ * cairo_font_options_set_<emphasis>feature_name</emphasis> and
+ * cairo_font_options_get_<emphasis>feature_name</emphasis>, like
+ * cairo_font_options_set_antialias() and
+ * cairo_font_options_get_antialias().
+ *
+ * New features may be added to a #cairo_font_options_t in the
+ * future. For this reason, cairo_font_options_copy(),
+ * cairo_font_options_equal(), cairo_font_options_merge(), and
+ * cairo_font_options_hash() should be used to copy, check
+ * for equality, merge, or compute a hash value of
+ * #cairo_font_options_t objects.
+ */
typedef struct _cairo_font_options cairo_font_options_t;
cairo_public cairo_font_options_t *
@@ -1160,6 +1187,17 @@ cairo_get_target (cairo_t *cr);
cairo_public cairo_surface_t *
cairo_get_group_target (cairo_t *cr);
+/**
+ * cairo_path_data_type_t:
+ * @CAIRO_PATH_MOVE_TO: A move-to operation
+ * @CAIRO_PATH_LINE_TO: A line-to operation
+ * @CAIRO_PATH_CURVE_TO: A curve-to operation
+ * @CAIRO_PATH_CLOSE_PATH: A close-path operation
+ *
+ * #cairo_path_data_t is used to describe the type of one portion
+ * of a path when represented as a #cairo_path_t.
+ * See #cairo_path_data_t for details.
+ **/
typedef enum _cairo_path_data_type {
CAIRO_PATH_MOVE_TO,
CAIRO_PATH_LINE_TO,
diff-tree 8a6308e1448f402bd4f32b18ba2c60a4bcdbbe6f (from fed13e77e1de071ddaaf829aced10b02f6bc8c90)
Author: Behdad Esfahbod <behdad at behdad.org>
Date: Fri Mar 2 22:00:25 2007 -0500
[doc] Update list of header files to ignore
diff --git a/doc/public/Headers.mk b/doc/public/Headers.mk
index 24e5e21..d6d7718 100644
--- a/doc/public/Headers.mk
+++ b/doc/public/Headers.mk
@@ -1,12 +1,12 @@
PRIVATE_TEST_HFILES = \
cairo-meta-surface-private.h \
cairo-truetype-subset-private.h \
- cairo-path-data-private.h \
cairo-hash-private.h \
cairo-cache-private.h \
cairo-output-stream-private.h \
cairo-arc-private.h \
cairo-xlib-test.h \
+ cairo-path-private.h \
cairo-paginated-surface-private.h \
cairo-scaled-font-test.h \
cairo-scaled-font-subsets-private.h \
More information about the cairo-commit
mailing list