[cairo-commit] 4 commits - doc/public src/cairo-device.c src/cairo-surface.c
Benjamin Otte
company at kemper.freedesktop.org
Thu Jul 8 19:09:47 PDT 2010
doc/public/cairo-sections.txt | 28 ---------
src/cairo-device.c | 128 ++++++++++++++++++++++++++++++++++++++++++
src/cairo-surface.c | 3
3 files changed, 130 insertions(+), 29 deletions(-)
New commits:
commit 9877c1932a44f7e5300d6fcd99c19748aa5a4828
Author: Benjamin Otte <otte at redhat.com>
Date: Fri Jul 9 03:52:45 2010 +0200
doc: Add more documentation for devices
Add general docs and document acquire/release. I'm not happy with the
documentation yet. In particular, I have 2 issues:
1) The threading guarantees Cairo provides are missing.
2) There's no docs on which Cairo functions do acquire devices.
I guess I'll have to fix them later.
diff --git a/src/cairo-device.c b/src/cairo-device.c
index 705cc58..b9f6971 100644
--- a/src/cairo-device.c
+++ b/src/cairo-device.c
@@ -37,6 +37,57 @@
#include "cairo-device-private.h"
#include "cairo-error-private.h"
+/**
+ * SECTION:cairo-device
+ * @Title: cairo_device_t
+ * @Short_Description: interface to underlying rendering system
+ * @See_Also: #cairo_surface_t
+ *
+ * Devices are the abstraction Cairo employs for the rendering system
+ * used by a #cairo_surface_t. You can get the device of a surface using
+ * cairo_surface_get_device().
+ *
+ * Devices are created using custom functions specific to the rendering
+ * system you want to use. See the documentation for the surface types
+ * for those functions.
+ *
+ * An important function that devices fulfill is sharing access to the
+ * rendering system between Cairo and your application. If you want to
+ * access a device directly that you used to draw to with Cairo, you must
+ * first call cairo_device_flush() to ensure that Cairo finishes all
+ * operations on the device and resets it to a clean state.
+ *
+ * Cairo also provides the functions cairo_device_acquire() and
+ * cairo_device_release() to synchronize access to the rendering system
+ * in a multithreaded environment. This is done internally, but can also
+ * be used by applications.
+ *
+ * Putting this all together, a function that works with devices should
+ * look something like this:
+ * <informalexample><programlisting>
+ * void
+ * my_device_modifying_function (cairo_device_t *device)
+ * {
+ * cairo_status_t status;
+ *
+ * // Ensure the device is properly reset
+ * cairo_device_flush (device);
+ * // Try to acquire the device
+ * status = cairo_device_acquire (device);
+ * if (status != CAIRO_STATUS_SUCCESS) {
+ * printf ("Failed to acquire the device: %s\n", cairo_status_to_string (status));
+ * return;
+ * }
+ *
+ * // Do the custom operations on the device here.
+ * // But do not call any Cairo functions that might acquire devices.
+ *
+ * // Release the device when done.
+ * cairo_device_release (device);
+ * }
+ * </programlisting></informalexample>
+ */
+
static const cairo_device_t _nil_device = {
CAIRO_REFERENCE_COUNT_INVALID,
CAIRO_STATUS_NO_MEMORY,
@@ -267,6 +318,34 @@ cairo_device_get_type (cairo_device_t *device)
return device->backend->type;
}
+/**
+ * cairo_device_acquire:
+ * @device: a #cairo_device_t
+ *
+ * Acquires the @device for the current thread. This function will block
+ * until no other thread has acquired the device.
+ *
+ * If the return value is %CAIRO_STATUS_SUCCESS, you successfully acquired the
+ * device. From now on your thread owns the device and no other thread will be
+ * able to acquire it until a matching call to cairo_device_release(). It is
+ * allowed to recursively acquire the device multiple times from the same
+ * thread.
+ *
+ * <note><para>You must never acquire two different devices at the same time
+ * unless this is explicitly allowed. Otherwise the possibility of deadlocks
+ * exist.
+ *
+ * As various Cairo functions can acquire devices when called, these functions
+ * may also cause deadlocks when you call them with an acquired device. So you
+ * must not have a device acquired when calling them. These functions are
+ * marked in the documentation.
+ * </para></note>
+ *
+ * Return value: %CAIRO_STATUS_SUCCESS on success or an error code if
+ * the device is in an error state and could not be
+ * acquired. After a successful call to cairo_device_acquire(),
+ * a matching call to cairo_device_release() is required.
+ **/
cairo_status_t
cairo_device_acquire (cairo_device_t *device)
{
@@ -289,6 +368,13 @@ cairo_device_acquire (cairo_device_t *device)
}
slim_hidden_def (cairo_device_acquire);
+/**
+ * cairo_device_release:
+ * @device: a #cairo_device_t
+ *
+ * Releases a @device previously acquired using cairo_device_acquire(). See
+ * that function for details.
+ **/
void
cairo_device_release (cairo_device_t *device)
{
commit 739d6e35fa5632b80b888d6475f2fdb6be6054a6
Author: Benjamin Otte <otte at redhat.com>
Date: Fri Jul 9 03:04:27 2010 +0200
doc: Clarify that cairo_surface_get_device() can return NULL
diff --git a/src/cairo-surface.c b/src/cairo-surface.c
index eaee461..7e2fb9f 100644
--- a/src/cairo-surface.c
+++ b/src/cairo-surface.c
@@ -239,7 +239,8 @@ _cairo_surface_allocate_unique_id (void)
* This function returns the device for a @surface.
* See #cairo_device_t.
*
- * Return value: The device for @surface.
+ * Return value: The device for @surface or %NULL if the surface does
+ * not have an associated device.
*
* Since: 1.10
**/
commit 65d0590b041835fb466f4a7073910ef1383d9e77
Author: Benjamin Otte <otte at redhat.com>
Date: Fri Jul 9 02:23:13 2010 +0200
doc: Copy docs for standard device APIs
Copied from the surface equivalents
diff --git a/src/cairo-device.c b/src/cairo-device.c
index 933eda9..705cc58 100644
--- a/src/cairo-device.c
+++ b/src/cairo-device.c
@@ -122,6 +122,19 @@ _cairo_device_init (cairo_device_t *device,
_cairo_user_data_array_init (&device->user_data);
}
+/**
+ * cairo_device_reference:
+ * @device: a #cairo_device_t
+ *
+ * Increases the reference count on @device by one. This prevents
+ * @device from being destroyed until a matching call to
+ * cairo_device_destroy() is made.
+ *
+ * The number of references to a #cairo_device_t can be get using
+ * cairo_device_get_reference_count().
+ *
+ * Return value: the referenced #cairo_device_t.
+ **/
cairo_device_t *
cairo_device_reference (cairo_device_t *device)
{
@@ -138,6 +151,16 @@ cairo_device_reference (cairo_device_t *device)
}
slim_hidden_def (cairo_device_reference);
+/**
+ * cairo_device_status:
+ * @device: a #cairo_device_t
+ *
+ * Checks whether an error has previously occurred for this
+ * device.
+ *
+ * Return value: %CAIRO_STATUS_SUCCESS on success or an error code if
+ * the device is in an error state.
+ **/
cairo_status_t
cairo_device_status (cairo_device_t *device)
{
@@ -184,6 +207,14 @@ cairo_device_finish (cairo_device_t *device)
}
slim_hidden_def (cairo_device_finish);
+/**
+ * cairo_device_destroy:
+ * @device: a #cairo_device_t
+ *
+ * Decreases the reference count on @device by one. If the result is
+ * zero, then @device and all associated resources are freed. See
+ * cairo_device_reference().
+ **/
void
cairo_device_destroy (cairo_device_t *device)
{
@@ -213,6 +244,17 @@ cairo_device_destroy (cairo_device_t *device)
}
slim_hidden_def (cairo_device_destroy);
+/**
+ * cairo_device_get_type:
+ * @device: a #cairo_device_t
+ *
+ * This function returns the type of the device. See #cairo_device_type_t
+ * for available types.
+ *
+ * Return value: The type of @device.
+ *
+ * Since: 1.10
+ **/
cairo_device_type_t
cairo_device_get_type (cairo_device_t *device)
{
commit 8a08b6fa5288f376688730c66ae9219d01180f42
Author: Benjamin Otte <otte at redhat.com>
Date: Fri Jul 9 02:21:00 2010 +0200
doc: Remove the <TITLE> declarations
This information was duplicated. It exists as the "@Title" of the
SECTION inline documentation already.
diff --git a/doc/public/cairo-sections.txt b/doc/public/cairo-sections.txt
index d5832aa..8757366 100644
--- a/doc/public/cairo-sections.txt
+++ b/doc/public/cairo-sections.txt
@@ -1,6 +1,5 @@
<SECTION>
<FILE>cairo-ft</FILE>
-<TITLE>ft-font</TITLE>
CAIRO_HAS_FT_FONT
CAIRO_HAS_FC_FONT
cairo_ft_font_face_create_for_ft_face
@@ -12,7 +11,6 @@ cairo_ft_scaled_font_unlock_face
<SECTION>
<FILE>cairo-win32-fonts</FILE>
-<TITLE>win32-font</TITLE>
CAIRO_HAS_WIN32_FONT
cairo_win32_font_face_create_for_logfontw
cairo_win32_font_face_create_for_hfont
@@ -26,7 +24,6 @@ cairo_win32_scaled_font_get_device_to_logical
<SECTION>
<FILE>cairo-quartz-fonts</FILE>
-<TITLE>quartz-font</TITLE>
CAIRO_HAS_QUARTZ_FONT
cairo_quartz_font_face_create_for_cgfont
cairo_quartz_font_face_create_for_atsu_font_id
@@ -34,7 +31,6 @@ cairo_quartz_font_face_create_for_atsu_font_id
<SECTION>
<FILE>cairo-user-fonts</FILE>
-<TITLE>user-font</TITLE>
CAIRO_HAS_USER_FONT
cairo_user_scaled_font_init_func_t
cairo_user_scaled_font_render_glyph_func_t
@@ -53,7 +49,6 @@ cairo_user_font_face_get_text_to_glyphs_func
<SECTION>
<FILE>cairo-image</FILE>
-<TITLE>image-surface</TITLE>
CAIRO_HAS_IMAGE_SURFACE
cairo_format_t
cairo_format_stride_for_width
@@ -68,7 +63,6 @@ cairo_image_surface_get_stride
<SECTION>
<FILE>cairo-pdf</FILE>
-<TITLE>pdf-surface</TITLE>
CAIRO_HAS_PDF_SURFACE
cairo_pdf_surface_create
cairo_pdf_surface_create_for_stream
@@ -81,7 +75,6 @@ cairo_pdf_surface_set_size
<SECTION>
<FILE>cairo-png</FILE>
-<TITLE>png-functions</TITLE>
CAIRO_HAS_PNG_FUNCTIONS
cairo_image_surface_create_from_png
cairo_read_func_t
@@ -93,7 +86,6 @@ cairo_surface_write_to_png_stream
<SECTION>
<FILE>cairo-ps</FILE>
-<TITLE>ps-surface</TITLE>
CAIRO_HAS_PS_SURFACE
cairo_ps_surface_create
cairo_ps_surface_create_for_stream
@@ -111,7 +103,6 @@ cairo_ps_surface_dsc_comment
<SECTION>
<FILE>cairo-win32</FILE>
-<TITLE>win32-surface</TITLE>
CAIRO_HAS_WIN32_SURFACE
cairo_win32_surface_create
cairo_win32_surface_create_with_dib
@@ -123,7 +114,6 @@ cairo_win32_surface_get_image
<SECTION>
<FILE>cairo-quartz</FILE>
-<TITLE>quartz-surface</TITLE>
CAIRO_HAS_QUARTZ_SURFACE
cairo_quartz_surface_create
cairo_quartz_surface_create_for_cg_context
@@ -135,7 +125,6 @@ cairo_quartz_image_surface_get_image
<SECTION>
<FILE>cairo-xlib</FILE>
-<TITLE>xlib-surface</TITLE>
CAIRO_HAS_XLIB_SURFACE
cairo_xlib_surface_create
cairo_xlib_surface_create_for_bitmap
@@ -152,7 +141,6 @@ cairo_xlib_surface_get_depth
<SECTION>
<FILE>cairo-xlib-xrender</FILE>
-<TITLE>xlib-xrender-surface</TITLE>
CAIRO_HAS_XLIB_XRENDER_SURFACE
cairo_xlib_surface_create_with_xrender_format
cairo_xlib_surface_get_xrender_format
@@ -160,7 +148,6 @@ cairo_xlib_surface_get_xrender_format
<SECTION>
<FILE>cairo-svg</FILE>
-<TITLE>svg-surface</TITLE>
CAIRO_HAS_SVG_SURFACE
cairo_svg_surface_create
cairo_svg_surface_create_for_stream
@@ -172,7 +159,6 @@ cairo_svg_version_to_string
<SECTION>
<FILE>cairo-device</FILE>
-<TITLE>device</TITLE>
cairo_device_t
cairo_device_reference
cairo_device_destroy
@@ -190,7 +176,6 @@ cairo_device_release
<SECTION>
<FILE>cairo-surface</FILE>
-<TITLE>surface</TITLE>
CAIRO_MIME_TYPE_JP2
CAIRO_MIME_TYPE_JPEG
CAIRO_MIME_TYPE_PNG
@@ -227,7 +212,6 @@ cairo_surface_get_mime_data
<SECTION>
<FILE>cairo-version</FILE>
-<TITLE>version-info</TITLE>
CAIRO_VERSION
CAIRO_VERSION_MAJOR
CAIRO_VERSION_MINOR
@@ -243,7 +227,6 @@ CAIRO_VERSION_STRINGIZE_
<SECTION>
<FILE>cairo-region</FILE>
-<TITLE>cairo_region_t</TITLE>
cairo_region_t
cairo_region_create
cairo_region_create_rectangle
@@ -273,7 +256,6 @@ cairo_region_xor_rectangle
<SECTION>
<FILE>cairo-pattern</FILE>
-<TITLE>pattern</TITLE>
cairo_pattern_t
cairo_pattern_add_color_stop_rgb
cairo_pattern_add_color_stop_rgba
@@ -308,7 +290,6 @@ cairo_pattern_get_user_data
<SECTION>
<FILE>cairo-matrix</FILE>
-<TITLE>matrix</TITLE>
cairo_matrix_t
cairo_matrix_init
cairo_matrix_init_identity
@@ -326,7 +307,6 @@ cairo_matrix_transform_point
<SECTION>
<FILE>cairo-status</FILE>
-<TITLE>error-status</TITLE>
cairo_status_t
cairo_status_to_string
cairo_debug_reset_static_data
@@ -334,7 +314,6 @@ cairo_debug_reset_static_data
<SECTION>
<FILE>cairo-font-face</FILE>
-<TITLE>cairo_font_face_t</TITLE>
cairo_font_face_t
cairo_font_face_reference
cairo_font_face_destroy
@@ -348,7 +327,6 @@ cairo_font_face_get_user_data
<SECTION>
<FILE>cairo-scaled-font</FILE>
-<TITLE>scaled-font</TITLE>
cairo_scaled_font_t
cairo_scaled_font_create
cairo_scaled_font_reference
@@ -373,7 +351,6 @@ cairo_scaled_font_get_user_data
<SECTION>
<FILE>cairo-font-options</FILE>
-<TITLE>cairo_font_options_t</TITLE>
cairo_font_options_t
cairo_font_options_create
cairo_font_options_copy
@@ -397,7 +374,6 @@ cairo_font_options_get_hint_metrics
<SECTION>
<FILE>cairo-types</FILE>
-<TITLE>types</TITLE>
cairo_bool_t
cairo_user_data_key_t
cairo_destroy_func_t
@@ -406,7 +382,6 @@ cairo_rectangle_int_t
<SECTION>
<FILE>cairo-transforms</FILE>
-<TITLE>transformations</TITLE>
cairo_translate
cairo_scale
cairo_rotate
@@ -423,7 +398,6 @@ cairo_device_to_user_distance
<SECTION>
<FILE>cairo-paths</FILE>
-<TITLE>paths</TITLE>
cairo_path_t
cairo_path_data_t
cairo_path_data_type_t
@@ -452,7 +426,6 @@ cairo_path_extents
<SECTION>
<FILE>cairo-text</FILE>
-<TITLE>text</TITLE>
cairo_glyph_t
cairo_font_slant_t
cairo_font_weight_t
@@ -486,7 +459,6 @@ cairo_text_cluster_free
<SECTION>
<FILE>cairo</FILE>
-<TITLE>context</TITLE>
cairo_t
cairo_create
cairo_reference
More information about the cairo-commit
mailing list