[cairo] RFC: Shadow API v2

[Chris Wilson]

On Wed, Oct 29, 2014 at 04:54:33PM -0700, Bryce Harrington wrote:
> This incorporate's Chris' feedback on the API.  It adds the get/set user
> data routines and the get_reference_count routine.
> 
> There's still a lot I'm uncertain about, but this seems like a pretty
> good starting point.   Any other comments or suggestions on this API?
> 
> Else, next step will be creating implementations of the functionality
> for the image backend.  I will try to reuse henry's work as much as
> possible, adapted to fit this interface.
> 
> Bryce
> 
> 
> /*
>  * Effect lifecycle management
>  */
> cairo_public cairo_effect_t *
> cairo_effect_create_drop_shadow (double x_offset, double y_offset,
>                                  double x_blur,   double y_blur);

In the long run, we are likely to want pen effects, material effects,
operator effects, clip effects? (it's a form of path...)

We can either use the same opaque type and just note where they are
applicable (which seems reasonably since in the long run they will all
have very similar API and placement in the pipeline), but we should
probably try to incorporate path into the name for these.

cairo_effect_create_drop_shadow_path(), cairo_effect_create_inset_shadow_path() ?

A bit unwieldly, so just a note in the comment saying this create an
effect of type CAIRO_EFFECT_TYPE_PATH.

> 
> 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);
> 
> cairo_public unsigned int
> cairo_effect_get_reference_count (cairo_pattern_t *pattern);
> 
> cairo_public void *
> cairo_effect_get_user_data (cairo_effect_t              *effect,
>                             const cairo_user_data_key_t *key);
> 
> cairo_public cairo_status_t
> cairo_effect_set_user_data (cairo_effect_t              *effect,
>                             const cairo_user_data_key_t *key,
>                             void                        *user_data,
>                             cairo_destroy_func_t         destroy);
> 
> 
> 
> /*
>  * Effect properties
>  */
> typedef enum _cairo_effect_type {
>     CAIRO_SHADOW_NONE = 0,
>     CAIRO_SHADOW_DROP,
>     CAIRO_SHADOW_INSET
> } cairo_effect_type_t;

So cairo_effect_type should be CAIRO_EFFECT_TYPE_PATH,
CAIRO_EFFECT_TYPE_PEN, etc.

> cairo_public cairo_effect_type_t
> cairo_effect_get_type (cairo_effect_t *effect);

For recognising individual effects, perhaps

cairo_effect_get_name() or cairo_path_effect_get_type() ?

But definitely we want to plan for future effect classes now.
-Chris

-- 
Chris Wilson, Intel Open Source Technology Centre