[cairo] RFC: Shadow API

[Bryce Harrington]

In September 2013, Henry proposed[0] adding a feature for Gaussian blur
and shadow, based on work carried in his cairogles branch[1].  The
proposed API[2] was felt to have too many entry points to the context for
setting all the various parameters (shadow color and type, blur
direction, etc.), and Chris suggested[3] coming up with a more generic
API that would handle path effects in a way more analogous to patterns.

Following is my own rough cut at making it more akin to cairo_pattern's
API design:


/*
 * Effect object management
 */
cairo_public cairo_effect_t *
cairo_effect_create_drop_shadow (double x_offset, double y_offset,
                                 double x_blur,   double y_blur);

cairo_public cairo_effect_t *
cairo_effect_create_inset_shadow (double x_offset, double y_offset,
                                  double x_blur,   double y_blur);

cairo_public cairo_status_t
cairo_effect_status (cairo_effect_t *effect);

cairo_public cairo_effect_t *
cairo_effect_reference (cairo_effect_t *effect);

cairo_public void
cairo_effect_destroy (cairo_effect_t *effect);


/*
 * Effect properties
 */
typedef enum _cairo_effect_type {
    CAIRO_EFFECT_NONE = 0,
    CAIRO_EFFECT_DROP_SHADOW,
    CAIRO_EFFECT_INSET_SHADOW
} cairo_effect_type_t;

cairo_public cairo_effect_type_t
cairo_effect_get_type (cairo_effect_t *effect);

cairo_public void
cairo_effect_set_rgb (cairo_pattern_t *pattern,
                      double red, double green, double blue);

cairo_public void
cairo_effect_set_rgba (cairo_pattern_t *pattern,
                       double red, double green, double blue,
                       double alpha);


/*
 * Applying effects to the context
 */
cairo_public void
cairo_set_path_effect (cairo_t *cr, cairo_effect_t *source);

cairo_public cairo_effect_t *
cairo_get_path_effect (cairo_t *cr);



Henry's API proposal included provision for shadow caching by the
application.  That certainly made a huge difference in the demos, so
maybe it's still going to be needed.  But I'm not sure whether this must
be switched on via an API call, or if the optimization can somehow be
handled internally.  If it does need an API call, it could be handled as an
effect property and set via something like cairo_effect_set_cached.

Last time, there was also some discussion regarding handling of inset
shadows, and whether the original object should be drawn with the shadow
or drawn as a second cairo operation.  These both remain open points of
discussion.

Bryce

0: http://lists.cairographics.org/archives/cairo/2013-September/024596.html
1: https://github.com/SRA-SiliconValley/cairogles/commits/filters-wip
2: http://lists.cairographics.org/archives/cairo/2013-September/024598.html
3: http://lists.cairographics.org/archives/cairo/2013-September/024597.html