[cairo] surfaces and backends
Carl Worth
cworth at redhat.com
Fri Feb 24 11:37:04 PST 2006
On Sat, 21 May 2005 11:01:22 -0400, Owen Taylor wrote:
> What if we had:
>
> enum {
> CAIRO_IMAGE_SURFACE_TYPE,
> CAIRO_XLIB_SURFACE_TYPE,
> [...]
> CAIRO_FT_FONT_FACE_TYPE,
> } CairoTypeID;
>
> CairoTypeID cairo_surface_get_type (cairo_surface_t *surface);
As I commented a while ago on the bug report:
How do we identify surface types?
https://bugs.freedesktop.org/show_bug.cgi?id=2765
I think this is the right basic style with which to tackle this
problem. But I think I'd prefer separate enums for the various object
types.
And Robert's recent proposal to add a bunch of new cairo_xlib_surface
functions made this seem more important to me. So here's a patch that
adds the API I have in mind, (no implementation yet, but there's
documentation here).
This patch is already committed to the get-type branch in my personal
tree if anyone wants to look at it.
Some of the things to notice in the patch:
* I had to choose a name for the pattern type created by create_rgb
and create_rgba. I consulted the language bindings guide and found
"solid". I went with that, and just added notes to the documentation
that solid means uniform color and might be opaque or translucent.
* I created a single cairo_font_type_t that is used by both
cairo_font_face_get_type and cairo_scaled_font_get_type.
* There is some inconsistency in the handling of type mismatches. I
documented what the current implementation does. I'm not sure that
we don't want to change the current behavior in some places, but
I'll follow up to Robert's message on that topic.
Any likes or dislikes about the API should be made soon. I'll add an
implementation shortly, and if I haven't heard any complaints, will
push this out to the central tree after that.
-Carl
---
src/cairo-surface.c | 3 +
src/cairo.h | 134 ++++++++++++++++++++++++++++++++++++++++++++++++++-
2 files changed, 134 insertions(+), 3 deletions(-)
9287d60d60f55ae3838a7cecfa9fa04a5f95e8de
diff --git a/src/cairo-surface.c b/src/cairo-surface.c
index 2982017..52aeafe 100644
--- a/src/cairo-surface.c
+++ b/src/cairo-surface.c
@@ -186,7 +186,8 @@ _cairo_surface_create_similar_scratch (c
*
* Create a new surface that is as compatible as possible with an
* existing surface. The new surface will use the same backend as
- * @other unless that is not possible for some reason.
+ * @other unless that is not possible for some reason. The type of the
+ * returned surface may be examined with cairo_surface_get_type().
*
* Return value: a pointer to the newly allocated surface. The caller
* owns the surface and should call cairo_surface_destroy when done
diff --git a/src/cairo.h b/src/cairo.h
index fbb3620..76f9257 100644
--- a/src/cairo.h
+++ b/src/cairo.h
@@ -896,6 +896,46 @@ cairo_font_face_destroy (cairo_font_face
cairo_public cairo_status_t
cairo_font_face_status (cairo_font_face_t *font_face);
+/**
+ * cairo_font_type_t
+ * @CAIRO_SCALED_FONT_TYPE_FT: The font is of type ft
+ * @CAIRO_SCALED_FONT_TYPE_WIN32: The font is of type win32
+ * @CAIRO_SCALED_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
+ * backends" within cairo.
+ *
+ * The type of a font face is determined by the function used to
+ * create it, which will generally be of the form
+ * 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
+ * of any type.
+ *
+ * The type of a scaled font is determined by the type of the font
+ * face passed to cairo_scaled_font_create. The scaled font type can
+ * be queried with cairo_scaled_font_get_type()
+ *
+ * The various cairo_scaled_font functions can be used with scaled
+ * 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_<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.
+ */
+typedef enum _cairo_font_type {
+ CAIRO_FONT_TYPE_FT,
+ CAIRO_FONT_TYPE_WIN32,
+ CAIRO_FONT_TYPE_ATSUI
+} cairo_font_type_t;
+
+cairo_public cairo_font_type_t
+cairo_font_face_get_type (cairo_scaled_font_t *font_face);
+
cairo_public void *
cairo_font_face_get_user_data (cairo_font_face_t *font_face,
const cairo_user_data_key_t *key);
@@ -923,6 +963,9 @@ cairo_scaled_font_destroy (cairo_scaled_
cairo_public cairo_status_t
cairo_scaled_font_status (cairo_scaled_font_t *scaled_font);
+cairo_public cairo_font_type_t
+cairo_scaled_font_get_type (cairo_scaled_font_t *scaled_font);
+
cairo_public void
cairo_scaled_font_extents (cairo_scaled_font_t *scaled_font,
cairo_font_extents_t *extents);
@@ -1148,13 +1191,63 @@ cairo_public cairo_surface_t *
cairo_surface_reference (cairo_surface_t *surface);
cairo_public void
+cairo_surface_finish (cairo_surface_t *surface);
+
+cairo_public void
cairo_surface_destroy (cairo_surface_t *surface);
cairo_public cairo_status_t
cairo_surface_status (cairo_surface_t *surface);
-cairo_public void
-cairo_surface_finish (cairo_surface_t *surface);
+/**
+ * cairo_surface_type_t
+ * @CAIRO_SURFACE_TYPE_IMAGE: The surface is of type image
+ * @CAIRO_SURFACE_TYPE_PDF: The surface is of type pdf
+ * @CAIRO_SURFACE_TYPE_PS: The surface is of type ps
+ * @CAIRO_SURFACE_TYPE_XLIB: The surface is of typs xlib
+ * @CAIRO_SURFACE_TYPE_XCB: The surface is of type xcb
+ * @CAIRO_SURFACE_TYPE_GLITZ: The surface is of type glitz
+ * @CAIRO_SURFACE_TYPE_QUARTZ: The surface is of type quartz
+ * @CAIRO_SURFACE_TYPE_WIN32: The surface is of type win32
+ * @CAIRO_SURFACE_TYPE_BEOS: The surface is of type beos
+ * @CAIRO_SURFACE_TYPE_DIRECTFB: The surface is of type directfb
+ * @CAIRO_SURFACE_TYPE_SVG: The surface is of type svg
+ *
+ * @cairo_surface_type_t is used to describe the type of a given
+ * surface. The surface types are also known as "backends" or "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_<type>_surface_create,
+ * (though see cairo_surface_create_similar as well).
+ *
+ * The surface type can be queried with cairo_surface_get_type()
+ *
+ * The various cairo_surface functions can be used with surfaces of
+ * 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_<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.
+ */
+typedef enum _cairo_surface_type {
+ CAIRO_SURFACE_TYPE_IMAGE,
+ CAIRO_SURFACE_TYPE_PDF,
+ CAIRO_SURFACE_TYPE_PS,
+ CAIRO_SURFACE_TYPE_XLIB,
+ CAIRO_SURFACE_TYPE_XCB,
+ CAIRO_SURFACE_TYPE_GLITZ,
+ CAIRO_SURFACE_TYPE_QUARTZ,
+ CAIRO_SURFACE_TYPE_WIN32,
+ CAIRO_SURFACE_TYPE_BEOS,
+ CAIRO_SURFACE_TYPE_DIRECTFB,
+ CAIRO_SURFACE_TYPE_SVG
+} cairo_surface_type_t;
+
+cairo_public cairo_surface_type_t
+cairo_surface_get_type (cairo_surface_t *surface);
#if CAIRO_HAS_PNG_FUNCTIONS
@@ -1290,6 +1383,43 @@ cairo_pattern_destroy (cairo_pattern_t *
cairo_public cairo_status_t
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).
+ * @CAIRO_PATTERN_TYPE_LINEAR_GRADIENT: The pattern is a linear gradient.
+ * @CAIRO_PATTERN_TYPE_RADIAL_GRADIENT: The pattern is a radial gradient.
+ *
+ * @cairo_pattern_type_t us used to describe the type of a given pattern.
+ *
+ * The type of a pattern is determined by the function used to create
+ * it. The cairo_pattern_create_rgb() and cairo_pattern_create_rgba()
+ * functions create SOLID patterns. The reamaining
+ * cairo_pattern_create functions map to pattern types in obvious
+ * ways.
+ *
+ * The pattern type can be queried with cairo_pattern_get_type()
+ *
+ * Most cairo_pattern functions can be called with a pattern of any
+ * type, (though trying to change the extend or filter for a solid
+ * pattern will have no effect). A notable exception is
+ * cairo_pattern_add_color_stop_rgb() and
+ * cairo_pattern_add_color_stop_rgba() which must only be called with
+ * gradient patterns. Otherwise the pattern will be shutdown and put
+ * into an error state.
+ */
+typedef enum _cairo_pattern_type {
+ CAIRO_PATTERN_TYPE_SOLID,
+ CAIRO_PATTERN_TYPE_SURFACE,
+ CAIRO_PATTERN_TYPE_LINEAR_GRADIENT,
+ CAIRO_PATTERN_TYPE_RADIAL_GRADIENT
+} cairo_pattern_type_t;
+
+cairo_public cairo_pattern_type_t
+cairo_pattern_get_type (cairo_pattern_t *pattern);
+
cairo_public void
cairo_pattern_add_color_stop_rgb (cairo_pattern_t *pattern,
double offset,
--
1.2.3.g2656-dirty
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/cairo/attachments/20060224/35e89732/attachment.pgp
More information about the cairo
mailing list