[cairo] Solid color pattern constructors

Kristian Høgsberg krh at bitplanet.net
Tue Jun 28 12:45:58 PDT 2005


Hi,

Here's a patch to add constructors for solid color patterns:

   cairo_pattern_t *
   cairo_pattern_create_rgb (double red, double green, double blue);

   cairo_pattern_t *
   cairo_pattern_create_rgba (double red, double green, double blue,
                              double alpha);

and with these we have constructors for all pattern types.  They 
probably wont become the most frequently used functions, but I have a 
couple of places in poppler where they would be convenient.  I also 
added documentation for them and the other pattern constructors.

Kristian
-------------- next part --------------
? hat
? doc/public/tmpl/cairo-image.sgml
? doc/public/tmpl/cairo-win3.sgml
Index: ChangeLog
===================================================================
RCS file: /cvs/cairo/cairo/ChangeLog,v
retrieving revision 1.676
diff -u -p -r1.676 ChangeLog
--- ChangeLog	21 Jun 2005 16:54:58 -0000	1.676
+++ ChangeLog	28 Jun 2005 19:44:55 -0000
@@ -1,3 +1,10 @@
+2005-06-28  Kristian Høgsberg  <krh at redhat.com>
+
+	* src/cairo-pattern.c (cairo_pattern_create_rgb)
+	(cairo_pattern_create_rgba): New functions to create a
+	cairo_pattern_t corresponding to a solid color and a translucent
+	color respectively.  Document a few pattern functions.
+
 2005-06-21  T Rowley  <tim.rowley at gmail.com>
 
 	* src/cairo-atsui-font.c: allow building against < 10.3 SDK.
Index: src/cairo-pattern.c
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo-pattern.c,v
retrieving revision 1.46
diff -u -p -r1.46 cairo-pattern.c
--- src/cairo-pattern.c	20 Jun 2005 18:09:51 -0000	1.46
+++ src/cairo-pattern.c	28 Jun 2005 19:44:55 -0000
@@ -294,6 +294,92 @@ _cairo_pattern_create_in_error (cairo_st
     return &pattern->base;
 }
 
