[cairo-commit] 2 commits - src/cairo.c
test/fill-and-stroke-alpha-add.c
test/fill-and-stroke-alpha-add-ref.png test/fill-and-stroke-alpha.c
test/fill-and-stroke-alpha-ref.png test/.gitignore test/Makefile.am
Carl Worth
cworth at kemper.freedesktop.org
Thu May 4 22:47:02 PDT 2006
src/cairo.c | 123 +++++++++++++++++++++++++++------
test/.gitignore | 2
test/Makefile.am | 4 +
test/fill-and-stroke-alpha-add-ref.png |binary
test/fill-and-stroke-alpha-add.c | 112 ++++++++++++++++++++++++++++++
test/fill-and-stroke-alpha-ref.png |binary
test/fill-and-stroke-alpha.c | 106 ++++++++++++++++++++++++++++
7 files changed, 325 insertions(+), 22 deletions(-)
New commits:
diff-tree b948683917e26315fdec773db8780662071554a1 (from 344c2c7acd0a87a7a28b4a73ba340b333fefb2bf)
Author: Carl Worth <cworth at cworth.org>
Date: Thu May 4 22:43:22 2006 -0700
Flesh out the documentation for cairo_push_group, cairo_pop_group and friends
diff --git a/src/cairo.c b/src/cairo.c
index 8aa885c..8ec603a 100644
--- a/src/cairo.c
+++ b/src/cairo.c
@@ -334,11 +334,44 @@ slim_hidden_def(cairo_restore);
* cairo_push_group:
* @cr: a cairo context
*
- * Pushes a CAIRO_CONTENT_COLOR_ALPHA temporary surface onto
- * the rendering stack, redirecting all rendering into it.
- * See cairo_push_group_with_content().
+ * Temporarily redirects drawing to an intermediate surface known as a
+ * group. The redirection lasts until the group is completed by a call
+ * to cairo_pop_group() or cairo_pop_group_to_source(). These calls
+ * provide the result of any drawing to the group as a pattern,
+ * (either as an explicit object, or set as the source pattern).
+ *
+ * This group functionality can be convenient for performing
+ * intermediate compositing. One common use of a group is to render
+ * objects as opaque within the group, (so that they occlude each
+ * other), and then blend the result with translucence onto the
+ * destination.
+ *
+ * Groups can be nested arbitrarily deep by making balanced calls to
+ * cairo_push_group()/cairo_pop_group(). Each call pushes/pops the new
+ * target group onto/from a stack.
+ *
+ * The cairo_push_group() function calls cairo_save() so that any
+ * changes to the graphics state will not be visible outside the
+ * group, (the pop_group functions call cairo_restore()).
+ *
+ * By default the intermediate group will have a content type of
+ * CAIRO_CONTENT_COLOR_ALPHA. Other content types can be chosen for
+ * the group by using cairo_push_group_with_content() instead.
+ *
+ * As an example, here is how one might fill and stroke a path with
+ * translucence, but without any portion of the fill being visible
+ * under the stroke:
+ *
+ * <informalexample><programlisting>
+ * cairo_push_group (cr);
+ * cairo_set_source (cr, fill_pattern);
+ * cairo_fill_preserve (cr);
+ * cairo_set_source (cr, stroke_pattern);
+ * cairo_stroke (cr);
+ * cairo_pop_group_to_source (cr);
+ * cairo_paint_with_alpha (cr, alpha);
+ * </programlisting></informalexample>
*/
-
void
cairo_push_group (cairo_t *cr)
{
@@ -352,17 +385,17 @@ slim_hidden_def(cairo_push_group);
* @content: a %cairo_content_t indicating the type of group that
* will be created
*
- * Pushes a temporary surface onto the rendering stack, redirecting
- * all rendering into it. The surface dimensions are the size of
- * the current clipping bounding box. Initially, this surface
- * is painted with CAIRO_OPERATOR_CLEAR.
- *
- * cairo_push_group() calls cairo_save() so that any changes to the
- * graphics state will not be visible after cairo_pop_group() or
- * cairo_pop_group_with_alpha(). See cairo_pop_group() and
- * cairo_pop_group_with_alpha().
+ * Temporarily redirects drawing to an intermediate surface known as a
+ * group. The redirection lasts until the group is completed by a call
+ * to cairo_pop_group() or cairo_pop_group_to_source(). These calls
+ * provide the result of any drawing to the group as a pattern,
+ * (either as an explicit object, or set as the source pattern).
+ *
+ * The group will have a content type of @content. The ability to
+ * control this content type is the only distinction between this
+ * function and cairo_push_group() which you should see for a more
+ * detailed description of group rendering.
*/
-
void
cairo_push_group_with_content (cairo_t *cr, cairo_content_t content)
{
@@ -407,6 +440,26 @@ bail:
}
slim_hidden_def(cairo_push_group_with_content);
+
+/**
+ * cairo_pop_group:
+ * @cr: a cairo context
+ *
+ * Terminates the redirection begun by a call to cairo_push_group() or
+ * cairo_push_group_with_content() and returns a new pattern
+ * containing the results of all drawing operations performed to the
+ * group.
+ *
+ * The cairo_pop_group() function calls cairo_restore(), (balancing a
+ * call to cairo_save() by the push_group function), so that any
+ * changes to the graphics state will not be visible outside the
+ * group.
+ *
+ * Return value: a newly created (surface) pattern containing the
+ * results of all drawing operations performed to the group. The
+ * caller owns the returned object and should call
+ * cairo_pattern_destroy() when finished with it.
+ **/
cairo_pattern_t *
cairo_pop_group (cairo_t *cr)
{
@@ -449,6 +502,31 @@ done:
}
slim_hidden_def(cairo_pop_group);
+/**
+ * cairo_pop_group_t_source:
+ * @cr: a cairo context
+ *
+ * Terminates the redirection begun by a call to cairo_push_group() or
+ * cairo_push_group_with_content() and installs the resulting pattern
+ * as the source pattern in the given cairo context.
+ *
+ * The behavior of this function is equivalent to the sequence of
+ * operations:
+ *
+ * <informalexample><programlisting>
+ * cairo_pattern_t *group = cairo_pop_group (cr);
+ * cairo_set_source (cr, group);
+ * cairo_pattern_destroy (group);
+ * </programlisting></informalexample>
+ *
+ * but is more convenient as their is no need for a variable to store
+ * the short-lived pointer to the pattern.
+ *
+ * The cairo_pop_group() function calls cairo_restore(), (balancing a
+ * call to cairo_save() by the push_group function), so that any
+ * changes to the graphics state will not be visible outside the
+ * group.
+ **/
void
cairo_pop_group_to_source (cairo_t *cr)
{
@@ -801,13 +879,13 @@ cairo_set_line_join (cairo_t *cr, cairo_
/**
* cairo_set_dash:
* @cr: a cairo context
- * @dashes: an array specifying alternate lengths of on and off po
+ * @dashes: an array specifying alternate lengths of on and off stroke portions
* @num_dashes: the length of the dashes array
* @offset: an offset into the dash pattern at which the stroke should start
*
* Sets the dash pattern to be used by cairo_stroke(). A dash pattern
* is specified by @dashes, an array of positive values. Each value
- * provides the user-space length of altenate "on" and "off" portions
+ * provides the user-space length of alternate "on" and "off" portions
* of the stroke. The @offset specifies an offset into the pattern at
* which the stroke begins.
*
@@ -2607,12 +2685,13 @@ cairo_get_target (cairo_t *cr)
* cairo_get_group_target:
* @cr: a cairo context
*
- * Gets the target surface for the current transparency group
- * started by the last cairo_push_group() call on the cairo
- * context.
- *
- * This function may return NULL if there is no transparency
- * group on the target.
+ * Gets the target surface for the current group as started by the
+ * most recent call to cairo_push_group() or
+ * cairo_push_group_with_content().
+ *
+ * This function will return NULL if called "outside" of any group
+ * rendering blocks, (that is, after the last balancing call to
+ * cairo_pop_group() or cairo_pop_group_to_source()).
*
* Return value: the target group surface, or NULL if none. This
* object is owned by cairo. To keep a reference to it, you must call
diff-tree 344c2c7acd0a87a7a28b4a73ba340b333fefb2bf (from a16f0b4223a5cc9faa68d844b8fd3ff1bfb996b7)
Author: Carl Worth <cworth at cworth.org>
Date: Thu May 4 21:35:23 2006 -0700
Add a couple more group-using tests: fill-and-stroke-alpha[-add]
diff --git a/test/.gitignore b/test/.gitignore
index 7546821..c3a0218 100644
--- a/test/.gitignore
+++ b/test/.gitignore
@@ -23,6 +23,8 @@ dash-offset-negative
dash-zero-length
extend-reflect
fill-and-stroke
+fill-and-stroke-alpha
+fill-and-stroke-alpha-add
fill-rule
filter-nearest-offset
ft-font-create-for-ft-face
diff --git a/test/Makefile.am b/test/Makefile.am
index d1ace03..0dbabc5 100644
--- a/test/Makefile.am
+++ b/test/Makefile.am
@@ -20,6 +20,8 @@ dash-offset-negative \
dash-zero-length \
extend-reflect \
fill-and-stroke \
+fill-and-stroke-alpha \
+fill-and-stroke-alpha-add \
fill-rule \
filter-nearest-offset \
font-face-get-type \
@@ -156,6 +158,8 @@ dash-zero-length-ps-argb32-ref.png \
fill-and-stroke-ref.png \
fill-and-stroke-rgb24-ref.png \
fill-and-stroke-ps-argb32-ref.png \
+fill-and-stroke-ref-alpha.png \
+fill-and-stroke-ref-alpha-add.png \
fill-rule-ref.png \
fill-rule-rgb24-ref.png \
fill-rule-ps-argb32-ref.png \
diff --git a/test/fill-and-stroke-alpha-add-ref.png b/test/fill-and-stroke-alpha-add-ref.png
new file mode 100644
index 0000000..d1da40a
Binary files /dev/null and b/test/fill-and-stroke-alpha-add-ref.png differ
diff --git a/test/fill-and-stroke-alpha-add.c b/test/fill-and-stroke-alpha-add.c
new file mode 100644
index 0000000..2e59cb8
--- /dev/null
+++ b/test/fill-and-stroke-alpha-add.c
@@ -0,0 +1,112 @@
+/*
+ * Copyright © 2005 Red Hat, Inc.
+ * Copyright © 2006 Red Hat, Inc.
+ *
+ * Permission to use, copy, modify, distribute, and sell this software
+ * and its documentation for any purpose is hereby granted without
+ * fee, provided that the above copyright notice appear in all copies
+ * and that both that copyright notice and this permission notice
+ * appear in supporting documentation, and that the name of
+ * Red Hat, Inc. not be used in advertising or publicity pertaining to
+ * distribution of the software without specific, written prior
+ * permission. Red Hat, Inc. makes no representations about the
+ * suitability of this software for any purpose. It is provided "as
+ * is" without express or implied warranty.
+ *
+ * RED HAT, INC. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
+ * SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ * FITNESS, IN NO EVENT SHALL RED HAT, INC. BE LIABLE FOR ANY SPECIAL,
+ * INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
+ * RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
+ * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+ * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ *
+ * Author: Carl D. Worth <cworth at cworth.org>
+ */
+
+#include "cairo-test.h"
+
+#define PAD 2
+#define SIZE 10
+
+cairo_test_t test = {
+ "fill-and-stroke-alpha-add",
+ "Use a group to fill/stroke a path (each with different alpha) using DEST_OUT and ADD to combine",
+ 2 * SIZE + 4 * PAD, SIZE + 2 * PAD
+};
+
+typedef void (*path_func_t) (cairo_t *cr);
+
+static void
+rectangle (cairo_t *cr)
+{
+ cairo_rectangle (cr, PAD, PAD, SIZE, SIZE);
+}
+
+static void
+circle (cairo_t *cr)
+{
+ cairo_arc (cr,
+ PAD + SIZE / 2, PAD + SIZE / 2,
+ SIZE / 2,
+ 0, 2 * M_PI);
+}
+
+/* Given a path-generating function and two possibly translucent
+ * patterns, fill and stroke the path with the patterns (to an
+ * offscreen group), then blend the result into the destination.
+ */
+static void
+fill_and_stroke (cairo_t *cr,
+ path_func_t path_func,
+ cairo_pattern_t *fill_pattern,
+ cairo_pattern_t *stroke_pattern)
+{
+ cairo_push_group (cr);
+ {
+ (path_func) (cr);
+ cairo_set_source (cr, fill_pattern);
+ cairo_fill_preserve (cr);
+
+ /* Use DEST_OUT to subtract stroke from fill. */
+ cairo_set_source_rgb (cr, 0.0, 0.0, 0.0);
+ cairo_set_operator (cr, CAIRO_OPERATOR_DEST_OUT);
+ cairo_stroke_preserve (cr);
+
+ /* Then use ADD to draw the stroke without a seam. */
+ cairo_set_source (cr, stroke_pattern);
+ cairo_set_operator (cr, CAIRO_OPERATOR_ADD);
+ cairo_stroke (cr);
+ }
+ cairo_pop_group_to_source (cr);
+ cairo_paint (cr);
+}
+
+static cairo_test_status_t
+draw (cairo_t *cr, int width, int height)
+{
+ cairo_pattern_t *blue;
+ cairo_pattern_t *red;
+
+ blue = cairo_pattern_create_rgba (0.0, 0.0, 1.0, 0.8);
+ red = cairo_pattern_create_rgba (1.0, 0.0, 0.0, 0.2);
+
+ cairo_test_paint_checkered (cr);
+
+ fill_and_stroke (cr, rectangle, blue, red);
+
+ cairo_translate (cr, SIZE + 2 * PAD, 0);
+
+ fill_and_stroke (cr, circle, red, blue);
+
+ cairo_pattern_destroy (blue);
+ cairo_pattern_destroy (red);
+
+ return CAIRO_TEST_SUCCESS;
+}
+
+int
+main (void)
+{
+ return cairo_test (&test, draw);
+}
diff --git a/test/fill-and-stroke-alpha-ref.png b/test/fill-and-stroke-alpha-ref.png
new file mode 100644
index 0000000..f1e8e23
Binary files /dev/null and b/test/fill-and-stroke-alpha-ref.png differ
diff --git a/test/fill-and-stroke-alpha.c b/test/fill-and-stroke-alpha.c
new file mode 100644
index 0000000..3b44415
--- /dev/null
+++ b/test/fill-and-stroke-alpha.c
@@ -0,0 +1,106 @@
+/*
+ * Copyright © 2005 Red Hat, Inc.
+ * Copyright © 2006 Red Hat, Inc.
+ *
+ * Permission to use, copy, modify, distribute, and sell this software
+ * and its documentation for any purpose is hereby granted without
+ * fee, provided that the above copyright notice appear in all copies
+ * and that both that copyright notice and this permission notice
+ * appear in supporting documentation, and that the name of
+ * Red Hat, Inc. not be used in advertising or publicity pertaining to
+ * distribution of the software without specific, written prior
+ * permission. Red Hat, Inc. makes no representations about the
+ * suitability of this software for any purpose. It is provided "as
+ * is" without express or implied warranty.
+ *
+ * RED HAT, INC. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
+ * SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ * FITNESS, IN NO EVENT SHALL RED HAT, INC. BE LIABLE FOR ANY SPECIAL,
+ * INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
+ * RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
+ * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+ * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ *
+ * Author: Carl D. Worth <cworth at cworth.org>
+ */
+
+#include "cairo-test.h"
+
+#define PAD 2
+#define SIZE 10
+
+cairo_test_t test = {
+ "fill-and-stroke-alpha",
+ "Use a group to fill/stroke a path then blend the result with alpha onto the destination",
+ 2 * SIZE + 4 * PAD, SIZE + 2 * PAD
+};
+
+typedef void (*path_func_t) (cairo_t *cr);
+
+static void
+rectangle (cairo_t *cr)
+{
+ cairo_rectangle (cr, PAD, PAD, SIZE, SIZE);
+}
+
+static void
+circle (cairo_t *cr)
+{
+ cairo_arc (cr,
+ PAD + SIZE / 2, PAD + SIZE / 2,
+ SIZE / 2,
+ 0, 2 * M_PI);
+}
+
+/* Given a path-generating function and two opaque patterns, fill and
+ * stroke the path with the patterns (to an offscreen group), then
+ * blend the result into the destination with the given alpha
+ * value.
+ */
+static void
+fill_and_stroke_alpha (cairo_t *cr,
+ path_func_t path_func,
+ cairo_pattern_t *fill_pattern,
+ cairo_pattern_t *stroke_pattern,
+ double alpha)
+{
+ cairo_push_group (cr);
+ {
+ (path_func) (cr);
+ cairo_set_source (cr, fill_pattern);
+ cairo_fill_preserve (cr);
+ cairo_set_source (cr, stroke_pattern);
+ cairo_stroke (cr);
+ }
+ cairo_pop_group_to_source (cr);
+ cairo_paint_with_alpha (cr, alpha);
+}
+
+static cairo_test_status_t
+draw (cairo_t *cr, int width, int height)
+{
+ cairo_pattern_t *blue;
+ cairo_pattern_t *red;
+
+ blue = cairo_pattern_create_rgb (0.0, 0.0, 1.0);
+ red = cairo_pattern_create_rgb (1.0, 0.0, 0.0);
+
+ cairo_test_paint_checkered (cr);
+
+ fill_and_stroke_alpha (cr, rectangle, blue, red, 0.5);
+
+ cairo_translate (cr, SIZE + 2 * PAD, 0);
+
+ fill_and_stroke_alpha (cr, circle, red, blue, 0.5);
+
+ cairo_pattern_destroy (blue);
+ cairo_pattern_destroy (red);
+
+ return CAIRO_TEST_SUCCESS;
+}
+
+int
+main (void)
+{
+ return cairo_test (&test, draw);
+}
More information about the cairo-commit
mailing list