From 66436d132772af627447a929ced3a8a18cc6915f Mon Sep 17 00:00:00 2001 From: Behdad Esfahbod Date: Fri, 30 Jun 2006 00:46:48 +0200 Subject: [PATCH] Update lots of docs. --- doc/public/Makefile.am | 9 +++- doc/public/cairo-sections.txt | 90 +++++++++++++++++++---------------- src/cairo-pdf-surface.c | 10 ++-- src/cairo-ps-surface.c | 16 +++---- src/cairo-svg-surface.c | 14 +++--- src/cairo-win32-font.c | 19 +++++++- src/cairo-win32-surface.c | 3 ++ src/cairo-xlib-surface.c | 72 ++++++++++++++++++++++++++++ src/cairo.h | 18 ++++--- 9 files changed, 177 insertions(+), 74 deletions(-) diff --git a/doc/public/Makefile.am b/doc/public/Makefile.am index 21996d26d..ce815e2e6 100644 --- a/doc/public/Makefile.am +++ b/doc/public/Makefile.am @@ -45,7 +45,14 @@ IGNORE_HFILES= \ cairo-scaled-font-test.h \ cairo-svg-test.h \ cairo-xlib-test.h \ - cairoint.h + cairoint.h \ + cairo-atsui.h \ + cairo-beos.h \ + cairo-directfb.h \ + cairo-glitz.h \ + cairo-quartz.h \ + cairo-xcb.h \ + cairo-xcb-xrender.h # CFLAGS and LDFLAGS for compiling scan program. Only needed diff --git a/doc/public/cairo-sections.txt b/doc/public/cairo-sections.txt index 575aa67aa..5215fe0f2 100644 --- a/doc/public/cairo-sections.txt +++ b/doc/public/cairo-sections.txt @@ -12,25 +12,23 @@ cairo_ft_scaled_font_unlock_face cairo-win32-fonts Win32 Fonts cairo_win32_font_face_create_for_logfontw +cairo_win32_font_face_create_for_hfont cairo_win32_scaled_font_select_font cairo_win32_scaled_font_done_font cairo_win32_scaled_font_get_metrics_factor -
-cairo-glitz -Glitz Surfaces -cairo_glitz_surface_create -
-
cairo-image Image Surfaces cairo_format_t cairo_image_surface_create cairo_image_surface_create_for_data +cairo_image_surface_get_data +cairo_image_surface_get_format cairo_image_surface_get_width cairo_image_surface_get_height +cairo_image_surface_get_stride
@@ -38,7 +36,7 @@ cairo_image_surface_get_height PDF Surfaces cairo_pdf_surface_create cairo_pdf_surface_create_for_stream -cairo_pdf_surface_set_dpi +cairo_pdf_surface_set_size
@@ -57,40 +55,18 @@ cairo_surface_write_to_png_stream PostScript Surfaces cairo_ps_surface_create cairo_ps_surface_create_for_stream -cairo_ps_surface_set_dpi -
- -
-cairo-quartz -Quartz Surfaces -cairo_quartz_surface_create +cairo_ps_surface_set_size +cairo_ps_surface_dsc_begin_setup +cairo_ps_surface_dsc_begin_page_setup +cairo_ps_surface_dsc_comment
cairo-win32 Win32 Surfaces cairo_win32_surface_create -
- -
-cairo-beos -BeOS Surfaces -cairo_beos_surface_create -cairo_beos_surface_create_for_bitmap -
- -
-cairo-xcb -XCB Surfaces -cairo_xcb_surface_create -cairo_xcb_surface_create_for_bitmap -cairo_xcb_surface_set_size -
- -
-cairo-xcb-xrender -XCB Render Surfaces -cairo_xcb_surface_create_with_xrender_format +cairo_win32_surface_create_with_dib +cairo_win32_surface_get_dc
@@ -99,7 +75,14 @@ cairo_xcb_surface_create_with_xrender_format cairo_xlib_surface_create cairo_xlib_surface_create_for_bitmap cairo_xlib_surface_set_size +cairo_xlib_surface_get_display +cairo_xlib_surface_get_screen cairo_xlib_surface_set_drawable +cairo_xlib_surface_get_drawable +cairo_xlib_surface_get_visual +cairo_xlib_surface_get_width +cairo_xlib_surface_get_height +cairo_xlib_surface_get_depth
@@ -113,8 +96,8 @@ cairo_xlib_surface_create_with_xrender_format SVG Surfaces cairo_svg_surface_create cairo_svg_surface_create_for_stream -cairo_svg_surface_set_dpi cairo_svg_surface_restrict_to_version +cairo_svg_version_t cairo_svg_get_versions cairo_svg_version_to_string
@@ -129,13 +112,18 @@ cairo_surface_destroy cairo_surface_finish cairo_surface_flush cairo_surface_get_font_options +cairo_surface_get_content cairo_surface_set_user_data cairo_surface_get_user_data cairo_surface_mark_dirty cairo_surface_mark_dirty_rectangle cairo_surface_reference cairo_surface_set_device_offset +cairo_surface_get_device_offset +cairo_surface_set_fallback_resolution cairo_surface_status +cairo_surface_type_t +cairo_surface_get_type
@@ -170,6 +158,8 @@ cairo_pattern_set_filter cairo_pattern_get_filter cairo_pattern_set_matrix cairo_pattern_get_matrix +cairo_pattern_type_t +cairo_pattern_get_type
@@ -207,6 +197,8 @@ cairo_font_face_destroy cairo_font_face_status cairo_font_face_get_user_data cairo_font_face_set_user_data +cairo_font_type_t +cairo_font_face_get_type
@@ -220,7 +212,13 @@ cairo_scaled_font_status cairo_font_extents_t cairo_scaled_font_extents cairo_text_extents_t +cairo_scaled_font_text_extents cairo_scaled_font_glyph_extents +cairo_scaled_font_get_font_face +cairo_scaled_font_get_font_options +cairo_scaled_font_get_font_matrix +cairo_scaled_font_get_ctm +cairo_scaled_font_get_type
@@ -284,6 +282,7 @@ cairo_path_destroy cairo_append_path cairo_get_current_point cairo_new_path +cairo_new_sub_path cairo_close_path cairo_arc cairo_arc_negative @@ -315,6 +314,7 @@ cairo_show_glyphs cairo_get_font_face cairo_font_extents cairo_set_font_face +cairo_set_scaled_font cairo_text_extents cairo_glyph_extents
@@ -326,10 +326,15 @@ cairo_t cairo_create cairo_reference cairo_destroy +cairo_status cairo_save cairo_restore -cairo_status cairo_get_target +cairo_push_group +cairo_push_group_with_content +cairo_pop_group +cairo_pop_group_to_source +cairo_get_group_target cairo_set_source_rgb cairo_set_source_rgba cairo_set_source @@ -375,6 +380,9 @@ cairo_in_stroke cairo_copy_page cairo_show_page +cairo_public +CAIRO_BEGIN_DECLS +CAIRO_END_DECLS cairo_current_font_extents cairo_get_font_extents cairo_current_operator @@ -388,7 +396,6 @@ cairo_current_miter_limit cairo_current_matrix cairo_current_target_surface cairo_get_status -cairo_get_status_string cairo_concat_matrix cairo_scale_font cairo_select_font @@ -409,6 +416,9 @@ cairo_xlib_surface_create_for_pixmap_with_visual cairo_xlib_surface_create_for_window_with_visual cairo_xcb_surface_create_for_pixmap_with_visual cairo_xcb_surface_create_for_window_with_visual +cairo_ps_surface_set_dpi +cairo_pdf_surface_set_dpi +cairo_svg_surface_set_dpi cairo_current_path cairo_current_path_flat cairo_get_path @@ -424,8 +434,6 @@ cairo_surface_get_filter cairo_matrix_create cairo_matrix_destroy cairo_matrix_copy -cairo_matrix_set_identity -cairo_matrix_set_affine cairo_matrix_get_affine cairo_set_target_surface cairo_set_target_glitz @@ -437,4 +445,6 @@ cairo_set_target_quartz cairo_set_target_win32 cairo_set_target_xcb cairo_set_target_drawable +cairo_get_status_string +cairo_status_string diff --git a/src/cairo-pdf-surface.c b/src/cairo-pdf-surface.c index 2bc349c00..663097f21 100644 --- a/src/cairo-pdf-surface.c +++ b/src/cairo-pdf-surface.c @@ -305,13 +305,13 @@ _cairo_pdf_surface_create_for_stream_internal (cairo_output_stream_t *output, /** * cairo_pdf_surface_create_for_stream: - * @write: a #cairo_write_func_t to accept the output data - * @closure: the closure argument for @write + * @write_func: a #cairo_write_func_t to accept the output data + * @closure: the closure argument for @write_func * @width_in_points: width of the surface, in points (1 point == 1/72.0 inch) * @height_in_points: height of the surface, in points (1 point == 1/72.0 inch) * * Creates a PDF surface of the specified size in points to be written - * incrementally to the stream represented by @write and @closure. + * incrementally to the stream represented by @write_func and @closure. * * Return value: a pointer to the newly created surface. The caller * owns the surface and should call cairo_surface_destroy when done @@ -324,7 +324,7 @@ _cairo_pdf_surface_create_for_stream_internal (cairo_output_stream_t *output, * Since: 1.2 */ cairo_surface_t * -cairo_pdf_surface_create_for_stream (cairo_write_func_t write, +cairo_pdf_surface_create_for_stream (cairo_write_func_t write_func, void *closure, double width_in_points, double height_in_points) @@ -332,7 +332,7 @@ cairo_pdf_surface_create_for_stream (cairo_write_func_t write, cairo_status_t status; cairo_output_stream_t *output; - output = _cairo_output_stream_create (write, NULL, closure); + output = _cairo_output_stream_create (write_func, NULL, closure); status = _cairo_output_stream_get_status (output); if (status) { _cairo_error (status); diff --git a/src/cairo-ps-surface.c b/src/cairo-ps-surface.c index 602130678..f8915a23d 100644 --- a/src/cairo-ps-surface.c +++ b/src/cairo-ps-surface.c @@ -773,13 +773,13 @@ cairo_ps_surface_create (const char *filename, /** * cairo_ps_surface_create_for_stream: - * @write: a #cairo_write_func_t to accept the output data - * @closure: the closure argument for @write + * @write_func: a #cairo_write_func_t to accept the output data + * @closure: the closure argument for @write_func * @width_in_points: width of the surface, in points (1 point == 1/72.0 inch) * @height_in_points: height of the surface, in points (1 point == 1/72.0 inch) * * Creates a PostScript surface of the specified size in points to be - * written incrementally to the stream represented by @write and + * written incrementally to the stream represented by @write_func and * @closure. See cairo_ps_surface_create() for a more convenient way * to simply direct the PostScript output to a named file. * @@ -948,23 +948,21 @@ cairo_ps_surface_set_size (cairo_surface_t *surface, * * * cairo_surface_t *surface = cairo_ps_surface_create (filename, width, height); - * + * ... * cairo_ps_surface_dsc_comment (surface, "%%Title: My excellent document"); * cairo_ps_surface_dsc_comment (surface, "%%Copyright: Copyright (C) 2006 Cairo Lover") - * + * ... * cairo_ps_surface_dsc_begin_setup (surface); * cairo_ps_surface_dsc_comment (surface, "%%IncludeFeature: *MediaColor White"); - * + * ... * cairo_ps_surface_dsc_begin_page_setup (surface); * cairo_ps_surface_dsc_comment (surface, "%%IncludeFeature: *PageSize A3"); * cairo_ps_surface_dsc_comment (surface, "%%IncludeFeature: *InputSlot LargeCapacity"); * cairo_ps_surface_dsc_comment (surface, "%%IncludeFeature: *MediaType Glossy"); * cairo_ps_surface_dsc_comment (surface, "%%IncludeFeature: *MediaColor Blue"); - * * ... draw to first page here .. - * * cairo_show_page (cr); - * + * ... * cairo_ps_surface_dsc_comment (surface, "%%IncludeFeature: *PageSize A5"); * ... * diff --git a/src/cairo-svg-surface.c b/src/cairo-svg-surface.c index 95de094f0..7e27787c4 100644 --- a/src/cairo-svg-surface.c +++ b/src/cairo-svg-surface.c @@ -156,13 +156,13 @@ static const cairo_paginated_surface_backend_t cairo_svg_surface_paginated_backe /** * cairo_svg_surface_create_for_stream: - * @write: a #cairo_write_func_t to accept the output data - * @closure: the closure argument for @write + * @write_func: a #cairo_write_func_t to accept the output data + * @closure: the closure argument for @write_func * @width_in_points: width of the surface, in points (1 point == 1/72.0 inch) * @height_in_points: height of the surface, in points (1 point == 1/72.0 inch) * * Creates a SVG surface of the specified size in points to be written - * incrementally to the stream represented by @write and @closure. + * incrementally to the stream represented by @write_func and @closure. * * Return value: a pointer to the newly created surface. The caller * owns the surface and should call cairo_surface_destroy when done @@ -175,7 +175,7 @@ static const cairo_paginated_surface_backend_t cairo_svg_surface_paginated_backe * Since: 1.2 */ cairo_surface_t * -cairo_svg_surface_create_for_stream (cairo_write_func_t write, +cairo_svg_surface_create_for_stream (cairo_write_func_t write_func, void *closure, double width, double height) @@ -183,7 +183,7 @@ cairo_svg_surface_create_for_stream (cairo_write_func_t write, cairo_status_t status; cairo_output_stream_t *stream; - stream = _cairo_output_stream_create (write, NULL, closure); + stream = _cairo_output_stream_create (write_func, NULL, closure); status = _cairo_output_stream_get_status (stream); if (status) { _cairo_error (status); @@ -294,10 +294,10 @@ cairo_svg_surface_restrict_to_version (cairo_surface_t *abstract_surface, /** * cairo_svg_get_versions: - * @version: supported version list + * @versions: supported version list * @num_versions: list length * - * Returns the list of supported versions. See + * Used to retrieve the list of supported versions. See * cairo_svg_surface_restrict_to_version(). * * Since: 1.2 diff --git a/src/cairo-win32-font.c b/src/cairo-win32-font.c index 144c3e14f..39c952224 100644 --- a/src/cairo-win32-font.c +++ b/src/cairo-win32-font.c @@ -1415,8 +1415,9 @@ static const cairo_font_face_backend_t _cairo_win32_font_face_backend = { * * Creates a new font for the Win32 font backend based on a * #LOGFONT. This font can then be used with - * cairo_set_font_face() or cairo_font_create(). The #cairo_scaled_font_t - * returned from cairo_font_create() is also for the Win32 backend + * cairo_set_font_face() or cairo_scaled_font_create(). + * The #cairo_scaled_font_t + * returned from cairo_scaled_font_create() is also for the Win32 backend * and can be used with functions such as cairo_win32_scaled_font_select_font(). * * Return value: a newly created #cairo_font_face_t. Free with @@ -1441,6 +1442,20 @@ cairo_win32_font_face_create_for_logfontw (LOGFONTW *logfont) return &font_face->base; } +/** + * cairo_win32_font_face_create_for_hfont: + * @font: An #HFONT structure specifying the font to use. + * + * Creates a new font for the Win32 font backend based on a + * #HFONT. This font can then be used with + * cairo_set_font_face() or cairo_scaled_font_create(). + * The #cairo_scaled_font_t + * returned from cairo_scaled_font_create() is also for the Win32 backend + * and can be used with functions such as cairo_win32_scaled_font_select_font(). + * + * Return value: a newly created #cairo_font_face_t. Free with + * cairo_font_face_destroy() when you are done using it. + **/ cairo_font_face_t * cairo_win32_font_face_create_for_hfont (HFONT font) { diff --git a/src/cairo-win32-surface.c b/src/cairo-win32-surface.c index 404dd4cdf..0554e43e3 100644 --- a/src/cairo-win32-surface.c +++ b/src/cairo-win32-surface.c @@ -1184,6 +1184,7 @@ cairo_win32_surface_create (HDC hdc) * * Return value: the newly created surface * + * Since: 1.2 **/ cairo_surface_t * cairo_win32_surface_create_with_dib (cairo_format_t format, @@ -1215,6 +1216,8 @@ _cairo_surface_is_win32 (cairo_surface_t *surface) * Also returns NULL if the surface is not a win32 surface. * * Return value: HDC or NULL if no HDC available. + * + * Since: 1.2 **/ HDC cairo_win32_surface_get_dc (cairo_surface_t *surface) diff --git a/src/cairo-xlib-surface.c b/src/cairo-xlib-surface.c index 8b9d02e5c..cffefa761 100644 --- a/src/cairo-xlib-surface.c +++ b/src/cairo-xlib-surface.c @@ -2082,6 +2082,16 @@ cairo_xlib_surface_set_drawable (cairo_surface_t *abstract_surface, surface->height = height; } +/** + * cairo_xlib_surface_get_display: + * @surface: a #cairo_xlib_surface_t + * + * Get the X Display for the underlying X Drawable. + * + * Return value: the display. + * + * Since: 1.2 + **/ Display * cairo_xlib_surface_get_display (cairo_surface_t *abstract_surface) { @@ -2095,6 +2105,18 @@ cairo_xlib_surface_get_display (cairo_surface_t *abstract_surface) return surface->dpy; } + * @dpy: an X Display + +/** + * cairo_xlib_surface_get_drawable: + * @surface: a #cairo_xlib_surface_t + * + * Get the underlying X Drawable used for the surface. + * + * Return value: the drawable. + * + * Since: 1.2 + **/ Drawable cairo_xlib_surface_get_drawable (cairo_surface_t *abstract_surface) { @@ -2108,6 +2130,16 @@ cairo_xlib_surface_get_drawable (cairo_surface_t *abstract_surface) return surface->drawable; } +/** + * cairo_xlib_surface_get_screen: + * @surface: a #cairo_xlib_surface_t + * + * Get the X Screen for the underlying X Drawable. + * + * Return value: the screen. + * + * Since: 1.2 + **/ Screen * cairo_xlib_surface_get_screen (cairo_surface_t *abstract_surface) { @@ -2121,6 +2153,16 @@ cairo_xlib_surface_get_screen (cairo_surface_t *abstract_surface) return surface->screen; } +/** + * cairo_xlib_surface_get_visual: + * @surface: a #cairo_xlib_surface_t + * + * Get the X Visual used for underlying X Drawable. + * + * Return value: the visual. + * + * Since: 1.2 + **/ Visual * cairo_xlib_surface_get_visual (cairo_surface_t *abstract_surface) { @@ -2134,6 +2176,16 @@ cairo_xlib_surface_get_visual (cairo_surface_t *abstract_surface) return surface->visual; } +/** + * cairo_xlib_surface_get_depth: + * @surface: a #cairo_xlib_surface_t + * + * Get the number of bits used to represent each pixel value. + * + * Return value: the depth of the surface in bits. + * + * Since: 1.2 + **/ int cairo_xlib_surface_get_depth (cairo_surface_t *abstract_surface) { @@ -2147,6 +2199,16 @@ cairo_xlib_surface_get_depth (cairo_surface_t *abstract_surface) return surface->depth; } +/** + * cairo_xlib_surface_get_width: + * @surface: a #cairo_xlib_surface_t + * + * Get the width of the X Drawable underlying the surface in pixels. + * + * Return value: the width of the surface in pixels. + * + * Since: 1.2 + **/ int cairo_xlib_surface_get_width (cairo_surface_t *abstract_surface) { @@ -2160,6 +2222,16 @@ cairo_xlib_surface_get_width (cairo_surface_t *abstract_surface) return surface->width; } +/** + * cairo_xlib_surface_get_height: + * @surface: a #cairo_xlib_surface_t + * + * Get the height of the X Drawable underlying the surface in pixels. + * + * Return value: the height of the surface in pixels. + * + * Since: 1.2 + **/ int cairo_xlib_surface_get_height (cairo_surface_t *abstract_surface) { diff --git a/src/cairo.h b/src/cairo.h index f5cdf887d..f1bdce983 100644 --- a/src/cairo.h +++ b/src/cairo.h @@ -929,9 +929,10 @@ cairo_font_face_status (cairo_font_face_t *font_face); /** * cairo_font_type_t - * @CAIRO_FONT_TYPE_FT: The font is of type ft - * @CAIRO_FONT_TYPE_WIN32: The font is of type win32 - * @CAIRO_FONT_TYPE_ATSUI: The font is of type atsui + * @CAIRO_FONT_TYPE_TOY: The font was created using cairo's toy font api + * @CAIRO_FONT_TYPE_FT: The font is of type FreeType + * @CAIRO_FONT_TYPE_WIN32: The font is of type Win32 + * @CAIRO_FONT_TYPE_ATSUI: The font is of type ATSUI * * @cairo_font_type_t is used to describe the type of a given font * face or scaled font. The font types are also known as "font @@ -939,7 +940,7 @@ cairo_font_face_status (cairo_font_face_t *font_face); * * The type of a font face is determined by the function used to * create it, which will generally be of the form - * cairo__font_face_create. The font face type can be queried + * cairo_type_font_face_create. The font face type can be queried * with cairo_font_face_get_type() * * The various cairo_font_face functions can be used with a font face @@ -953,7 +954,7 @@ cairo_font_face_status (cairo_font_face_t *font_face); * fonts of any type, but some font backends also provide * type-specific functions that must only be called with a scaled font * of the appropriate type. These functions have names that begin with - * cairo__scaled_font such as cairo_ft_scaled_font_lock_face. + * cairo_type_scaled_font such as cairo_ft_scaled_font_lock_face. * * The behavior of calling a type-specific function with a scaled font * of the wrong type is undefined. @@ -1235,7 +1236,7 @@ cairo_surface_status (cairo_surface_t *surface); * backends" within cairo. * * The type of a surface is determined by the function used to create - * it, which will generally be of the form cairo__surface_create, + * it, which will generally be of the form cairo_type_surface_create, * (though see cairo_surface_create_similar as well). * * The surface type can be queried with cairo_surface_get_type() @@ -1244,7 +1245,7 @@ cairo_surface_status (cairo_surface_t *surface); * any type, but some backends also provide type-specific functions * that must only be called with a surface of the appropriate * type. These functions have names that begin with - * cairo__surface such as cairo_image_surface_get_width(). + * cairo_type_surface such as cairo_image_surface_get_width(). * * The behavior of calling a type-specific function with a surface of * the wrong type is undefined. @@ -1430,7 +1431,6 @@ cairo_pattern_status (cairo_pattern_t *pattern); /** * cairo_pattern_type_t - * @CAIRO_PATTERN_TYPE_SOLID: The pattern is a solid (uniform) * color. It may be opaque or translucent. * @CAIRO_PATTERN_TYPE_SURFACE: The pattern is a based on a surface (an image). @@ -1567,12 +1567,10 @@ cairo_matrix_multiply (cairo_matrix_t *result, const cairo_matrix_t *a, const cairo_matrix_t *b); -/* XXX: Need a new name here perhaps. */ cairo_public void cairo_matrix_transform_distance (const cairo_matrix_t *matrix, double *dx, double *dy); -/* XXX: Need a new name here perhaps. */ cairo_public void cairo_matrix_transform_point (const cairo_matrix_t *matrix, double *x, double *y);