+/**
+ * cairo_pattern_create_rgb:
+ * @red: red component of the color
+ * @green: green component of the color
+ * @blue: blue component of the color
+ * 
+ * Create a new cairo_pattern_t corresponding to a solid, opaque
+ * color.  The color components are floating point numbers in the
+ * range 0 to 1.  If the values passed in are outside that range, they
+ * will be clamped.
+ * 
+ * Return value: the newly created #cairo_pattern_t if succesful, or
+ * an error pattern in case of no memory.  The caller owns the
+ * returned object and should call cairo_pattern_destroy() when
+ * finished with it.
+ *
+ * This function will always return a valid pointer, but if an error
+ * occurred the pattern status will be set to an error.  To inspect
+ * the status of a pattern use cairo_pattern_status().
+ **/
+cairo_pattern_t *
+cairo_pattern_create_rgb (double red, double green, double blue)
+{
+    cairo_color_t color;
+
+    _cairo_restrict_value (&red,   0.0, 1.0);
+    _cairo_restrict_value (&green, 0.0, 1.0);
+    _cairo_restrict_value (&blue,  0.0, 1.0);
+
+    _cairo_color_init_rgb (&color, red, green, blue);
+
+    return _cairo_pattern_create_solid (&color);
+}
+
+/**
+ * cairo_pattern_create_rgba:
+ * @red: red component of the color
+ * @green: green component of the color
+ * @blue: blue component of the color
+ * @alpha: alpha component of the color
+ * 
+ * Create a new cairo_pattern_t corresponding to a solid, opaque
+ * color.  The color components are floating point numbers in the
+ * range 0 to 1.  If the values passed in are outside that range, they
+ * will be clamped.
+ * 
+ * Return value: the newly created #cairo_pattern_t if succesful, or
+ * an error pattern in case of no memory.  The caller owns the
+ * returned object and should call cairo_pattern_destroy() when
+ * finished with it.
+ *
+ * This function will always return a valid pointer, but if an error
+ * occurred the pattern status will be set to an error.  To inspect
+ * the status of a pattern use cairo_pattern_status().
+ **/
+cairo_pattern_t *
+cairo_pattern_create_rgba (double red, double green, double blue,
+			   double alpha)
+{
+    cairo_color_t color;
+
+    _cairo_restrict_value (&red,   0.0, 1.0);
+    _cairo_restrict_value (&green, 0.0, 1.0);
+    _cairo_restrict_value (&blue,  0.0, 1.0);
+    _cairo_restrict_value (&alpha, 0.0, 1.0);
+
+    _cairo_color_init_rgba (&color, red, green, blue, alpha);
+
+    return _cairo_pattern_create_solid (&color);
+}
+
+/**
+ * cairo_pattern_create_for_surface:
+ * @surface: the surface 
+ * 
+ * Create a new cairo_pattern_t for the given surface.
+ * 
+ * Return value: the newly created #cairo_pattern_t if succesful, or
+ * an error pattern in case of no memory.  The caller owns the
+ * returned object and should call cairo_pattern_destroy() when
+ * finished with it.
+ *
+ * This function will always return a valid pointer, but if an error
+ * occurred the pattern status will be set to an error.  To inspect
+ * the status of a pattern use cairo_pattern_status().
+ **/
 cairo_pattern_t *
 cairo_pattern_create_for_surface (cairo_surface_t *surface)
 {
@@ -308,6 +394,28 @@ cairo_pattern_create_for_surface (cairo_
     return &pattern->base;
 }
 
+/**
+ * cairo_pattern_create_linear:
+ * @x0: x coordinate of the start point 
+ * @y0: y coordinate of the start point 
+ * @x1: x coordinate of the end point 
+ * @y1: y coordinate of the end point 
+ * 
+ * Create a new linear gradient cairo_pattern_t along the line defined
+ * by (x0, y0) and (x1, y1).  Before using the gradient pattern, a
+ * number of color stops should be defined using
+ * cairo_pattern_add_color_stop_rgb() or
+ * cairo_pattern_add_color_stop_rgba().
+ * 
+ * Return value: the newly created #cairo_pattern_t if succesful, or
+ * an error pattern in case of no memory.  The caller owns the
+ * returned object and should call cairo_pattern_destroy() when
+ * finished with it.
+ *
+ * This function will always return a valid pointer, but if an error
+ * occurred the pattern status will be set to an error.  To inspect
+ * the status of a pattern use cairo_pattern_status().
+ **/
 cairo_pattern_t *
 cairo_pattern_create_linear (double x0, double y0, double x1, double y1)
 {
@@ -322,6 +430,30 @@ cairo_pattern_create_linear (double x0, 
     return &pattern->base.base;
 }
 
+/**
+ * cairo_pattern_create_radial:
+ * @cx0: x coordinate for the center of the start circle
+ * @cy0: y coordinate for the center of the start circle
+ * @radius0: radius of the start cirle
+ * @cx1: x coordinate for the center of the end circle
+ * @cy1: y coordinate for the center of the end circle
+ * @radius1: radius of the end cirle
+ * 
+ * Create a new radial gradient cairo_pattern_t between the two
+ * circles defined by (x0, y0, c0) and (x1, y1, c0).  Before using the
+ * gradient pattern, a number of color stops should be defined using
+ * cairo_pattern_add_color_stop_rgb() or
+ * cairo_pattern_add_color_stop_rgba().
+ * 
+ * Return value: the newly created #cairo_pattern_t if succesful, or
+ * an error pattern in case of no memory.  The caller owns the
+ * returned object and should call cairo_pattern_destroy() when
+ * finished with it.
+ *
+ * This function will always return a valid pointer, but if an error
+ * occurred the pattern status will be set to an error.  To inspect
+ * the status of a pattern use cairo_pattern_status().
+ **/
 cairo_pattern_t *
 cairo_pattern_create_radial (double cx0, double cy0, double radius0,
 			     double cx1, double cy1, double radius1)
@@ -337,6 +469,14 @@ cairo_pattern_create_radial (double cx0,
     return &pattern->base.base;
 }
 
+/**
+ * cairo_pattern_reference:
+ * @pattern: a #cairo_pattern_t
+ * 
+ * Increases the reference count on @pattern by one. This prevents
+ * @pattern from being destroyed until a matching call to
+ * cairo_pattern_destroy() is made.
+ **/
 void
 cairo_pattern_reference (cairo_pattern_t *pattern)
 {
@@ -364,6 +504,14 @@ cairo_pattern_status (cairo_pattern_t *p
     return pattern->status;
 }
 
+/**
+ * cairo_pattern_destroy:
+ * @pattern: a #cairo_pattern_t
+ * 
+ * Decreases the reference count on @pattern by one. If the result is
+ * zero, then @pattern and all associated resources are freed.  See
+ * cairo_pattern_reference().
+ **/
 void
 cairo_pattern_destroy (cairo_pattern_t *pattern)
 {
Index: src/cairo.c
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo.c,v
retrieving revision 1.110
diff -u -p -r1.110 cairo.c
--- src/cairo.c	20 Jun 2005 18:09:51 -0000	1.110
+++ src/cairo.c	28 Jun 2005 19:44:56 -0000
@@ -320,18 +320,6 @@ cairo_set_operator (cairo_t *cr, cairo_o
 	_cairo_error (cr, cr->status);
 }
 
-static void
-_cairo_set_source_solid (cairo_t *cr, const cairo_color_t *color)
-{
-    cairo_pattern_t *source;
-
-    source = _cairo_pattern_create_solid (color);
-
-    cairo_set_source (cr, source);
-
-    cairo_pattern_destroy (source);
-}
-
 /**
  * cairo_set_source_rgb
  * @cr: a cairo context
@@ -350,20 +338,16 @@ _cairo_set_source_solid (cairo_t *cr, co
 void
 cairo_set_source_rgb (cairo_t *cr, double red, double green, double blue)
 {
-    cairo_color_t color;
+    cairo_pattern_t *pattern;
 
     if (cr->status) {
 	_cairo_error (cr, cr->status);
 	return;
     }
 
-    _cairo_restrict_value (&red, 0.0, 1.0);
-    _cairo_restrict_value (&green, 0.0, 1.0);
-    _cairo_restrict_value (&blue, 0.0, 1.0);
-
-    _cairo_color_init_rgb (&color, red, green, blue);
-
-    _cairo_set_source_solid (cr, &color);
+    pattern = cairo_pattern_create_rgb (red, green, blue);
+    cairo_set_source (cr, pattern);
+    cairo_pattern_destroy (pattern);
 }
 
 /**
@@ -387,21 +371,16 @@ cairo_set_source_rgba (cairo_t *cr,
 		       double red, double green, double blue,
 		       double alpha)
 {
-    cairo_color_t color;
+    cairo_pattern_t *pattern;
 
     if (cr->status) {
 	_cairo_error (cr, cr->status);
 	return;
     }
 
-    _cairo_restrict_value (&red,   0.0, 1.0);
-    _cairo_restrict_value (&green, 0.0, 1.0);
-    _cairo_restrict_value (&blue,  0.0, 1.0);
-    _cairo_restrict_value (&alpha, 0.0, 1.0);
-
-    _cairo_color_init_rgba (&color, red, green, blue, alpha);
-
-    _cairo_set_source_solid (cr, &color);
+    pattern = cairo_pattern_create_rgba (red, green, blue, alpha);
+    cairo_set_source (cr, pattern);
+    cairo_pattern_destroy (pattern);
 }
 
 void
Index: src/cairo.h
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo.h,v
retrieving revision 1.131
diff -u -p -r1.131 cairo.h
--- src/cairo.h	20 Jun 2005 16:59:23 -0000	1.131
+++ src/cairo.h	28 Jun 2005 19:44:56 -0000
@@ -992,6 +992,14 @@ cairo_image_surface_create_from_png_stre
 #endif
 
 /* Pattern creation functions */
+
+cairo_pattern_t *
+cairo_pattern_create_rgb (double red, double green, double blue);
+
+cairo_pattern_t *
+cairo_pattern_create_rgba (double red, double green, double blue,
+			   double alpha);
+
 cairo_pattern_t *
 cairo_pattern_create_for_surface (cairo_surface_t *surface);
 


More information about the cairo mailing list