From 0f5b7d82deb8941705b703ef27d442ca7627bf41 Mon Sep 17 00:00:00 2001 From: Owen Taylor Date: Thu, 27 Jan 2005 11:35:25 +0000 Subject: [PATCH] configure.in Makefile.am docs/Makefile.am docs/public/*: Add framework for doing docs via gtk-doc. src/cairo.[ch] src/cairo-matrix.c: Add some inline docs for arcs and matrices. gtk-doc.m4 acinclude.m4: Check in files from gtk-doc to make the dependency on gtk-doc optional. Add --enable-gtk-doc to the default args. --- ChangeLog | 14 + Makefile.am | 2 +- acinclude.m4 | 53 ++ autogen.sh | 2 +- configure.in | 5 + doc/.cvsignore | 2 + doc/Makefile.am | 2 + doc/public/.cvsignore | 15 + doc/public/Makefile.am | 45 ++ doc/public/cairo-docs.xml | 30 + doc/public/cairo-overrides.txt | 0 doc/public/cairo-sections.txt | 238 +++++++ doc/public/cairo.types | 0 doc/public/tmpl/.cvsignore | 1 + doc/public/tmpl/cairo-atsui.sgml | 25 + doc/public/tmpl/cairo-ft.sgml | 63 ++ doc/public/tmpl/cairo-glitz.sgml | 34 + doc/public/tmpl/cairo-matrix.sgml | 193 ++++++ doc/public/tmpl/cairo-pattern.sgml | 154 +++++ doc/public/tmpl/cairo-pdf.sgml | 42 ++ doc/public/tmpl/cairo-png.sgml | 40 ++ doc/public/tmpl/cairo-ps.sgml | 42 ++ doc/public/tmpl/cairo-quartz.sgml | 38 ++ doc/public/tmpl/cairo-surface.sgml | 112 +++ doc/public/tmpl/cairo-xcb.sgml | 28 + doc/public/tmpl/cairo-xlib.sgml | 39 ++ doc/public/tmpl/cairo.sgml | 1012 ++++++++++++++++++++++++++++ gtk-doc.make | 157 +++++ src/cairo-matrix.c | 162 +++++ src/cairo.c | 47 ++ src/cairo.h | 26 +- src/cairo_matrix.c | 162 +++++ 32 files changed, 2782 insertions(+), 3 deletions(-) create mode 100644 acinclude.m4 create mode 100644 doc/.cvsignore create mode 100644 doc/Makefile.am create mode 100644 doc/public/.cvsignore create mode 100644 doc/public/Makefile.am create mode 100644 doc/public/cairo-docs.xml create mode 100644 doc/public/cairo-overrides.txt create mode 100644 doc/public/cairo-sections.txt create mode 100644 doc/public/cairo.types create mode 100644 doc/public/tmpl/.cvsignore create mode 100644 doc/public/tmpl/cairo-atsui.sgml create mode 100644 doc/public/tmpl/cairo-ft.sgml create mode 100644 doc/public/tmpl/cairo-glitz.sgml create mode 100644 doc/public/tmpl/cairo-matrix.sgml create mode 100644 doc/public/tmpl/cairo-pattern.sgml create mode 100644 doc/public/tmpl/cairo-pdf.sgml create mode 100644 doc/public/tmpl/cairo-png.sgml create mode 100644 doc/public/tmpl/cairo-ps.sgml create mode 100644 doc/public/tmpl/cairo-quartz.sgml create mode 100644 doc/public/tmpl/cairo-surface.sgml create mode 100644 doc/public/tmpl/cairo-xcb.sgml create mode 100644 doc/public/tmpl/cairo-xlib.sgml create mode 100644 doc/public/tmpl/cairo.sgml create mode 100644 gtk-doc.make diff --git a/ChangeLog b/ChangeLog index c971b887e..855843cd2 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,17 @@ +2005-01-27 Owen Taylor + + * configure.in Makefile.am docs/Makefile.am docs/public/*: + Add framework for doing docs via gtk-doc. + + * src/cairo.[ch] src/cairo-matrix.c: Add some inline docs + for arcs and matrices. + + * gtk-doc.m4 acinclude.m4: Check in files from gtk-doc + to make the dependency on gtk-doc optional. + + * autogen.sh (LANG): Add --enable-gtk-doc to the default + args. + 2005-01-27 Kristian Høgsberg The overall idea of this rewrite is that we want to pass the diff --git a/Makefile.am b/Makefile.am index 3a33e9a7c..60ae80514 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,4 +1,4 @@ -SUBDIRS = src test +SUBDIRS = src test doc EXTRA_DIST = \ COPYING \ diff --git a/acinclude.m4 b/acinclude.m4 new file mode 100644 index 000000000..af73800bf --- /dev/null +++ b/acinclude.m4 @@ -0,0 +1,53 @@ +dnl -*- mode: autoconf -*- + +# serial 1 + +dnl Usage: +dnl GTK_DOC_CHECK([minimum-gtk-doc-version]) +AC_DEFUN([GTK_DOC_CHECK], +[ + AC_BEFORE([AC_PROG_LIBTOOL],[$0])dnl setup libtool first + AC_BEFORE([AM_PROG_LIBTOOL],[$0])dnl setup libtool first + dnl for overriding the documentation installation directory + AC_ARG_WITH(html-dir, + AC_HELP_STRING([--with-html-dir=PATH], [path to installed docs]),, + [with_html_dir='${datadir}/gtk-doc/html']) + HTML_DIR="$with_html_dir" + AC_SUBST(HTML_DIR) + + dnl enable/disable documentation building + AC_ARG_ENABLE(gtk-doc, + AC_HELP_STRING([--enable-gtk-doc], + [use gtk-doc to build documentation [default=no]]),, + enable_gtk_doc=no) + + have_gtk_doc=no + if test x$enable_gtk_doc = xyes; then + if test -z "$PKG_CONFIG"; then + AC_PATH_PROG(PKG_CONFIG, pkg-config, no) + fi + if test "$PKG_CONFIG" != "no" && $PKG_CONFIG --exists gtk-doc; then + have_gtk_doc=yes + fi + + dnl do we want to do a version check? +ifelse([$1],[],, + [gtk_doc_min_version=$1 + if test "$have_gtk_doc" = yes; then + AC_MSG_CHECKING([gtk-doc version >= $gtk_doc_min_version]) + if $PKG_CONFIG --atleast-version $gtk_doc_min_version gtk-doc; then + AC_MSG_RESULT(yes) + else + AC_MSG_RESULT(no) + have_gtk_doc=no + fi + fi +]) + if test "$have_gtk_doc" != yes; then + enable_gtk_doc=no + fi + fi + + AM_CONDITIONAL(ENABLE_GTK_DOC, test x$enable_gtk_doc = xyes) + AM_CONDITIONAL(GTK_DOC_USE_LIBTOOL, test -n "$LIBTOOL") +]) diff --git a/autogen.sh b/autogen.sh index 46ca3422b..616137855 100755 --- a/autogen.sh +++ b/autogen.sh @@ -133,4 +133,4 @@ do_cmd $AUTOMAKE $AUTOMAKE_FLAGS do_cmd $AUTOCONF -do_cmd ./configure --enable-maintainer-mode ${1+"$@"} && echo "Now type \`make' to compile" || exit 1 +do_cmd ./configure --enable-maintainer-mode --enable-gtk-doc ${1+"$@"} && echo "Now type \`make' to compile" || exit 1 diff --git a/configure.in b/configure.in index 74da3bab2..a0c818e88 100644 --- a/configure.in +++ b/configure.in @@ -346,6 +346,9 @@ AC_SUBST(CAIRO_CFLAGS) AC_SUBST(CAIRO_LIBS) dnl =========================================================================== +dnl Check for gtk-doc and docbook + +GTK_DOC_CHECK([1.3]) AC_OUTPUT([ cairo.pc @@ -353,6 +356,8 @@ Makefile src/Makefile src/cairo-features.h test/Makefile +doc/Makefile +doc/public/Makefile ]) dnl =========================================================================== diff --git a/doc/.cvsignore b/doc/.cvsignore new file mode 100644 index 000000000..282522db0 --- /dev/null +++ b/doc/.cvsignore @@ -0,0 +1,2 @@ +Makefile +Makefile.in diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 000000000..411ad5c93 --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,2 @@ +SUBDIRS=public + diff --git a/doc/public/.cvsignore b/doc/public/.cvsignore new file mode 100644 index 000000000..35479d5e3 --- /dev/null +++ b/doc/public/.cvsignore @@ -0,0 +1,15 @@ +*.stamp +Makefile +Makefile.in +cairo-decl-list.txt +cairo-decl.txt +cairo-undocumented.txt +cairo-unused.txt +cairo.hierarchy +cairo.interfaces +cairo.prerequisites +cairo.args +cairo.signals +html +xml + diff --git a/doc/public/Makefile.am b/doc/public/Makefile.am new file mode 100644 index 000000000..5a92e4ded --- /dev/null +++ b/doc/public/Makefile.am @@ -0,0 +1,45 @@ +## Process this file with automake to create Makefile.in. + +AUTOMAKE_OPTIONS = 1.7 + +# The name of the module. +DOC_MODULE=cairo + +# The top-level SGML file. +DOC_MAIN_SGML_FILE=cairo-docs.xml + +# Extra options to supply to gtkdoc-scan +SCAN_OPTIONS=--deprecated-guards="CAIRO_DISABLE_DEPRECATED" + +# The directory containing the source code. Relative to $(srcdir) +DOC_SOURCE_DIR=../../src + +# Used for dependencies +HFILE_GLOB=$(top_srcdir)/src/*.h +CFILE_GLOB=$(top_srcdir)/src/*.c $(top_srcdir)/src/*.h + +# Headers to ignore +IGNORE_HFILES= \ + cairo-features.h \ + cairoft-private.h \ + cairoint.h \ + cairo-wideint.h + +# CFLAGS and LDFLAGS for compiling scan program. Only needed +# if $(DOC_MODULE).types is non-empty. +INCLUDES = +GTKDOC_LIBS = + +# Extra options to supply to gtkdoc-mkdb +MKDB_OPTIONS=--sgml-mode --output-format=xml + +# Non-autogenerated SGML files to be included in $(DOC_MAIN_SGML_FILE) +content_files = + +# Images to copy into HTML directory +HTML_IMAGES = + +# Extra options to supply to gtkdoc-fixref +FIXXREF_OPTIONS= + +include $(top_srcdir)/gtk-doc.make diff --git a/doc/public/cairo-docs.xml b/doc/public/cairo-docs.xml new file mode 100644 index 000000000..a07791673 --- /dev/null +++ b/doc/public/cairo-docs.xml @@ -0,0 +1,30 @@ + + + +Cairo: A Vector Graphics Library + + Tutorial + + + Reference + + + + + + + + + + + + + + + + + + + + diff --git a/doc/public/cairo-overrides.txt b/doc/public/cairo-overrides.txt new file mode 100644 index 000000000..e69de29bb diff --git a/doc/public/cairo-sections.txt b/doc/public/cairo-sections.txt new file mode 100644 index 000000000..3072d19cb --- /dev/null +++ b/doc/public/cairo-sections.txt @@ -0,0 +1,238 @@ +
+cairo-atsui +ATSUI Fonts +cairo_atsui_font_create +
+ +
+cairo-ft +FreeType Fonts +cairo_ft_font_create +cairo_ft_font_create_for_ft_face +cairo_ft_font_lock_face +cairo_ft_font_unlock_face +cairo_ft_font_get_pattern +
+ +
+cairo-glitz +Glitz backend +cairo_set_target_glitz +cairo_glitz_surface_create +
+ +
+cairo-pdf +PDF Backend +cairo_set_target_pdf +cairo_pdf_surface_create +
+ +
+cairo-png +PNG Backend +cairo_set_target_png +cairo_png_surface_create +
+ +
+cairo-ps +PS Backend +cairo_set_target_ps +cairo_ps_surface_create +
+ +
+cairo-quartz +Quartz Backend +cairo_set_target_quartz_context +cairo_quartz_surface_create +
+ +
+cairo-xcb +XCB Backend +cairo_set_target_xcb +
+ +
+cairo-xlib +XLib Backend +cairo_set_target_drawable +cairo_xlib_surface_create +
+ +
+cairo-surface +cairo_surface_t +cairo_surface_t +cairo_surface_create_for_image +cairo_surface_create_similar +cairo_surface_reference +cairo_surface_destroy +cairo_surface_set_repeat +cairo_surface_set_matrix +cairo_surface_get_matrix +cairo_surface_set_filter +cairo_surface_get_filter +
+ +
+cairo-pattern +cairo_pattern_t +cairo_pattern_t +cairo_pattern_create_for_surface +cairo_pattern_create_linear +cairo_pattern_create_radial +cairo_pattern_reference +cairo_pattern_destroy +cairo_pattern_add_color_stop +cairo_pattern_set_matrix +cairo_pattern_get_matrix +cairo_extend_t +cairo_pattern_set_extend +cairo_pattern_get_extend +cairo_pattern_set_filter +cairo_pattern_get_filter +
+ +
+cairo-matrix +cairo_matrix_t +cairo_matrix_t +cairo_matrix_create +cairo_matrix_destroy +cairo_matrix_copy +cairo_matrix_set_identity +cairo_matrix_set_affine +cairo_matrix_get_affine +cairo_matrix_translate +cairo_matrix_scale +cairo_matrix_rotate +cairo_matrix_invert +cairo_matrix_multiply +cairo_matrix_transform_distance +cairo_matrix_transform_point +
+ +
+cairo +cairo_t +cairo_t +cairo_create +cairo_reference +cairo_destroy +cairo_save +cairo_restore +cairo_copy +cairo_set_target_surface +cairo_format_t +cairo_set_target_image +cairo_operator_t +cairo_set_operator +cairo_set_rgb_color +cairo_set_pattern +cairo_set_alpha +cairo_set_tolerance +cairo_fill_rule_t +cairo_set_fill_rule +cairo_set_line_width +cairo_line_cap_t +cairo_set_line_cap +cairo_line_join_t +cairo_set_line_join +cairo_set_dash +cairo_set_miter_limit +cairo_translate +cairo_scale +cairo_rotate +cairo_concat_matrix +cairo_set_matrix +cairo_default_matrix +cairo_identity_matrix +cairo_transform_point +cairo_transform_distance +cairo_inverse_transform_point +cairo_inverse_transform_distance +cairo_new_path +cairo_move_to +cairo_line_to +cairo_curve_to +cairo_arc +cairo_arc_negative +cairo_rel_move_to +cairo_rel_line_to +cairo_rel_curve_to +cairo_rectangle +cairo_close_path +cairo_stroke +cairo_fill +cairo_copy_page +cairo_show_page +cairo_in_stroke +cairo_in_fill +cairo_stroke_extents +cairo_fill_extents +cairo_init_clip +cairo_clip +cairo_font_t +cairo_glyph_t +cairo_text_extents_t +cairo_font_extents_t +cairo_font_slant_t +cairo_font_weight_t +cairo_select_font +cairo_scale_font +cairo_transform_font +cairo_show_text +cairo_show_glyphs +cairo_current_font +cairo_current_font_extents +cairo_set_font +cairo_text_extents +cairo_glyph_extents +cairo_text_path +cairo_glyph_path +cairo_font_reference +cairo_font_destroy +cairo_font_glyph_extents +cairo_show_surface +cairo_current_operator +cairo_current_rgb_color +cairo_current_pattern +cairo_current_alpha +cairo_current_tolerance +cairo_current_point +cairo_current_fill_rule +cairo_current_line_width +cairo_current_line_cap +cairo_current_line_join +cairo_current_miter_limit +cairo_current_matrix +cairo_current_target_surface +cairo_current_path +cairo_current_path_flat +cairo_status_t +cairo_status +cairo_status_string +cairo_filter_t +cairo_image_surface_create +cairo_image_surface_create_for_data + +CAIRO_BEGIN_DECLS +CAIRO_END_DECLS +cairo_get_operator +cairo_get_rgb_color +cairo_get_alpha +cairo_get_tolerance +cairo_get_current_point +cairo_get_fill_rule +cairo_get_line_width +cairo_get_line_cap +cairo_get_line_join +cairo_get_miter_limit +cairo_get_matrix +cairo_get_target_surface +cairo_get_status +cairo_get_status_string +
diff --git a/doc/public/cairo.types b/doc/public/cairo.types new file mode 100644 index 000000000..e69de29bb diff --git a/doc/public/tmpl/.cvsignore b/doc/public/tmpl/.cvsignore new file mode 100644 index 000000000..844dc52df --- /dev/null +++ b/doc/public/tmpl/.cvsignore @@ -0,0 +1 @@ +cairo-unused.sgml diff --git a/doc/public/tmpl/cairo-atsui.sgml b/doc/public/tmpl/cairo-atsui.sgml new file mode 100644 index 000000000..0d957ecdf --- /dev/null +++ b/doc/public/tmpl/cairo-atsui.sgml @@ -0,0 +1,25 @@ + +ATSUI Fonts + + + + + + + + + + + + + + + + + + + +@style: +@Returns: + + diff --git a/doc/public/tmpl/cairo-ft.sgml b/doc/public/tmpl/cairo-ft.sgml new file mode 100644 index 000000000..bcf52ac34 --- /dev/null +++ b/doc/public/tmpl/cairo-ft.sgml @@ -0,0 +1,63 @@ + +FreeType Fonts + + + + + + + + + + + + + + + + + + + +@pattern: +@scale: +@Returns: + + + + + + + +@face: +@load_flags: +@scale: +@Returns: + + + + + + + +@ft_font: +@Returns: + + + + + + + +@ft_font: + + + + + + + +@ft_font: +@Returns: + + diff --git a/doc/public/tmpl/cairo-glitz.sgml b/doc/public/tmpl/cairo-glitz.sgml new file mode 100644 index 000000000..101eb9e3e --- /dev/null +++ b/doc/public/tmpl/cairo-glitz.sgml @@ -0,0 +1,34 @@ + +Glitz backend + + + + + + + + + + + + + + + + + + + +@cr: +@surface: + + + + + + + +@surface: +@Returns: + + diff --git a/doc/public/tmpl/cairo-matrix.sgml b/doc/public/tmpl/cairo-matrix.sgml new file mode 100644 index 000000000..7438ab794 --- /dev/null +++ b/doc/public/tmpl/cairo-matrix.sgml @@ -0,0 +1,193 @@ + +cairo_matrix_t + + + + Transformation matrices + + + + typescairo_matrix + cairo_matrix_t is used throughout + Cairo to represents between different coordinates spaces. + A cairo_matrix holds an affine + transformation, such as a scale, rotation, or shear, or a + combination of those. Mathematically, the effect of an affine + transformation on a point (x,y) is given by: + + + x_new = x * a + y * c + tx; + y_new = x * b + y * d + ty; + + + The parameters a, b, + c, d, tx, + ty can be retrieved with + cairo_matrix_get_affine() and set with cairo_matrix_get_affine(). + + + The primary use of transformation matrices in Cairo is as the + current transformation matrix in a #cairo_t. The current + transformation matrix gives the transformation from user space + coordinates to device coordinates. See cairo_set_matrix(), + cairo_current_matrix(). + + + + + + + + + + + + + + + +> + + +@Returns: + + + + + + + +@matrix: + + + + + + + +@matrix: +@other: +@Returns: + + + + + + + +@matrix: +@Returns: + + + + + + + +@matrix: +@a: +@b: +@c: +@d: +@tx: +@ty: +@Returns: + +@cr: + + + + + + + +@matrix: +@a: +@b: +@c: +@d: +@tx: +@ty: +@Returns: + + + + + + + +@matrix: +@tx: +@ty: +@Returns: + + + + + + + +@matrix: +@sx: +@sy: +@Returns: + + + + + + + +@matrix: +@radians: +@Returns: + + + + + + + +@matrix: +@Returns: + + + + + + + +@result: +@a: +@b: +@Returns: + + + + + + + +@matrix: +@dx: +@dy: +@Returns: + + + + + + +@matrix: +@x: +@y: +@Returns: + + + + diff --git a/doc/public/tmpl/cairo-pattern.sgml b/doc/public/tmpl/cairo-pattern.sgml new file mode 100644 index 000000000..84728212b --- /dev/null +++ b/doc/public/tmpl/cairo-pattern.sgml @@ -0,0 +1,154 @@ + +cairo_pattern_t + + + + + + + + + + + + + + + + + + + + + + + + + +@surface: +@Returns: + + + + + + + +@x0: +@y0: +@x1: +@y1: +@Returns: + + + + + + + +@cx0: +@cy0: +@radius0: +@cx1: +@cy1: +@radius1: +@Returns: + + + + + + + +@pattern: + + + + + + + +@pattern: + + + + + + + +@pattern: +@offset: +@red: +@green: +@blue: +@alpha: +@Returns: + + + + + + + +@pattern: +@matrix: +@Returns: + + + + + + + +@pattern: +@matrix: +@Returns: + + + + + + + +@CAIRO_EXTEND_NONE: +@CAIRO_EXTEND_REPEAT: +@CAIRO_EXTEND_REFLECT: + + + + + + +@pattern: +@extend: +@Returns: + + + + + + + +@pattern: +@Returns: + + + + + + + +@pattern: +@filter: +@Returns: + + + + + + + +@pattern: +@Returns: + + diff --git a/doc/public/tmpl/cairo-pdf.sgml b/doc/public/tmpl/cairo-pdf.sgml new file mode 100644 index 000000000..e627c236e --- /dev/null +++ b/doc/public/tmpl/cairo-pdf.sgml @@ -0,0 +1,42 @@ + +PDF Backend + + + + + + + + + + + + + + + + + + + +@cr: +@file: +@width_inches: +@height_inches: +@x_pixels_per_inch: +@y_pixels_per_inch: + + + + + + + +@file: +@width_inches: +@height_inches: +@x_pixels_per_inch: +@y_pixels_per_inch: +@Returns: + + diff --git a/doc/public/tmpl/cairo-png.sgml b/doc/public/tmpl/cairo-png.sgml new file mode 100644 index 000000000..d4d5a66b5 --- /dev/null +++ b/doc/public/tmpl/cairo-png.sgml @@ -0,0 +1,40 @@ + +PNG Backend + + + + + + + + + + + + + + + + + + + +@cr: +@file: +@format: +@width: +@height: + + + + + + + +@file: +@format: +@width: +@height: +@Returns: + + diff --git a/doc/public/tmpl/cairo-ps.sgml b/doc/public/tmpl/cairo-ps.sgml new file mode 100644 index 000000000..70b2e7e8f --- /dev/null +++ b/doc/public/tmpl/cairo-ps.sgml @@ -0,0 +1,42 @@ + +PS Backend + + + + + + + + + + + + + + + + + + + +@cr: +@file: +@width_inches: +@height_inches: +@x_pixels_per_inch: +@y_pixels_per_inch: + + + + + + + +@file: +@width_inches: +@height_inches: +@x_pixels_per_inch: +@y_pixels_per_inch: +@Returns: + + diff --git a/doc/public/tmpl/cairo-quartz.sgml b/doc/public/tmpl/cairo-quartz.sgml new file mode 100644 index 000000000..04c9bc61f --- /dev/null +++ b/doc/public/tmpl/cairo-quartz.sgml @@ -0,0 +1,38 @@ + +Quartz Backend + + + + + + + + + + + + + + + + + + + +@cr: +@context: +@width: +@height: + + + + + + + +@context: +@width: +@height: +@Returns: + + diff --git a/doc/public/tmpl/cairo-surface.sgml b/doc/public/tmpl/cairo-surface.sgml new file mode 100644 index 000000000..2f8ad470c --- /dev/null +++ b/doc/public/tmpl/cairo-surface.sgml @@ -0,0 +1,112 @@ + +cairo_surface_t + + + + + + + + + + + + + + + + + + + + + + + + + +@data: +@format: +@width: +@height: +@stride: +@Returns: + + + + + + + +@other: +@format: +@width: +@height: +@Returns: + + + + + + + +@surface: + + + + + + + +@surface: + + + + + + + +@surface: +@repeat: +@Returns: + + + + + + + +@surface: +@matrix: +@Returns: + + + + + + + +@surface: +@matrix: +@Returns: + + + + + + + +@surface: +@filter: +@Returns: + + + + + + + +@surface: +@Returns: + + diff --git a/doc/public/tmpl/cairo-xcb.sgml b/doc/public/tmpl/cairo-xcb.sgml new file mode 100644 index 000000000..e5e1ee912 --- /dev/null +++ b/doc/public/tmpl/cairo-xcb.sgml @@ -0,0 +1,28 @@ + +XCB Backend + + + + + + + + + + + + + + + + + + + +@cr: +@dpy: +@drawable: +@visual: +@format: + + diff --git a/doc/public/tmpl/cairo-xlib.sgml b/doc/public/tmpl/cairo-xlib.sgml new file mode 100644 index 000000000..b18e76aae --- /dev/null +++ b/doc/public/tmpl/cairo-xlib.sgml @@ -0,0 +1,39 @@ + +XLib Backend + + + + + + + + + + + + + + + + + + + +@cr: +@dpy: +@drawable: + + + + + + + +@dpy: +@drawable: +@visual: +@format: +@colormap: +@Returns: + + diff --git a/doc/public/tmpl/cairo.sgml b/doc/public/tmpl/cairo.sgml new file mode 100644 index 000000000..491088f86 --- /dev/null +++ b/doc/public/tmpl/cairo.sgml @@ -0,0 +1,1012 @@ + +cairo_t + + +Drawing contexts. + + + + + #cairo_t is the main object used when drawing with Cairo. To + draw with Cairo, you create a #cairo_t, set the target surface, + and drawing options for the #cairo_t, create shapes with + functions like cairo_move_to() and cairo_line_to(), and then + draw ships with cairo_stroke() or cairo_fill(). + + + #cairo_t's can be pushed to a stack via cairo_save(). + They may then safely be changed, without loosing the current state. + Use cairo_restore() to restore to the saved state. + + + + + + + + + + + + + + + + + + +@Returns: + + + + + + + +@cr: + + + + + + + +@cr: + + + + + + + +@cr: + + + + + + + +@cr: + + + + + + + +@dest: +@src: + + + + + + + +@cr: +@surface: + + + + + + + +@CAIRO_FORMAT_ARGB32: +@CAIRO_FORMAT_RGB24: +@CAIRO_FORMAT_A8: +@CAIRO_FORMAT_A1: + + + + + + +@cr: +@data: +@format: +@width: +@height: +@stride: + + + + + + + +@CAIRO_OPERATOR_CLEAR: +@CAIRO_OPERATOR_SRC: +@CAIRO_OPERATOR_DST: +@CAIRO_OPERATOR_OVER: +@CAIRO_OPERATOR_OVER_REVERSE: +@CAIRO_OPERATOR_IN: +@CAIRO_OPERATOR_IN_REVERSE: +@CAIRO_OPERATOR_OUT: +@CAIRO_OPERATOR_OUT_REVERSE: +@CAIRO_OPERATOR_ATOP: +@CAIRO_OPERATOR_ATOP_REVERSE: +@CAIRO_OPERATOR_XOR: +@CAIRO_OPERATOR_ADD: +@CAIRO_OPERATOR_SATURATE: + + + + + + +@cr: +@op: + + + + + + + +@cr: +@red: +@green: +@blue: + + + + + + + +@cr: +@pattern: + + + + + + + +@cr: +@alpha: + + + + + + + +@cr: +@tolerance: + + + + + + + +@CAIRO_FILL_RULE_WINDING: +@CAIRO_FILL_RULE_EVEN_ODD: + + + + + + +@cr: +@fill_rule: + + + + + + + +@cr: +@width: + + + + + + + +@CAIRO_LINE_CAP_BUTT: +@CAIRO_LINE_CAP_ROUND: +@CAIRO_LINE_CAP_SQUARE: + + + + + + +@cr: +@line_cap: + + + + + + + +@CAIRO_LINE_JOIN_MITER: +@CAIRO_LINE_JOIN_ROUND: +@CAIRO_LINE_JOIN_BEVEL: + + + + + + +@cr: +@line_join: + + + + + + + +@cr: +@dashes: +@ndash: +@offset: + + + + + + + +@cr: +@limit: + + + + + + + +@cr: +@tx: +@ty: + + + + + + + +@cr: +@sx: +@sy: + + + + + + + +@cr: +@angle: + + + + + + + +@cr: +@matrix: + + + + + + + +@cr: +@matrix: + + + + + + + +@cr: + + + + + + + +@cr: + + + + + + + +@cr: +@x: +@y: + + + + + + + +@cr: +@dx: +@dy: + + + + + + + +@cr: +@x: +@y: + + + + + + + +@cr: +@dx: +@dy: + + + + + + + +@cr: + + + + + + + +@cr: +@x: +@y: + + + + + + + +@cr: +@x: +@y: + + + + + + + +@cr: +@x1: +@y1: +@x2: +@y2: +@x3: +@y3: + + + + + + + +@cr: +@xc: +@yc: +@radius: +@angle1: +@angle2: + + + + + + + +@cr: +@xc: +@yc: +@radius: +@angle1: +@angle2: + + + + + + + +@cr: +@dx: +@dy: + + + + + + + +@cr: +@dx: +@dy: + + + + + + + +@cr: +@dx1: +@dy1: +@dx2: +@dy2: +@dx3: +@dy3: + + + + + + + +@cr: +@x: +@y: +@width: +@height: + + + + + + + +@cr: + + + + + + + +@cr: + + + + + + + +@cr: + + + + + + + +@cr: + + + + + + + +@cr: + + + + + + + +@cr: +@x: +@y: +@Returns: + + + + + + + +@cr: +@x: +@y: +@Returns: + + + + + + + +@cr: +@x1: +@y1: +@x2: +@y2: + + + + + + + +@cr: +@x1: +@y1: +@x2: +@y2: + + + + + + + +@cr: + + + + + + + +@cr: + + + + + + + + + + + + + +@index: +@x: +@y: + + + + + + +@x_bearing: +@y_bearing: +@width: +@height: +@x_advance: +@y_advance: + + + + + + +@ascent: +@descent: +@height: +@max_x_advance: +@max_y_advance: + + + + + + +@CAIRO_FONT_SLANT_NORMAL: +@CAIRO_FONT_SLANT_ITALIC: +@CAIRO_FONT_SLANT_OBLIQUE: + + + + + + +@CAIRO_FONT_WEIGHT_NORMAL: +@CAIRO_FONT_WEIGHT_BOLD: + + + + + + +@cr: +@family: +@slant: +@weight: + + + + + + + +@cr: +@scale: + + + + + + + +@cr: +@matrix: + + + + + + + +@cr: +@utf8: + + + + + + + +@cr: +@glyphs: +@num_glyphs: + + + + + + + +@cr: +@Returns: + + + + + + + +@cr: +@extents: + + + + + + + +@cr: +@font: + + + + + + + +@cr: +@utf8: +@extents: + + + + + + + +@cr: +@glyphs: +@num_glyphs: +@extents: + + + + + + + +@cr: +@utf8: + + + + + + + +@cr: +@glyphs: +@num_glyphs: + + + + + + + +@font: + + + + + + + +@font: + + + + + + + +@font: +@font_matrix: +@glyphs: +@num_glyphs: +@extents: + + + + + + + +@cr: +@surface: +@width: +@height: + + + + + + + +@cr: +@Returns: + + + + + + + +@cr: +@red: +@green: +@blue: + + + + + + + +@cr: +@Returns: + + + + + + + +@cr: +@Returns: + + + + + + + +@cr: +@Returns: + + + + + + + +@cr: +@x: +@y: + + + + + + + +@cr: +@Returns: + + + + + + + +@cr: +@Returns: + + + + + + + +@cr: +@Returns: + + + + + + + +@cr: +@Returns: + + + + + + + +@cr: +@Returns: + + + + + + + +@cr: +@matrix: + + + + + + + +@cr: +@Returns: + + + + + + + +@cr: +@move_to: +@line_to: +@curve_to: +@close_path: +@closure: + + + + + + + +@cr: +@move_to: +@line_to: +@close_path: +@closure: + + + + + + + +@CAIRO_STATUS_SUCCESS: +@CAIRO_STATUS_NO_MEMORY: +@CAIRO_STATUS_INVALID_RESTORE: +@CAIRO_STATUS_INVALID_POP_GROUP: +@CAIRO_STATUS_NO_CURRENT_POINT: +@CAIRO_STATUS_INVALID_MATRIX: +@CAIRO_STATUS_NO_TARGET_SURFACE: +@CAIRO_STATUS_NULL_POINTER: + + + + + + +@cr: +@Returns: + + + + + + + +@cr: +@Returns: + + + + + + + +@CAIRO_FILTER_FAST: +@CAIRO_FILTER_GOOD: +@CAIRO_FILTER_BEST: +@CAIRO_FILTER_NEAREST: +@CAIRO_FILTER_BILINEAR: +@CAIRO_FILTER_GAUSSIAN: + + + + + + +@format: +@width: +@height: +@Returns: + + + + + + + +@data: +@format: +@width: +@height: +@stride: +@Returns: + + + + + + diff --git a/gtk-doc.make b/gtk-doc.make new file mode 100644 index 000000000..bdb3c5148 --- /dev/null +++ b/gtk-doc.make @@ -0,0 +1,157 @@ +# +# *** NOTE *** this file is checked into CVS for convenience only. +# DO NOT EDIT. Rather get changes into upstream gtk-doc and then +# update this version from the gtk-doc version. +# + +# -*- mode: makefile -*- + +#################################### +# Everything below here is generic # +#################################### + +if GTK_DOC_USE_LIBTOOL +GTKDOC_CC = $(LIBTOOL) --mode=compile $(CC) $(INCLUDES) $(AM_CFLAGS) $(CFLAGS) +GTKDOC_LD = $(LIBTOOL) --mode=link $(CC) $(AM_CFLAGS) $(CFLAGS) $(LDFLAGS) +else +GTKDOC_CC = $(CC) $(INCLUDES) $(AM_CFLAGS) $(CFLAGS) +GTKDOC_LD = $(CC) $(AM_CFLAGS) $(CFLAGS) $(LDFLAGS) +endif + +# We set GPATH here; this gives us semantics for GNU make +# which are more like other make's VPATH, when it comes to +# whether a source that is a target of one rule is then +# searched for in VPATH/GPATH. +# +GPATH = $(srcdir) + +TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE) + +EXTRA_DIST = \ + $(content_files) \ + $(HTML_IMAGES) \ + $(DOC_MAIN_SGML_FILE) \ + $(DOC_MODULE).types \ + $(DOC_MODULE)-sections.txt \ + $(DOC_MODULE)-overrides.txt + +DOC_STAMPS=scan-build.stamp tmpl-build.stamp sgml-build.stamp html-build.stamp \ + $(srcdir)/tmpl.stamp $(srcdir)/sgml.stamp $(srcdir)/html.stamp + +SCANOBJ_FILES = \ + $(DOC_MODULE).args \ + $(DOC_MODULE).hierarchy \ + $(DOC_MODULE).interfaces \ + $(DOC_MODULE).prerequisites \ + $(DOC_MODULE).signals + +CLEANFILES = $(SCANOBJ_FILES) $(DOC_MODULE)-unused.txt $(DOC_STAMPS) + +if ENABLE_GTK_DOC +all-local: html-build.stamp + +#### scan #### + +scan-build.stamp: $(HFILE_GLOB) $(CFILE_GLOB) + @echo '*** Scanning header files ***' + @-chmod -R u+w $(srcdir) + if grep -l '^..*$$' $(srcdir)/$(DOC_MODULE).types > /dev/null ; then \ + CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" CFLAGS="$(GTKDOC_CFLAGS)" LDFLAGS="$(GTKDOC_LIBS)" gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) --output-dir=$(srcdir) ; \ + else \ + cd $(srcdir) ; \ + for i in $(SCANOBJ_FILES) ; do \ + test -f $$i || touch $$i ; \ + done \ + fi + cd $(srcdir) && \ + gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --ignore-headers="$(IGNORE_HFILES)" $(SCAN_OPTIONS) $(EXTRA_HFILES) + touch scan-build.stamp + +$(DOC_MODULE)-decl.txt $(SCANOBJ_FILES): scan-build.stamp + @true + +#### templates #### + +tmpl-build.stamp: $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt + @echo '*** Rebuilding template files ***' + @-chmod -R u+w $(srcdir) + cd $(srcdir) && gtkdoc-mktmpl --module=$(DOC_MODULE) + touch tmpl-build.stamp + +tmpl.stamp: tmpl-build.stamp + @true + +#### xml #### + +sgml-build.stamp: tmpl.stamp $(CFILE_GLOB) $(srcdir)/tmpl/*.sgml + @echo '*** Building XML ***' + @-chmod -R u+w $(srcdir) + cd $(srcdir) && \ + gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --output-format=xml $(MKDB_OPTIONS) + touch sgml-build.stamp + +sgml.stamp: sgml-build.stamp + @true + +#### html #### + +html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) + @echo '*** Building HTML ***' + @-chmod -R u+w $(srcdir) + rm -rf $(srcdir)/html + mkdir $(srcdir)/html + cd $(srcdir)/html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) + test "x$(HTML_IMAGES)" = "x" || ( cd $(srcdir) && cp $(HTML_IMAGES) html ) + @echo '-- Fixing Crossreferences' + cd $(srcdir) && gtkdoc-fixxref --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS) + touch html-build.stamp +else +all-local: +endif + +############## + +clean-local: + rm -f *~ *.bak + rm -rf .libs + +maintainer-clean-local: clean + cd $(srcdir) && rm -rf xml html $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt + +install-data-local: + installfiles=`echo $(srcdir)/html/*`; \ + if test "$$installfiles" = '$(srcdir)/html/*'; \ + then echo '-- Nothing to install' ; \ + else \ + $(mkinstalldirs) $(DESTDIR)$(TARGET_DIR); \ + for i in $$installfiles; do \ + echo '-- Installing '$$i ; \ + $(INSTALL_DATA) $$i $(DESTDIR)$(TARGET_DIR); \ + done; \ + echo '-- Installing $(srcdir)/html/index.sgml' ; \ + $(INSTALL_DATA) $(srcdir)/html/index.sgml $(DESTDIR)$(TARGET_DIR) || :; \ + fi + +uninstall-local: + rm -f $(DESTDIR)$(TARGET_DIR)/* + +# +# Require gtk-doc when making dist +# +if ENABLE_GTK_DOC +dist-check-gtkdoc: +else +dist-check-gtkdoc: + @echo "*** gtk-doc must be installed and enabled in order to make dist" + @false +endif + +dist-hook: dist-check-gtkdoc dist-hook-local + mkdir $(distdir)/tmpl + mkdir $(distdir)/xml + mkdir $(distdir)/html + -cp $(srcdir)/tmpl/*.sgml $(distdir)/tmpl + -cp $(srcdir)/xml/*.xml $(distdir)/xml + -cp $(srcdir)/html/* $(distdir)/html + +.PHONY : dist-hook-local diff --git a/src/cairo-matrix.c b/src/cairo-matrix.c index b964b688c..a43d9e6d6 100644 --- a/src/cairo-matrix.c +++ b/src/cairo-matrix.c @@ -54,6 +54,14 @@ _cairo_matrix_scalar_multiply (cairo_matrix_t *matrix, double scalar); static void _cairo_matrix_compute_adjoint (cairo_matrix_t *matrix); +/** + * cairo_matrix_create: + * + * Creates a new identity matrix. + * + * Return value: a newly created matrix; free with cairo_matrix_destroy(), + * or %NULL if memory couldn't be allocated. + **/ cairo_matrix_t * cairo_matrix_create (void) { @@ -80,6 +88,12 @@ _cairo_matrix_fini (cairo_matrix_t *matrix) /* nothing to do here */ } +/** + * cairo_matrix_destroy: + * @matrix: a #cairo_matrix_t + * + * Frees a matrix created with cairo_matrix_create. + **/ void cairo_matrix_destroy (cairo_matrix_t *matrix) { @@ -87,6 +101,15 @@ cairo_matrix_destroy (cairo_matrix_t *matrix) free (matrix); } +/** + * cairo_matrix_copy: + * @matrix: a #cairo_matrix_t + * @other: another #cairo_ + * + * Modifies @matrix to be identical to @other. + * + * Return value: %CAIRO_STATUS_SUCCESS, always. + **/ cairo_status_t cairo_matrix_copy (cairo_matrix_t *matrix, const cairo_matrix_t *other) { @@ -96,6 +119,14 @@ cairo_matrix_copy (cairo_matrix_t *matrix, const cairo_matrix_t *other) } slim_hidden_def(cairo_matrix_copy); +/** + * cairo_matrix_set_identity: + * @matrix: a #cairo_matrix_t + * + * Modifies @matrix to be an identity transformation. + * + * Return value: %CAIRO_STATUS_SUCCESS, always. + **/ cairo_status_t cairo_matrix_set_identity (cairo_matrix_t *matrix) { @@ -105,6 +136,26 @@ cairo_matrix_set_identity (cairo_matrix_t *matrix) } slim_hidden_def(cairo_matrix_set_identity); +/** + * cairo_matrix_set_affine: + * @matrix: a cairo_matrix_t + * @a: a component of the affine transformation + * @b: b component of the affine transformation + * @c: c component of the affine transformation + * @d: d component of the affine transformation + * @tx: X translation component of the affine transformation + * @ty: Y translation component of the affine transformation + * + * Sets @matrix to be the affine transformation given by + * @a, b, @c, @d, @tx, @ty. The transformation is given + * by: + * + * x_new = x * a + y * c + tx; + * y_new = x * b + y * d + ty; + * + * + * Return value: %CAIRO_STATUS_SUCCESS, always. + **/ cairo_status_t cairo_matrix_set_affine (cairo_matrix_t *matrix, double a, double b, @@ -119,6 +170,21 @@ cairo_matrix_set_affine (cairo_matrix_t *matrix, } slim_hidden_def(cairo_matrix_set_affine); +/** + * cairo_matrix_get_affine: + * @matrix: a @cairo_matrix_t + * @a: location to store a component of affine transformation, or %NULL + * @b: location to store b component of affine transformation, or %NULL + * @c: location to store c component of affine transformation, or %NULL + * @d: location to store d component of affine transformation, or %NULL + * @tx: location to store X-translation component of affine transformation, or %NULL + * @ty: location to store Y-translation component of affine transformation, or %NULL + * + * Gets the matrix values for the affine tranformation that @matrix represents. + * See cairo_matrix_set_affine(). + * + * Return value: %CAIRO_STATUS_SUCCESS, always. + **/ cairo_status_t cairo_matrix_get_affine (cairo_matrix_t *matrix, double *a, double *b, @@ -153,6 +219,18 @@ _cairo_matrix_set_translate (cairo_matrix_t *matrix, tx, ty); } +/** + * cairo_matrix_translate: + * @matrix: a cairo_matrix_t + * @tx: amount to rotate in the X direction + * @ty: amount to rotate in the Y direction + * + * Applies a translation by @tx, @ty to the transformation in + * @matrix. The new transformation is given by first translating by + * @tx, @ty then applying the original transformation + * + * Return value: %CAIRO_STATUS_SUCCESS, always. + **/ cairo_status_t cairo_matrix_translate (cairo_matrix_t *matrix, double tx, double ty) { @@ -173,6 +251,18 @@ _cairo_matrix_set_scale (cairo_matrix_t *matrix, 0, 0); } +/** + * cairo_matrix_scale: + * @matrix: a #cairo_matrix_t + * @sx: Scale factor in the X direction + * @sy: Scale factor in the Y direction + * + * Applies scaling by @tx, @ty to the transformation in + * @matrix. The new transformation is given by first scaling by @sx + * and @sy then applying the original transformation + * + * Return value: %CAIRO_STATUS_SUCCESS, always. + **/ cairo_status_t cairo_matrix_scale (cairo_matrix_t *matrix, double sx, double sy) { @@ -202,6 +292,21 @@ _cairo_matrix_set_rotate (cairo_matrix_t *matrix, 0, 0); } +/** + * cairo_matrix_rotate: + * @matrix: a @cairo_matrix_t + * @radians: angle of rotation, in radians. Angles are defined + * so that an angle of 90 degrees (%M_PI radians) rotates the + * positive X axis into the positive Y axis. With the default + * Cairo choice of axis orientation, positive rotations are + * clockwise. + * + * Applies rotation by @radians to the transformation in + * @matrix. The new transformation is given by first rotating by + * @radians then applying the original transformation + * + * Return value: %CAIRO_STATUS_SUCCESS, always. + **/ cairo_status_t cairo_matrix_rotate (cairo_matrix_t *matrix, double radians) { @@ -212,6 +317,19 @@ cairo_matrix_rotate (cairo_matrix_t *matrix, double radians) return cairo_matrix_multiply (matrix, &tmp, matrix); } +/** + * cairo_matrix_multiply: + * @result: a @cairo_matrix_t in which to store the result + * @a: a @cairo_matrix_t + * @b: a @cairo_matrix_t + * + * Multiplies the affine transformations in @a and @b together + * and stores the result in @result. The resulting transformation + * is given by first applying the transformation in @b then + * applying the transformation in @a. + * + * Return value: %CAIRO_STATUS_SUCCESS, always. + **/ cairo_status_t cairo_matrix_multiply (cairo_matrix_t *result, const cairo_matrix_t *a, const cairo_matrix_t *b) { @@ -238,6 +356,27 @@ cairo_matrix_multiply (cairo_matrix_t *result, const cairo_matrix_t *a, const ca } slim_hidden_def(cairo_matrix_multiply); +/** + * cairo_matrix_transform_distance: + * @matrix: a @cairo_matrix_t + * @dx: a distance in the X direction. An in/out parameter + * @dy: a distance in the Y direction. An in/out parameter + * + * Transforms the vector (@dx,@dy) by @matrix. Translation is + * ignored. In terms of the components of the affine transformation: + * + * + * dx2 = dx1 * a + dy1 * c; + * dy2 = dx1 * b + dy1 * d; + * + * + * Affine transformations are position invariant, so the same vector + * always transforms to the same vector. If (@x1,@y1) transforms + * to (@x2,@y2) then (@x1+@dx1,@y1+@dy1) will transform to + * (@x1+@dx2,@y1+@dy2) for all values of @x1 and @x2. + * + * Return value: %CAIRO_STATUS_SUCCESS, always. + **/ cairo_status_t cairo_matrix_transform_distance (cairo_matrix_t *matrix, double *dx, double *dy) { @@ -255,6 +394,16 @@ cairo_matrix_transform_distance (cairo_matrix_t *matrix, double *dx, double *dy) } slim_hidden_def(cairo_matrix_transform_distance); +/** + * cairo_matrix_transform_point: + * @matrix: a @cairo_matrix_t + * @x: X position. An in/out parameter + * @y: Y position. An in/out parameter + * + * Transforms the point (@x, @y) by @matrix. + * + * Return value: %CAIRO_STATUS_SUCCESS, always. + **/ cairo_status_t cairo_matrix_transform_point (cairo_matrix_t *matrix, double *x, double *y) { @@ -351,6 +500,19 @@ _cairo_matrix_compute_adjoint (cairo_matrix_t *matrix) c*ty - d*tx, b*tx - a*ty); } +/** + * cairo_matrix_invert: + * @matrix: a @cairo_matrix_t + * + * Changes @matrix to be the inverse of it's original value. Not + * all transformation matrices have inverses; if the matrix + * collapses points together (it is degenerate), + * then it has no inverse and this function will fail. + * + * Returns: If @matrix has an inverse, modifies @matrix to + * be the inverse matrix and returns %CAIRO_STATUS_SUCCESS. Otherwise, + * returns %CAIRO_STATUS_INVALID_MATRIX. + **/ cairo_status_t cairo_matrix_invert (cairo_matrix_t *matrix) { diff --git a/src/cairo.c b/src/cairo.c index 20d94938c..8ebbc88d9 100644 --- a/src/cairo.c +++ b/src/cairo.c @@ -569,6 +569,39 @@ cairo_curve_to (cairo_t *cr, CAIRO_CHECK_SANITY (cr); } +/** + * cairo_arc: + * @cr: a Cairo context + * @xc: X position of the center of the arc + * @yc: Y position of the center of the arc + * @radius: the radius of the arc + * @angle1: the start angle, in radians + * @angle2: the end angle, in radians + * + * Adds an arc from @angle1 to @angle2 to the current path. If there + * is a current point, that point is connected to the start of the arc + * by a straight line segment. Angles are measured in radians with an + * angle of 0 along the X axis and an angle of %M_PI radians (90 + * degrees) along the Y axis, so with the default transformation + * matrix, positive angles are clockwise. (To convert from degrees to + * radians, use degrees * (M_PI / 180.).) This + * function gives the arc in the direction of increasing angle; see + * cairo_arc_negative() to get the arc in the direction of decreasing + * angle. + * + * A full arc is drawn as a circle. To make an oval arc, you can scale + * the current transformation matrix by different amounts in the X and + * Y directions. For example, to draw a full oval in the box given + * by @x, @y, @width, @height: + + * + * cairo_save (cr); + * cairo_translate (x + width / 2., y + height / 2.); + * cairo_scale (1. / (height / 2.), 1. / (width / 2.)); + * cairo_arc (cr, 0., 0., 1., 0., 2 * M_PI); + * cairo_restore (cr); + * + **/ void cairo_arc (cairo_t *cr, double xc, double yc, @@ -586,6 +619,20 @@ cairo_arc (cairo_t *cr, CAIRO_CHECK_SANITY (cr); } +/** + * cairo_arc_negative: + * @cr: a Cairo context + * @xc: X position of the center of the arc + * @yc: Y position of the center of the arc + * @radius: the radius of the arc + * @angle1: the start angle, in radians + * @angle2: the end angle, in radians + * + * Adds an arc from @angle1 to @angle2 to the current path. The + * function behaves identically to cairo_arc() except that instead of + * giving the arc in the direction of increasing angle, it gives + * the arc in the direction of decreasing angle. + **/ void cairo_arc_negative (cairo_t *cr, double xc, double yc, diff --git a/src/cairo.h b/src/cairo.h index daeaf940d..2f5facbcc 100644 --- a/src/cairo.h +++ b/src/cairo.h @@ -50,8 +50,23 @@ CAIRO_BEGIN_DECLS +/** + * cairo_t + * + * A #cairo_t contains the current state of the rendering device, + * including coordinates of yet to be drawn shapes. + **/ typedef struct _cairo cairo_t; + typedef struct _cairo_surface cairo_surface_t; + +/** + * cairo_t + * + * A cairo_matrix holds an affine + * transformation, such as a scale, rotation, or shear, or a + * combination of those. + **/ typedef struct _cairo_matrix cairo_matrix_t; typedef struct _cairo_pattern cairo_pattern_t; @@ -166,6 +181,15 @@ cairo_set_fill_rule (cairo_t *cr, cairo_fill_rule_t fill_rule); void cairo_set_line_width (cairo_t *cr, double width); + +/** + * cairo_line_cap_t + * @CAIRO_LINE_CAP_BUTT: start(stop) the line exactly at the start(end) point + * @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 + **/ typedef enum cairo_line_cap { CAIRO_LINE_CAP_BUTT, CAIRO_LINE_CAP_ROUND, @@ -676,7 +700,7 @@ cairo_status_t cairo_matrix_set_identity (cairo_matrix_t *matrix); cairo_status_t -cairo_matrix_set_affine (cairo_matrix_t *cr, +cairo_matrix_set_affine (cairo_matrix_t *matrix, double a, double b, double c, double d, double tx, double ty); diff --git a/src/cairo_matrix.c b/src/cairo_matrix.c index b964b688c..a43d9e6d6 100644 --- a/src/cairo_matrix.c +++ b/src/cairo_matrix.c @@ -54,6 +54,14 @@ _cairo_matrix_scalar_multiply (cairo_matrix_t *matrix, double scalar); static void _cairo_matrix_compute_adjoint (cairo_matrix_t *matrix); +/** + * cairo_matrix_create: + * + * Creates a new identity matrix. + * + * Return value: a newly created matrix; free with cairo_matrix_destroy(), + * or %NULL if memory couldn't be allocated. + **/ cairo_matrix_t * cairo_matrix_create (void) { @@ -80,6 +88,12 @@ _cairo_matrix_fini (cairo_matrix_t *matrix) /* nothing to do here */ } +/** + * cairo_matrix_destroy: + * @matrix: a #cairo_matrix_t + * + * Frees a matrix created with cairo_matrix_create. + **/ void cairo_matrix_destroy (cairo_matrix_t *matrix) { @@ -87,6 +101,15 @@ cairo_matrix_destroy (cairo_matrix_t *matrix) free (matrix); } +/** + * cairo_matrix_copy: + * @matrix: a #cairo_matrix_t + * @other: another #cairo_ + * + * Modifies @matrix to be identical to @other. + * + * Return value: %CAIRO_STATUS_SUCCESS, always. + **/ cairo_status_t cairo_matrix_copy (cairo_matrix_t *matrix, const cairo_matrix_t *other) { @@ -96,6 +119,14 @@ cairo_matrix_copy (cairo_matrix_t *matrix, const cairo_matrix_t *other) } slim_hidden_def(cairo_matrix_copy); +/** + * cairo_matrix_set_identity: + * @matrix: a #cairo_matrix_t + * + * Modifies @matrix to be an identity transformation. + * + * Return value: %CAIRO_STATUS_SUCCESS, always. + **/ cairo_status_t cairo_matrix_set_identity (cairo_matrix_t *matrix) { @@ -105,6 +136,26 @@ cairo_matrix_set_identity (cairo_matrix_t *matrix) } slim_hidden_def(cairo_matrix_set_identity); +/** + * cairo_matrix_set_affine: + * @matrix: a cairo_matrix_t + * @a: a component of the affine transformation + * @b: b component of the affine transformation + * @c: c component of the affine transformation + * @d: d component of the affine transformation + * @tx: X translation component of the affine transformation + * @ty: Y translation component of the affine transformation + * + * Sets @matrix to be the affine transformation given by + * @a, b, @c, @d, @tx, @ty. The transformation is given + * by: + * + * x_new = x * a + y * c + tx; + * y_new = x * b + y * d + ty; + * + * + * Return value: %CAIRO_STATUS_SUCCESS, always. + **/ cairo_status_t cairo_matrix_set_affine (cairo_matrix_t *matrix, double a, double b, @@ -119,6 +170,21 @@ cairo_matrix_set_affine (cairo_matrix_t *matrix, } slim_hidden_def(cairo_matrix_set_affine); +/** + * cairo_matrix_get_affine: + * @matrix: a @cairo_matrix_t + * @a: location to store a component of affine transformation, or %NULL + * @b: location to store b component of affine transformation, or %NULL + * @c: location to store c component of affine transformation, or %NULL + * @d: location to store d component of affine transformation, or %NULL + * @tx: location to store X-translation component of affine transformation, or %NULL + * @ty: location to store Y-translation component of affine transformation, or %NULL + * + * Gets the matrix values for the affine tranformation that @matrix represents. + * See cairo_matrix_set_affine(). + * + * Return value: %CAIRO_STATUS_SUCCESS, always. + **/ cairo_status_t cairo_matrix_get_affine (cairo_matrix_t *matrix, double *a, double *b, @@ -153,6 +219,18 @@ _cairo_matrix_set_translate (cairo_matrix_t *matrix, tx, ty); } +/** + * cairo_matrix_translate: + * @matrix: a cairo_matrix_t + * @tx: amount to rotate in the X direction + * @ty: amount to rotate in the Y direction + * + * Applies a translation by @tx, @ty to the transformation in + * @matrix. The new transformation is given by first translating by + * @tx, @ty then applying the original transformation + * + * Return value: %CAIRO_STATUS_SUCCESS, always. + **/ cairo_status_t cairo_matrix_translate (cairo_matrix_t *matrix, double tx, double ty) { @@ -173,6 +251,18 @@ _cairo_matrix_set_scale (cairo_matrix_t *matrix, 0, 0); } +/** + * cairo_matrix_scale: + * @matrix: a #cairo_matrix_t + * @sx: Scale factor in the X direction + * @sy: Scale factor in the Y direction + * + * Applies scaling by @tx, @ty to the transformation in + * @matrix. The new transformation is given by first scaling by @sx + * and @sy then applying the original transformation + * + * Return value: %CAIRO_STATUS_SUCCESS, always. + **/ cairo_status_t cairo_matrix_scale (cairo_matrix_t *matrix, double sx, double sy) { @@ -202,6 +292,21 @@ _cairo_matrix_set_rotate (cairo_matrix_t *matrix, 0, 0); } +/** + * cairo_matrix_rotate: + * @matrix: a @cairo_matrix_t + * @radians: angle of rotation, in radians. Angles are defined + * so that an angle of 90 degrees (%M_PI radians) rotates the + * positive X axis into the positive Y axis. With the default + * Cairo choice of axis orientation, positive rotations are + * clockwise. + * + * Applies rotation by @radians to the transformation in + * @matrix. The new transformation is given by first rotating by + * @radians then applying the original transformation + * + * Return value: %CAIRO_STATUS_SUCCESS, always. + **/ cairo_status_t cairo_matrix_rotate (cairo_matrix_t *matrix, double radians) { @@ -212,6 +317,19 @@ cairo_matrix_rotate (cairo_matrix_t *matrix, double radians) return cairo_matrix_multiply (matrix, &tmp, matrix); } +/** + * cairo_matrix_multiply: + * @result: a @cairo_matrix_t in which to store the result + * @a: a @cairo_matrix_t + * @b: a @cairo_matrix_t + * + * Multiplies the affine transformations in @a and @b together + * and stores the result in @result. The resulting transformation + * is given by first applying the transformation in @b then + * applying the transformation in @a. + * + * Return value: %CAIRO_STATUS_SUCCESS, always. + **/ cairo_status_t cairo_matrix_multiply (cairo_matrix_t *result, const cairo_matrix_t *a, const cairo_matrix_t *b) { @@ -238,6 +356,27 @@ cairo_matrix_multiply (cairo_matrix_t *result, const cairo_matrix_t *a, const ca } slim_hidden_def(cairo_matrix_multiply); +/** + * cairo_matrix_transform_distance: + * @matrix: a @cairo_matrix_t + * @dx: a distance in the X direction. An in/out parameter + * @dy: a distance in the Y direction. An in/out parameter + * + * Transforms the vector (@dx,@dy) by @matrix. Translation is + * ignored. In terms of the components of the affine transformation: + * + * + * dx2 = dx1 * a + dy1 * c; + * dy2 = dx1 * b + dy1 * d; + * + * + * Affine transformations are position invariant, so the same vector + * always transforms to the same vector. If (@x1,@y1) transforms + * to (@x2,@y2) then (@x1+@dx1,@y1+@dy1) will transform to + * (@x1+@dx2,@y1+@dy2) for all values of @x1 and @x2. + * + * Return value: %CAIRO_STATUS_SUCCESS, always. + **/ cairo_status_t cairo_matrix_transform_distance (cairo_matrix_t *matrix, double *dx, double *dy) { @@ -255,6 +394,16 @@ cairo_matrix_transform_distance (cairo_matrix_t *matrix, double *dx, double *dy) } slim_hidden_def(cairo_matrix_transform_distance); +/** + * cairo_matrix_transform_point: + * @matrix: a @cairo_matrix_t + * @x: X position. An in/out parameter + * @y: Y position. An in/out parameter + * + * Transforms the point (@x, @y) by @matrix. + * + * Return value: %CAIRO_STATUS_SUCCESS, always. + **/ cairo_status_t cairo_matrix_transform_point (cairo_matrix_t *matrix, double *x, double *y) { @@ -351,6 +500,19 @@ _cairo_matrix_compute_adjoint (cairo_matrix_t *matrix) c*ty - d*tx, b*tx - a*ty); } +/** + * cairo_matrix_invert: + * @matrix: a @cairo_matrix_t + * + * Changes @matrix to be the inverse of it's original value. Not + * all transformation matrices have inverses; if the matrix + * collapses points together (it is degenerate), + * then it has no inverse and this function will fail. + * + * Returns: If @matrix has an inverse, modifies @matrix to + * be the inverse matrix and returns %CAIRO_STATUS_SUCCESS. Otherwise, + * returns %CAIRO_STATUS_INVALID_MATRIX. + **/ cairo_status_t cairo_matrix_invert (cairo_matrix_t *matrix) {