Re: RFC v3: Path Effects API

Well, I think I will not come with anything better than SVG effect graph,
but that could be overkill as well, no idea :)





On Wed, Oct 19, 2016 at 1:11 AM, Bryce Harrington <[email protected]>
wrote:

> On Tue, Oct 18, 2016 at 11:01:03PM +0200, Petr Kobalíček wrote:
> > What about chaining effects, the API seems to only deal with one effect
> at
> > time, is that correct?
>
> I'd like the API to support chained effects, although you're right the
> API suggests there can be only one effect at a time.
>
> I'd like it to also support booleaned effects, which implies applying
> two effects and then a boolean on top to merge them together.  However,
> I'm a bit vague on exactly how all that should work.  Suggestions?
>
> Bryce
>
> > On Tue, Oct 18, 2016 at 6:27 PM, Bill Spitzak <[email protected]> wrote:
> >
> > > On Mon, Oct 17, 2016 at 11:15 AM, Bryce Harrington
> > > <[email protected]> wrote:
> > > > 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.
> > > >
> > > > In 2014 I posted[4] a rough cut at such an API, following
> > > > cairo_pattern's API design, and a v2 shortly thereafter[5].
> Following
> > > > is a v3 of that proposal, incorporating some of Chris Wilson's
> suggested
> > > > changes.
> > > >
> > > > In particular, this divides the API into a base class (Effects), and
> > > > sub-class (Path Effects), allowing for future introduction of pen
> > > > effects, material effects, etc.  This common API is intended to
> > > > provide a consistent way of handling all effects in the rendering
> > > > pipeline.
> > > >
> > > > v2:
> > > >   + Add get_data, set_data, reference_count for the cairo_object_t
> api
> > > >   + Rename enums
> > > > v3:
> > > >   + Path Effects are handled as a subclass of Effects
> > > >
> > > > ---
> > > >
> > > > /*
> > > >  * Effect lifecycle management
> > > >  */
> > > > 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_effect_t *effect);
> > > >
> > > > 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_funct_t destroy);
> > > >
> > > > /*
> > > >  * Effect properties
> > > >  */
> > > > typedef enum _cairo_effect_type {
> > > >     CAIRO_EFFECT_TYPE_NONE = 0,
> > > >     CAIRO_EFFECT_TYPE_PATH
> > > > } cairo_effect_type_t;
> > > >
> > > > /* Future types might include:
> > > >  *  CAIRO_EFFECT_TYPE_PEN
> > > >  *  CAIRO_EFFECT_TYPE_MATERIAL
> > > >  *  CAIRO_EFFECT_TYPE_OPERATOR
> > > >  *  CAIRO_EFFECT_TYPE_CLIP
> > > >  *  ...
> > > >  */
> > > >
> > > > cairo_public cairo_effect_type_t
> > > > cairo_effect_get_type (cairo_effect_t *effect);
> > > >
> > > >
> > > >
> > > > /* ------------------------------------------------------------
> ----------
> > > */
> > > >
> > > > /*
> > > >  * Path effect creation
> > > >  *
> > > >  * These create effects of type CAIRO_EFFECT_TYPE_PATH.
> > > >  */
> > > > cairo_public cairo_effect_t *
> > > > cairo_effect_create_drop_shadow_path (double x_offset, double
> y_offset,
> > > >                                       double x_blur,   double
> y_blur);
> > > >
> > > > cairo_public cairo_effect_t *
> > > > cairo_effect_create_inset_shadow_path (double x_inset, double
> y_inset,
> > > >                                        double x_blur,  double
> y_blur);
> > > >
> > > > /*
> > > >  * Applying path 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);
> > > >
> > > > /*
> > > >  * Path effect properties
> > > >  */
> > > > typedef enum _cairo_path_effect_type {
> > > >     CAIRO_PATH_EFFECT_NONE = 0,
> > > >     CAIRO_PATH_EFFECT_DROP_SHADOW,
> > > >     CAIRO_PATH_EFFECT_INSET_SHADOW
> > > > } cairo_path_effect_type_t;
> > > >
> > > > /* Future path effect types could include:
> > > >  *  CAIRO_PATH_EFFECT_PATTERN
> > > >  *  CAIRO_PATH_EFFECT_UNION
> > > >  *  CAIRO_PATH_EFFECT_DIFFERENCE
> > > >  *  CAIRO_PATH_EFFECT_INTERSECTION
> > > >  *  ...
> > > >  */
> > > >
> > > > cairo_public cairo_path_effect_type_t
> > > > cairo_path_effect_get_subtype (cairo_effect_t *effect);
> > > >
> > > > cairo_public void
> > > > cairo_path_effect_set_rgba (cairo_path_effect_t *path_effect,
> > > >                             double red, double green, double blue,
> > > >                             double alpha);
> > > >
> > > > Internally, both the effect type and subtype can be tracked in a
> single
> > > > property, e.g.:
> > > >
> > > >     type = CAIRO_EFFECT_TYPE_PATH << 24 |
> CAIRO_PATH_EFFECT_DROP_SHADOW;
> > > >
> > > >
> > > > 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.  An idea is to provide a
> > > > backend/user preference as to whether effects should be cached or
> > > > applied on the fly, e.g. cairo_effect_set_cached.
> > > >
> > > > Bryce
> > > >
> > > > 0:  https://lists.cairographics.org/archives/cairo/2013-
> > > September/024596.html
> > > > 1:  The cairogles branch is no longer available publically.  The
> private
> > > >     branch is at https://github.com/SRA-SiliconValley/cairogles
> > > > 2:  https://lists.cairographics.org/archives/cairo/2013-
> > > September/024598.html
> > > > 3:  https://lists.cairographics.org/archives/cairo/2013-
> > > September/024597.html
> > > > 4:  https://lists.cairographics.org/archives/cairo/2014-
> > > October/025748.html
> > > > 5:  https://lists.cairographics.org/archives/cairo/2014-
> > > October/025766.html
> > > > --
> > > > cairo mailing list
> > > > [email protected]
> > > > https://lists.cairographics.org/mailman/listinfo/cairo
> > >
> > > Seems to me there is excessive namespacing here. There is no need for
> > > an "effect type", it should just be clear from the effect description
> > > whether it has an effect on stroke, fill, or text, or which parts of
> > > the inputs it changes.
> > >
> > > Possibly you are thinking that the effects would be mutually exclusive
> > > and that the type is to identify the mutually exclusive set, but that
> > > seems really limiting and I think you will end up with one "type" for
> > > each effect. Instead just allow arbitrary sets of effects to be
> > > active. If two effects can't be done at the same time, it is either an
> > > error, or one of them takes precedence.
> > >
> > > I would also remove "PATH" from all your enumerations and function
> > > names. Some of them are really confusing now, for instance
> > > "cairo_effect_create_inset_shadow_path" does not create a path, it
> > > creates an effect.
> > > --
> > > cairo mailing list
> > > [email protected]
> > > https://lists.cairographics.org/mailman/listinfo/cairo
> > >
>

-- 
cairo mailing list
[email protected]
https://lists.cairographics.org/mailman/listinfo/cairo