Creating Live Path Effects

Instructions for making Live Path Effects.

Groundwork:

It is best to put your new effect in the /live_effects directory. Copy lpe-skeleton.cpp and lpe-skeleton.h to your files (say lpe-youreffect.cpp and lpe-youreffect.h), and rename everything from skeleton to your name.

Add your effect to the enumeration in effect.h: "enum EffectType". This way, Inkscape knows how to refer to your effect.

Add your effect to the "const Util::EnumData<EffectType> LPETypeData[INVALID_LPE]" array in /live_effects/effect.cpp. This way, Inkscape knows how to tell the user what the name of the effect is and also how to write its name to SVG.

One more thing to do: add your files to /live_effects/Makefile_insert. (Be aware of the spaces and tabs in that file!)

That's all! Now your effect should pop up in the LivePathEffect dialog in Inkscape! But your effect won't do anything now, it would just pass along the original path. Time to start writing the main machinery of your cool effect!

Write your effect:

The effect code should go into a doEffect function. The doEffect function receives the original path, and should return the path that results from your effect.

You have to choose between 4 doEffect functions and implement just one of them. There is a "chain" of these functions. The first doEffect function calls the second, which calls the 3rd, which calls the 4th. The 4th returns its result to the 3rd which returns its result to the 2nd which returns it to the first and finally Inkscape receives the result. But all these standard functions do nothing real, they just change the path from one type to another. You have to determine which type is most convenient for you and overload that function. This means you put your own doEffect function in the place where normally the standard function would be called.

These are the doEffect functions in the order in which they are called:

1. void doEffect (SPCurve * curve)
2. NArtBpath * doEffect (NArtBpath * path_in)
3. std::vector<Geom::Path> doEffect (std::vector<Geom::Path> & path_in)
4. Geom::Piecewise<Geom::D2<Geom::SBasis> > doEffect (Geom::Piecewise<Geom::D2<Geom::SBasis> > & pwd2_in)

It is easy to replace the standard doEffect function with yours. Let's say you want to create your effect with the path types of the 3rd function. You have to declare that one for your effect in lpe-youreffect.h: they are already writting down in there, you just have to un-comment the one you want, and you can delete the other doEffect functions. You must do the same in lpe-youreffect.cpp.

A "copy" effect has already been put in the .cpp file, you have to spice that up to make it do what you want. It is best to have a look at the doEffect functions of lpe-slant.cpp and lpe-skeleton.cpp to see what is possible and how to implement something!

Parameter types:

Your effect can have any number of parameters that you'd like. You have to define them in the .h file. "RealParam number" is already there in the skeleton file; you can delete this if you do not want that kind of parameter ofcourse. That is the location where you can put the parameters that you want.
You also have to initialise and register them, so Inkscape knows about them. This you should do in the .cpp file:

   // initialise your parameters here:
   number(_("Float parameter"), _("just a real number like 1.4!"), "svgname", &wr, this, 1.2)

The arguments are respectively, the name of the parameter in the UI, the tooltip text, the name of the parameter in SVG, 2 parameters that you don't have to bother about (they are always the same), and finally the default value. You can also omit the default value.

And these lines register your parameter:

   // register all your parameters here, so Inkscape knows which parameters this effect has:
   registerParameter( dynamic_cast<Parameter *>(&number) );

Available parameter types

Check the /live_effects/parameter dir for more up-to-date info; perhaps some parameter types were added! You have to include the .h file that belongs to the parameter type in your own .h file to be able to use that parameter type.

• ScalarParam: a number of type 'gdouble'.
  

include "live_effects/parameter/parameter.h"
(see lpe-slant.cpp to learn how to use this type)

• PointParam: a parameter that describes a coordinate on the page.
  

include "live_effects/parameter/point.h"
(see lpe-skeletal.cpp to learn how to use this type)

• PathParam: a parameter that is a path. This is a single path! If the input for this parameter are multiple paths, it is converted to just one path.
  

include "live_effects/parameter/path.h"
(see lpe-skeletal.cpp to learn how to use this type)

• EnumParam: a parameter that lets the user choose between a number of options from a dropdown box.
  

include "live_effects/parameter/enum.h"
(see lpe-skeletal.cpp to learn how to use this type)

• BoolParam:
  

include "live_effects/parameter/bool.h"

• RandomParam:
  

include "live_effects/parameter/random.h"

The parameters will automatically appear in the Live Path Effects dialog!