diff options
Diffstat (limited to 'doc/public')
| -rw-r--r-- | doc/public/Makefile.am | 17 | ||||
| -rw-r--r-- | doc/public/cairo-docs.xml | 12 | ||||
| -rw-r--r-- | doc/public/cairo-sections.txt | 196 | ||||
| -rw-r--r-- | doc/public/language-bindings.xml | 726 | ||||
| -rw-r--r-- | doc/public/tmpl/cairo-atsui.sgml | 3 | ||||
| -rw-r--r-- | doc/public/tmpl/cairo-font.sgml | 148 | ||||
| -rw-r--r-- | doc/public/tmpl/cairo-ft.sgml | 26 | ||||
| -rw-r--r-- | doc/public/tmpl/cairo-glitz.sgml | 8 | ||||
| -rw-r--r-- | doc/public/tmpl/cairo-matrix.sgml | 69 | ||||
| -rw-r--r-- | doc/public/tmpl/cairo-pattern.sgml | 18 | ||||
| -rw-r--r-- | doc/public/tmpl/cairo-pdf.sgml | 20 | ||||
| -rw-r--r-- | doc/public/tmpl/cairo-png.sgml | 41 | ||||
| -rw-r--r-- | doc/public/tmpl/cairo-ps.sgml | 12 | ||||
| -rw-r--r-- | doc/public/tmpl/cairo-quartz.sgml | 10 | ||||
| -rw-r--r-- | doc/public/tmpl/cairo-surface.sgml | 72 | ||||
| -rw-r--r-- | doc/public/tmpl/cairo-xcb.sgml | 7 | ||||
| -rw-r--r-- | doc/public/tmpl/cairo-xlib.sgml | 25 | ||||
| -rw-r--r-- | doc/public/tmpl/cairo.sgml | 363 |
18 files changed, 1457 insertions, 316 deletions
diff --git a/doc/public/Makefile.am b/doc/public/Makefile.am index b993bb978..f058d36aa 100644 --- a/doc/public/Makefile.am +++ b/doc/public/Makefile.am @@ -19,11 +19,15 @@ HFILE_GLOB=$(top_srcdir)/src/*.h CFILE_GLOB=$(top_srcdir)/src/*.c $(top_srcdir)/src/*.h # Headers to ignore -IGNORE_HFILES= \ - cairo-features.h \ - cairo-ft-private.h \ - cairo-win32-private.h \ - cairoint.h \ +IGNORE_HFILES= \ + cairo-features.h \ + cairo-ft-private.h \ + cairo-gstate-private.h \ + cairo-path-fixed-private.h \ + cairo-private.h \ + cairo-win32-private.h \ + cairo-xlib-test.h \ + cairoint.h \ cairo-wideint.h # CFLAGS and LDFLAGS for compiling scan program. Only needed @@ -35,7 +39,8 @@ GTKDOC_LIBS = MKDB_OPTIONS=--sgml-mode --output-format=xml # Non-autogenerated SGML files to be included in $(DOC_MAIN_SGML_FILE) -content_files = +content_files = \ + language-bindings.xml # Images to copy into HTML directory HTML_IMAGES = diff --git a/doc/public/cairo-docs.xml b/doc/public/cairo-docs.xml index 2a4cdae8a..729738aac 100644 --- a/doc/public/cairo-docs.xml +++ b/doc/public/cairo-docs.xml @@ -12,6 +12,7 @@ <xi:include href="xml/cairo-surface.xml"/> <xi:include href="xml/cairo-pattern.xml"/> <xi:include href="xml/cairo-matrix.xml"/> + <xi:include href="xml/cairo-font.xml"/> <xi:include href="xml/cairo-atsui.xml"/> <xi:include href="xml/cairo-ft.xml"/> <xi:include href="xml/cairo-glitz.xml"/> @@ -22,10 +23,9 @@ <xi:include href="xml/cairo-win32.xml"/> <xi:include href="xml/cairo-xcb.xml"/> <xi:include href="xml/cairo-xlib.xml"/> - </part> + </part> + <index> + <title>Index</title> + </index> + <xi:include href="language-bindings.xml"/> </book> - - - - - diff --git a/doc/public/cairo-sections.txt b/doc/public/cairo-sections.txt index 3da0fa801..b462436b8 100644 --- a/doc/public/cairo-sections.txt +++ b/doc/public/cairo-sections.txt @@ -7,70 +7,68 @@ cairo_atsui_font_create <SECTION> <FILE>cairo-ft</FILE> <TITLE>FreeType Fonts</TITLE> -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_ft_font_face_create_for_pattern +cairo_ft_font_face_create_for_ft_face +cairo_ft_scaled_font_lock_face +cairo_ft_scaled_font_unlock_face </SECTION> <SECTION> <FILE>cairo-glitz</FILE> <TITLE>Glitz backend</TITLE> -cairo_set_target_glitz cairo_glitz_surface_create </SECTION> <SECTION> <FILE>cairo-pdf</FILE> <TITLE>PDF Backend</TITLE> -cairo_set_target_pdf cairo_pdf_surface_create +cairo_pdf_surface_create_for_callback </SECTION> <SECTION> <FILE>cairo-png</FILE> <TITLE>PNG Backend</TITLE> -cairo_set_target_png -cairo_png_surface_create +cairo_image_surface_create_from_png +cairo_image_surface_create_from_png_stream +cairo_surface_write_to_png +cairo_surface_write_to_png_stream </SECTION> <SECTION> <FILE>cairo-ps</FILE> <TITLE>PS Backend</TITLE> -cairo_set_target_ps cairo_ps_surface_create </SECTION> <SECTION> <FILE>cairo-quartz</FILE> <TITLE>Quartz Backend</TITLE> -cairo_set_target_quartz_context cairo_quartz_surface_create </SECTION> <SECTION> <FILE>cairo-win32</FILE> <TITLE>Microsoft Windows Backend</TITLE> -cairo_set_target_win32 cairo_win32_surface_create -cairo_win32_font_create_for_logfontw -cairo_win32_font_select_font -cairo_win32_font_done_font -cairo_win32_font_get_scale_factor +cairo_win32_font_face_create_for_logfontw +cairo_win32_scaled_font_select_font +cairo_win32_scaled_font_done_font +cairo_win32_scaled_font_get_metrics_factor </SECTION> <SECTION> <FILE>cairo-xcb</FILE> <TITLE>XCB Backend</TITLE> -cairo_set_target_xcb +cairo_xcb_surface_create </SECTION> <SECTION> <FILE>cairo-xlib</FILE> <TITLE>XLib Backend</TITLE> -cairo_set_target_drawable cairo_xlib_surface_create +cairo_xlib_surface_create_with_visual +cairo_xlib_surface_set_size </SECTION> <SECTION> @@ -81,11 +79,15 @@ cairo_surface_create_for_image cairo_surface_create_similar cairo_surface_reference cairo_surface_destroy +cairo_surface_finish cairo_surface_set_repeat cairo_surface_set_matrix cairo_surface_get_matrix cairo_surface_set_filter cairo_surface_get_filter +cairo_surface_set_user_data +cairo_surface_get_user_data +cairo_surface_set_device_offset </SECTION> <SECTION> @@ -97,7 +99,8 @@ cairo_pattern_create_linear cairo_pattern_create_radial cairo_pattern_reference cairo_pattern_destroy -cairo_pattern_add_color_stop +cairo_pattern_add_color_stop_rgb +cairo_pattern_add_color_stop_rgba cairo_pattern_set_matrix cairo_pattern_get_matrix cairo_extend_t @@ -105,18 +108,19 @@ cairo_pattern_set_extend cairo_pattern_get_extend cairo_pattern_set_filter cairo_pattern_get_filter +<SUBSECTION Private> +cairo_pattern_add_color_stop </SECTION> <SECTION> <FILE>cairo-matrix</FILE> <TITLE>cairo_matrix_t</TITLE> 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_init +cairo_matrix_init_identity +cairo_matrix_init_translate +cairo_matrix_init_scale +cairo_matrix_init_rotate cairo_matrix_translate cairo_matrix_scale cairo_matrix_rotate @@ -124,6 +128,31 @@ cairo_matrix_invert cairo_matrix_multiply cairo_matrix_transform_distance cairo_matrix_transform_point +<SUBSECTION Private> +cairo_matrix_create +cairo_matrix_destroy +cairo_matrix_copy +cairo_matrix_set_identity +cairo_matrix_set_affine +cairo_matrix_get_affine +</SECTION> + +<SECTION> +<FILE>cairo-font</FILE> +<TITLE>Fonts</TITLE> +cairo_font_face_t +cairo_scaled_font_t +cairo_font_face_reference +cairo_font_face_destroy +cairo_font_face_get_user_data +cairo_font_face_set_user_data +cairo_scaled_font_create +cairo_scaled_font_reference +cairo_scaled_font_destroy +cairo_font_extents_t +cairo_scaled_font_extents +cairo_text_extents_t +cairo_scaled_font_glyph_extents </SECTION> <SECTION> @@ -136,13 +165,13 @@ 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_source_rgb +cairo_set_source_rgba +cairo_set_source +cairo_set_source_surface cairo_set_alpha cairo_set_tolerance cairo_fill_rule_t @@ -157,14 +186,14 @@ cairo_set_miter_limit cairo_translate cairo_scale cairo_rotate -cairo_concat_matrix +cairo_transform cairo_set_matrix cairo_default_matrix cairo_identity_matrix -cairo_transform_point -cairo_transform_distance -cairo_inverse_transform_point -cairo_inverse_transform_distance +cairo_user_to_device +cairo_user_to_device_distance +cairo_device_to_user +cairo_device_to_user_distance cairo_new_path cairo_move_to cairo_line_to @@ -176,8 +205,14 @@ cairo_rel_line_to cairo_rel_curve_to cairo_rectangle cairo_close_path +cairo_paint +cairo_paint_with_alpha +cairo_mask +cairo_mask_surface cairo_stroke +cairo_stroke_preserve cairo_fill +cairo_fill_preserve cairo_copy_page cairo_show_page cairo_in_stroke @@ -185,35 +220,61 @@ cairo_in_fill cairo_bool_t cairo_stroke_extents cairo_fill_extents -cairo_init_clip cairo_clip -cairo_font_t +cairo_clip_preserve +cairo_reset_clip 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_select_font_face +cairo_set_font_size +cairo_set_font_matrix +cairo_get_font_matrix cairo_show_text cairo_show_glyphs -cairo_current_font -cairo_current_font_extents -cairo_set_font +cairo_get_font_face +cairo_font_extents +cairo_set_font_face cairo_text_extents cairo_glyph_extents cairo_text_path cairo_glyph_path -cairo_font_reference -cairo_font_destroy -cairo_font_extents -cairo_font_glyph_extents cairo_show_surface +cairo_get_operator +cairo_get_source +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 +cairo_get_path +cairo_get_path_flat +cairo_copy_path +cairo_copy_path_flat +cairo_append_path +cairo_path_t +cairo_path_destroy +cairo_status_t +cairo_status +cairo_status_string +cairo_filter_t +cairo_image_surface_create +cairo_image_surface_create_for_data +cairo_image_surface_get_width +cairo_image_surface_get_height +cairo_destroy_func_t +cairo_user_data_key_t +cairo_read_func_t +cairo_write_func_t +<SUBSECTION Private> +CAIRO_BEGIN_DECLS +CAIRO_END_DECLS +cairo_concat_matrix cairo_current_operator -cairo_current_rgb_color -cairo_current_pattern -cairo_current_alpha cairo_current_tolerance cairo_current_point cairo_current_fill_rule @@ -225,27 +286,18 @@ 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 -<SUBSECTION Private> -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_current_font_extents +cairo_init_clip +cairo_inverse_transform_point +cairo_inverse_transform_distance +cairo_scale_font +cairo_select_font +cairo_set_pattern +cairo_set_rgb_color +cairo_transform_font +cairo_get_font_extents cairo_get_status cairo_get_status_string +cairo_transform_point +cairo_transform_distance </SECTION> diff --git a/doc/public/language-bindings.xml b/doc/public/language-bindings.xml new file mode 100644 index 000000000..1b999d82f --- /dev/null +++ b/doc/public/language-bindings.xml @@ -0,0 +1,726 @@ +<appendix id="language-bindings"> + <title>Creating a language binding for cairo</title> + <para> + While cairo is implemented and C, and has a C API, it is expected + that many users of cairo will be using it from languages other + than C. The glue that connects the core cairo library to another + language is known as a <firstterm>language + binding</firstterm>. This appendix attempts to collect together + issues that come up when creating a language bindings for cairo + and present standardized solutions to promote consistency among + the different language bindings. + </para> + <sect1 id="bindings-general"> + <title>General considerations</title> + <para> + The naming of the central <link + linkend="cairo-t"><type>cairo_t</type></link> type is a + special exception. The object is “a cairo context” not “a + cairo”, and names such as <type>cairo_t</type> rather than + <type>cairo_context_t</type> and + <function>cairo_set_source()</function> rather than + <function>cairo_context_set_source()</function> are simply + abbreviations to make the C API more palatable. In languages + which have object-oriented syntax, this abbreviation is much + less useful. In fact, if ‘Cairo’ is used as a namespace, then + in many languages, you'd end up with a ridiculous type name + like ‘Cairo.Cairo’. For this reason, and for inter-language + consistency all object-oriented languages should name this + type as if it were <type>cairo_context_t</type>. + </para> + <para> + The punctuation and casing of the type names and + method names of cairo should be changed to match the general + convention of the language. In Java, where type names are written + in StudlyCaps and method names in javaCaps, cairo_font_extents_t + will become FontExtents and + <literal>cairo_set_source(cr,source)</literal>, + <literal>cr.setSource(source)</literal>. + As compared to changing the punctuation, and casing, much + more reluctance should be used in changing the method names + themselves. Even if get is usually omitted from getters in + your language, you shouldn't bind cairo_get_source() as + cr.source(). + </para> + </sect1> + <sect1 id="bindings-memory"> + <title>Memory Management</title> + <para> + The objects in cairo can roughly be divided into two types: + refcounted opaque types like + <link + linkend="cairo-surface-t"><type>cairo_surface_t</type></link> + and plain structures like + <link + linkend="cairo-glyph-t"><type>cairo_glyph_t</type></link>. + <link + linkend="cairo-path-t"><type>cairo_path_t</type></link> + and + <link + linkend="cairo-path-data-t"><type>cairo_path_data_t</type></link> + are special cases and are treated separately in this appendix. + </para> + <para> + Refcounted opaque types all have a + <function>..._reference()</function> + function to increase the refcount by one and a + <function>..._destroy()</function> to decrease the refcount + by one. These should not be exposed to the user of the language + binding, but rather used to implement memory management within + the language binding. The simplest way to do memory management + for a language binding is to treat the language binding object + as a simple handle to the cairo object. The language binding + object references the cairo object, and unreferences it when + finalized. This is the recommended method, though there are + a couple of caveats to be noted: + </para> + <itemizedlist> + <listitem> + <para> + Equality won't work as expected. You can have two language + objects for the same cairo and they won't necessarily + compare equal. If the language allows customizing the + equality operation, then this is fixable by comparing + the underlying pointers. It also can be fixed by creating + at most one language object per cairo object, and + uniquifying via a <firstterm>pin table</firstterm> (a hash + table that goes from cairo object to language object). + For <type>cairo_surface_t</type> you can use also + <link + linkend="cairo-surface-set-user-data"><function>cairo_surface_set_user_data()</function></link> + instead of a separate pin table. + </para> + </listitem> + <listitem> + <para> + Derivation from the language object doesn't work because + you can lose the language object while keeping the Cairo + object. Code like: + </para> +<programlisting> +public class MySurface (ImageSurface) { + public MySurface (width, height) { + super (Format.ARGB32, width, height); + } + public int get42 () { + return 42; + } +} + + cr = Cairo(MySurface(width, height)); + surface = cr.getTarget(); +</programlisting> + <para> + Can result in <varname>surface</varname> containing an + <classname>ImageSurface</classname> not a <classname>MySurface</classname>. + This is not easily fixable without creating memory leaks, + and it's probably best to simply forbid deriving from the + language objects. + </para> + </listitem> + </itemizedlist> + <para> + When a plain structure is used as a return value from cairo, + this is done by passing it as a “out parameter”. + </para> +<programlisting> +cairo_font_extents_t extents; + +cairo_font_extents (cr, &extents);</programlisting> + <para> + In a language binding, this should typically be treated + as a return value: + </para> +<programlisting> +FontExtents extents = cr.fontExtents ();</programlisting> + <para> + A language binding has a choice in how it implements the + language objects for plain structures. It can use a pure + language object with fields corresponding to those of the C + structure, and convert from and to the C structure when calling + cairo functions or converting cairo return values. Or it + can keep a pointer to the C structure internally and wrap + it inside a language object much like occurs for refcounted + objects. The choice should be invisible to the user: they should + be able to imagine that it is implemented as a pure language + object. + </para> + </sect1> + <sect1 id="bindings-return-values"> + <title>Multiple return values</title> + <para> + There are a number of functions in the cairo API that have + multiple <firstterm>out parameters</firstterm> or + <firstterm>in-out parameters</firstterm>. In some languages + these can be translated into multiple return values. In Python, + what is: + </para> + <programlisting> +cairo_user_to_device (cr, &x, &y);</programlisting> + <para> + can by mapped to: + </para> + <programlisting> +(x, y) = cr.user_to_device (cr, x, y);</programlisting> + <para> + but many languages don't have provisions for multiple return + values, so it is necessary to introduce auxiliary types. + Most of the functions that require the auxiliary types + require a type that would, in C, look like + </para> + <programlisting> +typedef struct _cairo_point cairo_point_t; +struct _cairo_point { + double x; + double y; +}</programlisting> + <para> + The same type should be used both for functions that use a pair + of coordinates as an absolute position, and functions that use + a pair of coordinates as a displacement. While an argument could + be made that having a separate “distance” type is more correct, + it is more likely just to confuse users. + </para> + <programlisting> +void +cairo_user_to_device (cairo_t *cr, double *x, double *y); + +void +cairo_user_to_device_distance (cairo_t *cr, double *dx, double *dy); + +void +cairo_device_to_user (cairo_t *cr, double *x, double *y); + +void +cairo_device_to_user_distance (cairo_t *cr, double *dx, double *dy); + +void +cairo_matrix_transform_distance (cairo_matrix_t *matrix, double *dx, double *dy); + +void +cairo_matrix_transform_point (cairo_matrix_t *matrix, double *x, double *y); + +void +cairo_get_current_point (cairo_t *cr, double *x, double *y); + </programlisting> + <para> + There are also a couple of functions that return four values + representing a rectangle. These should be mapped to a + “rectangle” type that looks like: + </para> + <programlisting> +typedef struct _cairo_rectangle cairo_rectangle_t; +struct _cairo_rectangle { + double x; + double y; + double width; + double height; +}</programlisting> + <para> + The C function returns the rectangle as a set of two points to + facilitate rounding to integral extents, but this isn't worth + adding a “box” type to go along with the more obvious + “rectangle” representation. + </para> + <remark> + Q: Would it make sense here to define a standard + <function>cairo_rectangle_round()</function> method + that language bindings should map? + </remark> + <programlisting> +void +cairo_stroke_extents (cairo_t *cr, + double *x1, double *y1, + double *x2, double *y2); + +void +cairo_fill_extents (cairo_t *cr, + double *x1, double *y1, + double *x2, double *y2); + </programlisting> + </sect1> + <sect1 id="bindings-overloading"> + <title>Overloading and optional arguments</title> + <para> + Function overloading (having a several variants of a function + with the same name and different arguments) is a language + feature available in many languages but not in C. + </para> + <para> + In general, language binding authors should use restraint in + combining functions in the cairo API via function + overloading. What may seem like an obvious overload now may + turn out to be strange with future additions to cairo. + It might seem logical to make + <link + linkend="cairo-set-source-rgb"><function>cairo_set_source_rgb()</function></link> + an overload of <function>cairo_set_source()</function>, but future plans to add + <function>cairo_set_source_rgb_premultiplied()</function>, + which will also take three doubles make this a bad idea. For + this reason, only the following pairs of functions should + be combined via overloading + </para> + <programlisting> +void +cairo_set_source (cairo_t *cr, cairo_pattern_t *source); + +void +cairo_set_source_surface (cairo_t *cr, + cairo_surface_t *source, + double surface_x, + double surface_y); + +void +cairo_mask (cairo_t *cr, + cairo_pattern_t *pattern); + +void +cairo_mask_surface (cairo_t *cr, + cairo_surface_t *surface, + double surface_x, + double surface_y); + +cairo_surface_t * +cairo_image_surface_create (cairo_format_t format, + int width, + int height); +cairo_surface_t * +cairo_image_surface_create_for_data (unsigned char *data, + cairo_format_t format, + int width, + int height, + int stride); + +cairo_status_t +cairo_surface_write_to_png (cairo_surface_t *surface, + const char *filename); + +cairo_status_t +cairo_surface_write_to_png_stream (cairo_surface_t *surface, + cairo_write_func_t write_func, + void *closure); + +cairo_surface_t * +cairo_image_surface_create_from_png (const char *filename); + +cairo_surface_t * +cairo_image_surface_create_from_png_stream (cairo_read_func_t read_func, + void *closure); + </programlisting> + <para> + Note that there are cases where all constructors for a type + aren't overloaded together. For example + <link + linkend="cairo-image-surface-create-from-png"><function>cairo_image_surface_create_from_png()</function></link> + should <emphasis>not</emphasis> be overloaded together with + <link + linkend="cairo-image-surface-create"><function>cairo_image_surface_create()</function></link>. + In such cases, the remaining constructors will typically need to + be bound as static methods. In Java, for example, we might have: + </para> +<programlisting> +Surface surface1 = ImageSurface(Format.RGB24, 100, 100); +Surface surface2 = ImageSurface.createFromPNG("camera.png");</programlisting> + <para> + Some other overloads that add combinations not found in C may be + convenient for users for language bindings that provide + <type>cairo_point_t</type> and <type>cairo_rectangle_t</type> + types, for example: + </para> + <programlisting> +void +cairo_move_to (cairo_t *cr, + cairo_point_t *point); +void +cairo_rectangle (cairo_t *cr, + cairo_rectangle_t *rectangle); + </programlisting> + </sect1> + <sect1 id="bindings-streams"> + <title>Streams and File I/O</title> + <para> + Various places in the cairo API deal with reading and writing + data, whether from and to files, or to other sources and + destinations. In these cases, what is typically provided in the + C API is a simple version that just takes a filename, and a + complex version that takes a callback function. + An example is the PNG handling functions: + </para> +<programlisting> +cairo_surface_t * +cairo_image_surface_create_from_png (const char *filename); + +cairo_surface_t * +cairo_image_surface_create_from_png_stream (cairo_read_func_t read_func, + void *closure); + +cairo_status_t +cairo_surface_write_to_png (cairo_surface_t *surface, + const char *filename); + +cairo_status_t +cairo_surface_write_to_png_stream (cairo_surface_t *surface, + cairo_write_func_t write_func, + void *closure);</programlisting> + <para> + The expectation is that the filename version will be mapped + literally in the language binding, but the callback version + will be mapped to a version that takes a language stream + object. For example, in Java, the four functions above + might be mapped to: + </para> +<programlisting> +static public ImageSurface createFromPNG (String filename) throws IOException; +static public ImageSurface createFromPNG (InputStream stream) throws IOException; +public void writeToPNG (String filename) throws IOException; +public void writeToPNG (OutputStream stream) throws IOException; +</programlisting> + <para> + In many cases, it will be better to + implement the filename version internally + using the stream version, rather than building it on top of the + filename version in C. The reason for this is that will + naturally give a more standard handling of file errors for + the language, as seen in the above Java example, where + <methodname>createFromPNG()</methodname> is marked as raising + an exception. Propagating exceptions from inside the callback + function to the caller will pose a challenge to the language + binding implementor, since an exception must not propagate + through the Cairo code. A technique that will be useful in + some cases is to catch the exception in the callback, + store the exception object inside a structure pointed to by + <parameter>closure</parameter>, and then rethrow it once + the function returns. + </para> + <remark> + I'm not sure how to handle this for + <link + linkend="cairo-pdf-surface-create-for-callback"><function>cairo_pdf_surface_create_for_callback()</function></link>. + Other than keep a “exception to rethrow” thread-specific + variable + that is checked after <emphasis>every</emphasis> call to a Cairo + function. + </remark> + </sect1> + <sect1 id="bindings-errors"> + <title>Error handling</title> + <para> + The error handling approach in C for Cairo has multiple + elements: + </para> + <itemizedlist> + <listitem><para> + When a method on an object fails, the object is put into + an error state. Subsequent operations on the object do + nothing. The status of the object can be queried with + a function like <link + linkend="cairo-status"><function>status()</function></link>. + </para></listitem> + <listitem><para> + Constructors, rather than + returning<constant>NULL</constant> on out-of-memory failure, + return a special singleton object on which all + operations do nothing. Retrieving the status of the + singleton object returns <constant>CAIRO_STATUS_NO_MEMORY</constant> + </para> + <remark> + Is this going to apply to + <type>cairo_surface_t</type> as well? + </remark> + <remark> + What about cairo_copy_path_data()? It's probably going to + have to return <constant>NULL</constant>. + </remark> + </listitem> + <listitem><para> + Errors propagate from object to object. Setting a pattern + in an out-of-memory state as the source of a + <type>cairo_t</type> puts the type into an error state. + </para></listitem> + </itemizedlist> + <remark>Much of the above is not yet implemented at the time of + this writing</remark> + <para> + A language binding could copy the C approach, and for a + language without exceptions, this is likely the right thing + to do. However, for a language with exceptions, exposing + a completely different style of error handling for cairo + would be strange. So, instead, status should be checked + after every call to cairo, and exceptions thrown as necessary. + </para> + <para> + One problem that can arise with this, in languages + where handling exceptions is mandatory (like Java), is that almost + every cairo function can result in a status being set, + usually because of an out-of-memory condition. This could make + cairo hard to use. To resolve this problem, let's classify then + cairo status codes: + </para> +<programlisting> +/* Memory */ +CAIRO_STATUS_NO_MEMORY, + +/* Programmer error */ +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_INVALID_STRING +CAIRO_STATUS_SURFACE_FINISHED +CAIRO_STATUS_BAD_NESTING + +/* Language binding implementation */ +CAIRO_STATUS_NULL_POINTER +CAIRO_STATUS_INVALID_PATH_DATA +CAIRO_STATUS_SURFACE_TYPE_MISMATCH + +/* Other */ +CAIRO_STATUS_READ_ERROR +CAIRO_STATUS_WRITE_ERROR +</programlisting> + <para> + If we look at these, the + <constant>CAIRO_STATUS_NO_MEMORY</constant> + should map to the native out-of-memory exception, which could + happen at any point in any case. Most of the others indicate + programmer error, and handling them in user code would be + silly. These should be mapped into whatever the language uses + for assertion failures, rather than errors that are normally + handled. (In Java, a subclass of Error rather than Exception, + perhaps.) And <constant>CAIRO_STATUS_READ_ERROR</constant>, + and <constant>CAIRO_STATUS_WRITE_ERROR</constant> can occur + only in very specific places. (In fact, as described + in <xref linkend="bindings-streams"/>, these errors may be + mapped into the language's native I/O error types.) + So, there really aren't exceptions that the programmer must + handle at most points in the Cairo API. + </para> + </sect1> + <sect1 id="bindings-patterns"> + <title>Patterns</title> + <para> + The cairo C API allows for creating a number of different types + of patterns. All of these different types of patterns map to + <link + linkend="cairo-pattern-t"><type>cairo_pattern_t</type></link> + in C, but in an object oriented language, there should instead + be a hierarchy of types. (The functions that should map to + constructors for the various types are listed after the type, + methods on that type are listed below) + </para> + <programlisting> +cairo_pattern_t + <link linkend="cairo-pattern-set-matrix"><function>cairo_pattern_set_matrix()</function></link> + <link linkend="cairo-pattern-get-matrix"><function>cairo_pattern_get_matrix()</function></link> + cairo_solid_pattern_t + cairo_surface_pattern_t (<link linkend="cairo-pattern-create-for-surface"><function>cairo_pattern_create_for_surface()</function></link>) + <link linkend="cairo-pattern-set-extend"><function>cairo_pattern_set_extend()</function></link> + <link linkend="cairo-pattern-get-extend"><function>cairo_pattern_get_extend()</function></link> + <link linkend="cairo-pattern-set-filter"><function>cairo_pattern_set_filter()</function></link> + <link linkend="cairo-pattern-get-filter"><function>cairo_pattern_get_filter()</function></link> + cairo_gradient_t + <link linkend="cairo-pattern-add-color-stop-rgb"><function>cairo_pattern_add_color_stop_rgb()</function></link> + <link linkend="cairo-pattern-add-color-stop-rgba"><function>cairo_pattern_add_color_stop_rgba()</function></link> + cairo_linear_gradient_t (<link linkend="cairo-pattern-create-linear"><function>cairo_pattern_create_linear()</function></link>) + cairo_radial_gradient_t (<link linkend="cairo-pattern-create-radial"><function>cairo_pattern_create_radial()</function></link>) + </programlisting> + <para> + </para> + </sect1> + <sect1 id="bindings-surfaces"> + <title>Surfaces</title> + <para> + Like patterns, surfaces, which use only the + <link + linkend="cairo-surface-t"><type>cairo_surface_t</type></link> + type in the C API should be broken up into a heirarchy of types + in a language binding. + </para> + <programlisting> +cairo_surface_t + cairo_image_surface_t + cairo_atsui_surface_t + cairo_win32_surface_t + cairo_xlib_surface_t + </programlisting> + <para> + Unlike patterns, the constructors and methods on these types are + clearly named, and can be trivially associated with the + appropriate subtype. Many language bindings will want to avoid + binding the platform-specific subtypes at all, since the + methods on these types are not useful without passing in native + C types. Unless there is a language binding for Xlib available, + there is no way to represent a XLib <type>Display</type> * in + that language. + </para> + <para> + This doesn't mean that platform-specific surface types can't + be used in a language binding that doesn't bind the constructor. + A very common situation is to use a cairo language binding in + combination with a binding for a higher level system like + the <ulink url="http://www.gtk.org/">GTK+</ulink> widget + toolkit. In such a situation, the higher level toolkit provides + ways to get references to platform specific surfaces. + </para> + <para> + The <link + linkend="cairo-surface-set-user-data"><function>cairo_surface_set_user_data()</function></link>, + and <link + linkend="cairo-surface-get-user-data"><function>cairo_surface_get_user_data()</function></link> + methods are provided for use in language bindings, and should + not be directly exposed to applications. One example of the use + of these functions in a language binding is creating a binding for: + </para> +<programlisting> +cairo_surface_t * +<link linkend="cairo-image-surface-create-for-data"><function>cairo_image_surface_create_for_data</function></link> (unsigned char *data, + cairo_format_t format, + int width, + int height, + int stride); +</programlisting> + <para> + The memory block passed in for <parameter>data</parameter> must be + kept around until the surface is destroyed, so the language + binding must have some way of determining when that happens. The + way to do this is to use the <parameter>destroy</parameter> + argument to <function>cairo_surface_set_user_data()</function>. + </para> + <remark> + Some languages may not have a suitable “pointer to a block of + data” type to pass in for <parameter>data</parameter>. And even + where a language does have such a type, the user will be + frequently able to cause the backing store to be reallocated + to a different location or truncated. Should we recommend a + standard type name and binding for a buffer object here? + </remark> + </sect1> + <sect1 id="bindings-fonts"> + <title>Fonts</title> + <para> + Fonts are once more an area where there is a hierarchy of types: + </para> +<programlisting> +cairo_font_face_t + cairo_ft_font_face_t + cairo_win32_font_face_t +cairo_scaled_font_t + cairo_ft_scaled_font_t + cairo_win32_scaled_font_t +</programlisting> + <para> + The methods on the subtypes are, however, not useful without + bindings for fontconfig and FreeType or for the Win32 GDI, + so most language bindings will choose not to bind these + types. + </para> + <para> + The <link + linkend="cairo-font-face-set-user-data"><function>cairo_font_face_set_user_data()</function></link>, + and <link + linkend="cairo-font-face-get-user-data"><function>cairo_font_face_get_user_data()</function></link> + methods are provided for use in language bindings, and should + not be directly exposed to applications. + </para> + </sect1> + <sect1 id="bindings-path"> + <title>cairo_path_t</title> + <para> + The <link linkend="cairo-path-t"><type>cairo_path_t</type></link> type is one + area in which most language bindings will differ significantly + from the C API. The C API for <type>cairo_path_t</type> is + designed for efficiency and to avoid auxiliary objects that + would be have to be manually memory managed by the + application. However, + a language binding should not present <type>cairo_path_t</type> as an + array, but rather as an opaque that can be iterated + over. Different languages have quite different conventions for + how iterators work, so it is impossible to give an exact + specification for how this API should work, but the type names + and methods should be similar to the language's mapping of the following: + </para> + <programlisting> +typedef struct cairo_path_iterator cairo_path_iterator_t; +typedef struct cairo_path_element cairo_path_element_t; + +cairo_path_iterator_t * +cairo_path_get_iterator (cairo_path_t *path); + +cairo_bool_t +cairo_path_iterator_has_next (cairo_path_iterator_t *iterator); + +cairo_path_element_t * +cairo_path_iterator_next (cairo_path_iterator_t *iterator); + +cairo_path_element_type_t +cairo_path_element_get_type (cairo_path_element_t *element); + +void +cairo_path_element_get_point (cairo_path_element_t *element, + int index, + double *x, + double *y); + </programlisting> + <para> + The above is written using the Java conventions for + iterators. To illustrate how the API for PathIterator might + depend on the native iteration conventions of the API, examine + three versions of the loop, first written in a hypothetical Java + binding: + </para> + <programlisting> +PathIterator iter = cr.copyPath().iterator(); +while (cr.hasNext()) { + PathElement element = iter.next(); + if (element.getType() == PathElementType.MOVE_TO) { + Point p = element.getPoint(0); + doMoveTo (p.x, p.y); + } +}</programlisting> + <para> + And then in a hypothetical C++ binding: + </para> + <programlisting> +Path path = cr.copyPath(); +for (PathIterator iter = path.begin(); iter != path.end(); iter++) { + PathElement element = *iter; + if (element.getType() == PathElementType.MOVE_TO) { + Point p = element.getPoint(0); + doMoveTo (p.x, p.y); + } +}</programlisting> + <para> + And then finally in a Python binding: + </para> +<programlisting> +for element in cr.copy_path(): + if element.getType == cairo.PATH_ELEMENT_MOVE_TO: + (x, y) = element.getPoint(0) + doMoveTo (x, y);</programlisting> + <para> + While many of the API elements stay the same in the three + examples, the exact iteration mechanism is quite different, to + match how users of the language would expect to iterate over + a container. + </para> + <para> + You should not present an API for mutating or for creating new + <type>cairo_path_t</type> objects. In the future, these + guidelines may be extended to present an API for creating a + <type>cairo_path_t</type> from scratch for use with + <link + linkend="cairo-append-path"><function>cairo_append_path()</function></link> + but the current expectation is that <function>cairo_append_path()</function> will + mostly be used with paths from + <link + linkend="cairo-append-path"><function>cairo_copy_path()</function></link>. + </para> + </sect1> +</appendix> +<!-- +Local variables: +mode: sgml +sgml-parent-document: ("cairo-docs.xml" "book" "book" "appendix") +End: +--> diff --git a/doc/public/tmpl/cairo-atsui.sgml b/doc/public/tmpl/cairo-atsui.sgml index 0d957ecdf..a47ee8c68 100644 --- a/doc/public/tmpl/cairo-atsui.sgml +++ b/doc/public/tmpl/cairo-atsui.sgml @@ -14,6 +14,9 @@ ATSUI Fonts </para> +<!-- ##### SECTION Stability_Level ##### --> + + <!-- ##### FUNCTION cairo_atsui_font_create ##### --> <para> diff --git a/doc/public/tmpl/cairo-font.sgml b/doc/public/tmpl/cairo-font.sgml new file mode 100644 index 000000000..66502930e --- /dev/null +++ b/doc/public/tmpl/cairo-font.sgml @@ -0,0 +1,148 @@ +<!-- ##### SECTION Title ##### --> +Fonts + +<!-- ##### SECTION Short_Description ##### --> +Font Handling + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### TYPEDEF cairo_font_face_t ##### --> +<para> + +</para> + + +<!-- ##### TYPEDEF cairo_scaled_font_t ##### --> +<para> + +</para> + + +<!-- ##### FUNCTION cairo_font_face_reference ##### --> +<para> + +</para> + +@font_face: + + +<!-- ##### FUNCTION cairo_font_face_destroy ##### --> +<para> + +</para> + +@font_face: + + +<!-- ##### FUNCTION cairo_font_face_get_user_data ##### --> +<para> + +</para> + +@font_face: +@key: +@Returns: + + +<!-- ##### FUNCTION cairo_font_face_set_user_data ##### --> +<para> + +</para> + +@font_face: +@key: +@user_data: +@destroy: +@Returns: + + +<!-- ##### FUNCTION cairo_scaled_font_create ##### --> +<para> + +</para> + +@font_face: +@font_matrix: +@ctm: +@Returns: + + +<!-- ##### FUNCTION cairo_scaled_font_reference ##### --> +<para> + +</para> + +@scaled_font: +<!-- # Unused Parameters # --> +@font: + + +<!-- ##### FUNCTION cairo_scaled_font_destroy ##### --> +<para> + +</para> + +@scaled_font: +<!-- # Unused Parameters # --> +@font: + + +<!-- ##### STRUCT cairo_font_extents_t ##### --> +<para> + +</para> + +@ascent: +@descent: +@height: +@max_x_advance: +@max_y_advance: + +<!-- ##### FUNCTION cairo_scaled_font_extents ##### --> +<para> + +</para> + +@scaled_font: +@extents: +@Returns: +<!-- # Unused Parameters # --> +@font: + + +<!-- ##### STRUCT cairo_text_extents_t ##### --> +<para> + +</para> + +@x_bearing: +@y_bearing: +@width: +@height: +@x_advance: +@y_advance: + +<!-- ##### FUNCTION cairo_scaled_font_glyph_extents ##### --> +<para> + +</para> + +@scaled_font: +@glyphs: +@num_glyphs: +@extents: +<!-- # Unused Parameters # --> +@font: + + diff --git a/doc/public/tmpl/cairo-ft.sgml b/doc/public/tmpl/cairo-ft.sgml index bcf52ac34..d9f7cbfc1 100644 --- a/doc/public/tmpl/cairo-ft.sgml +++ b/doc/public/tmpl/cairo-ft.sgml @@ -14,50 +14,42 @@ FreeType Fonts </para> -<!-- ##### FUNCTION cairo_ft_font_create ##### --> +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### FUNCTION cairo_ft_font_face_create_for_pattern ##### --> <para> </para> @pattern: -@scale: @Returns: -<!-- ##### FUNCTION cairo_ft_font_create_for_ft_face ##### --> +<!-- ##### FUNCTION cairo_ft_font_face_create_for_ft_face ##### --> <para> </para> @face: @load_flags: -@scale: @Returns: -<!-- ##### FUNCTION cairo_ft_font_lock_face ##### --> +<!-- ##### FUNCTION cairo_ft_scaled_font_lock_face ##### --> <para> </para> -@ft_font: +@scaled_font: @Returns: -<!-- ##### FUNCTION cairo_ft_font_unlock_face ##### --> +<!-- ##### FUNCTION cairo_ft_scaled_font_unlock_face ##### --> <para> </para> -@ft_font: - - -<!-- ##### FUNCTION cairo_ft_font_get_pattern ##### --> -<para> - -</para> - -@ft_font: -@Returns: +@scaled_font: diff --git a/doc/public/tmpl/cairo-glitz.sgml b/doc/public/tmpl/cairo-glitz.sgml index 101eb9e3e..9594d87a5 100644 --- a/doc/public/tmpl/cairo-glitz.sgml +++ b/doc/public/tmpl/cairo-glitz.sgml @@ -14,13 +14,7 @@ Glitz backend </para> -<!-- ##### FUNCTION cairo_set_target_glitz ##### --> -<para> - -</para> - -@cr: -@surface: +<!-- ##### SECTION Stability_Level ##### --> <!-- ##### FUNCTION cairo_glitz_surface_create ##### --> diff --git a/doc/public/tmpl/cairo-matrix.sgml b/doc/public/tmpl/cairo-matrix.sgml index dc24c5754..c58abe488 100644 --- a/doc/public/tmpl/cairo-matrix.sgml +++ b/doc/public/tmpl/cairo-matrix.sgml @@ -38,77 +38,78 @@ cairo_matrix_t </para> -<!-- ##### TYPEDEF cairo_matrix_t ##### --> -<para> - -</para> +<!-- ##### SECTION Stability_Level ##### --> -<!-- ##### FUNCTION cairo_matrix_create ##### --> +<!-- ##### STRUCT cairo_matrix_t ##### --> <para> </para> -@Returns: - +@xx: +@yx: +@xy: +@yy: +@x0: +@y0: -<!-- ##### FUNCTION cairo_matrix_destroy ##### --> +<!-- ##### FUNCTION cairo_matrix_init ##### --> <para> </para> @matrix: +@xx: +@yx: +@xy: +@yy: +@x0: +@y0: +<!-- # Unused Parameters # --> +@Param7: +@a: +@b: +@c: +@d: +@tx: +@ty: -<!-- ##### FUNCTION cairo_matrix_copy ##### --> +<!-- ##### FUNCTION cairo_matrix_init_identity ##### --> <para> </para> @matrix: -@other: -@Returns: -<!-- ##### FUNCTION cairo_matrix_set_identity ##### --> +<!-- ##### FUNCTION cairo_matrix_init_translate ##### --> <para> </para> @matrix: -@Returns: +@tx: +@ty: -<!-- ##### FUNCTION cairo_matrix_set_affine ##### --> +<!-- ##### FUNCTION cairo_matrix_init_scale ##### --> <para> </para> @matrix: -@a: -@b: -@c: -@d: -@tx: -@ty: -@Returns: -<!-- # Unused Parameters # --> -@cr: +@sx: +@sy: -<!-- ##### FUNCTION cairo_matrix_get_affine ##### --> +<!-- ##### FUNCTION cairo_matrix_init_rotate ##### --> <para> </para> @matrix: -@a: -@b: -@c: -@d: -@tx: -@ty: -@Returns: +@radians: <!-- ##### FUNCTION cairo_matrix_translate ##### --> @@ -119,6 +120,7 @@ cairo_matrix_t @matrix: @tx: @ty: +<!-- # Unused Parameters # --> @Returns: @@ -130,6 +132,7 @@ cairo_matrix_t @matrix: @sx: @sy: +<!-- # Unused Parameters # --> @Returns: @@ -140,6 +143,7 @@ cairo_matrix_t @matrix: @radians: +<!-- # Unused Parameters # --> @Returns: @@ -160,6 +164,7 @@ cairo_matrix_t @result: @a: @b: +<!-- # Unused Parameters # --> @Returns: @@ -171,6 +176,7 @@ cairo_matrix_t @matrix: @dx: @dy: +<!-- # Unused Parameters # --> @Returns: @@ -181,6 +187,7 @@ cairo_matrix_t @matrix: @x: @y: +<!-- # Unused Parameters # --> @Returns: <!-- diff --git a/doc/public/tmpl/cairo-pattern.sgml b/doc/public/tmpl/cairo-pattern.sgml index 84728212b..30deec9b8 100644 --- a/doc/public/tmpl/cairo-pattern.sgml +++ b/doc/public/tmpl/cairo-pattern.sgml @@ -14,6 +14,9 @@ cairo_pattern_t </para> +<!-- ##### SECTION Stability_Level ##### --> + + <!-- ##### TYPEDEF cairo_pattern_t ##### --> <para> @@ -71,7 +74,20 @@ cairo_pattern_t @pattern: -<!-- ##### FUNCTION cairo_pattern_add_color_stop ##### --> +<!-- ##### FUNCTION cairo_pattern_add_color_stop_rgb ##### --> +<para> + +</para> + +@pattern: +@offset: +@red: +@green: +@blue: +@Returns: + + +<!-- ##### FUNCTION cairo_pattern_add_color_stop_rgba ##### --> <para> </para> diff --git a/doc/public/tmpl/cairo-pdf.sgml b/doc/public/tmpl/cairo-pdf.sgml index e627c236e..8ff0ea17e 100644 --- a/doc/public/tmpl/cairo-pdf.sgml +++ b/doc/public/tmpl/cairo-pdf.sgml @@ -14,25 +14,35 @@ PDF Backend </para> -<!-- ##### FUNCTION cairo_set_target_pdf ##### --> +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### FUNCTION cairo_pdf_surface_create ##### --> <para> </para> -@cr: -@file: +@fp: @width_inches: @height_inches: @x_pixels_per_inch: @y_pixels_per_inch: +@Returns: +<!-- # Unused Parameters # --> +@write_func: +@destroy_closure_func: +@closure: +@file: -<!-- ##### FUNCTION cairo_pdf_surface_create ##### --> +<!-- ##### FUNCTION cairo_pdf_surface_create_for_callback ##### --> <para> </para> -@file: +@write_func: +@destroy_closure_func: +@closure: @width_inches: @height_inches: @x_pixels_per_inch: diff --git a/doc/public/tmpl/cairo-png.sgml b/doc/public/tmpl/cairo-png.sgml index d4d5a66b5..dd4486c71 100644 --- a/doc/public/tmpl/cairo-png.sgml +++ b/doc/public/tmpl/cairo-png.sgml @@ -14,27 +14,46 @@ PNG Backend </para> -<!-- ##### FUNCTION cairo_set_target_png ##### --> +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### FUNCTION cairo_image_surface_create_from_png ##### --> +<para> + +</para> + +@filename: +@Returns: + + +<!-- ##### FUNCTION cairo_image_surface_create_from_png_stream ##### --> <para> </para> -@cr: -@file: -@format: -@width: -@height: +@read_func: +@closure: +@Returns: + + +<!-- ##### FUNCTION cairo_surface_write_to_png ##### --> +<para> + +</para> + +@surface: +@filename: +@Returns: -<!-- ##### FUNCTION cairo_png_surface_create ##### --> +<!-- ##### FUNCTION cairo_surface_write_to_png_stream ##### --> <para> </para> -@file: -@format: -@width: -@height: +@surface: +@write_func: +@closure: @Returns: diff --git a/doc/public/tmpl/cairo-ps.sgml b/doc/public/tmpl/cairo-ps.sgml index 70b2e7e8f..4cb4a0268 100644 --- a/doc/public/tmpl/cairo-ps.sgml +++ b/doc/public/tmpl/cairo-ps.sgml @@ -14,17 +14,7 @@ PS Backend </para> -<!-- ##### FUNCTION cairo_set_target_ps ##### --> -<para> - -</para> - -@cr: -@file: -@width_inches: -@height_inches: -@x_pixels_per_inch: -@y_pixels_per_inch: +<!-- ##### SECTION Stability_Level ##### --> <!-- ##### FUNCTION cairo_ps_surface_create ##### --> diff --git a/doc/public/tmpl/cairo-quartz.sgml b/doc/public/tmpl/cairo-quartz.sgml index 04c9bc61f..c83de6c77 100644 --- a/doc/public/tmpl/cairo-quartz.sgml +++ b/doc/public/tmpl/cairo-quartz.sgml @@ -14,15 +14,7 @@ Quartz Backend </para> -<!-- ##### FUNCTION cairo_set_target_quartz_context ##### --> -<para> - -</para> - -@cr: -@context: -@width: -@height: +<!-- ##### SECTION Stability_Level ##### --> <!-- ##### FUNCTION cairo_quartz_surface_create ##### --> diff --git a/doc/public/tmpl/cairo-surface.sgml b/doc/public/tmpl/cairo-surface.sgml index 2f8ad470c..e92935a6c 100644 --- a/doc/public/tmpl/cairo-surface.sgml +++ b/doc/public/tmpl/cairo-surface.sgml @@ -14,23 +14,27 @@ cairo_surface_t </para> +<!-- ##### SECTION Stability_Level ##### --> + + <!-- ##### TYPEDEF cairo_surface_t ##### --> <para> </para> -<!-- ##### FUNCTION cairo_surface_create_for_image ##### --> +<!-- ##### MACRO cairo_surface_create_for_image ##### --> <para> </para> +@Returns: +<!-- # Unused Parameters # --> @data: @format: @width: @height: @stride: -@Returns: <!-- ##### FUNCTION cairo_surface_create_similar ##### --> @@ -61,52 +65,100 @@ cairo_surface_t @surface: -<!-- ##### FUNCTION cairo_surface_set_repeat ##### --> +<!-- ##### FUNCTION cairo_surface_finish ##### --> <para> </para> @surface: -@repeat: @Returns: -<!-- ##### FUNCTION cairo_surface_set_matrix ##### --> +<!-- ##### MACRO cairo_surface_set_repeat ##### --> <para> </para> -@surface: -@matrix: @Returns: +<!-- # Unused Parameters # --> +@surface: +@repeat: -<!-- ##### FUNCTION cairo_surface_get_matrix ##### --> +<!-- ##### MACRO cairo_surface_set_matrix ##### --> <para> </para> +@Returns: +<!-- # Unused Parameters # --> @surface: @matrix: + + +<!-- ##### MACRO cairo_surface_get_matrix ##### --> +<para> + +</para> + @Returns: +<!-- # Unused Parameters # --> +@surface: +@matrix: -<!-- ##### FUNCTION cairo_surface_set_filter ##### --> +<!-- ##### MACRO cairo_surface_set_filter ##### --> <para> </para> +@Returns: +<!-- # Unused Parameters # --> @surface: @filter: + + +<!-- ##### MACRO cairo_surface_get_filter ##### --> +<para> + +</para> + @Returns: +<!-- # Unused Parameters # --> +@surface: -<!-- ##### FUNCTION cairo_surface_get_filter ##### --> +<!-- ##### FUNCTION cairo_surface_set_user_data ##### --> <para> </para> @surface: +@key: +@user_data: +@destroy: @Returns: +<!-- # Unused Parameters # --> +@data: + + +<!-- ##### FUNCTION cairo_surface_get_user_data ##### --> +<para> + +</para> + +@surface: +@key: +@Returns: + + +<!-- ##### FUNCTION cairo_surface_set_device_offset ##### --> +<para> + +</para> + +@surface: +@x_offset: +@y_offset: diff --git a/doc/public/tmpl/cairo-xcb.sgml b/doc/public/tmpl/cairo-xcb.sgml index e5e1ee912..416d71638 100644 --- a/doc/public/tmpl/cairo-xcb.sgml +++ b/doc/public/tmpl/cairo-xcb.sgml @@ -14,15 +14,18 @@ XCB Backend </para> -<!-- ##### FUNCTION cairo_set_target_xcb ##### --> +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### FUNCTION cairo_xcb_surface_create ##### --> <para> </para> -@cr: @dpy: @drawable: @visual: @format: +@Returns: diff --git a/doc/public/tmpl/cairo-xlib.sgml b/doc/public/tmpl/cairo-xlib.sgml index b18e76aae..30282b226 100644 --- a/doc/public/tmpl/cairo-xlib.sgml +++ b/doc/public/tmpl/cairo-xlib.sgml @@ -14,17 +14,24 @@ XLib Backend </para> -<!-- ##### FUNCTION cairo_set_target_drawable ##### --> +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### FUNCTION cairo_xlib_surface_create ##### --> <para> </para> -@cr: @dpy: @drawable: +@format: +@Returns: +<!-- # Unused Parameters # --> +@visual: +@colormap: -<!-- ##### FUNCTION cairo_xlib_surface_create ##### --> +<!-- ##### FUNCTION cairo_xlib_surface_create_with_visual ##### --> <para> </para> @@ -32,8 +39,16 @@ XLib Backend @dpy: @drawable: @visual: -@format: -@colormap: @Returns: +<!-- ##### FUNCTION cairo_xlib_surface_set_size ##### --> +<para> + +</para> + +@surface: +@width: +@height: + + diff --git a/doc/public/tmpl/cairo.sgml b/doc/public/tmpl/cairo.sgml index a9e195c73..06a5fba6d 100644 --- a/doc/public/tmpl/cairo.sgml +++ b/doc/public/tmpl/cairo.sgml @@ -24,6 +24,9 @@ Drawing contexts. </para> +<!-- ##### SECTION Stability_Level ##### --> + + <!-- ##### TYPEDEF cairo_t ##### --> <para> @@ -35,6 +38,7 @@ Drawing contexts. </para> +@target: @Returns: @@ -70,24 +74,16 @@ Drawing contexts. @cr: -<!-- ##### FUNCTION cairo_copy ##### --> +<!-- ##### MACRO cairo_copy ##### --> <para> </para> +<!-- # Unused Parameters # --> @dest: @src: -<!-- ##### FUNCTION cairo_set_target_surface ##### --> -<para> - -</para> - -@cr: -@surface: - - <!-- ##### ENUM cairo_format_t ##### --> <para> @@ -98,35 +94,22 @@ Drawing contexts. @CAIRO_FORMAT_A8: @CAIRO_FORMAT_A1: -<!-- ##### FUNCTION cairo_set_target_image ##### --> -<para> - -</para> - -@cr: -@data: -@format: -@width: -@height: -@stride: - - <!-- ##### ENUM cairo_operator_t ##### --> <para> </para> @CAIRO_OPERATOR_CLEAR: -@CAIRO_OPERATOR_SRC: -@CAIRO_OPERATOR_DST: +@CAIRO_OPERATOR_SOURCE: @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_DEST: +@CAIRO_OPERATOR_DEST_OVER: +@CAIRO_OPERATOR_DEST_IN: +@CAIRO_OPERATOR_DEST_OUT: +@CAIRO_OPERATOR_DEST_ATOP: @CAIRO_OPERATOR_XOR: @CAIRO_OPERATOR_ADD: @CAIRO_OPERATOR_SATURATE: @@ -140,7 +123,18 @@ Drawing contexts. @op: -<!-- ##### FUNCTION cairo_set_rgb_color ##### --> +<!-- ##### FUNCTION cairo_set_source_rgb ##### --> +<para> + +</para> + +@cr: +@red: +@green: +@blue: + + +<!-- ##### FUNCTION cairo_set_source_rgba ##### --> <para> </para> @@ -149,22 +143,37 @@ Drawing contexts. @red: @green: @blue: +@alpha: -<!-- ##### FUNCTION cairo_set_pattern ##### --> +<!-- ##### FUNCTION cairo_set_source ##### --> <para> </para> @cr: +@source: +<!-- # Unused Parameters # --> @pattern: -<!-- ##### FUNCTION cairo_set_alpha ##### --> +<!-- ##### FUNCTION cairo_set_source_surface ##### --> +<para> + +</para> + +@cr: +@surface: +@x: +@y: + + +<!-- ##### MACRO cairo_set_alpha ##### --> <para> </para> +<!-- # Unused Parameters # --> @cr: @alpha: @@ -289,7 +298,7 @@ Drawing contexts. @angle: -<!-- ##### FUNCTION cairo_concat_matrix ##### --> +<!-- ##### FUNCTION cairo_transform ##### --> <para> </para> @@ -307,11 +316,12 @@ Drawing contexts. @matrix: -<!-- ##### FUNCTION cairo_default_matrix ##### --> +<!-- ##### MACRO cairo_default_matrix ##### --> <para> </para> +<!-- # Unused Parameters # --> @cr: @@ -323,7 +333,7 @@ Drawing contexts. @cr: -<!-- ##### FUNCTION cairo_transform_point ##### --> +<!-- ##### FUNCTION cairo_user_to_device ##### --> <para> </para> @@ -333,7 +343,7 @@ Drawing contexts. @y: -<!-- ##### FUNCTION cairo_transform_distance ##### --> +<!-- ##### FUNCTION cairo_user_to_device_distance ##### --> <para> </para> @@ -343,7 +353,7 @@ Drawing contexts. @dy: -<!-- ##### FUNCTION cairo_inverse_transform_point ##### --> +<!-- ##### FUNCTION cairo_device_to_user ##### --> <para> </para> @@ -353,7 +363,7 @@ Drawing contexts. @y: -<!-- ##### FUNCTION cairo_inverse_transform_distance ##### --> +<!-- ##### FUNCTION cairo_device_to_user_distance ##### --> <para> </para> @@ -485,6 +495,43 @@ Drawing contexts. @cr: +<!-- ##### FUNCTION cairo_paint ##### --> +<para> + +</para> + +@cr: + + +<!-- ##### FUNCTION cairo_paint_with_alpha ##### --> +<para> + +</para> + +@cr: +@alpha: + + +<!-- ##### FUNCTION cairo_mask ##### --> +<para> + +</para> + +@cr: +@pattern: + + +<!-- ##### FUNCTION cairo_mask_surface ##### --> +<para> + +</para> + +@cr: +@surface: +@surface_x: +@surface_y: + + <!-- ##### FUNCTION cairo_stroke ##### --> <para> @@ -493,6 +540,14 @@ Drawing contexts. @cr: +<!-- ##### FUNCTION cairo_stroke_preserve ##### --> +<para> + +</para> + +@cr: + + <!-- ##### FUNCTION cairo_fill ##### --> <para> @@ -501,6 +556,14 @@ Drawing contexts. @cr: +<!-- ##### FUNCTION cairo_fill_preserve ##### --> +<para> + +</para> + +@cr: + + <!-- ##### FUNCTION cairo_copy_page ##### --> <para> @@ -569,7 +632,7 @@ Drawing contexts. @y2: -<!-- ##### FUNCTION cairo_init_clip ##### --> +<!-- ##### FUNCTION cairo_clip ##### --> <para> </para> @@ -577,7 +640,7 @@ Drawing contexts. @cr: -<!-- ##### FUNCTION cairo_clip ##### --> +<!-- ##### FUNCTION cairo_clip_preserve ##### --> <para> </para> @@ -585,11 +648,13 @@ Drawing contexts. @cr: -<!-- ##### TYPEDEF cairo_font_t ##### --> +<!-- ##### FUNCTION cairo_reset_clip ##### --> <para> </para> +@cr: + <!-- ##### STRUCT cairo_glyph_t ##### --> <para> @@ -600,29 +665,6 @@ Drawing contexts. @x: @y: -<!-- ##### STRUCT cairo_text_extents_t ##### --> -<para> - -</para> - -@x_bearing: -@y_bearing: -@width: -@height: -@x_advance: -@y_advance: - -<!-- ##### STRUCT cairo_font_extents_t ##### --> -<para> - -</para> - -@ascent: -@descent: -@height: -@max_x_advance: -@max_y_advance: - <!-- ##### ENUM cairo_font_slant_t ##### --> <para> @@ -640,7 +682,7 @@ Drawing contexts. @CAIRO_FONT_WEIGHT_NORMAL: @CAIRO_FONT_WEIGHT_BOLD: -<!-- ##### FUNCTION cairo_select_font ##### --> +<!-- ##### FUNCTION cairo_select_font_face ##### --> <para> </para> @@ -651,16 +693,16 @@ Drawing contexts. @weight: -<!-- ##### FUNCTION cairo_scale_font ##### --> +<!-- ##### FUNCTION cairo_set_font_size ##### --> <para> </para> @cr: -@scale: +@size: -<!-- ##### FUNCTION cairo_transform_font ##### --> +<!-- ##### FUNCTION cairo_set_font_matrix ##### --> <para> </para> @@ -669,6 +711,16 @@ Drawing contexts. @matrix: +<!-- ##### FUNCTION cairo_get_font_matrix ##### --> +<para> + +</para> + +@cr: +@matrix: +@Returns: + + <!-- ##### FUNCTION cairo_show_text ##### --> <para> @@ -688,7 +740,7 @@ Drawing contexts. @num_glyphs: -<!-- ##### FUNCTION cairo_current_font ##### --> +<!-- ##### FUNCTION cairo_get_font_face ##### --> <para> </para> @@ -697,22 +749,26 @@ Drawing contexts. @Returns: -<!-- ##### FUNCTION cairo_current_font_extents ##### --> +<!-- ##### FUNCTION cairo_font_extents ##### --> <para> </para> @cr: @extents: +<!-- # Unused Parameters # --> +@font: +@Returns: +@font_matrix: -<!-- ##### FUNCTION cairo_set_font ##### --> +<!-- ##### FUNCTION cairo_set_font_face ##### --> <para> </para> @cr: -@font: +@font_face: <!-- ##### FUNCTION cairo_text_extents ##### --> @@ -755,66 +811,65 @@ Drawing contexts. @num_glyphs: -<!-- ##### FUNCTION cairo_font_reference ##### --> +<!-- ##### MACRO cairo_show_surface ##### --> <para> </para> -@font: +<!-- # Unused Parameters # --> +@cr: +@surface: +@width: +@height: -<!-- ##### FUNCTION cairo_font_destroy ##### --> +<!-- ##### FUNCTION cairo_get_operator ##### --> <para> </para> -@font: +@cr: +@Returns: -<!-- ##### FUNCTION cairo_font_glyph_extents ##### --> +<!-- ##### FUNCTION cairo_get_source ##### --> <para> </para> -@font: -@font_matrix: -@glyphs: -@num_glyphs: -@extents: +@cr: +@Returns: -<!-- ##### FUNCTION cairo_show_surface ##### --> +<!-- ##### FUNCTION cairo_get_tolerance ##### --> <para> </para> @cr: -@surface: -@width: -@height: +@Returns: -<!-- ##### FUNCTION cairo_current_operator ##### --> +<!-- ##### FUNCTION cairo_get_current_point ##### --> <para> </para> @cr: -@Returns: +@x: +@y: -<!-- ##### FUNCTION cairo_current_rgb_color ##### --> +<!-- ##### FUNCTION cairo_get_fill_rule ##### --> <para> </para> @cr: -@red: -@green: -@blue: +@Returns: -<!-- ##### FUNCTION cairo_current_pattern ##### --> +<!-- ##### FUNCTION cairo_get_line_width ##### --> <para> </para> @@ -823,7 +878,7 @@ Drawing contexts. @Returns: -<!-- ##### FUNCTION cairo_current_alpha ##### --> +<!-- ##### FUNCTION cairo_get_line_cap ##### --> <para> </para> @@ -832,7 +887,7 @@ Drawing contexts. @Returns: -<!-- ##### FUNCTION cairo_current_tolerance ##### --> +<!-- ##### FUNCTION cairo_get_line_join ##### --> <para> </para> @@ -841,26 +896,27 @@ Drawing contexts. @Returns: -<!-- ##### FUNCTION cairo_current_point ##### --> +<!-- ##### FUNCTION cairo_get_miter_limit ##### --> <para> </para> @cr: -@x: -@y: +@Returns: -<!-- ##### FUNCTION cairo_current_fill_rule ##### --> +<!-- ##### FUNCTION cairo_get_matrix ##### --> <para> </para> @cr: +@matrix: +<!-- # Unused Parameters # --> @Returns: -<!-- ##### FUNCTION cairo_current_line_width ##### --> +<!-- ##### FUNCTION cairo_get_target ##### --> <para> </para> @@ -869,25 +925,34 @@ Drawing contexts. @Returns: -<!-- ##### FUNCTION cairo_current_line_cap ##### --> +<!-- ##### MACRO cairo_get_path ##### --> <para> </para> +<!-- # Unused Parameters # --> @cr: -@Returns: +@move_to: +@line_to: +@curve_to: +@close_path: +@closure: -<!-- ##### FUNCTION cairo_current_line_join ##### --> +<!-- ##### MACRO cairo_get_path_flat ##### --> <para> </para> +<!-- # Unused Parameters # --> @cr: -@Returns: +@move_to: +@line_to: +@close_path: +@closure: -<!-- ##### FUNCTION cairo_current_miter_limit ##### --> +<!-- ##### FUNCTION cairo_copy_path ##### --> <para> </para> @@ -896,47 +961,38 @@ Drawing contexts. @Returns: -<!-- ##### FUNCTION cairo_current_matrix ##### --> +<!-- ##### FUNCTION cairo_copy_path_flat ##### --> <para> </para> @cr: -@matrix: +@Returns: -<!-- ##### FUNCTION cairo_current_target_surface ##### --> +<!-- ##### FUNCTION cairo_append_path ##### --> <para> </para> @cr: -@Returns: +@path: -<!-- ##### FUNCTION cairo_current_path ##### --> +<!-- ##### STRUCT cairo_path_t ##### --> <para> </para> -@cr: -@move_to: -@line_to: -@curve_to: -@close_path: -@closure: - +@data: +@num_data: -<!-- ##### FUNCTION cairo_current_path_flat ##### --> +<!-- ##### FUNCTION cairo_path_destroy ##### --> <para> </para> -@cr: -@move_to: -@line_to: -@close_path: -@closure: +@path: <!-- ##### ENUM cairo_status_t ##### --> @@ -953,6 +1009,12 @@ Drawing contexts. @CAIRO_STATUS_NO_TARGET_SURFACE: @CAIRO_STATUS_NULL_POINTER: @CAIRO_STATUS_INVALID_STRING: +@CAIRO_STATUS_INVALID_PATH_DATA: +@CAIRO_STATUS_READ_ERROR: +@CAIRO_STATUS_WRITE_ERROR: +@CAIRO_STATUS_SURFACE_FINISHED: +@CAIRO_STATUS_SURFACE_TYPE_MISMATCH: +@CAIRO_STATUS_BAD_NESTING: <!-- ##### FUNCTION cairo_status ##### --> <para> @@ -1017,3 +1079,58 @@ End: --> +<!-- ##### FUNCTION cairo_image_surface_get_width ##### --> +<para> + +</para> + +@surface: +@Returns: + + +<!-- ##### FUNCTION cairo_image_surface_get_height ##### --> +<para> + +</para> + +@surface: +@Returns: + + +<!-- ##### USER_FUNCTION cairo_destroy_func_t ##### --> +<para> + +</para> + +@data: + + +<!-- ##### STRUCT cairo_user_data_key_t ##### --> +<para> + +</para> + +@unused: + +<!-- ##### USER_FUNCTION cairo_read_func_t ##### --> +<para> + +</para> + +@closure: +@data: +@length: +@Returns: + + +<!-- ##### USER_FUNCTION cairo_write_func_t ##### --> +<para> + +</para> + +@closure: +@data: +@length: +@Returns: + + |