Synfig Studio :: Documentation - User contributions [en]

Dev:Build Instructions

2009-05-26T10:46:04Z

Dooglus: /* synfig */ line was 625 not 622 for me

[[Category:Building]]

== Notes ==

If you are using the released versions instead of SVN, none of the libtoolize or autoreconf steps are necessary. For released versions, "./configure && make && sudo make install" should be enough.

If you are using packages for synfig's dependencies, you want the '''development packages''' not the main packages. Check below for your distribution's packages.

Please read the [[Source code|source code]] page to check out the latest code. Please also check the [[Download|download page]] and the [[FAQ]] to find out about any issues that you may run into along the way.

Some Linux/BSD distros have a pkg-config that doesn't look in /usr/local/lib/pkgconfig by default. So if you are installing in anywhere other than the system pkg-config path, please run "export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig" or similar before building or installing anything.

Don't use automake 1.4, there are problems with it.

Using automake 1.9, 'make install' seems to re-link and re-install all the synfig core modules every time whether they have changed or not. [http://dooglus.rincevent.net/synfig/automake.html here] is an ugly workaround - it's only worth using if you intend to rebuild synfig repeatedly

The instructions below result in 3 separate subversion working directories being created. This is inconvenient to work with - you'll need to 'svn commit' in 3 different places to send changes, 'svn update' in 3 different places to get the latest updates, etc. [[Subversion|This page]] shows how to arrange for the code to be checked out into a single working directory. You can also download a daily updated tarball that uses this from the [[Source code|source code]] page.

The CVS requirement is only because the autopoint program run by autoreconf needs CVS. You can avoid the need for CVS by disabling the translation/gettext stuff in configure.ac.

If you don't want to install to a system-wide directory using sudo, run something like these commands before starting:

<pre>
export PREFIX="$HOME/opt"
export PKG_CONFIG_PATH="$PKG_CONFIG_PATH:$PREFIX/lib/pkgconfig"
export PATH="$PATH:$PREFIX/bin"
</pre>

And when you run ./configure, run it with --prefix="$PREFIX" and don't use sudo when you do make install.

=== Automatic build/update script ===

You can use [http://zelgadis.profusehost.net/files/synfig/synfigstudio-svn-build this] script to quickly build/update synfigstudio from SVN (software installed in ~/synfig-svn by default).

To use the script just execute following single command in terminal:
<pre>cd && \
wget http://zelgadis.profusehost.net/files/synfig/synfigstudio-svn-build && \
chmod +x synfigstudio-svn-build && \
./synfigstudio-svn-build initialize</pre>

'''WARNING:''' Your system must satisfy synfig's build requiments, the sript won't do it for you.

=== System-specific instructions ===

* Gentoo: SVN [[Gentoo Ebuilds|ebuilds]] are available
* MacOS X: [[Building_On_Mac_OS_X|instructions for building]] with the GTK+ Aqua port are available.
* PCLinuxOS: [[PCLinuxOS build instructions|build instructions]]
* Windows: [[Windows build instructions|instructions for building]] in [[Mingw_installation|mingw]] are available.

== ETL ==

ETL is a template library, there is nothing to build really, it just needed to be installed.

Requires: autoconf automake<br>
* Debian: build-essential autoconf automake

''Type the following commands at the directory that holds '''ETL:'''''
<pre>
$ autoreconf --install --force
$ ./configure
$ sudo make install
</pre>

== synfig ==

Requires: ETL (etl-dev, already installed if you successfully built etl), libxml++, libsigc++, libltdl, libtool, gettext, cvs<br>
* Debian: etl-dev libxml++2.6-dev libsigc++-2.0-dev libltdl3-dev libtool gettext cvs
* Gentoo: virtual/ETL dev-cpp/libxmlpp dev-libs/libsigc++ dev-util/cvs
** If you are using ./configure --prefix="$PREFIX" to configure synfig, do not install virtual/ETL.

Note: libpng isn't required to build synfig, but if you build synfig without PNG support and go on to build synfigstudio, that step will fail (because the build process for synfigstudio uses synfig to create .png icon files). The package is libpng12-dev on Debian or media-libs/libpng on Gentoo.

Note: the 'configure.ac' file in the synfig-core directory doesn't work with libtool version 2, as shipped with ubuntu 8.10. To work around the problem until a proper fix is found, comment out line 622 or thereabouts (it says "AC_CONFIG_SUBDIRS(libltdl)") by putting a "#" at the front of the line. The line is required for older versions of libtool, as shipped with other distributions.

Optional: libpng, libmng, libjpeg, libfreetype, libfontconfig, libopenexr, libavcodec, libmagick++, vimage (MacOS only, proprietary)<br>
* Debian: libpng12-dev libmng-dev libjpeg62-dev libfreetype6-dev libfontconfig1-dev libopenexr-dev libavcodec-dev libavformat-dev libswscale-dev libmagick++9-dev
* Gentoo: sys-devel/libtool media-libs/libpng media-libs/libmng media-libs/jpeg media-libs/freetype media-libs/fontconfig media-libs/openexr media-libs/libavcodec
*Ubuntu (since Jaunty): Same libraries as Debian but do not use libmagick++9-dev, use graphicsmagick-libmagick-dev-compat instead.
Runtime: encodedv (from libdv), ffmpeg, convert (from imagemagick)
* Debian: libdv-bin ffmpeg imagemagick
* Gentoo: media-libs/libdv media-video/ffmpeg media-gfx/imagemagick

''Type the following commands at the directory that holds '''synfig-core:'''''
<pre>
$ libtoolize --ltdl --copy --force
$ autoreconf --install --force
$ ./configure
$ make
$ sudo make install
</pre>

Notes:

* Don't use --enable-half, it is slow.

== synfigstudio ==

Requires: ETL (etl-dev, already installed if you successfully built etl), synfig (libsynfig-dev, already installed if you successfully built synfig), gtkmm >= 2.4, gtk >= 2.0, glibmm, libsigc++, libltdl, libtool, gettext, cvs<br>
* Debian: etl-dev libsynfig-dev libgtkmm-2.4-dev libgtk2.0-dev libglibmm-2.4-dev libsigc++-2.0-dev libltdl3-dev libtool gettext cvs
* Gentoo: virtual/ETL virtual/synfig dev-cpp/gtkmm-2.4 dev-libs/libsigc++ sys-devel/libtool
** If you are using ./configure --prefix="$PREFIX" to configure synfigstudio, do not install virtual/ETL or virtual/synfig.
Optional: fonts (for the images), [http://www.fmod.org FMOD] (version 3.x, proprietary)
* Debian: ttf-freefont ttf-dejavu ttf-dustin
* Gentoo: freefonts dejavu

''Type the following commands at the directory that holds '''synfig-studio:'''''
<pre>
$ autoreconf --install --force
$ ./configure
$ make
$ sudo make install
</pre>



== finalizing ==

Depending on where you installed synfig to, you might have to tell your system where the libraries can be found. That can be done via the following command:

<pre>
$ sudo ldconfig
</pre>

File:Tree3.gif

2008-12-19T11:13:59Z

Dooglus: an example of the bones work in progress

an example of the bones work in progress

Convert

2008-12-18T22:15:02Z

Dooglus: /* Random */

Right-clicking on a value in the Parameters dialog brings up a context menu which has a sub-menu called "Convert". The "Convert" menu allows you to specify that the parameter should be controlled automatically in various ways. Depending on the type of the parameter the Convert menu will contain different options.

To convert the value back to its original type, select "Disconnect" from its context menu.

== Convert Types ==

=== Add ===

Converting a parameter to "Add" adds three sub-parameters, the first two of which are the same type as the parameter itself:
* <param> "LHS"
* <param> "RHS"
* real "Scalar"

The "Add" conversion can be used with parameters of type [[Convert#Angle|angle]], [[Convert#Color|color]], [[Convert#Gradient|gradient]], [[Convert#Integer|integer]], [[Convert#Real|real]], [[Convert#Time|time]], and [[Convert#Vector|vector]].

The resulting value is:
(LHS + RHS) * Scalar

=== Angle String ===

Converting an [[Convert#String|string]]-valued parameter to "Angle String" adds four sub-parameters:
* angle "Angle"
* integer "Width"
* integer "Precision"
* bool "Zero Padded"

The resulting value a string containing the value of "Angle" (in degrees) formatted as a string with a minimum width "Width", with "Precision" decimal places. If "Zero Padded" is true, it will be left-padded with "0" characters.

=== aTan2 ===

Converting an [[Convert#Angle|angle]]-valued parameter to "aTan2" adds two sub-parameters:
* real "X"
* real "Y".

The resulting value is:
atan2(y,x)

ie. atan(y/x) but without an error when x is 0. The value is the angle between the x axis and the vector (x,y).

=== BLine ===

Converting a [[Convert#List|list]] parameter to "BLine" doesn't seem to change anything. Perhaps that's the default type for lists of vertices, such as are found in outlines and regions?

=== BLine Tangent ===

Converting a [[Convert#Angle|angle]], [[Convert#Real|real]] (since SVN r1862), or [[Convert#Vector|vector]] parameter to "BLine Tangent" adds six sub-parameters:
* bline "BLine"
* bool "Loop"
* real "Amount"
* angle "Offset" (since SVN r1863)
* real "Scale" (since SVN r1863)
* bool "Fixed Length" (since SVN r1863)

Amount is a number between 0 and 1, defining the distance along the given bline. The resulting value for the whole parameter is the tangent to the bline, at the given point along the bline, optionally rotated and scaled according to the "Offset", "Scale", and "Fixed Length" parameters.

"Offset" is an angle used to give the tangent an extra rotation before returning it. If "Fixed Length" is true, the tangent is then scaled to have a length equal to "Scale". Otherwise the tangent is multiplied by "Scale".

If a vector was converted the result is the tangent itself. If an angle was converted, the result is the angle of the tangent to the horizontal, and if a real was converted, the result is the length of the tangent.

This [[Following a BLine|tutorial]] gives an example of the use of this convert type.

=== BLine Vertex ===

Converting a [[Convert#Vector|vector]] parameter to "BLine Vertex" adds three sub-parameters:
* bline "BLine"
* bool "Loop"
* real "Amount"

Amount is a number between 0 and 1, defining the distance along the given bline. The resulting value for the whole parameter is a vector giving the position of the given point along the bline.

This [[Following a BLine|tutorial]] gives an example of the use of this convert type.

=== BLine Width ===

Converting a [[Convert#Real|real]] parameter to "BLine Width" adds three sub-parameters:
* bline "BLine"
* bool "Loop"
* real "Amount"
* real "Scale" (since SVN r1872)

Amount is a number between 0 and 1, defining the distance along the given bline. The resulting value for the whole parameter is the width of the bline at the given point along it, multiplied by the "Scale" parameter.

=== Composite ===

Converting a [[Convert#BLinePoint|blinepoint]] parameter to "Composite" adds six sub-parameters:
* vector "Vertex"
* real "Width"
* real "Origin"
* bool "Split Tangents"
* vector "Tangent 1"
* vector "Tangent 2"

Converting a [[Convert#Color|color]] parameter to "Composite" adds four real-valued sub-parameters:
* real "Red"
* real "Green"
* real "Blue"
* real "Alpha"

Converting a [[Convert#Segment|segment]] parameter to "Composite" adds four vertex sub-parameters:
* vertex "Vertex 1"
* vertex "Tangent 1"
* vertex "Vertex 2"
* vertex "Tangent 2"

Converting a [[Convert#Vector|vector]] parameter to "Composite" adds two real-valued sub-parameters:
* real "X-Axis"
* real "Y-Axis"

The resulting value is a blinepoint, color, segment, or vector made by combining the component parts.

=== Cos ===

Converting a [[Convert#Real|real]]-valued parameter to "Cos" adds two sub-parameters:
* angle "Angle"
* real "Amplitude".

The resulting value is:
Amplitude * cos(Angle)

=== Dot Product ===

Converting a [[Convert#Real|real]] or [[Convert#Angle|angle]] parameter to a "Dot Product" adds two sub-parameters:
* vector "LHS"
* vector "RHS"

If the converted value is an angle, the return value is the angle between the two vectors:

return = acos((LHS · RHS) / (|LHS| * |RHS|))

If the converted value is a real, the result value is the dot product of the two vectors:

return = LHS · RHS = |LHS| * |RHS| * cos(alpha)

(where alpha is the angle between LHS and RHS).

=== Duplicate ===

This ValueNode type is only used by the [[Duplicate Layer]]. It never appears in the Convert menu. It is used to control the range of the Index in the Duplicate Layer (q.v.).

The "Duplicate" ValueNode type has 3 real-valued sub-parameters:

* real "From"
* real "To"
* real "Step"

The value of the ValueNode varies from the value of "From" to the value of "To" in steps of size "Step". The sign of "Step" is ignored. If From<To the steps are positive, else they're negative.

=== Dynamic List ===

Converting a [[Convert#List|list]] parameter to "Dynamic List" seems to replace each of the "Vertex NNN" sub-parameters with "Item NNN" parameters which can't be expanded, but can be exported.

=== Exponential ===

Converting a [[Convert#Real|real]] parameter to "Exponential" adds two sub-parameters:

* real "Exponent"
* real "Scale"

The resulting value is the result raising the [http://en.wikipedia.org/wiki/E_%28mathematical_constant%29 mathematical constant 'e'] to the power of Exponent, and scaling the result by Scale. That is, it returns:
Scale * e^Exponent

This is useful for tracking layers which have been zoomed, since the Zoom layer scales by e^(zoom factor).

See [http://youtube.com/watch?v=GAWtndOHkUw this video] for an example of the use of this convert type.

=== From Integer ===

This is currently disabled. It converts an integer to one of several types.

=== Gradient Color ===

Converting a [[Convert#Color|color]] parameter to "Gradient Color" adds two sub-parameters:

* gradient "Gradient"
* real "Index"

The resulting value is a color taken from the gradient at the given index position. Index 0 corresponds to the left of the gradient; index 1 corresponds to the right of the gradient.

=== Gradient Rotate ===

Converting a [[Convert#Gradient|gradient]] parameter to "Gradient Rotate" adds two sub-parameters:

* gradient "Gradient"
* real "Offset"

The resulting value is a gradient based on the "Gradient" parameter, but shifted left (for negative values) or right, according to the value of the "Offset" parameter. An offset of 1.0 will shift the gradient by its entire visible width. Values shifted off the left or right edge aren't lost - they aren't visible in the gradient as it's displayed in the parameters dialog, but they will still be used when rendering (depending on parameters such as 'Loop' and 'Zigzag', which can cause gradients to be looped between their their left and right edges, rather than using the non-displayed parts).

=== Int String ===

Converting an [[Convert#String|string]]-valued parameter to "Int String" adds three sub-parameters:
* integer "Int"
* integer "Width"
* bool "Zero Padded"

The resulting value a string containing "Int" formatted as a string with a minimum width "Width". If "Zero Padded" is true, it will be left-padded with "0" characters.

=== Joined List ===

Converting a [[Convert#String|string]] parameter to be 'Joined List' adds four sub-parameters:
* list "Strings"
* string "Before"
* string "Separator"
* string "After"

The result is a string containing the value of "Before", followed by all the strings in the "Strings" list, with the value of "Separator" between each pair, followed by the value of "After".

=== Linear ===

Converting an [[Convert#Angle|angle]] parameter to be 'Linear' adds two angle sub-parameters:
* angle "Rate"
* angle "Offset"

Converting a [[Convert#Color|color]] parameter to be 'Linear' adds two angle sub-parameters (since svn r617):
* color "Rate"
* color "Offset"

Converting an [[Convert#Integer|integer]] parameter to be 'Linear' adds two angle sub-parameters (since svn r617):
* integer "Rate"
* integer "Offset"

Converting a [[Convert#Real|real]] parameter to be 'Linear' adds two real-valued sub-parameters:
* real "Rate"
* real "Offset"

Converting a [[Convert#Time|time]] parameter to be 'Linear' adds two time sub-parameters:
* time "Rate"
* time "Offset"

Converting a [[Convert#Vector|vector]] parameter to be 'Linear' adds two vector sub-parameters:
* vector "Slope"
* vector "Offset"

The parameter's value will change linearly over time, starting with the value specified by "Offset" at time zero, and increasing by the value specified by "Rate" (or "Slope", in the case of vector parameters) every second.

The resulting value for vector parameters is:
Offset + Slope*time

and for the other 5 types of parameter it is:
Offset + Rate*time

=== Logarithm ===

Converting a [[Convert#Real|real]]-valued parameter to "Logarithm" adds three sub-parameters:

* real "Link"
* real "Epsilon".
* real "Infinite".

The resulting value is:

Log(Link) (if Link >= Epsilon)
-Infinite (if Link < Epsilon)

The epsilon and infinite parameters are only needed to prevent logarithm of negative or zero numbers. For regular operation the resulting value is simply the natural logarithm of Link. In fact a logarithm of a negative number cannot be calculated in the space of Real numbers. This convert type returns -Infinite for simplicity.

=== Radial Composite ===

Converting a [[Convert#Color|color]] to "Radial Composite" adds four sub-parameters:
* real "Luma"
* real "Saturation"
* angle "Hue"
* real "Alpha"

Converting a [[Convert#Vector|vector]] to "Radial Composite" adds two sub-parameters:
* real "Radius"
* angle "Theta"

For color parameters, the resulting value is the color with the given lima, saturation, hue, and alpha amounts.

For vector parameters, the resulting value is the point reached by traveling a distance "Radius" from the origin, in the distance given by the angle "Theta".

=== Random ===

Converting a parameter to "Random" adds five sub-parameters, the first of which is the same type as the converted parameter:

* <param> "Link"
* real "Radius"
* integer "Seed"
* real "Animation Speed"
* integer "Interpolation"
* real "Loop Time" (since SVN r2315)

"Random" can be used on [[Convert#Angle|angles]], [[Convert#Color|colors]], [[Convert#Integer|integers]], [[Convert#Real|reals]], [[Convert#Time|times]], and [[Convert#Vector|vectors]].

It is used to cause a parameter's value to vary randomly over time, around a central value:

* "Link" provides the central value.
* "Radius" defines the maximum random difference.
* "Seed" seeds the random number generator
* "Animation Speed" defines how often a new random value is chosen (in choices per second)
* "Interpolation" determines how the value is interpolated from one random choice to the next. Possible values are:
** 0 - no interpolation; the value jumps from one value to the next
** 1 - linear interpolation
** 2 - cosine
** 3 - spline
** 4 - cubic (the default); uses [http://www.gamedev.net/reference/articles/article1497.asp Catmull-Rom] spline interpolation
* "Loop Time" (added in SVN r2315) makes the random value repeat after the given time. The value ends up the same at the given time as at time=0 so it's possible to make random looping animations without a nasty jump when the time wraps back to zero.

The "Interpolation" sub-parameter should really be a drop-down menu, rather than an integer field, but that isn't yet implemented.

=== Range ===

Converting a parameter to "Range" adds three sub-parameters, all the same type as the parameter itself:
* <param> "Min"
* <param> "Max"
* <param> "Link"

"Range" can be used on [[Convert#Angle|angles]], [[Convert#Integer|integers]], [[Convert#Real|reals]], and [[Convert#Time|times]].

It is used to limit the value of the linked parameter to be between Min and Max.

The resulting value is:
Min (if Link < Min)
Max (if Link > Max)
Link (otherwise)

=== Real String ===

Converting a [[Convert#String|string]] parameter to "Real String" adds four sub-parameters:

* real "Real"
* int "Width"
* int "Precision"
* bool "Zero Padded"

The result is a string formatted to contain the given value "Real". "Width" specifies the minimum field width, "Precision" specifies the number of decimal places and "Zero Padded" specifies whether to pad with zeros on the left hand side.

For example, with Real=3.1415, Width=6, Precision=2, and ZeroPadded=true, we get:
"003.14"
(6 characters long, 2 decimal places, and padded with zeros on the left).

=== Reciprocal ===

Converting a [[Convert#Real|real]]-valued parameter to "Reciprocal" adds three sub-parameters:
* real "Link"
* real "Epsilon".
* real "Infinite".

The resulting value is:
1/Link (Link <= -epsilon or epsilon <= Link)
Infinite (if 0 <= Link < epsilon)
-Infinite (if -epsilon < Link < 0)

The epsilon and infinite parameters are only needed to prevent division by zero. For regular operation the resulting value is simply the reciprocal of Link.

=== Reference ===

Converting a parameter to "Reference" adds a single sub-parameter called "Link". The "Link" parameter is the same type as the parameter being converted.

It doesn't seem to do anything at all, other than adding an extra parameter. Whatever value is put into "Link" becomes the value of the parameter being converted.

The only use for this conversion type I can think of is the following:

* you know that point A should follow point B, so you export point B and connect point A to it
* you're not yet sure exactly how point B should move, so you experiment with different conversion types for point B
* changing the conversion type for point B breaks the connection you made in the first step
* converting point B to be a reference, and then experimenting with different conversions in its "Link" parameter allows point A to connect to point B and for the connection to remain in place while you experiment in the "Link" parameter

The resulting value is:
Link

=== Repeat Gradient ===

Converting a [[Convert#Gradient|gradient]] parameter to "Repeat Gradient" adds seven sub-parameters:
* gradient "Gradient"
* integer "Count"
* real "Width"
* bool "Specify Start"
* bool "Specify End"
* color "Start Color"
* color "End Color"

The resulting value is a gradient containing "Count" equally spaced, equally wide copies of gradient "Gradient". Each copy has "Gradient" going forwards and then backwards. "Width" specifies relative width of the forward copy, with a width of 0 or less meaning only the backward copy is used, and a width of 1 or more meaning only the forward copy is used. A value of 0.5 will result in the forward and reverse copies of "Gradient" being the same width.

If "Specify Start" is checked then "Start Color" will be inserted at the beginning of the new gradient, otherwise the beginning of "Gradient" will be used as the beginning of the new gradient.

If "Specify End" is checked then "End Color" will be appended to the end of the new gradient, otherwise the end of "Gradient" will be used as the end of the new gradient.

Here's an example of a repeated gradient - the radiating green/yellow lines are a repeated gradient, applied to a perpendicular curve gradient. This gradient was repeated with a width of 0.5, meaning it is used backwards and forwards the same amount:

[[Image:Repeat-gradient-valuenode-gradient.png]]

and here's the resulting image, along with the .sif file:

[[Image:Repeat-gradient-valuenode.png]]
[[Image:Repeat-gradient-valuenode.sif]]

=== Reverse Tangent ===

Converting a blinepoint parameter to "Reverse Tangent" adds two sub-parameters: one called "Reference" of type BLinePoint, and a boolean parameter called "Reverse".
* BLinePoint "Reference"
* bool "Reverse"

"Reverse Tangent" can only be used on [[Convert#BLinePoint|blinepoints]].

The resulting value is the same as the reference BLinePoint, but with its tangents switched over. This is useful when attempting to link the verticies of a region to the vertices of an outline when the region and the outline were drawn in opposite directions, and so tangent1 of an outline vertex needs to be linked to tangent2 of the region vertex, and vice versa.

=== Scale ===

Converting a parameter to "Scale" adds two sub-parameters: one called "Link", of the same type as the parameter itself, and a real-valued parameter called "Scalar".
* <param> "Link"
* real "Scalar"

"Scale" can be used on [[Convert#Angle|angles]], [[Convert#Color|colors]], [[Convert#Integer|integers]], [[Convert#Real|reals]], [[Convert#Time|times]], and [[Convert#Vector|vectors]].

The resulting value is:
Link * Scalar

=== Segment Tangent ===

Converting a [[Convert#Vector|vector]] parameter to "Segment Tangent" adds two sub-parameters:
* segment "Segment"
* real "Amount"

Amount is a number between 0 and 1, defining the distance along the given segment. The resulting value for the whole parameter is the tangent to the segment, at the given point along the segment.

=== Segment Vertex ===

Converting a [[Convert#Vector|vector]] parameter to "Segment Vertex" adds two sub-parameters:
* segment "Segment"
* real "Amount"

Amount is a number between 0 and 1, defining the distance along the given segment. The resulting value is the vertex at the given point along the segment.

=== Sine ===

Converting a [[Convert#Real|real]]-valued parameter to "Sine" adds two sub-parameters:
* angle "Angle"
* real "Amplitude".

The resulting value is:
Amplitude * sin(Angle)

=== Step ===

Converting an [[Convert#Angle|angle]], [[Convert#Color|color]], [[Convert#Integer|integer]], [[Convert#Real|real]], [[Convert#Time|time]], or [[Convert#Vector|vector]] parameter to be 'Step' adds four sub-parameters:
* <param> "Link"
* time "Duration"
* time "Start Time"
* real "Intersection"

The parameter's value will change in steps. Each step is "Duration" seconds long. The steps start at times "Start Time", "Start Time"+"Duration", etc. The value of the valuenode is the value of "Link" at some time. "Intersection" determines which time is used. An "Intersection" of 0.0 means that the value of "Link" at the start of the step should be used. An "Intersection" of 0.5 (the default) means to use the value of "Link" at the middle of the step, etc.

The resulting value at time <math>T</math> is:
<math>Link \Bigg ( \Bigg ( Duration \cdot \left ( \left \lfloor \frac{T - Start\ Time}{Duration} \right \rfloor + Intersection \right ) \Bigg ) + Start \ Time \Bigg )</math>

==== Example ====

"Link" is a sine wave. "Duration" is 10f (the frame rate is 24 fps). "Start Time" is 1s.

So one step starts at 1s, and others start at 0s 14f, 0s 4f, 1s 10f, etc.

This is the sine wave:

[[Image:Smooth-sine.png]]

And this is the effect of the Step valuenode on it, with an "Intersection" of 0.0. Notice that at time 0s, the step has a negative value -- that step runs from -6f to 4f, and so its value is the value of Link at time -6f. ''These images were created in [http://www.gimp.org/ The Gimp] - it's not currently possible to view two curves at the same time in Synfig Studio.''

[[Image:Stepped-sine-0.0.png]]

Here it is with an "Intersection" of 0.5:

[[Image:Stepped-sine-0.5.png]]

and here, with an "Intersection" of 1.0:

[[Image:Stepped-sine-1.0.png]]

=== Stripes ===

Converting a [[Convert#Gradient|gradient]] parameter to "Stripes" adds four sub-parameters:
* color "Color 1"
* color "Color 2"
* integer "Stripe Count"
* real "Width"

The resulting value is a gradient containing "Stripe Count" equally spaced, equally wide stripes of color "Color 2" with a background of "Color 1". "Width" specifies the width of the stripes, with a width of 0 or less meaning they are invisible, and a width of 1 or more meaning the whole gradient is of "Color 2".

=== Subtract ===

Converting a parameter to "Subtract" adds three sub-parameters, the first two of which are the same type as the parameter itself:
* <param> "LHS"
* <param> "RHS"
* real "Scalar"

The "Subtract" conversion can be used with parameters of type [[Convert#Angle|angle]], [[Convert#Color|color]], [[Convert#Gradient|gradient]], [[Convert#Integer|integer]], [[Convert#Real|real]], [[Convert#Time|time]], and [[Convert#Vector|vector]].

The resulting value is:
(LHS - RHS) * Scalar

=== Switch ===

Converting a parameter to "Switch" adds three sub-parameters:
* <param> "Link Off"
* <param> "Link On"
* bool "Switch"

"Link Off" and "Link On" are the same type as the parameter being converted.

The resulting value is the value of "Link Off" when "Switch" is off, and "Link On" when "Switch" is on.

This conversion can be used on all value types.

=== Time Loop ===

Converting a parameter to "Time Loop" adds four sub-parameters: one called "Link", of the same type as the parameter itself, and three time parameters:

* <param> "Link"
* time "Link Time"
* time "Local Time"
* time "Duration"

It works similarly to the [[Time Loop Layer]] but affects only a single parameter.

For any integer value n, from "Local Time + abs(Duration)*n" to "Local Time + abs(Duration)*(n+1)", the resulting value of the parameter is the same as that of the "Link" parameter from "Link Time" to "Link Time + Duration".

In other words, "Duration" seconds of values of the parameter "Link" starting from time "Link Time" onwards are looped over and over, with the value of the "Link"ed parameter at time "Link Time" corresponding to the resulting value at time "Local Time".

As an example, suppose the "Link" parameter has a value of time the current time. At 0s the value is 0, at 10s the value is 20.

If we set:
* Link Time = 5s
* Local Time = 2s
* Duration = 4s
then from 2s to 6s and from 6s to 10s, etc., the resulting value is the value of "Link" from 5s to 9s, as follows:

Then the resulting values will be:
* 0s -> "Link" value at 7s = 14
* 1s -> "Link" value at 8s = 16
* 2s -> "Link" value at 5s = 10 (at "Link Time" = 2s, result is the value of "Link" at "Link Time" = 5s = 10)
* 3s -> "Link" value at 6s = 12
* 4s -> "Link" value at 7s = 14
* 5s -> "Link" value at 8s = 16
* 6s -> "Link" value at 5s = 10 ("Duration" = 4s later, the value is the same as at 2s)
* 7s -> "Link" value at 6s = 12

If "Duration" is zero, the resulting value is whatever the value of the "Link" parameter is at time "Link Time".

If "Duration" is negative, the resulting value at "Local Time" still matches the value of "Link" at "Link Time", but the animation goes in the opposite direction. For example:

If we set:
* Link Time = 5s
* Local Time = 2s
* Duration = -4s
then from 2s to 6s and from 6s to 10s, etc., the resulting value is the value of "Link" from 5s to 1s, as follows:

Then the resulting values will be:
* 0s -> "Link" value at 3s = 6
* 1s -> "Link" value at 2s = 4
* 2s -> "Link" value at 5s = 10 (at "Link Time" = 2s, result is the value of "Link" at "Link Time" = 5s = 10)
* 3s -> "Link" value at 4s = 8
* 4s -> "Link" value at 3s = 6
* 5s -> "Link" value at 2s = 4
* 6s -> "Link" value at 5s = 10 (4s later, the value is the same as at "Link Time" = 2s)
* 7s -> "Link" value at 4s = 8

This conversion can be used on all value types.

=== Time String ===

Converting a [[Convert#String|string]] parameter to "Time String" adds one sub-parameter called "Time", of type time:

* time "Time"

The result is a string containing the given time.

=== Timed Swap ===

This convert type was disabled in Synfig 0.61.06 and earlier because it didn't work.

Converting a parameter to "Timed Swap" adds four sub-parameters:
* <param> "Before"
* <param> "After"
* time "Swap Time"
* time "Swap Duration"

"Before" and "After" are the same type as the parameter being converted.

This conversion type linearly switches from "Before" to "After", taking "Swap Duration" seconds to do so, and completing the swap at "Swap Time".

Note that this doesn't give us anything that we can't achieve using the "[[Convert#Linear|Linear]]" conversion type and a few waypoints.

"Timed Swap" can be used on [[Convert#Angle|angles]], [[Convert#Color|colors]], [[Convert#Integer|integers]], [[Convert#Real|reals]], [[Convert#Time|times]], and [[Convert#Vector|vectors]].

The resulting value is:
if time > "Swap Time" then "After"
else if time < ("Swap Time" - "Swap Duration") then "Before"
else interpolate between "Before" and "After"

=== Two-Tone ===

Converting a [[Convert#Gradient|gradient]] to "Two-Tone" adds two color-valued sub-parameters:
* color "Color1"
* color "Color2"

The resulting gradient has two CPoints, one at each end, starting with "Color1" and ending with "Color2".

These color parameters can be animated, giving us the ability to have the gradient change color over time. This can be used as a workaround for [http://sourceforge.net/tracker/index.php?func=detail&aid=1568818&group_id=144022&atid=757416 this bug].

=== Vector Angle ===

Converting an [[Convert#Angle|angle]] to "Vector Angle" adds a vector sub-parameter:
* vector "Vector"

The resulting value is the angle between the vector and the X axis.

=== Vector Length ===

Converting a [[Convert#Real|real]] to "Vector Length" adds a vector sub-parameter:
* vector "Vector"

The resulting value is the length of the vector.

=== Vector X ===

Converting a [[Convert#Real|real]] to "Vector X" adds a vector sub-parameter:
* vector "Vector"

The resulting value is the X component of the vector.

=== Vector Y ===

Converting a [[Convert#Real|real]] to "Vector Y" adds a vector sub-parameter:
* vector "Vector"

The resulting value is the Y component of the vector.

== Which Value Types can use which Convert Types? ==

There are 13 different types of value in Synfig. Each of these types has a different set of convert types available to it, as follows:

=== Angle ===

[[Image:angle_icon.png|32px]]

* Angle parameters can be converted to [[Convert#Add|Add]], [[Convert#aTan2|aTan2]], [[Convert#BLine Tangent|BLine Tangent]], [[Convert#Dot Product|Dot Product]], [[Convert#Linear|Linear]], [[Convert#Random|Random]], [[Convert#Range|Range]], [[Convert#Scale|Scale]], [[Convert#Step|Step]], [[Convert#Subtract|Subtract]], [[Convert#Switch|Switch]], [[Convert#Time Loop|Time Loop]], [[Convert#Timed Swap|Timed Swap]], [[Convert#Vector Angle|Vector Angle]], and [[Convert#Reference|Reference]] types.

=== BLinePoint ===
[[Image:blinepoint_icon.png|32px]]

* BLinePoint parameters can be converted to [[Convert#Composite|Composite]], [[Convert#Reverse Tangent|Reverse Tangent]], [[Convert#Switch|Switch]], [[Convert#Time Loop|Time Loop]], and [[Convert#Reference|Reference]] types.

=== Bool ===
[[Image:bool_icon.png|32px]]

* Bool parameters can only be converted to the [[Convert#Switch|Switch]], [[Convert#Time Loop|Time Loop]], and [[Convert#Reference|Reference]] types.

=== Canvas ===
[[Image:canvas_pointer_icon.png|32px]]

* Canvas parameters can be converted to the [[Convert#Switch|Switch]], [[Convert#Time Loop|Time Loop]], and [[Convert#Reference|Reference]] type.

=== Color ===
[[Image:color_icon.png|32px]]
* Color parameters can be converted to [[Convert#Add|Add]], [[Convert#Composite|Composite]], [[Convert#Gradient Color|Gradient Color]], [[Convert#Linear|Linear]], [[Convert#Radial Composite|Radial Composite]], [[Convert#Random|Random]], [[Convert#Scale|Scale]], [[Convert#Step|Step]], [[Convert#Subtract|Subtract]], [[Convert#Switch|Switch]], [[Convert#Time Loop|Time Loop]], [[Convert#Timed Swap|Timed Swap]], and [[Convert#Reference|Reference]] types.

=== Gradient ===
[[Image:gradient_icon.png|32px]]

* Gradient parameters can be converted to [[Convert#Add|Add]], [[Convert#Gradient Rotate|Gradient Rotate]], [[Convert#Repeat Gradient|Repeat Gradient]], [[Convert#Stripes|Stripes]], [[Convert#Subtract|Subtract]], [[Convert#Switch|Switch]], [[Convert#Time Loop|Time Loop]], [[Convert#Two-Tone|Two-Tone]], and [[Convert#Reference|Reference]] types.

=== Integer ===
[[Image:Integer_icon.png|32px]]
* Integer parameters can be converted to [[Convert#Add|Add]], [[Convert#Linear|Linear]], [[Convert#Random|Random]], [[Convert#Range|Range]], [[Convert#Scale|Scale]], [[Convert#Step|Step]], [[Convert#Subtract|Subtract]], [[Convert#Switch|Switch]], [[Convert#Time Loop|Time Loop]], [[Convert#Timed Swap|Timed Swap]], and [[Convert#Reference|Reference]] types.

=== List ===
[[Image:list_icon.png|32px]]
* List parameters can be converted to [[Convert#BLine|BLine]], [[Convert#Dynamic List|Dynamic List]], [[Convert#Switch|Switch]], [[Convert#Time Loop|Time Loop]], and [[Convert#Reference|Reference]] types.

=== Real ===
[[Image:real_icon.png|32px]]
* Real parameters can be converted to [[Convert#Add|Add]], [[Convert#BLine Width|BLine Width]], [[Convert#Cos|Cos]], [[Convert#Dot Product|Dot Product]], [[Convert#Exponential|Exponential]], [[Convert#Linear|Linear]], [[Convert#Logarithm|Logarithm]], [[Convert#Random|Random]], [[Convert#Range|Range]], [[Convert#Reciprocal|Reciprocal]], [[Convert#Scale|Scale]], [[Convert#Sine|Sine]], [[Convert#Step|Step]], [[Convert#Subtract|Subtract]], [[Convert#Switch|Switch]], [[Convert#Time Loop|Time Loop]], [[Convert#Timed Swap|Timed Swap]], [[Convert#Vector Length|Vector Length]], [[Convert#Vector X|Vector X]], [[Convert#Vector Y|Vector Y]], and [[Convert#Reference|Reference]] types.

=== Segment ===
[[Image:segment_icon.png|32px]]
* Segment parameters can be converted to the [[Convert#Composite|Composite]], [[Convert#Switch|Switch]], [[Convert#Time Loop|Time Loop]], and [[Convert#Reference|Reference]] types.

=== String ===
[[Image:string_icon.png|32px]]
* String parameters can be converted to the [[Convert#Angle String|Angle String]], [[Convert#Int String|Int String]], [[Convert#Joined List|Joined List]], [[Convert#Real String|Real String]], [[Convert#Switch|Switch]], [[Convert#Time Loop|Time Loop]], [[Convert#Time String|Time String]], and [[Convert#Reference|Reference]] types.

=== Time ===
[[Image:time_icon.png|32px]]
* Time parameters can be converted to the [[Convert#Add|Add]], [[Convert#Linear|Linear]], [[Convert#Random|Random]], [[Convert#Range|Range]], [[Convert#Scale|Scale]], [[Convert#Step|Step]], [[Convert#Subtract|Subtract]], [[Convert#Switch|Switch]], [[Convert#Time Loop|Time Loop]], [[Convert#Timed Swap|Timed Swap]], and [[Convert#Reference|Reference]] types.

=== Vector ===
[[Image:vector_icon.png|32px]]
* Vector parameters can be converted to [[Convert#Add|Add]], [[Convert#BLine Tangent|BLine Tangent]], [[Convert#BLine Vertex|BLine Vertex]], [[Convert#Composite|Composite]], [[Convert#Linear|Linear]], [[Convert#Radial Composite|Radial Composite]], [[Convert#Random|Random]], [[Convert#Scale|Scale]], [[Convert#Segment Tangent|Segment Tangent]], [[Convert#Segment Vertex|Segment Vertex]], [[Convert#Step|Step]], [[Convert#Subtract|Subtract]], [[Convert#Switch|Switch]], [[Convert#Time Loop|Time Loop]], [[Convert#Timed Swap|Timed Swap]], and [[Convert#Reference|Reference]] types.

== Compatibility ==

When a new ValueNode type is added to Synfig, the .sif file format is extended to include a way of writing the new type. This extension won't be able to be read by any older version of Synfig. Here's a list of the ValueNode types that have been added, along with the subversion revision number in which they first appeared:

<blockquote>
{| style="width:55%"
| '''Version''' || '''Revision''' || '''Convert'''
|-
| <hr> || <hr> || <hr>
|-
| '''(0.61.09)''' || not yet released ||  
|-
|   || 2034 || [[#Logarithm|Logarithm]]
|-
|   || 2010 || [[#Int String|Int String]]
|-
|   || 2010 || [[#Angle String|Angle String]]
|-
|   || 2007 || [[#Joined List|Joined List]]
|-
|   || 2003 || [[#Real String|Real String]]
|-
|   || 2000 || [[#Time String|Time String]]
|-
|   || 1891 || [[#Dot Product|Dot Product]]
|-
|   || 1885 || [[#Gradient Color|Gradient Color]]
|-
|   || 1882 || [[#Vector X|Vector X]]
|-
|   || 1882 || [[#Vector Y|Vector Y]]
|-
|   || 1881 || [[#Vector Length|Vector Length]]
|-
|   || 1880 || [[#Vector Angle|Vector Angle]]
|-
| <hr> || <hr> || <hr>
|-
| '''(0.61.08)''' || 1839 ||  
|-
|   || 1694 || [[#BLine Width|BLine Width]]
|-
|   || 1690 || [[#Random|Random]] (for bools)
|-
|   || 1691 || [[#Step|Step]]
|-
|   || 1354 || [[#Subtract|Subtract]] (for gradients)
|-
|   || 1354 || [[#Add|Add]] (for gradients)
|-
|   || 1267 || [[#From Integer|From Integer]]
|-
|   || 1267 || [[#Duplicate|Duplicate]]
|-
|   || 1238 || [[#Reciprocal|Reciprocal]]
|-
|   || 1226 || [[#Time Loop|Time Loop]]
|-
|   || 1162 || [[#Reverse Tangent|Reverse Tangent]]
|-
|   || 1132 || [[#aTan2|aTan2]]
|-
|   || 1111 || [[#Cos|Cos]]
|-
|   || 923 || [[#Switch|Switch]]
|-
|   || 907 || [[#Random|Random]]
|-
| <hr> || <hr> || <hr>
|-
| '''(0.61.07)''' || 878 ||  
|-
|   || 776 || [[#Range|Range]]
|-
|   || 744 || [[#BLine Vertex|BLine Vertex]]
|-
|   || 744 || [[#BLine Tangent|BLine Tangent]]
|-
|   || 742 || [[#Add|Add]]
|-
|   || 739 || [[#Exponential|Exponential]]
|-
|   || 666 || [[#Repeat Gradient|Repeat Gradient]]
|-
|   || 610 || [[#Timed Swap|Timed Swap]]
|-
| <hr> || <hr> || <hr>
|-
| '''(0.61.06)''' || 536 ||  
|-|}
</blockquote>

Convert

2008-12-18T22:14:38Z

Dooglus: /* Random */ add 'loop' param

Right-clicking on a value in the Parameters dialog brings up a context menu which has a sub-menu called "Convert". The "Convert" menu allows you to specify that the parameter should be controlled automatically in various ways. Depending on the type of the parameter the Convert menu will contain different options.

To convert the value back to its original type, select "Disconnect" from its context menu.

== Convert Types ==

=== Add ===

Converting a parameter to "Add" adds three sub-parameters, the first two of which are the same type as the parameter itself:
* <param> "LHS"
* <param> "RHS"
* real "Scalar"

The "Add" conversion can be used with parameters of type [[Convert#Angle|angle]], [[Convert#Color|color]], [[Convert#Gradient|gradient]], [[Convert#Integer|integer]], [[Convert#Real|real]], [[Convert#Time|time]], and [[Convert#Vector|vector]].

The resulting value is:
(LHS + RHS) * Scalar

=== Angle String ===

Converting an [[Convert#String|string]]-valued parameter to "Angle String" adds four sub-parameters:
* angle "Angle"
* integer "Width"
* integer "Precision"
* bool "Zero Padded"

The resulting value a string containing the value of "Angle" (in degrees) formatted as a string with a minimum width "Width", with "Precision" decimal places. If "Zero Padded" is true, it will be left-padded with "0" characters.

=== aTan2 ===

Converting an [[Convert#Angle|angle]]-valued parameter to "aTan2" adds two sub-parameters:
* real "X"
* real "Y".

The resulting value is:
atan2(y,x)

ie. atan(y/x) but without an error when x is 0. The value is the angle between the x axis and the vector (x,y).

=== BLine ===

Converting a [[Convert#List|list]] parameter to "BLine" doesn't seem to change anything. Perhaps that's the default type for lists of vertices, such as are found in outlines and regions?

=== BLine Tangent ===

Converting a [[Convert#Angle|angle]], [[Convert#Real|real]] (since SVN r1862), or [[Convert#Vector|vector]] parameter to "BLine Tangent" adds six sub-parameters:
* bline "BLine"
* bool "Loop"
* real "Amount"
* angle "Offset" (since SVN r1863)
* real "Scale" (since SVN r1863)
* bool "Fixed Length" (since SVN r1863)

Amount is a number between 0 and 1, defining the distance along the given bline. The resulting value for the whole parameter is the tangent to the bline, at the given point along the bline, optionally rotated and scaled according to the "Offset", "Scale", and "Fixed Length" parameters.

"Offset" is an angle used to give the tangent an extra rotation before returning it. If "Fixed Length" is true, the tangent is then scaled to have a length equal to "Scale". Otherwise the tangent is multiplied by "Scale".

If a vector was converted the result is the tangent itself. If an angle was converted, the result is the angle of the tangent to the horizontal, and if a real was converted, the result is the length of the tangent.

This [[Following a BLine|tutorial]] gives an example of the use of this convert type.

=== BLine Vertex ===

Converting a [[Convert#Vector|vector]] parameter to "BLine Vertex" adds three sub-parameters:
* bline "BLine"
* bool "Loop"
* real "Amount"

Amount is a number between 0 and 1, defining the distance along the given bline. The resulting value for the whole parameter is a vector giving the position of the given point along the bline.

This [[Following a BLine|tutorial]] gives an example of the use of this convert type.

=== BLine Width ===

Converting a [[Convert#Real|real]] parameter to "BLine Width" adds three sub-parameters:
* bline "BLine"
* bool "Loop"
* real "Amount"
* real "Scale" (since SVN r1872)

Amount is a number between 0 and 1, defining the distance along the given bline. The resulting value for the whole parameter is the width of the bline at the given point along it, multiplied by the "Scale" parameter.

=== Composite ===

Converting a [[Convert#BLinePoint|blinepoint]] parameter to "Composite" adds six sub-parameters:
* vector "Vertex"
* real "Width"
* real "Origin"
* bool "Split Tangents"
* vector "Tangent 1"
* vector "Tangent 2"

Converting a [[Convert#Color|color]] parameter to "Composite" adds four real-valued sub-parameters:
* real "Red"
* real "Green"
* real "Blue"
* real "Alpha"

Converting a [[Convert#Segment|segment]] parameter to "Composite" adds four vertex sub-parameters:
* vertex "Vertex 1"
* vertex "Tangent 1"
* vertex "Vertex 2"
* vertex "Tangent 2"

Converting a [[Convert#Vector|vector]] parameter to "Composite" adds two real-valued sub-parameters:
* real "X-Axis"
* real "Y-Axis"

The resulting value is a blinepoint, color, segment, or vector made by combining the component parts.

=== Cos ===

Converting a [[Convert#Real|real]]-valued parameter to "Cos" adds two sub-parameters:
* angle "Angle"
* real "Amplitude".

The resulting value is:
Amplitude * cos(Angle)

=== Dot Product ===

Converting a [[Convert#Real|real]] or [[Convert#Angle|angle]] parameter to a "Dot Product" adds two sub-parameters:
* vector "LHS"
* vector "RHS"

If the converted value is an angle, the return value is the angle between the two vectors:

return = acos((LHS · RHS) / (|LHS| * |RHS|))

If the converted value is a real, the result value is the dot product of the two vectors:

return = LHS · RHS = |LHS| * |RHS| * cos(alpha)

(where alpha is the angle between LHS and RHS).

=== Duplicate ===

This ValueNode type is only used by the [[Duplicate Layer]]. It never appears in the Convert menu. It is used to control the range of the Index in the Duplicate Layer (q.v.).

The "Duplicate" ValueNode type has 3 real-valued sub-parameters:

* real "From"
* real "To"
* real "Step"

The value of the ValueNode varies from the value of "From" to the value of "To" in steps of size "Step". The sign of "Step" is ignored. If From<To the steps are positive, else they're negative.

=== Dynamic List ===

Converting a [[Convert#List|list]] parameter to "Dynamic List" seems to replace each of the "Vertex NNN" sub-parameters with "Item NNN" parameters which can't be expanded, but can be exported.

=== Exponential ===

Converting a [[Convert#Real|real]] parameter to "Exponential" adds two sub-parameters:

* real "Exponent"
* real "Scale"

The resulting value is the result raising the [http://en.wikipedia.org/wiki/E_%28mathematical_constant%29 mathematical constant 'e'] to the power of Exponent, and scaling the result by Scale. That is, it returns:
Scale * e^Exponent

This is useful for tracking layers which have been zoomed, since the Zoom layer scales by e^(zoom factor).

See [http://youtube.com/watch?v=GAWtndOHkUw this video] for an example of the use of this convert type.

=== From Integer ===

This is currently disabled. It converts an integer to one of several types.

=== Gradient Color ===

Converting a [[Convert#Color|color]] parameter to "Gradient Color" adds two sub-parameters:

* gradient "Gradient"
* real "Index"

The resulting value is a color taken from the gradient at the given index position. Index 0 corresponds to the left of the gradient; index 1 corresponds to the right of the gradient.

=== Gradient Rotate ===

Converting a [[Convert#Gradient|gradient]] parameter to "Gradient Rotate" adds two sub-parameters:

* gradient "Gradient"
* real "Offset"

The resulting value is a gradient based on the "Gradient" parameter, but shifted left (for negative values) or right, according to the value of the "Offset" parameter. An offset of 1.0 will shift the gradient by its entire visible width. Values shifted off the left or right edge aren't lost - they aren't visible in the gradient as it's displayed in the parameters dialog, but they will still be used when rendering (depending on parameters such as 'Loop' and 'Zigzag', which can cause gradients to be looped between their their left and right edges, rather than using the non-displayed parts).

=== Int String ===

Converting an [[Convert#String|string]]-valued parameter to "Int String" adds three sub-parameters:
* integer "Int"
* integer "Width"
* bool "Zero Padded"

The resulting value a string containing "Int" formatted as a string with a minimum width "Width". If "Zero Padded" is true, it will be left-padded with "0" characters.

=== Joined List ===

Converting a [[Convert#String|string]] parameter to be 'Joined List' adds four sub-parameters:
* list "Strings"
* string "Before"
* string "Separator"
* string "After"

The result is a string containing the value of "Before", followed by all the strings in the "Strings" list, with the value of "Separator" between each pair, followed by the value of "After".

=== Linear ===

Converting an [[Convert#Angle|angle]] parameter to be 'Linear' adds two angle sub-parameters:
* angle "Rate"
* angle "Offset"

Converting a [[Convert#Color|color]] parameter to be 'Linear' adds two angle sub-parameters (since svn r617):
* color "Rate"
* color "Offset"

Converting an [[Convert#Integer|integer]] parameter to be 'Linear' adds two angle sub-parameters (since svn r617):
* integer "Rate"
* integer "Offset"

Converting a [[Convert#Real|real]] parameter to be 'Linear' adds two real-valued sub-parameters:
* real "Rate"
* real "Offset"

Converting a [[Convert#Time|time]] parameter to be 'Linear' adds two time sub-parameters:
* time "Rate"
* time "Offset"

Converting a [[Convert#Vector|vector]] parameter to be 'Linear' adds two vector sub-parameters:
* vector "Slope"
* vector "Offset"

The parameter's value will change linearly over time, starting with the value specified by "Offset" at time zero, and increasing by the value specified by "Rate" (or "Slope", in the case of vector parameters) every second.

The resulting value for vector parameters is:
Offset + Slope*time

and for the other 5 types of parameter it is:
Offset + Rate*time

=== Logarithm ===

Converting a [[Convert#Real|real]]-valued parameter to "Logarithm" adds three sub-parameters:

* real "Link"
* real "Epsilon".
* real "Infinite".

The resulting value is:

Log(Link) (if Link >= Epsilon)
-Infinite (if Link < Epsilon)

The epsilon and infinite parameters are only needed to prevent logarithm of negative or zero numbers. For regular operation the resulting value is simply the natural logarithm of Link. In fact a logarithm of a negative number cannot be calculated in the space of Real numbers. This convert type returns -Infinite for simplicity.

=== Radial Composite ===

Converting a [[Convert#Color|color]] to "Radial Composite" adds four sub-parameters:
* real "Luma"
* real "Saturation"
* angle "Hue"
* real "Alpha"

Converting a [[Convert#Vector|vector]] to "Radial Composite" adds two sub-parameters:
* real "Radius"
* angle "Theta"

For color parameters, the resulting value is the color with the given lima, saturation, hue, and alpha amounts.

For vector parameters, the resulting value is the point reached by traveling a distance "Radius" from the origin, in the distance given by the angle "Theta".

=== Random ===

Converting a parameter to "Random" adds five sub-parameters, the first of which is the same type as the converted parameter:

* <param> "Link"
* real "Radius"
* integer "Seed"
* real "Animation Speed"
* integer "Interpolation"
* real "Loop Time" (since SVN r2315)

"Random" can be used on [[Convert#Angle|angles]], [[Convert#Color|colors]], [[Convert#Integer|integers]], [[Convert#Real|reals]], [[Convert#Time|times]], and [[Convert#Vector|vectors]].

It is used to cause a parameter's value to vary randomly over time, around a central value:

* "Link" provides the central value.
* "Radius" defines the maximum random difference.
* "Seed" seeds the random number generator
* "Animation Speed" defines how often a new random value is chosen (in choices per second)
* "Interpolation" determines how the value is interpolated from one random choice to the next. Possible values are:
** 0 - no interpolation; the value jumps from one value to the next
** 1 - linear interpolation
** 2 - cosine
** 3 - spline
** 4 - cubic (the default); uses [http://www.gamedev.net/reference/articles/article1497.asp Catmull-Rom] spline interpolation
* "Loop Time" (adding in SVN r2315) makes the random value repeat after the given time. The value ends up the same at the given time as at time=0 so it's possible to make random looping animations without a nasty jump when the time wraps back to zero.

The "Interpolation" sub-parameter should really be a drop-down menu, rather than an integer field, but that isn't yet implemented.

=== Range ===

Converting a parameter to "Range" adds three sub-parameters, all the same type as the parameter itself:
* <param> "Min"
* <param> "Max"
* <param> "Link"

"Range" can be used on [[Convert#Angle|angles]], [[Convert#Integer|integers]], [[Convert#Real|reals]], and [[Convert#Time|times]].

It is used to limit the value of the linked parameter to be between Min and Max.

The resulting value is:
Min (if Link < Min)
Max (if Link > Max)
Link (otherwise)

=== Real String ===

Converting a [[Convert#String|string]] parameter to "Real String" adds four sub-parameters:

* real "Real"
* int "Width"
* int "Precision"
* bool "Zero Padded"

The result is a string formatted to contain the given value "Real". "Width" specifies the minimum field width, "Precision" specifies the number of decimal places and "Zero Padded" specifies whether to pad with zeros on the left hand side.

For example, with Real=3.1415, Width=6, Precision=2, and ZeroPadded=true, we get:
"003.14"
(6 characters long, 2 decimal places, and padded with zeros on the left).

=== Reciprocal ===

Converting a [[Convert#Real|real]]-valued parameter to "Reciprocal" adds three sub-parameters:
* real "Link"
* real "Epsilon".
* real "Infinite".

The resulting value is:
1/Link (Link <= -epsilon or epsilon <= Link)
Infinite (if 0 <= Link < epsilon)
-Infinite (if -epsilon < Link < 0)

The epsilon and infinite parameters are only needed to prevent division by zero. For regular operation the resulting value is simply the reciprocal of Link.

=== Reference ===

Converting a parameter to "Reference" adds a single sub-parameter called "Link". The "Link" parameter is the same type as the parameter being converted.

It doesn't seem to do anything at all, other than adding an extra parameter. Whatever value is put into "Link" becomes the value of the parameter being converted.

The only use for this conversion type I can think of is the following:

* you know that point A should follow point B, so you export point B and connect point A to it
* you're not yet sure exactly how point B should move, so you experiment with different conversion types for point B
* changing the conversion type for point B breaks the connection you made in the first step
* converting point B to be a reference, and then experimenting with different conversions in its "Link" parameter allows point A to connect to point B and for the connection to remain in place while you experiment in the "Link" parameter

The resulting value is:
Link

=== Repeat Gradient ===

Converting a [[Convert#Gradient|gradient]] parameter to "Repeat Gradient" adds seven sub-parameters:
* gradient "Gradient"
* integer "Count"
* real "Width"
* bool "Specify Start"
* bool "Specify End"
* color "Start Color"
* color "End Color"

The resulting value is a gradient containing "Count" equally spaced, equally wide copies of gradient "Gradient". Each copy has "Gradient" going forwards and then backwards. "Width" specifies relative width of the forward copy, with a width of 0 or less meaning only the backward copy is used, and a width of 1 or more meaning only the forward copy is used. A value of 0.5 will result in the forward and reverse copies of "Gradient" being the same width.

If "Specify Start" is checked then "Start Color" will be inserted at the beginning of the new gradient, otherwise the beginning of "Gradient" will be used as the beginning of the new gradient.

If "Specify End" is checked then "End Color" will be appended to the end of the new gradient, otherwise the end of "Gradient" will be used as the end of the new gradient.

Here's an example of a repeated gradient - the radiating green/yellow lines are a repeated gradient, applied to a perpendicular curve gradient. This gradient was repeated with a width of 0.5, meaning it is used backwards and forwards the same amount:

[[Image:Repeat-gradient-valuenode-gradient.png]]

and here's the resulting image, along with the .sif file:

[[Image:Repeat-gradient-valuenode.png]]
[[Image:Repeat-gradient-valuenode.sif]]

=== Reverse Tangent ===

Converting a blinepoint parameter to "Reverse Tangent" adds two sub-parameters: one called "Reference" of type BLinePoint, and a boolean parameter called "Reverse".
* BLinePoint "Reference"
* bool "Reverse"

"Reverse Tangent" can only be used on [[Convert#BLinePoint|blinepoints]].

The resulting value is the same as the reference BLinePoint, but with its tangents switched over. This is useful when attempting to link the verticies of a region to the vertices of an outline when the region and the outline were drawn in opposite directions, and so tangent1 of an outline vertex needs to be linked to tangent2 of the region vertex, and vice versa.

=== Scale ===

Converting a parameter to "Scale" adds two sub-parameters: one called "Link", of the same type as the parameter itself, and a real-valued parameter called "Scalar".
* <param> "Link"
* real "Scalar"

"Scale" can be used on [[Convert#Angle|angles]], [[Convert#Color|colors]], [[Convert#Integer|integers]], [[Convert#Real|reals]], [[Convert#Time|times]], and [[Convert#Vector|vectors]].

The resulting value is:
Link * Scalar

=== Segment Tangent ===

Converting a [[Convert#Vector|vector]] parameter to "Segment Tangent" adds two sub-parameters:
* segment "Segment"
* real "Amount"

Amount is a number between 0 and 1, defining the distance along the given segment. The resulting value for the whole parameter is the tangent to the segment, at the given point along the segment.

=== Segment Vertex ===

Converting a [[Convert#Vector|vector]] parameter to "Segment Vertex" adds two sub-parameters:
* segment "Segment"
* real "Amount"

Amount is a number between 0 and 1, defining the distance along the given segment. The resulting value is the vertex at the given point along the segment.

=== Sine ===

Converting a [[Convert#Real|real]]-valued parameter to "Sine" adds two sub-parameters:
* angle "Angle"
* real "Amplitude".

The resulting value is:
Amplitude * sin(Angle)

=== Step ===

Converting an [[Convert#Angle|angle]], [[Convert#Color|color]], [[Convert#Integer|integer]], [[Convert#Real|real]], [[Convert#Time|time]], or [[Convert#Vector|vector]] parameter to be 'Step' adds four sub-parameters:
* <param> "Link"
* time "Duration"
* time "Start Time"
* real "Intersection"

The parameter's value will change in steps. Each step is "Duration" seconds long. The steps start at times "Start Time", "Start Time"+"Duration", etc. The value of the valuenode is the value of "Link" at some time. "Intersection" determines which time is used. An "Intersection" of 0.0 means that the value of "Link" at the start of the step should be used. An "Intersection" of 0.5 (the default) means to use the value of "Link" at the middle of the step, etc.

The resulting value at time <math>T</math> is:
<math>Link \Bigg ( \Bigg ( Duration \cdot \left ( \left \lfloor \frac{T - Start\ Time}{Duration} \right \rfloor + Intersection \right ) \Bigg ) + Start \ Time \Bigg )</math>

==== Example ====

"Link" is a sine wave. "Duration" is 10f (the frame rate is 24 fps). "Start Time" is 1s.

So one step starts at 1s, and others start at 0s 14f, 0s 4f, 1s 10f, etc.

This is the sine wave:

[[Image:Smooth-sine.png]]

And this is the effect of the Step valuenode on it, with an "Intersection" of 0.0. Notice that at time 0s, the step has a negative value -- that step runs from -6f to 4f, and so its value is the value of Link at time -6f. ''These images were created in [http://www.gimp.org/ The Gimp] - it's not currently possible to view two curves at the same time in Synfig Studio.''

[[Image:Stepped-sine-0.0.png]]

Here it is with an "Intersection" of 0.5:

[[Image:Stepped-sine-0.5.png]]

and here, with an "Intersection" of 1.0:

[[Image:Stepped-sine-1.0.png]]

=== Stripes ===

Converting a [[Convert#Gradient|gradient]] parameter to "Stripes" adds four sub-parameters:
* color "Color 1"
* color "Color 2"
* integer "Stripe Count"
* real "Width"

The resulting value is a gradient containing "Stripe Count" equally spaced, equally wide stripes of color "Color 2" with a background of "Color 1". "Width" specifies the width of the stripes, with a width of 0 or less meaning they are invisible, and a width of 1 or more meaning the whole gradient is of "Color 2".

=== Subtract ===

Converting a parameter to "Subtract" adds three sub-parameters, the first two of which are the same type as the parameter itself:
* <param> "LHS"
* <param> "RHS"
* real "Scalar"

The "Subtract" conversion can be used with parameters of type [[Convert#Angle|angle]], [[Convert#Color|color]], [[Convert#Gradient|gradient]], [[Convert#Integer|integer]], [[Convert#Real|real]], [[Convert#Time|time]], and [[Convert#Vector|vector]].

The resulting value is:
(LHS - RHS) * Scalar

=== Switch ===

Converting a parameter to "Switch" adds three sub-parameters:
* <param> "Link Off"
* <param> "Link On"
* bool "Switch"

"Link Off" and "Link On" are the same type as the parameter being converted.

The resulting value is the value of "Link Off" when "Switch" is off, and "Link On" when "Switch" is on.

This conversion can be used on all value types.

=== Time Loop ===

Converting a parameter to "Time Loop" adds four sub-parameters: one called "Link", of the same type as the parameter itself, and three time parameters:

* <param> "Link"
* time "Link Time"
* time "Local Time"
* time "Duration"

It works similarly to the [[Time Loop Layer]] but affects only a single parameter.

For any integer value n, from "Local Time + abs(Duration)*n" to "Local Time + abs(Duration)*(n+1)", the resulting value of the parameter is the same as that of the "Link" parameter from "Link Time" to "Link Time + Duration".

In other words, "Duration" seconds of values of the parameter "Link" starting from time "Link Time" onwards are looped over and over, with the value of the "Link"ed parameter at time "Link Time" corresponding to the resulting value at time "Local Time".

As an example, suppose the "Link" parameter has a value of time the current time. At 0s the value is 0, at 10s the value is 20.

If we set:
* Link Time = 5s
* Local Time = 2s
* Duration = 4s
then from 2s to 6s and from 6s to 10s, etc., the resulting value is the value of "Link" from 5s to 9s, as follows:

Then the resulting values will be:
* 0s -> "Link" value at 7s = 14
* 1s -> "Link" value at 8s = 16
* 2s -> "Link" value at 5s = 10 (at "Link Time" = 2s, result is the value of "Link" at "Link Time" = 5s = 10)
* 3s -> "Link" value at 6s = 12
* 4s -> "Link" value at 7s = 14
* 5s -> "Link" value at 8s = 16
* 6s -> "Link" value at 5s = 10 ("Duration" = 4s later, the value is the same as at 2s)
* 7s -> "Link" value at 6s = 12

If "Duration" is zero, the resulting value is whatever the value of the "Link" parameter is at time "Link Time".

If "Duration" is negative, the resulting value at "Local Time" still matches the value of "Link" at "Link Time", but the animation goes in the opposite direction. For example:

If we set:
* Link Time = 5s
* Local Time = 2s
* Duration = -4s
then from 2s to 6s and from 6s to 10s, etc., the resulting value is the value of "Link" from 5s to 1s, as follows:

Then the resulting values will be:
* 0s -> "Link" value at 3s = 6
* 1s -> "Link" value at 2s = 4
* 2s -> "Link" value at 5s = 10 (at "Link Time" = 2s, result is the value of "Link" at "Link Time" = 5s = 10)
* 3s -> "Link" value at 4s = 8
* 4s -> "Link" value at 3s = 6
* 5s -> "Link" value at 2s = 4
* 6s -> "Link" value at 5s = 10 (4s later, the value is the same as at "Link Time" = 2s)
* 7s -> "Link" value at 4s = 8

This conversion can be used on all value types.

=== Time String ===

Converting a [[Convert#String|string]] parameter to "Time String" adds one sub-parameter called "Time", of type time:

* time "Time"

The result is a string containing the given time.

=== Timed Swap ===

This convert type was disabled in Synfig 0.61.06 and earlier because it didn't work.

Converting a parameter to "Timed Swap" adds four sub-parameters:
* <param> "Before"
* <param> "After"
* time "Swap Time"
* time "Swap Duration"

"Before" and "After" are the same type as the parameter being converted.

This conversion type linearly switches from "Before" to "After", taking "Swap Duration" seconds to do so, and completing the swap at "Swap Time".

Note that this doesn't give us anything that we can't achieve using the "[[Convert#Linear|Linear]]" conversion type and a few waypoints.

"Timed Swap" can be used on [[Convert#Angle|angles]], [[Convert#Color|colors]], [[Convert#Integer|integers]], [[Convert#Real|reals]], [[Convert#Time|times]], and [[Convert#Vector|vectors]].

The resulting value is:
if time > "Swap Time" then "After"
else if time < ("Swap Time" - "Swap Duration") then "Before"
else interpolate between "Before" and "After"

=== Two-Tone ===

Converting a [[Convert#Gradient|gradient]] to "Two-Tone" adds two color-valued sub-parameters:
* color "Color1"
* color "Color2"

The resulting gradient has two CPoints, one at each end, starting with "Color1" and ending with "Color2".

These color parameters can be animated, giving us the ability to have the gradient change color over time. This can be used as a workaround for [http://sourceforge.net/tracker/index.php?func=detail&aid=1568818&group_id=144022&atid=757416 this bug].

=== Vector Angle ===

Converting an [[Convert#Angle|angle]] to "Vector Angle" adds a vector sub-parameter:
* vector "Vector"

The resulting value is the angle between the vector and the X axis.

=== Vector Length ===

Converting a [[Convert#Real|real]] to "Vector Length" adds a vector sub-parameter:
* vector "Vector"

The resulting value is the length of the vector.

=== Vector X ===

Converting a [[Convert#Real|real]] to "Vector X" adds a vector sub-parameter:
* vector "Vector"

The resulting value is the X component of the vector.

=== Vector Y ===

Converting a [[Convert#Real|real]] to "Vector Y" adds a vector sub-parameter:
* vector "Vector"

The resulting value is the Y component of the vector.

== Which Value Types can use which Convert Types? ==

There are 13 different types of value in Synfig. Each of these types has a different set of convert types available to it, as follows:

=== Angle ===

[[Image:angle_icon.png|32px]]

* Angle parameters can be converted to [[Convert#Add|Add]], [[Convert#aTan2|aTan2]], [[Convert#BLine Tangent|BLine Tangent]], [[Convert#Dot Product|Dot Product]], [[Convert#Linear|Linear]], [[Convert#Random|Random]], [[Convert#Range|Range]], [[Convert#Scale|Scale]], [[Convert#Step|Step]], [[Convert#Subtract|Subtract]], [[Convert#Switch|Switch]], [[Convert#Time Loop|Time Loop]], [[Convert#Timed Swap|Timed Swap]], [[Convert#Vector Angle|Vector Angle]], and [[Convert#Reference|Reference]] types.

=== BLinePoint ===
[[Image:blinepoint_icon.png|32px]]

* BLinePoint parameters can be converted to [[Convert#Composite|Composite]], [[Convert#Reverse Tangent|Reverse Tangent]], [[Convert#Switch|Switch]], [[Convert#Time Loop|Time Loop]], and [[Convert#Reference|Reference]] types.

=== Bool ===
[[Image:bool_icon.png|32px]]

* Bool parameters can only be converted to the [[Convert#Switch|Switch]], [[Convert#Time Loop|Time Loop]], and [[Convert#Reference|Reference]] types.

=== Canvas ===
[[Image:canvas_pointer_icon.png|32px]]

* Canvas parameters can be converted to the [[Convert#Switch|Switch]], [[Convert#Time Loop|Time Loop]], and [[Convert#Reference|Reference]] type.

=== Color ===
[[Image:color_icon.png|32px]]
* Color parameters can be converted to [[Convert#Add|Add]], [[Convert#Composite|Composite]], [[Convert#Gradient Color|Gradient Color]], [[Convert#Linear|Linear]], [[Convert#Radial Composite|Radial Composite]], [[Convert#Random|Random]], [[Convert#Scale|Scale]], [[Convert#Step|Step]], [[Convert#Subtract|Subtract]], [[Convert#Switch|Switch]], [[Convert#Time Loop|Time Loop]], [[Convert#Timed Swap|Timed Swap]], and [[Convert#Reference|Reference]] types.

=== Gradient ===
[[Image:gradient_icon.png|32px]]

* Gradient parameters can be converted to [[Convert#Add|Add]], [[Convert#Gradient Rotate|Gradient Rotate]], [[Convert#Repeat Gradient|Repeat Gradient]], [[Convert#Stripes|Stripes]], [[Convert#Subtract|Subtract]], [[Convert#Switch|Switch]], [[Convert#Time Loop|Time Loop]], [[Convert#Two-Tone|Two-Tone]], and [[Convert#Reference|Reference]] types.

=== Integer ===
[[Image:Integer_icon.png|32px]]
* Integer parameters can be converted to [[Convert#Add|Add]], [[Convert#Linear|Linear]], [[Convert#Random|Random]], [[Convert#Range|Range]], [[Convert#Scale|Scale]], [[Convert#Step|Step]], [[Convert#Subtract|Subtract]], [[Convert#Switch|Switch]], [[Convert#Time Loop|Time Loop]], [[Convert#Timed Swap|Timed Swap]], and [[Convert#Reference|Reference]] types.

=== List ===
[[Image:list_icon.png|32px]]
* List parameters can be converted to [[Convert#BLine|BLine]], [[Convert#Dynamic List|Dynamic List]], [[Convert#Switch|Switch]], [[Convert#Time Loop|Time Loop]], and [[Convert#Reference|Reference]] types.

=== Real ===
[[Image:real_icon.png|32px]]
* Real parameters can be converted to [[Convert#Add|Add]], [[Convert#BLine Width|BLine Width]], [[Convert#Cos|Cos]], [[Convert#Dot Product|Dot Product]], [[Convert#Exponential|Exponential]], [[Convert#Linear|Linear]], [[Convert#Logarithm|Logarithm]], [[Convert#Random|Random]], [[Convert#Range|Range]], [[Convert#Reciprocal|Reciprocal]], [[Convert#Scale|Scale]], [[Convert#Sine|Sine]], [[Convert#Step|Step]], [[Convert#Subtract|Subtract]], [[Convert#Switch|Switch]], [[Convert#Time Loop|Time Loop]], [[Convert#Timed Swap|Timed Swap]], [[Convert#Vector Length|Vector Length]], [[Convert#Vector X|Vector X]], [[Convert#Vector Y|Vector Y]], and [[Convert#Reference|Reference]] types.

=== Segment ===
[[Image:segment_icon.png|32px]]
* Segment parameters can be converted to the [[Convert#Composite|Composite]], [[Convert#Switch|Switch]], [[Convert#Time Loop|Time Loop]], and [[Convert#Reference|Reference]] types.

=== String ===
[[Image:string_icon.png|32px]]
* String parameters can be converted to the [[Convert#Angle String|Angle String]], [[Convert#Int String|Int String]], [[Convert#Joined List|Joined List]], [[Convert#Real String|Real String]], [[Convert#Switch|Switch]], [[Convert#Time Loop|Time Loop]], [[Convert#Time String|Time String]], and [[Convert#Reference|Reference]] types.

=== Time ===
[[Image:time_icon.png|32px]]
* Time parameters can be converted to the [[Convert#Add|Add]], [[Convert#Linear|Linear]], [[Convert#Random|Random]], [[Convert#Range|Range]], [[Convert#Scale|Scale]], [[Convert#Step|Step]], [[Convert#Subtract|Subtract]], [[Convert#Switch|Switch]], [[Convert#Time Loop|Time Loop]], [[Convert#Timed Swap|Timed Swap]], and [[Convert#Reference|Reference]] types.

=== Vector ===
[[Image:vector_icon.png|32px]]
* Vector parameters can be converted to [[Convert#Add|Add]], [[Convert#BLine Tangent|BLine Tangent]], [[Convert#BLine Vertex|BLine Vertex]], [[Convert#Composite|Composite]], [[Convert#Linear|Linear]], [[Convert#Radial Composite|Radial Composite]], [[Convert#Random|Random]], [[Convert#Scale|Scale]], [[Convert#Segment Tangent|Segment Tangent]], [[Convert#Segment Vertex|Segment Vertex]], [[Convert#Step|Step]], [[Convert#Subtract|Subtract]], [[Convert#Switch|Switch]], [[Convert#Time Loop|Time Loop]], [[Convert#Timed Swap|Timed Swap]], and [[Convert#Reference|Reference]] types.

== Compatibility ==

When a new ValueNode type is added to Synfig, the .sif file format is extended to include a way of writing the new type. This extension won't be able to be read by any older version of Synfig. Here's a list of the ValueNode types that have been added, along with the subversion revision number in which they first appeared:

<blockquote>
{| style="width:55%"
| '''Version''' || '''Revision''' || '''Convert'''
|-
| <hr> || <hr> || <hr>
|-
| '''(0.61.09)''' || not yet released ||  
|-
|   || 2034 || [[#Logarithm|Logarithm]]
|-
|   || 2010 || [[#Int String|Int String]]
|-
|   || 2010 || [[#Angle String|Angle String]]
|-
|   || 2007 || [[#Joined List|Joined List]]
|-
|   || 2003 || [[#Real String|Real String]]
|-
|   || 2000 || [[#Time String|Time String]]
|-
|   || 1891 || [[#Dot Product|Dot Product]]
|-
|   || 1885 || [[#Gradient Color|Gradient Color]]
|-
|   || 1882 || [[#Vector X|Vector X]]
|-
|   || 1882 || [[#Vector Y|Vector Y]]
|-
|   || 1881 || [[#Vector Length|Vector Length]]
|-
|   || 1880 || [[#Vector Angle|Vector Angle]]
|-
| <hr> || <hr> || <hr>
|-
| '''(0.61.08)''' || 1839 ||  
|-
|   || 1694 || [[#BLine Width|BLine Width]]
|-
|   || 1690 || [[#Random|Random]] (for bools)
|-
|   || 1691 || [[#Step|Step]]
|-
|   || 1354 || [[#Subtract|Subtract]] (for gradients)
|-
|   || 1354 || [[#Add|Add]] (for gradients)
|-
|   || 1267 || [[#From Integer|From Integer]]
|-
|   || 1267 || [[#Duplicate|Duplicate]]
|-
|   || 1238 || [[#Reciprocal|Reciprocal]]
|-
|   || 1226 || [[#Time Loop|Time Loop]]
|-
|   || 1162 || [[#Reverse Tangent|Reverse Tangent]]
|-
|   || 1132 || [[#aTan2|aTan2]]
|-
|   || 1111 || [[#Cos|Cos]]
|-
|   || 923 || [[#Switch|Switch]]
|-
|   || 907 || [[#Random|Random]]
|-
| <hr> || <hr> || <hr>
|-
| '''(0.61.07)''' || 878 ||  
|-
|   || 776 || [[#Range|Range]]
|-
|   || 744 || [[#BLine Vertex|BLine Vertex]]
|-
|   || 744 || [[#BLine Tangent|BLine Tangent]]
|-
|   || 742 || [[#Add|Add]]
|-
|   || 739 || [[#Exponential|Exponential]]
|-
|   || 666 || [[#Repeat Gradient|Repeat Gradient]]
|-
|   || 610 || [[#Timed Swap|Timed Swap]]
|-
| <hr> || <hr> || <hr>
|-
| '''(0.61.06)''' || 536 ||  
|-|}
</blockquote>

Time Loop Layer

2008-12-13T11:51:20Z

Dooglus: add an 'otherwise' to show that the sentence only applies if the previous one doesn't

The Time Loop layer can be used to repeat an animation over and over. It loops a section of the layers under it over and over.

See also the [[Convert#Time_Loop|Time Loop ValueNode]] conversion, which can be used to loop the value of a single parameter, rather than an entire layer or group of layers.

[Note: ''the Time Loop layer used to have parameters 'start time' and 'end time'. Documentation for that old version of the layer [[Time Loop Layer (v0.1)|is available]]''.

It has 6 parameters, as follows:
* real "Z Depth"
* time "Link Time"
* time "Local Time"
* time "Duration"
* bool "Only For Positive Duration"
* bool "Symmetrical"

These parameters, like any other in Synfig can be animated, so that they change over time. This can be confusing, so make sure you aren't in Animate Edit Mode when working with the Time Loop layer, unless you know what you're doing!

If 'Only For Positive Duration' is checked, and 'Duration' is zero or negative, then the time loop layer is effectively disabled, and acts as if it wasn't there.

Otherwise, when the Duration is zero, the Time Loop layer freezes the animation of the children layers at the value of "Link Time".

Otherwise, the Time Loop layer repeatedly loops through the 'Duration' seconds of its child layers, from 'Link Time' to 'Link Time' + 'Duration'. 'Local Time' is used to line up the offset of the time looping. When the Time Loop layer is asked to set its time to 'Local Time', it sets the time in its child layers to be 'Link Time', ie. the start of the loop.

If 'Symmetrical' isn't checked, and the current time is less than 'local time', then 'duration' is taken off the resulting time. This is to provide compatibility with [[Time Loop Layer (v0.1)|version 0.1]] of the time loop layer.

For example, suppose:
* Link Time is 5s
* Duration is 3s
* Local Time' is 4s

And suppose that the Time Loop layer is applied over an existing animation. The 'Link Time' and 'Duration' specify that the section from 5s to 8s in the children layers will be looped. The 'Local Time' specifies that this loop will be at the beginning at 4s. (And so also therefore at 1s, 7s, 10s, etc).

This is how the mapping actually works:

{| border="1" cellspacing="0"
|'''real time'''||'''child time<br/>(symmetrical = true)'''||'''child time<br/>(symmetrical = false)'''
|-
| 0 || 7 || 4
|-
| 1 || 5 || 2
|-
| 2 || 6 || 3
|-
| 3 || 7 || 4
|-
| 4 || 5 || 5 (local time = 4; link time = 5)
|-
| 5 || 6 || 6
|-
| 6 || 7 || 7
|-
| 7 || 5 || 5 (duration = 3, so loop repeats after 3 seconds)
|-
| 8 || 6 || 6
|-
| 9 || 7 || 7
|-
| 10 || 5 || 5
|}

Specifying a huge number for the Duration parameter effectively turns the Time Loop layer into a Time Shift layer. The Link Time and Local Time parameters controls which time in the children lines up with which time in the Time Loop layer, giving the amount of the timeshift, with both positive and negative differences working as expected.

== Contrived Example ==

Download and examine this example file: [[Media:Time-loop-demo-0.2.sifz|Time-loop-demo-0.2.sifz]]

It's a 10 second animation, and shows 2 circles. The top one moves linearly from the left to the right. Its position is marked by static text digits 0 through 10.

The other circle is an identical copy of the first one, with the same waypoints, but it's inside an encapsulation layer. The parameters are:
* Link Time: 5s
* Duration: 1.5s
* Local Time: 2s
* Symmetrical: true

So as time=2s, the top circle is at position 2 (local time) and the bottom circle is at position 5 (link time):

[[Image:Time-loop-demo-0.2-2s-0f.png]]

The loop is 1.5s long, so the bottom circle is also at position 5 every 1.5 seconds before and after this point in time, for example at t=3.5s and at t=8s:

[[Image:Time-loop-demo-0.2-3s-12f.png]]
[[Image:Time-loop-demo-0.2-8s-0f.png]]

The following two images show the positions at t=0s and t=3s. The loop starts at t=2s, so it's also at the start at t=0.5s. So at t=0s it's half a second before finishing the previous loop. And at t=3s the same is true, but 2 loops later on:

[[Image:Time-loop-demo-0.2-0s-0f.png]]
[[Image:Time-loop-demo-0.2-3s-0f.png]]

There's a rendered copy of this example on [http://www.youtube.com/watch?v=WyYLd7319Gw YouTube], and it's also available for download: [[Media:Time-loop-demo-0.2.avi‎|Time-loop-demo-0.2.avi‎]].

Dev:Bone Layer

2008-11-30T11:30:51Z

Dooglus: /* What happen if there are more than one bone affecting the point? */

== Initial seed for concepts ==

[http://dooglus.rincevent.net/synfig/logs/2008/%23synfig-2008-11-12.log This portion] of IRC logs sets the basis for the implementation of a Bone Layer. The interesting part is from 16:49 to 18:56.

Also [http://dooglus.rincevent.net/synfig/logs/2008/%23synfig-2008-11-13.log this one] has some interesting thoughts. From 8:20 to 14:43

== Concepts ==
This is an unsorted list of concepts to let me clarify my thoughts and also allow others to understand the following sections.

=== Bones intentions ===
Initial intention of Bones is to attempt to emulate the skeleton of a vertebrate animal. In this way you have the skin and a skeleton. Part of the skin are associated with the various bones of the skeleton. When the skeleton moves the skin follows.

=== Application of bones in animation ===
In traditional animation producing a walk cycle implies drawing each keyframe for the walk and maybe, depending on the walking speed, drawing the in betweens too. To avoid having to draw the in between images there are tweening animation programs (like Synfig) to help the animator. Then the animator just needs to draw the keyframes and the application does the rest. That's quite good but in certain situations you see your self redrawing the same pose (with small variations) frequently at different times. Then bones come to help. They aid the animator in the following manner.

* With the manipulation of a single object (or a set of them) you can manage a lot of points of the drawing definition.
* Rotations of drawings using keyframes needs lots of them (by nature of the fact that tweening is defined in the x,y coordinates system and the rotation is performed in the angle, radius coordinate system). Using bones you can perform rotations of large angles with just two waypoints. Also since characters have limbs and limbs in living beings do mainly rotations, the usage of bones becomes handy in that kind of animation.
* Once the character (or whatever thing that uses bones) is rigged (the skeleton structure is created and the relationship between it and the skin is defined) it is possible to produce different kinds of keyframes for different purposes: Walk, run, jump, sit, ...

== How can we do implement this? ==
The relationship between the skeleton and the skin is like this:

*The Skin is made using Points and BLines. BLines are defined by Points. Points are made of Vertexes and Tangents
*Skeleton is made of bones and the relationships between them.
*''If Bones would have influence on the Vertexes and Tangents then the bones movements would move the points and therefore the skin would be moved''.

That's the key, if we understand how a bone has influence on a vertex and a tangent then we can find the way a skeleton can have influence over a skin.

=== Bones Properties ===
From my experience with bones in other 2D animation applications, watching the strong and weak points, bones needs to have the following properties:

* A bone has an origin point about which the rotation is performed.
* A bone has a length.
* A bone has an angle.
* A bone can have a region of influence.
* A bone can have a one or zero parent bones.
* A bone can have one or more child bones.
* A skeleton is defined as a connected set of bones (consisting of exactly one parent-less bone and its children bones and their descendants).

All the bones in a Synfig Document can produce several distinct skeletons (depending on how many parent-less bones are in it).

=== How does a Vertex move under the influence of a single Bone? ===

Conceptually a bone has influence over a point by doing [http://en.wikipedia.org/wiki/Affine_transformation affine transformations] of its position according to the bone values. See also [http://en.wikipedia.org/wiki/Transformation_matrix transformation matrix]. A bone produces rotation, scale and translation to a point in this way:

[[Image:Bonesimulation2.png]]

As you can see the values that produce the movement of the point P to the point P' are given by:

*Translation of the bone: O'-O
*Rotation of the bone: <math>\alpha'-\alpha</math>
*Scale of the bone: s=length'/length

Then, given a Point P in the 2D space and knowing the translation, rotation and scale of the bone you can calculate the new position P' using this formula:

<math>
T(-O)=\begin{bmatrix}
1 & 0 & 0 \\
0 & 1 & 0 \\
-O_x & -O_y & 1
\end{bmatrix}
</math> Translation to origin (0,0)

<math>
R(-\alpha)=\begin{bmatrix}
\cos(-\alpha) & \sin(-\alpha) & 0 \\
-\sin(-\alpha) & \cos(-\alpha) & 0 \\
0 & 0 & 1
\end{bmatrix}
</math> Rotate by an angle of amount '<math>-\alpha</math>' about the origin. That aligns the bone with the X axis

<math>
S_x(length'/length)=\begin{bmatrix}
length'/length & 0 & 0 \\
0 & 1 & 0 \\
0 & 0 & 1
\end{bmatrix}
</math> Scale by a value of 's=length'/length' in the direction of X (the current direction of the bone).

<math>
R(\alpha^')=\begin{bmatrix}
\cos(\alpha^') & \sin(\alpha^') & 0 \\
-\sin(\alpha^') & \cos(\alpha^') & 0 \\
0 & 0 & 1
\end{bmatrix}
</math> Rotate by an angle of amount '<math>\alpha'</math>' about the origin.

<math>
T(O^')=\begin{bmatrix}
1 & 0 & 0 \\
0 & 1 & 0 \\
O^'_x & O^'_y & 1
\end{bmatrix}
</math> Translation to new position O'

Then the transformation from P to P' is given by the matrix multiplication:

<math> P'=P\cdot T(-O)\cdot R(-\alpha)\cdot S_x(length'/length)\cdot R(\alpha^')\cdot T(O^')</math>

<math> P'=P\cdot T\cdot R\cdot S_x\cdot R'\cdot T'=P\cdot B</math>

=== Can Points (Bone influenced) be moved independently? ===

Yes, they should be. If not the animator is restricted to only doing the animation with bones which would lead to some insoluble problems during the animation. Considering this, the point position result comes from the addition of two terms:
*(a) The movement of the point as described by the influence of the bone(s): P(B)
*(b) The free movement of the point in the 2D space. P(animated)

In terms of the interface with the user, the value P(animated) is just obtained in this way:

#In any position of the time line (bones are animated) the point has a position given by the influence of the bones: P(B).
#The user selects a point, drags it, placing it at P'.
#The final position of the point is P' but the user cannot modify the first term P(B) so the second term (b) becomes: P(animated)=P'-P(B).

===What happen if there are more than one bone affecting the point?===

The first thing you can think when you deal with more than one bone having influence over the same point is to calculate the average of the sum of the influences of all bones. So if there are N bones affecting the point then we can think of summing all the resulting points from each bone and then dividing the result by N to not scale the result.

<math> B=\frac{\sum_{k=1}^N B_k}{N} </math>

Where <math>B_k</math> is the bone matrix for the bone ''k'' on the point P.

That's fine but I would like to have more control to the way the bones affect the points. When you move a bone it looks reasonable that not all the points are influenced in the same way. This can be solved by using a "weighted" average instead of a plain one. That means giving a different amount of influence to one bone than to the other.

<math> B=\frac{\sum_{k=1}^N B_k \cdot w_k}{\sum_{k=1}^N w_k} </math>

Where <math>w_k</math> is the weight for the bone ''k'' over the point P.

=== Skeleton ===

A skeleton is a set of bones linked one to others in a tree hierarchy. A bone can have several children (or none) but only one parent (or none). This configuration allows to do a easy calculation of the forward kinematic (FK )of the chain and the inverse kinematic (IK) of the chain of bones. If the hierarchy were not tree type then the FK and IK can be not soluble.

For those IK and FK calculations it is good to have the bone referenced to its parent. So the parameters of the bone are described as relative to the parent bone. The parent bone defines a local coordinate system where the origin of the coordinate system lies on the Origin of the bone and the tip of the bone is pointing to the positive direction of the X axis.

[[Image: skeleton.png]]

As you can see in this image, each skeleton position and orientation is defined by the relative position of its immediate parent bone. In the diagram bone3 is a child of bone2 and bone 2 is a child of bone1. The bone 1 is the root parent bone but you can imagine it attached to a "master root bone" (defined by the origin of coordinates -red circumference- and the horizontal) so it can be said that the bone1 has its origin and angle defined relative to its "parent".

In this skeleton the three bones are parented in a linear way. But as you can imagine, following the rules stated for child-parent, a bone can have more than one child but not more than one parent.
That means that defined a bone in the skeleton, there is only one sequence of parents to reach the root parent of the skeleton. Also it means too that one root bone defines one skeleton so each skeleton has only one root bone and only one.

Consider this: B3 is child of B2 and B2 is child of B1. Also B4 is child of B2 and B5 is child of B4. The way to travel from B5 to B1 is unique: B5->B4->B2->B1.

=== Setup and Animation ===

During the animation of the skeleton it is supposed that the position of each bone, its angle and its scale changes. Position and angle are relative to the parent bone, but scale is a value that calculates the current length of the bone compared with the "original" bone length (scale=length'/length) as you can see from the original formulas in the previous section. That means that the "original" bone length shouldn't be never zero, otherwise there will be a division by zero and the scale of the bone becomes infinite.

Also, the final position P' of a point that moves influenced by a single bone is given by the original point position relative to the bone in its "original" position (P).

What I'm trying to explain is that it is needed that the setup of the bone (position, alpha and length) and the setup position of the point (P) to be moved would be given to calculate the final position of the point (P') given a moved position of the bone (position', alpha', length')

Said this and considered the information of the previous sections, the bones and points that are influenced from the bones should have the following parameters:

'''BONES PARAMETERS'''
{|
! Parameter !! Notation !! Type !! Animated !! Comment
|-
| Origin ||<math> \textstyle O_j(t) </math> || Vector (Real,Real) ||Yes|| Relative to the parent
|-
| Angle || <math> \textstyle \alpha_j(t) </math> || Angle (DEG) ||Yes|| Relative to the parent
|-
| Length || <math> \textstyle l_j(t) </math> || Real ||Yes|| Calculated, not animatable.
|-
| Scale || <math> \textstyle s_j(t) </math> || Real ||Yes|| <math> \textstyle l_j(t) =l^0_j \cdot s_j(t) </math>
|-
| Setup Origin || <math> \textstyle O^0_j(t) </math> || Vector (Real,Real) ||Yes|| Relative to the parent
|-
| Setup Angle || <math> \textstyle \alpha^0_j(t) </math> || Angle (DEG) ||Yes|| Relative to the parent
|-
| Setup Length || <math> \textstyle l^0_j </math> || Real || No|| Constant, zero not allowed.
|-
| Setup Scale || <math> \textstyle s^0_j </math> || Real || No|| <math> \textstyle s^0_j = 1 </math>
|-
| Parent || <math> \textstyle PBone_j(t) </math> || Bone ||Yes||
|}

'''POINT PARAMETERS'''

{|
! Parameter !! Notation !! Type !! Animated !! Comment
|-
| Position ||<math> \textstyle V(t) </math> || Vector (Real,Real) ||Yes|| Calculated: <math> \textstyle V(t) =VF(t) + VS(t) \cdot M(t) </math> Global coordinates
|-
| Free Position ||<math> \textstyle VF(t) </math> || Vector (Real, Real) ||Yes|| Global Coordinates
|-
| Setup Position ||<math> \textstyle VS(t) </math> || Vector (Real, Real) ||Yes|| Global Coordinates
|-
| Bone Influence Matrix ||<math> \textstyle M(t) </math> || Matrix (3x3) ||Yes|| Calculated. See formulas below
|-
| Bone Influence Id ||<math> \textstyle BoneID_i </math> || Bone || No || 'i' is the index for all the Bones that influences on the Point
|-
| Influence weight ||<math> \textstyle w_i </math> || Real || Yes || the weight associated to the BoneID_i
|}

(t) denotes ''calculated at the time t''

=== Position of a Point due to Bones Influence ===

According to the table, the final position of a point influenced by the bones is calculated based on two terms: A free movement of the point plus a bone drive movement. In this section we are going to calculate the second term.

<math> \textstyle V(t) =VF(t) + VS(t) \cdot M(t) </math>

<math> M(t) = \cfrac{\sum_{i=1}^N M_i(t) \cdot w_i(t)}{\sum_{i=1}^N w_i(t)} </math>

<math> M_i(t)=B^0_i(t) \cdot B_i(t) </math>

where i is a index that runs all the Bones Influence ID from i=1 to N (N= total number of bones that influence to the point)

<math> B^0_i(t)= \prod_{j=bone}^{j=root} C_j^0(t)</math>

<math> B_i(t)= \prod_{j=root}^{j=bone} C_j(t)</math>

where 'j' runs the bone skeleton jumping from a child/parent bone to a parent/child bone each time. The travel of the index 'j' from ''bone'' to ''root'' and from ''root'' to ''bone'' is fixed -and unique- by the nature of skeletons constructions (a bone, a parent), as mentioned before.

<math> C_j^0(t) = T(-O_j^0(t)) \cdot R(-\alpha_j^0(t)) \cdot S_x(\frac{1}{s^0_j})</math>

This matrix calculates the position of the point in local coordinates in relation to the bone 'j' at setup position. Notice that <math> s^0_j </math> is equal to <math> \textstyle 1 </math> for any bone and for any time.

<math> C_j(t) = S_x(s_j(t))\cdot R(\alpha_j(t)) \cdot T(O_j(t)) </math>

This matrix calculates the global position of the point due to the bone 'j' at animated position of the skeleton.

=== Calculate the position and angle of a bone in a skeleton ===

==== Position and Angle at Setup ====

If the bones are described using relative coordinates to its predecessor, the position <math>\textstyle Q^0_j</math> and the angle <math>\textstyle \beta^0_j</math> of the bone 'j' in relation to the "master root bone" (ie. the global coordinate system) is given by those equations:

<math>Q^0_j(t) = O^0_j(t) \cdot B^0_j(t)</math>

<math>\beta^0_j(t) = \sum_{i=j}^{root} \alpha^0_i(t)</math>

where

<math>B^0_j(t)=\prod_{i=parent}^{root} B^0_i(t)</math>

where 'i' goes form the parent of the bone 'j' and climbs up by one parent each time until it reaches the 'root' bone of the skeleton.

<math>B^0_i(t)= T(-O^0_i(t)) \cdot R(-\alpha^0_i(t)) \cdot S_x(\frac{1}{s^0_j})</math>

<math>B^0_i(t)</math> is the inverse matrix transformation of the position of the bone relative to its immediate parent.

Notice that at setup, <math>s^0_j</math> is always equal to 1.

====Animated Position and Angle ====

Once calculated the position and angle of a bone in global coordinates you can calculate its animated position and angle by the transformation of their parents in the skeleton.

<math>Q_j(t) = O^0_j(t) \cdot B^0_j(t) \cdot B_j(t)</math>

<math>\beta_j(t)= \beta^0_j(t) + \sum_{i=root}^{parent} \alpha_i(t)</math>

where <math>B_j(t)=\prod_{i=root}^{parent} B_i(t)</math>

where 'i' goes form the root bone and jumps down by one child each time until it reaches the 'parent' bone of the bone 'j'.

<math>B_i(t)= S_x(s_j(t)) \cdot R(\alpha_i(t)) \cdot T(O_i(t)) </math>

<math>\textstyle B_i(t)</math> is the transformation matrix of the position of the bone 'j' at the time t.

The results <math>\textstyle Q_j(t), \beta_j(t)</math> are obtained in global coordinates.

Dev:Bone Layer

2008-11-30T11:27:50Z

Dooglus: /* Can Points (Bone influenced) be moved independently? */

== Initial seed for concepts ==

[http://dooglus.rincevent.net/synfig/logs/2008/%23synfig-2008-11-12.log This portion] of IRC logs sets the basis for the implementation of a Bone Layer. The interesting part is from 16:49 to 18:56.

Also [http://dooglus.rincevent.net/synfig/logs/2008/%23synfig-2008-11-13.log this one] has some interesting thoughts. From 8:20 to 14:43

== Concepts ==
This is an unsorted list of concepts to let me clarify my thoughts and also allow others to understand the following sections.

=== Bones intentions ===
Initial intention of Bones is to attempt to emulate the skeleton of a vertebrate animal. In this way you have the skin and a skeleton. Part of the skin are associated with the various bones of the skeleton. When the skeleton moves the skin follows.

=== Application of bones in animation ===
In traditional animation producing a walk cycle implies drawing each keyframe for the walk and maybe, depending on the walking speed, drawing the in betweens too. To avoid having to draw the in between images there are tweening animation programs (like Synfig) to help the animator. Then the animator just needs to draw the keyframes and the application does the rest. That's quite good but in certain situations you see your self redrawing the same pose (with small variations) frequently at different times. Then bones come to help. They aid the animator in the following manner.

* With the manipulation of a single object (or a set of them) you can manage a lot of points of the drawing definition.
* Rotations of drawings using keyframes needs lots of them (by nature of the fact that tweening is defined in the x,y coordinates system and the rotation is performed in the angle, radius coordinate system). Using bones you can perform rotations of large angles with just two waypoints. Also since characters have limbs and limbs in living beings do mainly rotations, the usage of bones becomes handy in that kind of animation.
* Once the character (or whatever thing that uses bones) is rigged (the skeleton structure is created and the relationship between it and the skin is defined) it is possible to produce different kinds of keyframes for different purposes: Walk, run, jump, sit, ...

== How can we do implement this? ==
The relationship between the skeleton and the skin is like this:

*The Skin is made using Points and BLines. BLines are defined by Points. Points are made of Vertexes and Tangents
*Skeleton is made of bones and the relationships between them.
*''If Bones would have influence on the Vertexes and Tangents then the bones movements would move the points and therefore the skin would be moved''.

That's the key, if we understand how a bone has influence on a vertex and a tangent then we can find the way a skeleton can have influence over a skin.

=== Bones Properties ===
From my experience with bones in other 2D animation applications, watching the strong and weak points, bones needs to have the following properties:

* A bone has an origin point about which the rotation is performed.
* A bone has a length.
* A bone has an angle.
* A bone can have a region of influence.
* A bone can have a one or zero parent bones.
* A bone can have one or more child bones.
* A skeleton is defined as a connected set of bones (consisting of exactly one parent-less bone and its children bones and their descendants).

All the bones in a Synfig Document can produce several distinct skeletons (depending on how many parent-less bones are in it).

=== How does a Vertex move under the influence of a single Bone? ===

Conceptually a bone has influence over a point by doing [http://en.wikipedia.org/wiki/Affine_transformation affine transformations] of its position according to the bone values. See also [http://en.wikipedia.org/wiki/Transformation_matrix transformation matrix]. A bone produces rotation, scale and translation to a point in this way:

[[Image:Bonesimulation2.png]]

As you can see the values that produce the movement of the point P to the point P' are given by:

*Translation of the bone: O'-O
*Rotation of the bone: <math>\alpha'-\alpha</math>
*Scale of the bone: s=length'/length

Then, given a Point P in the 2D space and knowing the translation, rotation and scale of the bone you can calculate the new position P' using this formula:

<math>
T(-O)=\begin{bmatrix}
1 & 0 & 0 \\
0 & 1 & 0 \\
-O_x & -O_y & 1
\end{bmatrix}
</math> Translation to origin (0,0)

<math>
R(-\alpha)=\begin{bmatrix}
\cos(-\alpha) & \sin(-\alpha) & 0 \\
-\sin(-\alpha) & \cos(-\alpha) & 0 \\
0 & 0 & 1
\end{bmatrix}
</math> Rotate by an angle of amount '<math>-\alpha</math>' about the origin. That aligns the bone with the X axis

<math>
S_x(length'/length)=\begin{bmatrix}
length'/length & 0 & 0 \\
0 & 1 & 0 \\
0 & 0 & 1
\end{bmatrix}
</math> Scale by a value of 's=length'/length' in the direction of X (the current direction of the bone).

<math>
R(\alpha^')=\begin{bmatrix}
\cos(\alpha^') & \sin(\alpha^') & 0 \\
-\sin(\alpha^') & \cos(\alpha^') & 0 \\
0 & 0 & 1
\end{bmatrix}
</math> Rotate by an angle of amount '<math>\alpha'</math>' about the origin.

<math>
T(O^')=\begin{bmatrix}
1 & 0 & 0 \\
0 & 1 & 0 \\
O^'_x & O^'_y & 1
\end{bmatrix}
</math> Translation to new position O'

Then the transformation from P to P' is given by the matrix multiplication:

<math> P'=P\cdot T(-O)\cdot R(-\alpha)\cdot S_x(length'/length)\cdot R(\alpha^')\cdot T(O^')</math>

<math> P'=P\cdot T\cdot R\cdot S_x\cdot R'\cdot T'=P\cdot B</math>

=== Can Points (Bone influenced) be moved independently? ===

Yes, they should be. If not the animator is restricted to only doing the animation with bones which would lead to some insoluble problems during the animation. Considering this, the point position result comes from the addition of two terms:
*(a) The movement of the point as described by the influence of the bone(s): P(B)
*(b) The free movement of the point in the 2D space. P(animated)

In terms of the interface with the user, the value P(animated) is just obtained in this way:

#In any position of the time line (bones are animated) the point has a position given by the influence of the bones: P(B).
#The user selects a point, drags it, placing it at P'.
#The final position of the point is P' but the user cannot modify the first term P(B) so the second term (b) becomes: P(animated)=P'-P(B).

===What happen if there are more than one bone affecting the point?===

The first thing you can think when you deal with more than one bone making influence over the same point is to calculate the average of the sum of the influences of all bones. So if there are N bones affecting to the point then we can think on sum all the resulting points from each bone and then divide the result by N to not scale the result.

<math> B=\frac{\sum_{k=1}^N B_k}{N} </math>

Where <math>B_k</math> is the bone matrix for the bone ''k'' on the point P.

That's fine but I would like to have more control to the way the bones affects to the points. When you move a bone it looks reasonable that not all the points are influence in the same way. This can be solved by using "weighted" average instead of a plain one. That means give different amount of influence to one bone than to other.

<math> B=\frac{\sum_{k=1}^N B_k \cdot w_k}{\sum_{k=1}^N w_k} </math>

Where <math>w_k</math> is the weight for the bone ''k'' over the point P.

=== Skeleton ===

A skeleton is a set of bones linked one to others in a tree hierarchy. A bone can have several children (or none) but only one parent (or none). This configuration allows to do a easy calculation of the forward kinematic (FK )of the chain and the inverse kinematic (IK) of the chain of bones. If the hierarchy were not tree type then the FK and IK can be not soluble.

For those IK and FK calculations it is good to have the bone referenced to its parent. So the parameters of the bone are described as relative to the parent bone. The parent bone defines a local coordinate system where the origin of the coordinate system lies on the Origin of the bone and the tip of the bone is pointing to the positive direction of the X axis.

[[Image: skeleton.png]]

As you can see in this image, each skeleton position and orientation is defined by the relative position of its immediate parent bone. In the diagram bone3 is a child of bone2 and bone 2 is a child of bone1. The bone 1 is the root parent bone but you can imagine it attached to a "master root bone" (defined by the origin of coordinates -red circumference- and the horizontal) so it can be said that the bone1 has its origin and angle defined relative to its "parent".

In this skeleton the three bones are parented in a linear way. But as you can imagine, following the rules stated for child-parent, a bone can have more than one child but not more than one parent.
That means that defined a bone in the skeleton, there is only one sequence of parents to reach the root parent of the skeleton. Also it means too that one root bone defines one skeleton so each skeleton has only one root bone and only one.

Consider this: B3 is child of B2 and B2 is child of B1. Also B4 is child of B2 and B5 is child of B4. The way to travel from B5 to B1 is unique: B5->B4->B2->B1.

=== Setup and Animation ===

During the animation of the skeleton it is supposed that the position of each bone, its angle and its scale changes. Position and angle are relative to the parent bone, but scale is a value that calculates the current length of the bone compared with the "original" bone length (scale=length'/length) as you can see from the original formulas in the previous section. That means that the "original" bone length shouldn't be never zero, otherwise there will be a division by zero and the scale of the bone becomes infinite.

Also, the final position P' of a point that moves influenced by a single bone is given by the original point position relative to the bone in its "original" position (P).

What I'm trying to explain is that it is needed that the setup of the bone (position, alpha and length) and the setup position of the point (P) to be moved would be given to calculate the final position of the point (P') given a moved position of the bone (position', alpha', length')

Said this and considered the information of the previous sections, the bones and points that are influenced from the bones should have the following parameters:

'''BONES PARAMETERS'''
{|
! Parameter !! Notation !! Type !! Animated !! Comment
|-
| Origin ||<math> \textstyle O_j(t) </math> || Vector (Real,Real) ||Yes|| Relative to the parent
|-
| Angle || <math> \textstyle \alpha_j(t) </math> || Angle (DEG) ||Yes|| Relative to the parent
|-
| Length || <math> \textstyle l_j(t) </math> || Real ||Yes|| Calculated, not animatable.
|-
| Scale || <math> \textstyle s_j(t) </math> || Real ||Yes|| <math> \textstyle l_j(t) =l^0_j \cdot s_j(t) </math>
|-
| Setup Origin || <math> \textstyle O^0_j(t) </math> || Vector (Real,Real) ||Yes|| Relative to the parent
|-
| Setup Angle || <math> \textstyle \alpha^0_j(t) </math> || Angle (DEG) ||Yes|| Relative to the parent
|-
| Setup Length || <math> \textstyle l^0_j </math> || Real || No|| Constant, zero not allowed.
|-
| Setup Scale || <math> \textstyle s^0_j </math> || Real || No|| <math> \textstyle s^0_j = 1 </math>
|-
| Parent || <math> \textstyle PBone_j(t) </math> || Bone ||Yes||
|}

'''POINT PARAMETERS'''

{|
! Parameter !! Notation !! Type !! Animated !! Comment
|-
| Position ||<math> \textstyle V(t) </math> || Vector (Real,Real) ||Yes|| Calculated: <math> \textstyle V(t) =VF(t) + VS(t) \cdot M(t) </math> Global coordinates
|-
| Free Position ||<math> \textstyle VF(t) </math> || Vector (Real, Real) ||Yes|| Global Coordinates
|-
| Setup Position ||<math> \textstyle VS(t) </math> || Vector (Real, Real) ||Yes|| Global Coordinates
|-
| Bone Influence Matrix ||<math> \textstyle M(t) </math> || Matrix (3x3) ||Yes|| Calculated. See formulas below
|-
| Bone Influence Id ||<math> \textstyle BoneID_i </math> || Bone || No || 'i' is the index for all the Bones that influences on the Point
|-
| Influence weight ||<math> \textstyle w_i </math> || Real || Yes || the weight associated to the BoneID_i
|}

(t) denotes ''calculated at the time t''

=== Position of a Point due to Bones Influence ===

According to the table, the final position of a point influenced by the bones is calculated based on two terms: A free movement of the point plus a bone drive movement. In this section we are going to calculate the second term.

<math> \textstyle V(t) =VF(t) + VS(t) \cdot M(t) </math>

<math> M(t) = \cfrac{\sum_{i=1}^N M_i(t) \cdot w_i(t)}{\sum_{i=1}^N w_i(t)} </math>

<math> M_i(t)=B^0_i(t) \cdot B_i(t) </math>

where i is a index that runs all the Bones Influence ID from i=1 to N (N= total number of bones that influence to the point)

<math> B^0_i(t)= \prod_{j=bone}^{j=root} C_j^0(t)</math>

<math> B_i(t)= \prod_{j=root}^{j=bone} C_j(t)</math>

where 'j' runs the bone skeleton jumping from a child/parent bone to a parent/child bone each time. The travel of the index 'j' from ''bone'' to ''root'' and from ''root'' to ''bone'' is fixed -and unique- by the nature of skeletons constructions (a bone, a parent), as mentioned before.

<math> C_j^0(t) = T(-O_j^0(t)) \cdot R(-\alpha_j^0(t)) \cdot S_x(\frac{1}{s^0_j})</math>

This matrix calculates the position of the point in local coordinates in relation to the bone 'j' at setup position. Notice that <math> s^0_j </math> is equal to <math> \textstyle 1 </math> for any bone and for any time.

<math> C_j(t) = S_x(s_j(t))\cdot R(\alpha_j(t)) \cdot T(O_j(t)) </math>

This matrix calculates the global position of the point due to the bone 'j' at animated position of the skeleton.

=== Calculate the position and angle of a bone in a skeleton ===

==== Position and Angle at Setup ====

If the bones are described using relative coordinates to its predecessor, the position <math>\textstyle Q^0_j</math> and the angle <math>\textstyle \beta^0_j</math> of the bone 'j' in relation to the "master root bone" (ie. the global coordinate system) is given by those equations:

<math>Q^0_j(t) = O^0_j(t) \cdot B^0_j(t)</math>

<math>\beta^0_j(t) = \sum_{i=j}^{root} \alpha^0_i(t)</math>

where

<math>B^0_j(t)=\prod_{i=parent}^{root} B^0_i(t)</math>

where 'i' goes form the parent of the bone 'j' and climbs up by one parent each time until it reaches the 'root' bone of the skeleton.

<math>B^0_i(t)= T(-O^0_i(t)) \cdot R(-\alpha^0_i(t)) \cdot S_x(\frac{1}{s^0_j})</math>

<math>B^0_i(t)</math> is the inverse matrix transformation of the position of the bone relative to its immediate parent.

Notice that at setup, <math>s^0_j</math> is always equal to 1.

====Animated Position and Angle ====

Once calculated the position and angle of a bone in global coordinates you can calculate its animated position and angle by the transformation of their parents in the skeleton.

<math>Q_j(t) = O^0_j(t) \cdot B^0_j(t) \cdot B_j(t)</math>

<math>\beta_j(t)= \beta^0_j(t) + \sum_{i=root}^{parent} \alpha_i(t)</math>

where <math>B_j(t)=\prod_{i=root}^{parent} B_i(t)</math>

where 'i' goes form the root bone and jumps down by one child each time until it reaches the 'parent' bone of the bone 'j'.

<math>B_i(t)= S_x(s_j(t)) \cdot R(\alpha_i(t)) \cdot T(O_i(t)) </math>

<math>\textstyle B_i(t)</math> is the transformation matrix of the position of the bone 'j' at the time t.

The results <math>\textstyle Q_j(t), \beta_j(t)</math> are obtained in global coordinates.

Dev:Bone Layer

2008-11-30T11:26:52Z

Dooglus: /* Can Points (Bone influenced) be moved independently? */

== Initial seed for concepts ==

[http://dooglus.rincevent.net/synfig/logs/2008/%23synfig-2008-11-12.log This portion] of IRC logs sets the basis for the implementation of a Bone Layer. The interesting part is from 16:49 to 18:56.

Also [http://dooglus.rincevent.net/synfig/logs/2008/%23synfig-2008-11-13.log this one] has some interesting thoughts. From 8:20 to 14:43

== Concepts ==
This is an unsorted list of concepts to let me clarify my thoughts and also allow others to understand the following sections.

=== Bones intentions ===
Initial intention of Bones is to attempt to emulate the skeleton of a vertebrate animal. In this way you have the skin and a skeleton. Part of the skin are associated with the various bones of the skeleton. When the skeleton moves the skin follows.

=== Application of bones in animation ===
In traditional animation producing a walk cycle implies drawing each keyframe for the walk and maybe, depending on the walking speed, drawing the in betweens too. To avoid having to draw the in between images there are tweening animation programs (like Synfig) to help the animator. Then the animator just needs to draw the keyframes and the application does the rest. That's quite good but in certain situations you see your self redrawing the same pose (with small variations) frequently at different times. Then bones come to help. They aid the animator in the following manner.

* With the manipulation of a single object (or a set of them) you can manage a lot of points of the drawing definition.
* Rotations of drawings using keyframes needs lots of them (by nature of the fact that tweening is defined in the x,y coordinates system and the rotation is performed in the angle, radius coordinate system). Using bones you can perform rotations of large angles with just two waypoints. Also since characters have limbs and limbs in living beings do mainly rotations, the usage of bones becomes handy in that kind of animation.
* Once the character (or whatever thing that uses bones) is rigged (the skeleton structure is created and the relationship between it and the skin is defined) it is possible to produce different kinds of keyframes for different purposes: Walk, run, jump, sit, ...

== How can we do implement this? ==
The relationship between the skeleton and the skin is like this:

*The Skin is made using Points and BLines. BLines are defined by Points. Points are made of Vertexes and Tangents
*Skeleton is made of bones and the relationships between them.
*''If Bones would have influence on the Vertexes and Tangents then the bones movements would move the points and therefore the skin would be moved''.

That's the key, if we understand how a bone has influence on a vertex and a tangent then we can find the way a skeleton can have influence over a skin.

=== Bones Properties ===
From my experience with bones in other 2D animation applications, watching the strong and weak points, bones needs to have the following properties:

* A bone has an origin point about which the rotation is performed.
* A bone has a length.
* A bone has an angle.
* A bone can have a region of influence.
* A bone can have a one or zero parent bones.
* A bone can have one or more child bones.
* A skeleton is defined as a connected set of bones (consisting of exactly one parent-less bone and its children bones and their descendants).

All the bones in a Synfig Document can produce several distinct skeletons (depending on how many parent-less bones are in it).

=== How does a Vertex move under the influence of a single Bone? ===

Conceptually a bone has influence over a point by doing [http://en.wikipedia.org/wiki/Affine_transformation affine transformations] of its position according to the bone values. See also [http://en.wikipedia.org/wiki/Transformation_matrix transformation matrix]. A bone produces rotation, scale and translation to a point in this way:

[[Image:Bonesimulation2.png]]

As you can see the values that produce the movement of the point P to the point P' are given by:

*Translation of the bone: O'-O
*Rotation of the bone: <math>\alpha'-\alpha</math>
*Scale of the bone: s=length'/length

Then, given a Point P in the 2D space and knowing the translation, rotation and scale of the bone you can calculate the new position P' using this formula:

<math>
T(-O)=\begin{bmatrix}
1 & 0 & 0 \\
0 & 1 & 0 \\
-O_x & -O_y & 1
\end{bmatrix}
</math> Translation to origin (0,0)

<math>
R(-\alpha)=\begin{bmatrix}
\cos(-\alpha) & \sin(-\alpha) & 0 \\
-\sin(-\alpha) & \cos(-\alpha) & 0 \\
0 & 0 & 1
\end{bmatrix}
</math> Rotate by an angle of amount '<math>-\alpha</math>' about the origin. That aligns the bone with the X axis

<math>
S_x(length'/length)=\begin{bmatrix}
length'/length & 0 & 0 \\
0 & 1 & 0 \\
0 & 0 & 1
\end{bmatrix}
</math> Scale by a value of 's=length'/length' in the direction of X (the current direction of the bone).

<math>
R(\alpha^')=\begin{bmatrix}
\cos(\alpha^') & \sin(\alpha^') & 0 \\
-\sin(\alpha^') & \cos(\alpha^') & 0 \\
0 & 0 & 1
\end{bmatrix}
</math> Rotate by an angle of amount '<math>\alpha'</math>' about the origin.

<math>
T(O^')=\begin{bmatrix}
1 & 0 & 0 \\
0 & 1 & 0 \\
O^'_x & O^'_y & 1
\end{bmatrix}
</math> Translation to new position O'

Then the transformation from P to P' is given by the matrix multiplication:

<math> P'=P\cdot T(-O)\cdot R(-\alpha)\cdot S_x(length'/length)\cdot R(\alpha^')\cdot T(O^')</math>

<math> P'=P\cdot T\cdot R\cdot S_x\cdot R'\cdot T'=P\cdot B</math>

=== Can Points (Bone influenced) be moved independently? ===

Yes, they should be. If not the animator is restricted to only doing the animation with bones which would lead to some insoluble problems during the animation. Considering this, the point position result comes from the addition of two terms:
*(a) The movement of the point as described by the influence of the bone(s): P(B)
*(b) The free movement of the point in the 2D space. P(animated)

In terms of the interface with the user, the value P(animated) is just obtained in this way:

#In any position of the time line (bones are animated) the point has a position given by the influence of the bones: P(B).
#The user wrap a point, drags it, placing it at P'.
#The final position of the point is P' but the user cannot modify the first term P(B) so the second term (b) becomes: P(animated)=P'-P(B).

===What happen if there are more than one bone affecting the point?===

The first thing you can think when you deal with more than one bone making influence over the same point is to calculate the average of the sum of the influences of all bones. So if there are N bones affecting to the point then we can think on sum all the resulting points from each bone and then divide the result by N to not scale the result.

<math> B=\frac{\sum_{k=1}^N B_k}{N} </math>

Where <math>B_k</math> is the bone matrix for the bone ''k'' on the point P.

That's fine but I would like to have more control to the way the bones affects to the points. When you move a bone it looks reasonable that not all the points are influence in the same way. This can be solved by using "weighted" average instead of a plain one. That means give different amount of influence to one bone than to other.

<math> B=\frac{\sum_{k=1}^N B_k \cdot w_k}{\sum_{k=1}^N w_k} </math>

Where <math>w_k</math> is the weight for the bone ''k'' over the point P.

=== Skeleton ===

A skeleton is a set of bones linked one to others in a tree hierarchy. A bone can have several children (or none) but only one parent (or none). This configuration allows to do a easy calculation of the forward kinematic (FK )of the chain and the inverse kinematic (IK) of the chain of bones. If the hierarchy were not tree type then the FK and IK can be not soluble.

For those IK and FK calculations it is good to have the bone referenced to its parent. So the parameters of the bone are described as relative to the parent bone. The parent bone defines a local coordinate system where the origin of the coordinate system lies on the Origin of the bone and the tip of the bone is pointing to the positive direction of the X axis.

[[Image: skeleton.png]]

As you can see in this image, each skeleton position and orientation is defined by the relative position of its immediate parent bone. In the diagram bone3 is a child of bone2 and bone 2 is a child of bone1. The bone 1 is the root parent bone but you can imagine it attached to a "master root bone" (defined by the origin of coordinates -red circumference- and the horizontal) so it can be said that the bone1 has its origin and angle defined relative to its "parent".

In this skeleton the three bones are parented in a linear way. But as you can imagine, following the rules stated for child-parent, a bone can have more than one child but not more than one parent.
That means that defined a bone in the skeleton, there is only one sequence of parents to reach the root parent of the skeleton. Also it means too that one root bone defines one skeleton so each skeleton has only one root bone and only one.

Consider this: B3 is child of B2 and B2 is child of B1. Also B4 is child of B2 and B5 is child of B4. The way to travel from B5 to B1 is unique: B5->B4->B2->B1.

=== Setup and Animation ===

During the animation of the skeleton it is supposed that the position of each bone, its angle and its scale changes. Position and angle are relative to the parent bone, but scale is a value that calculates the current length of the bone compared with the "original" bone length (scale=length'/length) as you can see from the original formulas in the previous section. That means that the "original" bone length shouldn't be never zero, otherwise there will be a division by zero and the scale of the bone becomes infinite.

Also, the final position P' of a point that moves influenced by a single bone is given by the original point position relative to the bone in its "original" position (P).

What I'm trying to explain is that it is needed that the setup of the bone (position, alpha and length) and the setup position of the point (P) to be moved would be given to calculate the final position of the point (P') given a moved position of the bone (position', alpha', length')

Said this and considered the information of the previous sections, the bones and points that are influenced from the bones should have the following parameters:

'''BONES PARAMETERS'''
{|
! Parameter !! Notation !! Type !! Animated !! Comment
|-
| Origin ||<math> \textstyle O_j(t) </math> || Vector (Real,Real) ||Yes|| Relative to the parent
|-
| Angle || <math> \textstyle \alpha_j(t) </math> || Angle (DEG) ||Yes|| Relative to the parent
|-
| Length || <math> \textstyle l_j(t) </math> || Real ||Yes|| Calculated, not animatable.
|-
| Scale || <math> \textstyle s_j(t) </math> || Real ||Yes|| <math> \textstyle l_j(t) =l^0_j \cdot s_j(t) </math>
|-
| Setup Origin || <math> \textstyle O^0_j(t) </math> || Vector (Real,Real) ||Yes|| Relative to the parent
|-
| Setup Angle || <math> \textstyle \alpha^0_j(t) </math> || Angle (DEG) ||Yes|| Relative to the parent
|-
| Setup Length || <math> \textstyle l^0_j </math> || Real || No|| Constant, zero not allowed.
|-
| Setup Scale || <math> \textstyle s^0_j </math> || Real || No|| <math> \textstyle s^0_j = 1 </math>
|-
| Parent || <math> \textstyle PBone_j(t) </math> || Bone ||Yes||
|}

'''POINT PARAMETERS'''

{|
! Parameter !! Notation !! Type !! Animated !! Comment
|-
| Position ||<math> \textstyle V(t) </math> || Vector (Real,Real) ||Yes|| Calculated: <math> \textstyle V(t) =VF(t) + VS(t) \cdot M(t) </math> Global coordinates
|-
| Free Position ||<math> \textstyle VF(t) </math> || Vector (Real, Real) ||Yes|| Global Coordinates
|-
| Setup Position ||<math> \textstyle VS(t) </math> || Vector (Real, Real) ||Yes|| Global Coordinates
|-
| Bone Influence Matrix ||<math> \textstyle M(t) </math> || Matrix (3x3) ||Yes|| Calculated. See formulas below
|-
| Bone Influence Id ||<math> \textstyle BoneID_i </math> || Bone || No || 'i' is the index for all the Bones that influences on the Point
|-
| Influence weight ||<math> \textstyle w_i </math> || Real || Yes || the weight associated to the BoneID_i
|}

(t) denotes ''calculated at the time t''

=== Position of a Point due to Bones Influence ===

According to the table, the final position of a point influenced by the bones is calculated based on two terms: A free movement of the point plus a bone drive movement. In this section we are going to calculate the second term.

<math> \textstyle V(t) =VF(t) + VS(t) \cdot M(t) </math>

<math> M(t) = \cfrac{\sum_{i=1}^N M_i(t) \cdot w_i(t)}{\sum_{i=1}^N w_i(t)} </math>

<math> M_i(t)=B^0_i(t) \cdot B_i(t) </math>

where i is a index that runs all the Bones Influence ID from i=1 to N (N= total number of bones that influence to the point)

<math> B^0_i(t)= \prod_{j=bone}^{j=root} C_j^0(t)</math>

<math> B_i(t)= \prod_{j=root}^{j=bone} C_j(t)</math>

where 'j' runs the bone skeleton jumping from a child/parent bone to a parent/child bone each time. The travel of the index 'j' from ''bone'' to ''root'' and from ''root'' to ''bone'' is fixed -and unique- by the nature of skeletons constructions (a bone, a parent), as mentioned before.

<math> C_j^0(t) = T(-O_j^0(t)) \cdot R(-\alpha_j^0(t)) \cdot S_x(\frac{1}{s^0_j})</math>

This matrix calculates the position of the point in local coordinates in relation to the bone 'j' at setup position. Notice that <math> s^0_j </math> is equal to <math> \textstyle 1 </math> for any bone and for any time.

<math> C_j(t) = S_x(s_j(t))\cdot R(\alpha_j(t)) \cdot T(O_j(t)) </math>

This matrix calculates the global position of the point due to the bone 'j' at animated position of the skeleton.

=== Calculate the position and angle of a bone in a skeleton ===

==== Position and Angle at Setup ====

If the bones are described using relative coordinates to its predecessor, the position <math>\textstyle Q^0_j</math> and the angle <math>\textstyle \beta^0_j</math> of the bone 'j' in relation to the "master root bone" (ie. the global coordinate system) is given by those equations:

<math>Q^0_j(t) = O^0_j(t) \cdot B^0_j(t)</math>

<math>\beta^0_j(t) = \sum_{i=j}^{root} \alpha^0_i(t)</math>

where

<math>B^0_j(t)=\prod_{i=parent}^{root} B^0_i(t)</math>

where 'i' goes form the parent of the bone 'j' and climbs up by one parent each time until it reaches the 'root' bone of the skeleton.

<math>B^0_i(t)= T(-O^0_i(t)) \cdot R(-\alpha^0_i(t)) \cdot S_x(\frac{1}{s^0_j})</math>

<math>B^0_i(t)</math> is the inverse matrix transformation of the position of the bone relative to its immediate parent.

Notice that at setup, <math>s^0_j</math> is always equal to 1.

====Animated Position and Angle ====

Once calculated the position and angle of a bone in global coordinates you can calculate its animated position and angle by the transformation of their parents in the skeleton.

<math>Q_j(t) = O^0_j(t) \cdot B^0_j(t) \cdot B_j(t)</math>

<math>\beta_j(t)= \beta^0_j(t) + \sum_{i=root}^{parent} \alpha_i(t)</math>

where <math>B_j(t)=\prod_{i=root}^{parent} B_i(t)</math>

where 'i' goes form the root bone and jumps down by one child each time until it reaches the 'parent' bone of the bone 'j'.

<math>B_i(t)= S_x(s_j(t)) \cdot R(\alpha_i(t)) \cdot T(O_i(t)) </math>

<math>\textstyle B_i(t)</math> is the transformation matrix of the position of the bone 'j' at the time t.

The results <math>\textstyle Q_j(t), \beta_j(t)</math> are obtained in global coordinates.

Dev:Bone Layer

2008-11-30T11:19:33Z

Dooglus: /* How does a Vertex move under the influence of a single Bone? */

== Initial seed for concepts ==

[http://dooglus.rincevent.net/synfig/logs/2008/%23synfig-2008-11-12.log This portion] of IRC logs sets the basis for the implementation of a Bone Layer. The interesting part is from 16:49 to 18:56.

Also [http://dooglus.rincevent.net/synfig/logs/2008/%23synfig-2008-11-13.log this one] has some interesting thoughts. From 8:20 to 14:43

== Concepts ==
This is an unsorted list of concepts to let me clarify my thoughts and also allow others to understand the following sections.

=== Bones intentions ===
Initial intention of Bones is to attempt to emulate the skeleton of a vertebrate animal. In this way you have the skin and a skeleton. Part of the skin are associated with the various bones of the skeleton. When the skeleton moves the skin follows.

=== Application of bones in animation ===
In traditional animation producing a walk cycle implies drawing each keyframe for the walk and maybe, depending on the walking speed, drawing the in betweens too. To avoid having to draw the in between images there are tweening animation programs (like Synfig) to help the animator. Then the animator just needs to draw the keyframes and the application does the rest. That's quite good but in certain situations you see your self redrawing the same pose (with small variations) frequently at different times. Then bones come to help. They aid the animator in the following manner.

* With the manipulation of a single object (or a set of them) you can manage a lot of points of the drawing definition.
* Rotations of drawings using keyframes needs lots of them (by nature of the fact that tweening is defined in the x,y coordinates system and the rotation is performed in the angle, radius coordinate system). Using bones you can perform rotations of large angles with just two waypoints. Also since characters have limbs and limbs in living beings do mainly rotations, the usage of bones becomes handy in that kind of animation.
* Once the character (or whatever thing that uses bones) is rigged (the skeleton structure is created and the relationship between it and the skin is defined) it is possible to produce different kinds of keyframes for different purposes: Walk, run, jump, sit, ...

== How can we do implement this? ==
The relationship between the skeleton and the skin is like this:

*The Skin is made using Points and BLines. BLines are defined by Points. Points are made of Vertexes and Tangents
*Skeleton is made of bones and the relationships between them.
*''If Bones would have influence on the Vertexes and Tangents then the bones movements would move the points and therefore the skin would be moved''.

That's the key, if we understand how a bone has influence on a vertex and a tangent then we can find the way a skeleton can have influence over a skin.

=== Bones Properties ===
From my experience with bones in other 2D animation applications, watching the strong and weak points, bones needs to have the following properties:

* A bone has an origin point about which the rotation is performed.
* A bone has a length.
* A bone has an angle.
* A bone can have a region of influence.
* A bone can have a one or zero parent bones.
* A bone can have one or more child bones.
* A skeleton is defined as a connected set of bones (consisting of exactly one parent-less bone and its children bones and their descendants).

All the bones in a Synfig Document can produce several distinct skeletons (depending on how many parent-less bones are in it).

=== How does a Vertex move under the influence of a single Bone? ===

Conceptually a bone has influence over a point by doing [http://en.wikipedia.org/wiki/Affine_transformation affine transformations] of its position according to the bone values. See also [http://en.wikipedia.org/wiki/Transformation_matrix transformation matrix]. A bone produces rotation, scale and translation to a point in this way:

[[Image:Bonesimulation2.png]]

As you can see the values that produce the movement of the point P to the point P' are given by:

*Translation of the bone: O'-O
*Rotation of the bone: <math>\alpha'-\alpha</math>
*Scale of the bone: s=length'/length

Then, given a Point P in the 2D space and knowing the translation, rotation and scale of the bone you can calculate the new position P' using this formula:

<math>
T(-O)=\begin{bmatrix}
1 & 0 & 0 \\
0 & 1 & 0 \\
-O_x & -O_y & 1
\end{bmatrix}
</math> Translation to origin (0,0)

<math>
R(-\alpha)=\begin{bmatrix}
\cos(-\alpha) & \sin(-\alpha) & 0 \\
-\sin(-\alpha) & \cos(-\alpha) & 0 \\
0 & 0 & 1
\end{bmatrix}
</math> Rotate by an angle of amount '<math>-\alpha</math>' about the origin. That aligns the bone with the X axis

<math>
S_x(length'/length)=\begin{bmatrix}
length'/length & 0 & 0 \\
0 & 1 & 0 \\
0 & 0 & 1
\end{bmatrix}
</math> Scale by a value of 's=length'/length' in the direction of X (the current direction of the bone).

<math>
R(\alpha^')=\begin{bmatrix}
\cos(\alpha^') & \sin(\alpha^') & 0 \\
-\sin(\alpha^') & \cos(\alpha^') & 0 \\
0 & 0 & 1
\end{bmatrix}
</math> Rotate by an angle of amount '<math>\alpha'</math>' about the origin.

<math>
T(O^')=\begin{bmatrix}
1 & 0 & 0 \\
0 & 1 & 0 \\
O^'_x & O^'_y & 1
\end{bmatrix}
</math> Translation to new position O'

Then the transformation from P to P' is given by the matrix multiplication:

<math> P'=P\cdot T(-O)\cdot R(-\alpha)\cdot S_x(length'/length)\cdot R(\alpha^')\cdot T(O^')</math>

<math> P'=P\cdot T\cdot R\cdot S_x\cdot R'\cdot T'=P\cdot B</math>

=== Can Points (Bone influenced) be moved independently? ===

Yes, they should be. If not the animator is tight to only do the animation with the bones animation what would end to some insoluble problems during the animation. Considered this, the point position result comes from the addition of two terms:
*(a) The movement of the point as described by the influence of the bone(s): P(B)
*(b) The free movement of the point in the 2D space. P(animated)

In terms of the interface with the user, the value P(animated)is just obtained in this way:

#In any position of the time line (bones are animated) the point have a position given by the influence of the bones: P(B).
#The user wrap a point, drags it, placing it at P'.
#The final position of the point is P' but the user cannot modify the first term P(B) so the second term (b) becomes: P(animated)=P'-P(B).

===What happen if there are more than one bone affecting the point?===

The first thing you can think when you deal with more than one bone making influence over the same point is to calculate the average of the sum of the influences of all bones. So if there are N bones affecting to the point then we can think on sum all the resulting points from each bone and then divide the result by N to not scale the result.

<math> B=\frac{\sum_{k=1}^N B_k}{N} </math>

Where <math>B_k</math> is the bone matrix for the bone ''k'' on the point P.

That's fine but I would like to have more control to the way the bones affects to the points. When you move a bone it looks reasonable that not all the points are influence in the same way. This can be solved by using "weighted" average instead of a plain one. That means give different amount of influence to one bone than to other.

<math> B=\frac{\sum_{k=1}^N B_k \cdot w_k}{\sum_{k=1}^N w_k} </math>

Where <math>w_k</math> is the weight for the bone ''k'' over the point P.

=== Skeleton ===

A skeleton is a set of bones linked one to others in a tree hierarchy. A bone can have several children (or none) but only one parent (or none). This configuration allows to do a easy calculation of the forward kinematic (FK )of the chain and the inverse kinematic (IK) of the chain of bones. If the hierarchy were not tree type then the FK and IK can be not soluble.

For those IK and FK calculations it is good to have the bone referenced to its parent. So the parameters of the bone are described as relative to the parent bone. The parent bone defines a local coordinate system where the origin of the coordinate system lies on the Origin of the bone and the tip of the bone is pointing to the positive direction of the X axis.

[[Image: skeleton.png]]

As you can see in this image, each skeleton position and orientation is defined by the relative position of its immediate parent bone. In the diagram bone3 is a child of bone2 and bone 2 is a child of bone1. The bone 1 is the root parent bone but you can imagine it attached to a "master root bone" (defined by the origin of coordinates -red circumference- and the horizontal) so it can be said that the bone1 has its origin and angle defined relative to its "parent".

In this skeleton the three bones are parented in a linear way. But as you can imagine, following the rules stated for child-parent, a bone can have more than one child but not more than one parent.
That means that defined a bone in the skeleton, there is only one sequence of parents to reach the root parent of the skeleton. Also it means too that one root bone defines one skeleton so each skeleton has only one root bone and only one.

Consider this: B3 is child of B2 and B2 is child of B1. Also B4 is child of B2 and B5 is child of B4. The way to travel from B5 to B1 is unique: B5->B4->B2->B1.

=== Setup and Animation ===

During the animation of the skeleton it is supposed that the position of each bone, its angle and its scale changes. Position and angle are relative to the parent bone, but scale is a value that calculates the current length of the bone compared with the "original" bone length (scale=length'/length) as you can see from the original formulas in the previous section. That means that the "original" bone length shouldn't be never zero, otherwise there will be a division by zero and the scale of the bone becomes infinite.

Also, the final position P' of a point that moves influenced by a single bone is given by the original point position relative to the bone in its "original" position (P).

What I'm trying to explain is that it is needed that the setup of the bone (position, alpha and length) and the setup position of the point (P) to be moved would be given to calculate the final position of the point (P') given a moved position of the bone (position', alpha', length')

Said this and considered the information of the previous sections, the bones and points that are influenced from the bones should have the following parameters:

'''BONES PARAMETERS'''
{|
! Parameter !! Notation !! Type !! Animated !! Comment
|-
| Origin ||<math> \textstyle O_j(t) </math> || Vector (Real,Real) ||Yes|| Relative to the parent
|-
| Angle || <math> \textstyle \alpha_j(t) </math> || Angle (DEG) ||Yes|| Relative to the parent
|-
| Length || <math> \textstyle l_j(t) </math> || Real ||Yes|| Calculated, not animatable.
|-
| Scale || <math> \textstyle s_j(t) </math> || Real ||Yes|| <math> \textstyle l_j(t) =l^0_j \cdot s_j(t) </math>
|-
| Setup Origin || <math> \textstyle O^0_j(t) </math> || Vector (Real,Real) ||Yes|| Relative to the parent
|-
| Setup Angle || <math> \textstyle \alpha^0_j(t) </math> || Angle (DEG) ||Yes|| Relative to the parent
|-
| Setup Length || <math> \textstyle l^0_j </math> || Real || No|| Constant, zero not allowed.
|-
| Setup Scale || <math> \textstyle s^0_j </math> || Real || No|| <math> \textstyle s^0_j = 1 </math>
|-
| Parent || <math> \textstyle PBone_j(t) </math> || Bone ||Yes||
|}

'''POINT PARAMETERS'''

{|
! Parameter !! Notation !! Type !! Animated !! Comment
|-
| Position ||<math> \textstyle V(t) </math> || Vector (Real,Real) ||Yes|| Calculated: <math> \textstyle V(t) =VF(t) + VS(t) \cdot M(t) </math> Global coordinates
|-
| Free Position ||<math> \textstyle VF(t) </math> || Vector (Real, Real) ||Yes|| Global Coordinates
|-
| Setup Position ||<math> \textstyle VS(t) </math> || Vector (Real, Real) ||Yes|| Global Coordinates
|-
| Bone Influence Matrix ||<math> \textstyle M(t) </math> || Matrix (3x3) ||Yes|| Calculated. See formulas below
|-
| Bone Influence Id ||<math> \textstyle BoneID_i </math> || Bone || No || 'i' is the index for all the Bones that influences on the Point
|-
| Influence weight ||<math> \textstyle w_i </math> || Real || Yes || the weight associated to the BoneID_i
|}

(t) denotes ''calculated at the time t''

=== Position of a Point due to Bones Influence ===

According to the table, the final position of a point influenced by the bones is calculated based on two terms: A free movement of the point plus a bone drive movement. In this section we are going to calculate the second term.

<math> \textstyle V(t) =VF(t) + VS(t) \cdot M(t) </math>

<math> M(t) = \cfrac{\sum_{i=1}^N M_i(t) \cdot w_i(t)}{\sum_{i=1}^N w_i(t)} </math>

<math> M_i(t)=B^0_i(t) \cdot B_i(t) </math>

where i is a index that runs all the Bones Influence ID from i=1 to N (N= total number of bones that influence to the point)

<math> B^0_i(t)= \prod_{j=bone}^{j=root} C_j^0(t)</math>

<math> B_i(t)= \prod_{j=root}^{j=bone} C_j(t)</math>

where 'j' runs the bone skeleton jumping from a child/parent bone to a parent/child bone each time. The travel of the index 'j' from ''bone'' to ''root'' and from ''root'' to ''bone'' is fixed -and unique- by the nature of skeletons constructions (a bone, a parent), as mentioned before.

<math> C_j^0(t) = T(-O_j^0(t)) \cdot R(-\alpha_j^0(t)) \cdot S_x(\frac{1}{s^0_j})</math>

This matrix calculates the position of the point in local coordinates in relation to the bone 'j' at setup position. Notice that <math> s^0_j </math> is equal to <math> \textstyle 1 </math> for any bone and for any time.

<math> C_j(t) = S_x(s_j(t))\cdot R(\alpha_j(t)) \cdot T(O_j(t)) </math>

This matrix calculates the global position of the point due to the bone 'j' at animated position of the skeleton.

=== Calculate the position and angle of a bone in a skeleton ===

==== Position and Angle at Setup ====

If the bones are described using relative coordinates to its predecessor, the position <math>\textstyle Q^0_j</math> and the angle <math>\textstyle \beta^0_j</math> of the bone 'j' in relation to the "master root bone" (ie. the global coordinate system) is given by those equations:

<math>Q^0_j(t) = O^0_j(t) \cdot B^0_j(t)</math>

<math>\beta^0_j(t) = \sum_{i=j}^{root} \alpha^0_i(t)</math>

where

<math>B^0_j(t)=\prod_{i=parent}^{root} B^0_i(t)</math>

where 'i' goes form the parent of the bone 'j' and climbs up by one parent each time until it reaches the 'root' bone of the skeleton.

<math>B^0_i(t)= T(-O^0_i(t)) \cdot R(-\alpha^0_i(t)) \cdot S_x(\frac{1}{s^0_j})</math>

<math>B^0_i(t)</math> is the inverse matrix transformation of the position of the bone relative to its immediate parent.

Notice that at setup, <math>s^0_j</math> is always equal to 1.

====Animated Position and Angle ====

Once calculated the position and angle of a bone in global coordinates you can calculate its animated position and angle by the transformation of their parents in the skeleton.

<math>Q_j(t) = O^0_j(t) \cdot B^0_j(t) \cdot B_j(t)</math>

<math>\beta_j(t)= \beta^0_j(t) + \sum_{i=root}^{parent} \alpha_i(t)</math>

where <math>B_j(t)=\prod_{i=root}^{parent} B_i(t)</math>

where 'i' goes form the root bone and jumps down by one child each time until it reaches the 'parent' bone of the bone 'j'.

<math>B_i(t)= S_x(s_j(t)) \cdot R(\alpha_i(t)) \cdot T(O_i(t)) </math>

<math>\textstyle B_i(t)</math> is the transformation matrix of the position of the bone 'j' at the time t.

The results <math>\textstyle Q_j(t), \beta_j(t)</math> are obtained in global coordinates.

Dev:Bone Layer

2008-11-29T20:54:52Z

Dooglus: part-way through editing for english

== Initial seed for concepts ==

[http://dooglus.rincevent.net/synfig/logs/2008/%23synfig-2008-11-12.log This portion] of IRC logs sets the basis for the implementation of a Bone Layer. The interesting part is from 16:49 to 18:56.

Also [http://dooglus.rincevent.net/synfig/logs/2008/%23synfig-2008-11-13.log this one] has some interesting thoughts. From 8:20 to 14:43

== Concepts ==
This is an unsorted list of concepts to let me clarify my thoughts and also allow others to understand the following sections.

=== Bones intentions ===
Initial intention of Bones is to attempt to emulate the skeleton of a vertebrate animal. In this way you have the skin and a skeleton. Part of the skin are associated with the various bones of the skeleton. When the skeleton moves the skin follows.

=== Application of bones in animation ===
In traditional animation producing a walk cycle implies drawing each keyframe for the walk and maybe, depending on the walking speed, drawing the in betweens too. To avoid having to draw the in between images there are tweening animation programs (like Synfig) to help the animator. Then the animator just needs to draw the keyframes and the application does the rest. That's quite good but in certain situations you see your self redrawing the same pose (with small variations) frequently at different times. Then bones come to help. They aid the animator in the following manner.

* With the manipulation of a single object (or a set of them) you can manage a lot of points of the drawing definition.
* Rotations of drawings using keyframes needs lots of them (by nature of the fact that tweening is defined in the x,y coordinates system and the rotation is performed in the angle, radius coordinate system). Using bones you can perform rotations of large angles with just two waypoints. Also since characters have limbs and limbs in living beings do mainly rotations, the usage of bones becomes handy in that kind of animation.
* Once the character (or whatever thing that uses bones) is rigged (the skeleton structure is created and the relationship between it and the skin is defined) it is possible to produce different kinds of keyframes for different purposes: Walk, run, jump, sit, ...

== How can we do implement this? ==
The relationship between the skeleton and the skin is like this:

*The Skin is made using Points and BLines. BLines are defined by Points. Points are made of Vertexes and Tangents
*Skeleton is made of bones and the relationships between them.
*''If Bones would have influence on the Vertexes and Tangents then the bones movements would move the points and therefore the skin would be moved''.

That's the key, if we understand how a bone has influence on a vertex and a tangent then we can find the way a skeleton can have influence over a skin.

=== Bones Properties ===
From my experience with bones in other 2D animation applications, watching the strong and weak points, bones needs to have the following properties:

* A bone has an origin point about which the rotation is performed.
* A bone has a length.
* A bone has an angle with the horizontal.
* A bone can have a region of influence.
* A bone can have a one or zero parent bones.
* A bone can have one or more child bones.
* A skeleton is defined as a connected set of bones (consisting of exactly one parent-less bone and its children bones and their descendants).

All the bones in a Synfig Document can produce several distinct skeletons (depending on how many parent-less bones are in it).

=== How does a Vertex move under the influence of a single Bone? ===

Conceptually a bone has influence over a point doing [http://en.wikipedia.org/wiki/Affine_transformation affine transformation] of it position according to the bone values. See also [http://en.wikipedia.org/wiki/Transformation_matrix transformation matrix]. A bone produces rotation, scale and translation to a point in this way:

[[Image:Bonesimulation2.png]]

As you can see the values that produces the movement of the point P to the point P' are given by:

*Translation of the bone: O'-O
*Rotation of the bone: <math>\alpha'-\alpha</math>
*Scale of the bone: s=length'/length

Then, given a Point P in the 2D space and known the translation, rotation and scale of the bone you can calculate the new point position P' using this formulation:

<math>
T(-O)=\begin{bmatrix}
1 & 0 & 0 \\
0 & 1 & 0 \\
-O_x & -O_y & 1
\end{bmatrix}
</math> Translation to origin (0,0)

<math>
R(-\alpha)=\begin{bmatrix}
\cos(-\alpha) & \sin(-\alpha) & 0 \\
-\sin(-\alpha) & \cos(-\alpha) & 0 \\
0 & 0 & 1
\end{bmatrix}
</math> Rotate an angle of amount '<math>-\alpha</math>' around the origin. That aligns the bone with the X axis

<math>
S_x(length'/length)=\begin{bmatrix}
length'/length & 0 & 0 \\
0 & 1 & 0 \\
0 & 0 & 1
\end{bmatrix}
</math> Scale a value of 's=length'/length' in the direction of X (the current direction of the bone).

<math>
R(\alpha^')=\begin{bmatrix}
\cos(\alpha^') & \sin(\alpha^') & 0 \\
-\sin(\alpha^') & \cos(\alpha^') & 0 \\
0 & 0 & 1
\end{bmatrix}
</math> Rotate an angle of amount '<math>\alpha'</math>' around the origin.

<math>
T(O^')=\begin{bmatrix}
1 & 0 & 0 \\
0 & 1 & 0 \\
O^'_x & O^'_y & 1
\end{bmatrix}
</math> Translation to new position O'

Then the transformation from P to P' is give by the matrix multiplication:

<math> P'=P\cdot T(-O)\cdot R(-\alpha)\cdot S_x(length'/length)\cdot R(\alpha^')\cdot T(O^')</math>

<math> P'=P\cdot T\cdot R\cdot S_x\cdot R'\cdot T'=P\cdot B</math>

=== Can Points (Bone influenced) be moved independently? ===

Yes, they should be. If not the animator is tight to only do the animation with the bones animation what would end to some insoluble problems during the animation. Considered this, the point position result comes from the addition of two terms:
*(a) The movement of the point as described by the influence of the bone(s): P(B)
*(b) The free movement of the point in the 2D space. P(animated)

In terms of the interface with the user, the value P(animated)is just obtained in this way:

#In any position of the time line (bones are animated) the point have a position given by the influence of the bones: P(B).
#The user wrap a point, drags it, placing it at P'.
#The final position of the point is P' but the user cannot modify the first term P(B) so the second term (b) becomes: P(animated)=P'-P(B).

===What happen if there are more than one bone affecting the point?===

The first thing you can think when you deal with more than one bone making influence over the same point is to calculate the average of the sum of the influences of all bones. So if there are N bones affecting to the point then we can think on sum all the resulting points from each bone and then divide the result by N to not scale the result.

<math> B=\frac{\sum_{k=1}^N B_k}{N} </math>

Where <math>B_k</math> is the bone matrix for the bone ''k'' on the point P.

That's fine but I would like to have more control to the way the bones affects to the points. When you move a bone it looks reasonable that not all the points are influence in the same way. This can be solved by using "weighted" average instead of a plain one. That means give different amount of influence to one bone than to other.

<math> B=\frac{\sum_{k=1}^N B_k \cdot w_k}{\sum_{k=1}^N w_k} </math>

Where <math>w_k</math> is the weight for the bone ''k'' over the point P.

=== Skeleton ===

A skeleton is a set of bones linked one to others in a tree hierarchy. A bone can have several children (or none) but only one parent (or none). This configuration allows to do a easy calculation of the forward kinematic (FK )of the chain and the inverse kinematic (IK) of the chain of bones. If the hierarchy were not tree type then the FK and IK can be not soluble.

For those IK and FK calculations it is good to have the bone referenced to its parent. So the parameters of the bone are described as relative to the parent bone. The parent bone defines a local coordinate system where the origin of the coordinate system lies on the Origin of the bone and the tip of the bone is pointing to the positive direction of the X axis.

[[Image: skeleton.png]]

As you can see in this image, each skeleton position and orientation is defined by the relative position of its immediate parent bone. In the diagram bone3 is a child of bone2 and bone 2 is a child of bone1. The bone 1 is the root parent bone but you can imagine it attached to a "master root bone" (defined by the origin of coordinates -red circumference- and the horizontal) so it can be said that the bone1 has its origin and angle defined relative to its "parent".

In this skeleton the three bones are parented in a linear way. But as you can imagine, following the rules stated for child-parent, a bone can have more than one child but not more than one parent.
That means that defined a bone in the skeleton, there is only one sequence of parents to reach the root parent of the skeleton. Also it means too that one root bone defines one skeleton so each skeleton has only one root bone and only one.

Consider this: B3 is child of B2 and B2 is child of B1. Also B4 is child of B2 and B5 is child of B4. The way to travel from B5 to B1 is unique: B5->B4->B2->B1.

=== Setup and Animation ===

During the animation of the skeleton it is supposed that the position of each bone, its angle and its scale changes. Position and angle are relative to the parent bone, but scale is a value that calculates the current length of the bone compared with the "original" bone length (scale=length'/length) as you can see from the original formulas in the previous section. That means that the "original" bone length shouldn't be never zero, otherwise there will be a division by zero and the scale of the bone becomes infinite.

Also, the final position P' of a point that moves influenced by a single bone is given by the original point position relative to the bone in its "original" position (P).

What I'm trying to explain you is that it is needed that the setup of the bone (position, alpha and length) and the setup position of the point (P) to be moved would be given to calculate the final position of the point (P') given a moved position of the bone (position', alpha', length')

Said this and considered the information of the previous sections, the bones and points that are influenced from the bones should have the following parameters:

'''BONES PARAMETERS'''
{|
! Parameter !! Notation !! Type !! Animated !! Comment
|-
| Origin ||<math> \textstyle O_j(t) </math> || Vector (Real,Real) ||Yes|| Relative to the parent
|-
| Angle || <math> \textstyle \alpha_j(t) </math> || Angle (DEG) ||Yes|| Relative to the parent
|-
| Length || <math> \textstyle l_j(t) </math> || Real ||Yes|| Calculated, not animatable.
|-
| Scale || <math> \textstyle s_j(t) </math> || Real ||Yes|| <math> \textstyle l_j(t) =l^0_j \cdot s_j(t) </math>
|-
| Setup Origin || <math> \textstyle O^0_j(t) </math> || Vector (Real,Real) ||Yes|| Relative to the parent
|-
| Setup Angle || <math> \textstyle \alpha^0_j(t) </math> || Angle (DEG) ||Yes|| Relative to the parent
|-
| Setup Length || <math> \textstyle l^0_j </math> || Real || No|| Constant, zero not allowed.
|-
| Setup Scale || <math> \textstyle s^0_j </math> || Real || No|| <math> \textstyle s^0_j = 1 </math>
|-
| Parent || <math> \textstyle PBone_j(t) </math> || Bone ||Yes||
|}

'''POINT PARAMETERS'''

{|
! Parameter !! Notation !! Type !! Animated !! Comment
|-
| Position ||<math> \textstyle V(t) </math> || Vector (Real,Real) ||Yes|| Calculated: <math> \textstyle V(t) =VF(t) + VS(t) \cdot M(t) </math> Global coordinates
|-
| Setup Position ||<math> \textstyle VS(t) </math> || Vector (Real, Real) ||Yes|| Absolute Coordinates
|-
| Bone Influence Matrix ||<math> \textstyle M(t) </math> || Matrix (3x3) ||Yes|| Calculated. See formulas below
|-
| Bone Influence Id ||<math> \textstyle BoneID_i </math> || Bone || No || 'i' is the index for all the Bones that influences on the Point
|-
| Influence weight ||<math> \textstyle w_i </math> || Real || Yes || the weight associated to the BoneID_i
|}

(t) denotes ''calculated at the time t''

=== Position of a Point due to Bones Influence ===

According to the table, the final position of a point influenced by the bones is calculated based on two terms: A free movement of the point plus a bone drive movement. In this section we are going to calculate the second term.

<math> \textstyle V(t) =VF(t) + VS(t) \cdot M(t) </math>

<math> M(t) = \cfrac{\sum_{i=1}^N M_i(t) \cdot w_i(t)}{\sum_{i=1}^N w_i(t)} </math>

<math> M_i(t)=B^0_i(t) \cdot B_i(t) </math>

where i is a index that runs all the Bones Influence ID from i=1 to N (N= total number of bones that influence to the point)

<math> B^0_i(t)= \prod_{j=bone}^{j=root} C_j^0(t)</math>

<math> B_i(t)= \prod_{j=root}^{j=bone} C_j(t)</math>

where 'j' runs the bone skeleton jumping from a child/parent bone to a parent/child bone each time. The travel of the index 'j' from ''bone'' to ''root'' and from ''root'' to ''bone'' is fixed -and unique- by the nature of skeletons constructions (a bone, a parent), as mentioned before.

<math> C_j^0(t) = T(-O_j^0(t)) \cdot R(-\alpha_j^0(t)) \cdot S_x(\frac{1}{s^0_j})</math>

This matrix calculates the position of the point in local coordinates in relation to the bone 'j' at setup position. Notice that <math> s^0_j </math> is equal to <math> \textstyle 1 </math> for any bone and for any time.

<math> C_j(t) = S_x(s_j(t))\cdot R(\alpha_j(t)) \cdot T(O_j(t)) </math>

This matrix calculates the global position of the point due to the bone 'j' at animated position of the skeleton.

=== Calculate the position and angle of a bone in a skeleton ===

==== Position and Angle at Setup ====

If the bones are described using relative coordinates to its predecessor, the position <math>\textstyle Q^0_j</math> and the angle <math>\textstyle \beta^0_j</math> of the bone 'j' in relation to the "master root bone" (ie. the global coordinate system) is given by those equations:

<math>Q^0_j(t) = O^0_j(t) \cdot B^0_j(t)</math>

<math>\beta^0_j(t) = \sum_{i=j}^{root} \alpha^0_i(t)</math>

where

<math>B^0_j(t)=\prod_{i=parent}^{root} B^0_i(t)</math>

where 'i' goes form the parent of the bone 'j' and climbs up by one parent each time until it reaches the 'root' bone of the skeleton.

<math>B^0_i(t)= T(-O^0_i(t)) \cdot R(-\alpha^0_i(t)) \cdot S_x(\frac{1}{s^0_j})</math>

<math>B^0_i(t)</math> is the inverse matrix transformation of the position of the bone relative to its immediate parent.

Notice that at setup, <math>s^0_j</math> is always equal to 1.

====Animated Position and Angle ====

Once calculated the position and angle of a bone in global coordinates you can calculate its animated position and angle by the transformation of their parents in the skeleton.

<math>Q_j(t) = O^0_j(t) \cdot B^0_j(t) \cdot B_j(t)</math>

<math>\beta_j(t)= \beta^0_j(t) + \sum_{i=root}^{parent} \alpha_i(t)</math>

where <math>B_j(t)=\prod_{i=root}^{parent} B_i(t)</math>

where 'i' goes form the root bone and jumps down by one child each time until it reaches the 'parent' bone of the bone 'j'.

<math>B_i(t)= S_x(s_j(t)) \cdot R(\alpha_i(t)) \cdot T(O_i(t)) </math>

<math>\textstyle B_i(t)</math> is the transformation matrix of the position of the bone 'j' at the time t.

The results <math>\textstyle Q_j(t), \beta_j(t)</math> are obtained in global coordinates.

Keyboard Shortcuts

2008-11-28T19:33:27Z

Dooglus: delete -> control-delete

[[Category:Permalink]]

Here is a list of some of the keyboard sortcuts you currently have at your disposal. These are the defaults. There is a way to customize these, but it is currently not intuitive. Basically you need to edit the accelrc file in your synfig settings directory.

{| border="1" cellspacing="0" align="center" width="80%"
|'''Keystroke'''||'''Description'''
|-
| <Control>-A || Select all ducks
|-
| <Shift><Control>-A || Select all layers
|-
| <Control>-C || Copy currently selected layer(s) and put them in the clipboard
|-
| <Control>-D || Deselect all ducks
|-
| <Shift><Control>-D || Deselect all layers
|-
| <Control>-G || Toggle grid show
|-
| <Control>-I || Import image
|-
| <Control>-L || Toggle grid snap
|-
| <Control>-N || New composition (since r1386)
|-
| <Control>-O || Open composition (since r1386)
|-
| <Alt>-O || Toggle onion skin (since r1525 - it was Control-O until r1386)
|-
| <Control>-P || Play the current animation in the WorkArea
|-
| <Control>-Q || Quit Synfig Studio
|-
| <Control>-R || Redo
|-
| <Control>-S || Save
|-
| <Control>-V || Paste the layer(s) from the clipboard above the currently selected layer
|-
| <Control>-W || Closes the current animation document.
|-
| <Control>-X || Cut currently selected layer(s) and put them in the clipboard
|-
| <Control>-Z || Undo
|-
| <Control>-` || Toggle low/high-resolution (defaults to low resolution)
|-
| <Control>-0...9 || Change the current rendering quality (lower is better, but 0==10)
|-
| <Alt>-1 || Toggle display of "Position" ducks
|-
| <Alt>-2 || Toggle display of "Vertex" ducks
|-
| <Alt>-3 || Toggle display of "Tangent" ducks
|-
| <Alt>-4 || Toggle display of "Radius" ducks
|-
| <Alt>-5 || Toggle display of "Width" ducks (DEFAULTS TO OFF)
|-
| <Alt>-6 || Toggle display of "Angle" ducks
|-
| <Control>-'-' || Zoom out of canvas (spacial zoom)
|-
| <Control>-'=' || Zoom in on canvas (spacial zoom)
|-
| <Control>-<Shift>-Z || Zoom canvas to 100% (spacial zoom)
|-
| <Control>-'_' || Zoom out of timeline (temporal zoom)
|-
| <Control>-'+' || Zoom in on timeline (temporal zoom)
|-
| <Control>-',' || Move backward one frame
|-
| <Control>-'.' || Move forward one frame (be careful - can step past the end of an animation; fixed in svn r452)
|-
| <Control>-'<' || Move backward one second
|-
| <Control>-'>' || Move forward one second
|-
| <Control>-'[' || Move backward to previous [[Keyframe|keyframe]]
|-
| <Control>-']' || Move forward to next keyframe
|-
| Home || Jump to beginning of timeline (broken; fixed in svn r451)
|-
| End || Jump to end of timeline (broken; fixed in svn r451)
|-
| <Control>-'(' || Decrease workarea pixel size
|-
| <Control>-')' || Increase workarea pixel size
|-
| <Control>-<Alt>-'(' || Decrease 'amount' of selected layer
|-
| <Control>-<Alt>-')' || Increase 'amount' of selected layer
|-
| <Shift>-PgUp || Raise currently selected layers
|-
| <Shift>-PgDn || Lower currently selected layers
|-
| <Alt>-A || Select 'normal' tool
|-
| <Alt>-V || Select 'smooth move' tool (shortcut added in svn r548)
|-
| <Alt>-S || Select 'scale' tool (shortcut changed in svn r1985)
|-
| <Alt>-T || Select 'rotate' tool (shortcut changed in svn r1985)
|-
| <Alt>-M || Select 'mirror' tool (shortcut added in svn r548)
|-
| <Alt>-C || Select 'circle' tool (shortcut added in svn r548)
|-
| <Alt>-R || Select 'rectangle' tool (shortcut added in svn r548)
|-
| <Alt>-Q || Select 'star' tool (tool and shortcut added in svn r1983)
|-
| <Alt>-G || Select 'gradient' tool
|-
| <Alt>-P || Select 'polygon' tool (shortcut added in svn r548)
|-
| <Alt>-B || Select 'bline' tool
|-
| <Alt>-X || Select 'text' tool (tool and shortcut added in svn r1959)
|-
| <Alt>-F || Select 'fill' tool
|-
| <Alt>-E || Select 'eyedrop' tool
|-
| <Alt>-Z || Select 'zoom' tool
|-
| <Alt>-D || Select 'draw' tool (shortcut changed in svn r2009)
|-
| <Alt>-K || Select 'sketch' tool (shortcut added in svn r548)
|-
| <Alt>-W || Select 'width' tool (shortcut changed in svn r2009)
|-
| F8 || Canvas Properties
|-
| F9 || Render
|-
| F11 || Preview
|-
| F12 || Canvas Options (Grid size, etc.)
|-
| <Escape> || Stop current process. For example: when pressed it leaves the current state (Circle, Rectangle, Star, Gradient, Text, Fill, Eyedrop, Zoom, Draw and Sketch Tools) and returns to the Normal Tool State. Seems to be missing for the rest of Tools.
|-
| <Delete> || Deletes the currently selected canvas. (CAREFUL! There is currently a bug which makes this work in just about any context! ie: if you are editing a parameter and press the delete key, it will delete the layer! this can be easily undone, but just keep it in mind) Since SVN r2303 this has been changed to <Control>-<Delete> to avoid that bug.
|-
| <Cursor Key> || Nudge the currently selected duck(s) one pixel in the given direction
|-
| <Shift>-<Cursor Key> || Nudge the currently selected duck(s) ten pixels in the given direction
|-
| <Backspace> || Select the immediate paste canvas parent (if any) of the current selected layer.
|-
|}

== Hotkeys Visual Guide ==
A good way to learn all this shorcuts is putting them in front of your eyes all the time. Because of that, we bring to you a beatiful "Hotkeys Visual Guide" that you can use as a poster.

<gallery>
Image:hotkeys-visual-guide-SVN2011.png|PNG Version - SVN2011
</gallery>

We offer you two print sizes (both in PDF):
* [http://synfig.org/images/c/cd/Hotkeys-visual-guide-SVN2011-A4.pdf A4 Version]
* [A3 Version]

And these are the source files in SVG format:
* [http://synfig.org/images/e/e1/Hotkeys-visual-guide-SVN2011-A4.svg A4 Version]
* [http://synfig.org/images/c/c2/Hotkeys-visual-guide-SVN2011-A3.svg A3 Version]

Give us your [[Talk:Keyboard_Shortcuts|feedback and comments]].

Focus Point

2008-11-26T23:46:54Z

Dooglus:

[[Category:Parameters]]
The "Focus Point" parameter (added in SVN r2290, not yet released) is present only in the [[Paste Canvas]] layer. It has a Vector value. It defines which point in the encapsulated layers will stay still as the Paste Canvas layer's [[Zoom Parameter]] changes.

The Focus Point is relative to the Paste Canvas layer's [[Origin Parameter]] and defaults to (0,0) so its duck will be hidden behind the green Origin duck initially. Its duck can be seen by turning the Origin ducks off temporarily (by hitting ALT-1) or by editing its value to something small by non-zero in the Params Panel.

It's best to edit the Focus Point parameter while the Paste Canvas' Zoom is set to 0. Otherwise you'll be seeing a scaled version of the contents.

Focus Point

2008-11-26T23:46:31Z

Dooglus:

[[Category:Parameters]]
The "Focus Point" parameter is present only in the [[Paste Canvas]] layer. It has a Vector value. It defines which point in the encapsulated layers will stay still as the Paste Canvas layer's [[Zoom Parameter]] changes.

The Focus Point is relative to the Paste Canvas layer's [[Origin Parameter]] and defaults to (0,0) so its duck will be hidden behind the green Origin duck initially. Its duck can be seen by turning the Origin ducks off temporarily (by hitting ALT-1) or by editing its value to something small by non-zero in the Params Panel.

It's best to edit the Focus Point parameter while the Paste Canvas' Zoom is set to 0. Otherwise you'll be seeing a scaled version of the contents.

Focus Point

2008-11-26T23:45:31Z

Dooglus: New page:  Category:Parameters The "Focus Point" parameter is present only in the Paste Canvas layer. It has a Vector value. It defines which point in the encapsulated lay...

[[Category:Parameters]]
The "Focus Point" parameter is present only in the [[Paste Canvas]] layer. It has a Vector value. It defines which point in the encapsulated layers will stay still as the Paste Canvas layer's Zoom parameter changes.

The Focus Point is relative to the Paste Canvas layer's Origin parameter and defaults to (0,0) so its duck will be hidden behind the green Origin duck initially. Its duck can be seen by turning the Origin ducks off temporarily (by hitting ALT-1) or by editing its value to something small by non-zero in the Params Panel.

It's best to edit the Focus Point parameter while the Paste Canvas' Zoom is set to 0. Otherwise you'll be seeing a scaled version of the contents.

Group Layer

2008-11-26T23:39:39Z

Dooglus: add 'focus point' parameter; mention translate, scale, time offset

[[Category:Parameters]]
[[Image:Pastecanvas_icon.png|64px]]

The Paste Canvas layer is a special layer that can hold other layers. It is generated via the [[Encapsulate]] command accessed via the context menu in the [[Layers Panel]] or through the [[Layer Menu]] in the [[Canvas Menu Caret]]. As well as grouping a set of layers it can also translate them, scale them, and even modify the time for the layers it contains.

Paste Canvas layers can also be created through the [[New Layer Menu]], using New Layer > Other > Paste Canvas.

A Paste Canvas layer has the following parameters:
* [[Z Depth]]
* [[Amount Parameter|Amount]]
* [[Blend Method]]
* [[Origin Parameter|Origin]]
* [[Canvas]]: This is "Inline Canvas" by default if the Paste Canvas layer was created by encapsulating other layers, or "Pasted Canvas" if it was created from the [[New Layer Menu]]. This parameter lets you select another canvas.
* [[Zoom Parameter|Zoom]]
* [[Time Offset Parameter|Time Offset]]
* [[Children Lock]]
* [[Focus Point]] (since SVN r2290)

== Canvas Parameter ==
[[Image:canvas_pointer_icon.png|64px]]

The canvas parameter presents a drop-down menu of the exported canvases, plus an extra entry called "Other...". Selecting "Other..." presents the user with a text entry box asking for the name of the canvas to use. The name typed should have the following format (where <nowiki>[ ]</nowiki> indicates an optional part, ( ) is for grouping, and * means "0 or more times"):

<nowiki> [[</nowiki>''filename''<nowiki>]#][:]</nowiki>''id''(:''id'')*

In its simplest form, this is just an ''id'', ie. the exported name of one of the child canvases of the current canvas.

Other possibilities are:
* if a '#' is present, the part before the '#' is interpreted as the filename of an external .sif file to use.
* if the '#' is the first character of the string (ie. the filename is blank) then the '#' is ignored, and the current canvas is used instead
* if a ':' appears before the first ''id'', it means to start at the root canvas of the current canvas
* each subsequent :id steps down into the specified child

Examples:
* '''/usr/share/doc/synfig/examples/business_card.sifz#:IndividualCard''' -- gives the absolute path to a .sifz file, and says to use the canvas that was exported from its root canvas as "IndividualCard"
* '''../../examples/business_card.sifz#:IndividualCard''' -- the same, but with a relative path to the .sifz file
* '''#:sy:head:eyes:left''' -- look in the current composition, and starting from the root, navigate down through the canvas tree. Find a child canvas of the root canvas called 'sy', look in 'sy' for a child canvas called 'head', and so on.
* ''':sy:head:eyes:left''' -- exactly as above. an empty filename is the same as not using the '#' at all
* '''eyes:left''' -- without a ':' before the first ''id'', this starts at the current canvas (presumably the PasteCanvas in question is in the "head" subcanvas of the "sy" subcanvas of the root)

Zoom Tool

2008-11-25T20:45:07Z

Dooglus: /* Usage */ add drag+CTRL to zoom out; link to mouse shourtcuts; mention CTRL+wheel

[[Category:Tools]]
[[Image:Zoom_icon.png|64px]] <span style="font-size:150%">'''ALT-Z'''</span>

==Description==

The Zoom tool is used to get a closer or far away view of the objects that are being edited in the working area. It doesn't affect to the output render so you don't mind how close or far away are watching your composition that it is rendered as described in the [[render options]]

==Usage==

Click on the Zoom tool button. Then the current status would change to zoom. You can:

* Click anywhere in the working area: it will zoom in to 125% of the current zoom level. The zoom will be centered such that the point clicked on remains in the same place.
* CTRL + click anywhere in the working area: it will zoom out to 80% of the current zoom level. (Notice that 80% of 125 is 100, so zooming in one step and out one step will leave you back at the original zoom level).
* Click at any place and drag to create a rectangle: it will zoom to fit the rectangle in the current working window.
* Click at any place and drag to create a rectangle, holding CTRL as you release the mouse button: it will zoom out to fit the current working window in the rectangle.

Alternatively you can always use the existing [[Mouse_Shortcuts|mouse short cuts]] for that task (CTRL + mouse wheel) or the zoom buttons at the left bottom corners of the working area.

[[Image:Zoom_buttons.png]]

They do following:

* Zoom in to 125% of the current zoom level
* Zoom to 100% (press again and restore last zoom)
* Zoom to fit the window (press again an restore last zoom)
* Zoom out to 80% of the current zoom level

Unit System

2008-11-20T09:16:34Z

Dooglus: pixels per unit isn't fixed

Selecting "[[Toolbox|Toolbox]] > File > [[Setup Dialog|Setup]] > Misc." lets you set the unit system, with choices:
* units (u)
* pixels (px)
* points (pt)
* inches (in)
* metres (m)
* centimeters (cm)
* millimeters (mm)

The conversions are:
* 1cm = 0.01m = 10mm
* 1in = 2.54cm
* 1in = 72pt
* 1u = (image width in pixels)/(image area width)px
* 1in = (res)px

The default document is 480 x 270 pixels and has an image area from (-4,2.25) to (4,-2.25), giving an image area of 8 x 4.5 units, so by default 1 unit is 480 / 8 = 60 pixels.

At an XRes = YRes = 36, 1in = 72pt = 36px = 0.6u.

At an XRes = YRes = 72, 1in = 72pt = 72px = 1.2u.

Another example, linking all 7 units:

72 DPI: (1m = 100cm = 1000mm = 39.37in = 2834.65pt) = (2834.65px = 47.24u)
36 DPI: (1m = 100cm = 1000mm = 39.37in = 2834.65pt) = (1417.32px = 23.62u)

Zoom Tool

2008-11-18T10:57:42Z

Dooglus: /* Usage */

[[Category:Tools]]
[[Image:Zoom_icon.png|64px]] <span style="font-size:150%">'''ALT-Z'''</span>

==Description==

The Zoom tool is used to get a closer or far away view of the objects that are being edited in the working area. It doesn't affect to the output render so you don't mind how close or far away are watching your composition that it is rendered as described in the [[render options]]

==Usage==

Click on the Zoom tool button. Then the current status would change to zoom. You can:

* Click anywhere in the working area: it will zoom in to 125% of the current zoom level. The zoom will be centered such that the point clicked on remains in the same place.
* CTRL + click anywhere in the working area: it will zoom out to 80% of the current zoom level. (Notice that 80% of 125 is 100, so zooming in one step and out one step will leave you back at the original zoom level).
* Click at any place and drag to create a rectangle: it will zoom to fit the rectangle in the current working window.

Alternatively you can always use the existing mouse short cuts for that task or the zoom buttons at the left bottom corners of the working area.

[[Image:Zoom_buttons.png]]

They do following:

* Zoom in 25%
* Zoom to 100% (press again and restore last zoom)
* Zoom to fit the window (press again an restore last zoom)
* Zoom out 20%

Download

2008-11-16T22:25:21Z

Dooglus: /* Releases */ link to forum thread about ubuntu 8.10 problem

<div style="margin-bottom:20px; margin-top:-10px;-moz-border-radius:10px; padding:5px; width:100%; text-align:center; border: 1px solid #a6d577; background: #F8EA85;">We are updating the download page to have the new release available on all platforms</div>

== Disclaimer ==

We are aware that there are lots of features missing in synfig. This software is under development and needs more polishing to become a mature program. Lots of bugs have been killed and now the stability of the program has increased considerably. There are some known issues than occasionally might make you frustrated. Despite this disclaimer there are proofs that the program is completely usable for professional work as demonstrated by some of the works in the [[Gallery]]. Please help us to make a better program in any of its aspects (artwork, translation, wiki improvement, tutorials, finding bugs, sending patches, etc.). We will embrace any of your proposals!.

A special thanks to [http://www.bridgetone.com/ Bridgetone] for hosting our videos and early downloads!

== Download ==

Synfig 0.61.09 is the latest release from the Synfig community. Please read the [[Releases/0.61.09|release notes]] for information about what changed.

[[#source|<img src="http://www.reactos.org/media/pictures/2007/devpack1.png"/>]] [[#windows|<img src="http://www.bibirmer.com/Extensions/windows_icon.png">]] [[#macosx|<img src="http://www.washington.edu/computing/web/images/icon-macos.gif"/>]] [[#ubuntu|<img src="http://www.ubuntu.com/themes/ubuntu07/images/icon-ubuntu.png"/>]] [[#debian|<img src="http://www.winehq.org/images/distro/debian.png"/>]] [[#fink|<img src="http://upload.wikimedia.org/wikipedia/en/thumb/2/25/FinkLogo.jpg/80px-FinkLogo.jpg"/>]] [[#zenwalk|<img src="http://wiki.zenwalk.org/images/thumb/d/dd/CommunityPortal.png/50px-CommunityPortal.png"/>]]
[[#gentoo|<img src="http://fillets.sourceforge.net/img/logo/gentoo.png"/>]]
[[#arch|<img src="http://upload.wikimedia.org/wikipedia/commons/thumb/2/21/Archlinux_logo.svg/48px-Archlinux_logo.svg.png"/>]]
[[#pardus|<img src="http://www.acikbilgi.com/wp-content/pardus.jpg"/>]]
[[#freebsd|<img src="http://albumshaper.sourceforge.net/images/supportedSystems/freebsd.png"/>]]
[[#opensuse|<img src="http://files.opensuse.org/opensuse/en/2/22/Geeko_head_simple.png"/>]]
[[#slackware|<img src="http://www.slackware.com/~msimons/slackware/grfx/shared/slackweb.jpg"/>]]
[[#fedora|<img src="https://www.inteco.es/extfrontinteco/osi/actualizacionesSW/SO/fedora_peq.png
"/>]]
[[#mandriva|<img src="http://www.mandriva.com/archives/var/mdk/storage/images/media/images/star_on_transparent_background/261440-3-eng-US/star_on_transparent_background.png">]]
[[#momonga|<img src="http://www.momonga-linux.org/img/momo_banner.png">]]

=== Licence ===

ETL, synfig and synfigstudio are [[License|licensed]] under the GNU General Public Licence, version 2 or later.

=== Issues ===

<div id="macosx_issues"></div>
'''MacOS X''': '''''Taken offline''''', please see bug [http://sf.net/support/tracker.php?aid=1686495 1686495]. Patches and volunteers to create new packages are welcome. Until someone volunteers, you can [[Building_On_Mac_OS_X|build it yourself]] or install via [[#fink|fink]].

<div id="windows_issues"></div>
'''Windows''': There are [[Security|'''security issues''']] with the dv, imagemagick and ffmpeg targets, please avoid using them to import or render untrusted files.

'''Windows''': Rendering issues may be encountered on Hyperthreaded or multi-core CPUs. Please see the FAQ for [[FAQ#Can_I_do_anything_to_improve_the_stability_of_the_Windows_version_of_Synfig.3F|workaround details]].

=== Releases ===

If you know of any other packages, please add them below or [[Contact|contact]] us and ask for them to be added here.

{|
|-
!align="center"| Type
!align="center"| Links
! Notes
|-
|align="center"| <div id="source"></div>[[Source code]]
|align="center"| [http://sf.net/project/showfiles.php?group_id=144022&package_id=198849 ETL] [http://sf.net/project/showfiles.php?group_id=144022&package_id=158279 synfig] [http://sf.net/project/showfiles.php?group_id=144022&package_id=198850 synfigstudio]
| Please read the [[Build_instructions|build instructions]].
|-
|align="center"| <div id="windows"></div>[http://www.microsoft.com/windows/ Windows]
|align="center"| [http://downloads.sourceforge.net/gladewin32/gtk-2.10.11-win32-1.exe gtk] [http://ftp.gnome.org/pub/gnome/binaries/win32/gtkmm/2.10/gtkmm-win32-runtime-2.10.11-1.exe gtkmm]
[http://downloads.sourceforge.net/synfig/synfig-0.61.09.exe synfig] [http://downloads.sourceforge.net/synfig/synfigstudio-0.61.09.exe synfigstudio]
| Has '''''[[#windows_issues|important issues]]'''''. All four are '''''required''''', see the [http://uk.youtube.com/watch?v=mrDqiRI7fwk install walkthrough video].
|-
|align="center"| <div id="macosx"></div>[http://www.apple.com/macosx/ MacOS X]
|
| '''''Taken offline''''', has [[#macosx_issues|major issues]]
|-
|align="center"| <div id="ubuntu"></div>[http://www.ubuntu.com/ Ubuntu]
|align="center"| [http://packages.ubuntu.com/src:etl etl] [http://packages.ubuntu.com/src:synfig synfig] [http://packages.ubuntu.com/src:synfigstudio synfigstudio]
| Available in Ubuntu 7.04 (Feisty Fawn) and later in universe. For information on Synfig on Ubuntu 8.10 Intrepid Ibex see [http://synfig.org/forums/viewtopic.php?f=13&t=277 this link].
|-
|align="center"| <div id="debian"></div>[http://www.debian.org/ Debian]
|align="center"| [http://packages.debian.org/src:etl etl] [http://packages.debian.org/src:synfig synfig] [http://packages.debian.org/src:synfigstudio synfigstudio]
| Available in Debian 5.0 (lenny) and later in main
|-
|align="center"| <div id="fink"></div>[http://www.finkproject.org/ Fink]
|align="center"| [http://pdb.finkproject.org/pdb/package.php/etl etl] [http://pdb.finkproject.org/pdb/package.php/synfig synfig] [http://pdb.finkproject.org/pdb/package.php/synfigstudio synfigstudio]
| Available in Fink unstable
|-
|align="center"| <div id="momonga"></div>[http://www.momonga-linux.org/ Momonga]
|align="center"| [http://sophie.zarb.org/rpmfind?distrib=Momonga&version=&arch=&search=etl&st=rpmname etl] [http://sophie.zarb.org/rpmfind?distrib=Momonga&version=&arch=&search=synfig&st=rpmname synfig] [http://sophie.zarb.org/rpmfind?distrib=Momonga&version=&arch=&search=synfigstudio&st=rpmname synfigstudio]
| Available in Momonga Linux 5 and later
|-
|align="center"| <div id="zenwalk"></div>[http://www.zenwalk.org/ Zenwalk]
|align="center"| [http://packages.zenwalk.org/?q=ETL&zversion=all etl] [http://packages.zenwalk.org/?q=synfig-core&zversion=all synfig] [http://packages.zenwalk.org/?q=synfig-studio&zversion=all synfigstudio]
| Available in Zenwalk extras
|-
|align="center"| <div id="gentoo"></div>[http://www.gentoo.org Gentoo]
|align="center"| [http://bugs.gentoo.org/show_bug.cgi?id=111277 etl] [http://bugs.gentoo.org/show_bug.cgi?id=111278 synfig] [http://bugs.gentoo.org/show_bug.cgi?id=111279 synfigstudio]
| Available in Gentoo [http://www.gentoo.org/proj/en/sunrise/ Project Sunrise]
|-
|align="center"| <div id="arch"></div>[http://www.archlinux.org/ Arch Linux]
|align="center"| [http://aur.archlinux.org/packages.php?K=VoriaETL etl] [http://aur.archlinux.org/packages.php?K=synfig synfig synfigstudio]
|Available in Arch Linux unsupported
|-
|align="center"| <div id="pardus"></div>[http://www.pardus.org.tr/eng/ Pardus]
|align="center"| [http://packages.pardus.org.tr/contrib/source/etl.html etl] [http://packages.pardus.org.tr/contrib/source/synfig.html synfig] [http://packages.pardus.org.tr/contrib/source/synfigstudio.html synfigstudio]
| Available in Pardus contrib
|-
|align="center"| <div id="freebsd"></div>[http://www.freebsd.org/ FreeBSD]
|align="center"| [http://www.freebsd.org/cgi/url.cgi?ports/devel/etl/pkg-descr etl] [http://www.freebsd.org/cgi/url.cgi?ports/devel/synfig/pkg-descr synfig] [http://www.freebsd.org/cgi/url.cgi?ports/graphics/synfigstudio/pkg-descr synfigstudio]
| Available in FreeBSD ports
|-
|align="center"| <div id="mandriva"></div>[http://www.mandriva.com/ Mandriva]
|align="center"| [http://sophie.zarb.org/rpmfind?distrib=Mandriva&version=&arch=&search=etl&st=rpmname etl] [http://sophie.zarb.org/rpmfind?distrib=Mandriva&version=&arch=&search=synfig&st=rpmname synfig] [http://sophie.zarb.org/rpmfind?distrib=Mandriva&version=&arch=&search=synfigstudio&st=rpmname synfigstudio]
| Available in Mandriva [http://wiki.mandriva.com/en/Policies/SoftwareMedia#.2Fcontrib.2Fbackports /contrib/backports]
|-
|align="center"| <div id="opensuse"></div>[http://www.opensuse.org openSUSE]
|align="center"| [http://packman.links2linux.de/package/etl etl] [http://packman.links2linux.de/package/synfig synfig] [http://packman.links2linux.de/package/synfigstudio synfigstudio]
| Available in [http://packman.links2linux.de/ PackMan]
|-
|align="center"| <div id="slackware"></div>[http://www.slackware.com/ Slackware]
|align="center"| [http://slacky.eu/?searchword=synfig&option=com_search&Itemid=5 etl synfig synfigstudio]
| Available in [http://slacky.eu/ Slacky.eu]
|-
|align="center"| <div id="fedora"></div>[http://fedoraproject.org/ Fedora]
|align="center"| [https://bugzilla.redhat.com/show_bug.cgi?id=428567 etl] [https://bugzilla.redhat.com/show_bug.cgi?id=428568 synfig]
| Available in [https://bugzilla.redhat.com/ Red Hat Bugzilla]
|}

=== Snapshots ===

{|
|-
!align="center"| Type
!align="center"| Links
! Notes
|-
|align="center"| [[Source code]]
|align="center"| [http://synfig.org/code/ETL-svn.tar.gz etl] [http://synfig.org/code/synfig-svn.tar.gz synfig] [http://synfig.org/code/synfigstudio-svn.tar.gz synfigstudio]
| Please read the [[Build_instructions|build instructions]]. Automatically updated daily from SVN.
|-
|align="center"| [http://www.microsoft.com/windows/ Windows]
|align="center"| [http://downloads.sourceforge.net/gladewin32/gtk-2.10.11-win32-1.exe gtk] [http://ftp.gnome.org/pub/gnome/binaries/win32/gtkmm/2.10/gtkmm-win32-runtime-2.10.11-1.exe gtkmm] [http://synfig.org/files/synfig-0.61.09-2167.exe synfig] [http://synfig.org/files/synfigstudio-0.61.09-2167.exe synfigstudio]
| Built occasionally by pxegeek, currently SVN 2167. Has '''''[[#windows_issues|important issues]]'''''. All four are '''''required''''', see the [http://uk.youtube.com/watch?v=mrDqiRI7fwk install walkthrough video].
|-
|align="center"| [http://www.gentoo.org Gentoo]
|align="center"| [[Gentoo_Ebuilds#SVN_Ebuilds|etl synfig synfigstudio]]
|-
|align="center"| [http://fedoraproject.org/ Fedora]
|align="center"| Fedora 8: [http://atrus.mmaa.ru/synfig/#fc etl synfig synfigstudio]<br>
Fedora 7: [http://zelgadis.profusehost.net/blog/tags/download/ etl synfig synfigstudio]
| Built by Atrus and Zelgadis
|-
|align="center"| [http://www.ubuntu.com/ Ubuntu]
|align="center"| [http://dooglus.rincevent.net/synfig/repository/ repositories] for feisty (svn 1513), gutsy (svn 1456), hardy (svn 1514)
| These packages are outdated as of 2 October 2008
|-
|align="center"| [http://www.debian.org/ Debian]
|align="center"| [http://dooglus.rincevent.net/synfig/repository/ repository] for sid (svn 1514)
| These packages are outdated as of 2 October 2008
|}

Dev:Source code

2008-11-14T23:07:22Z

Dooglus: link to the sf.net SVN browser

[[Category:Code]] [[Category:Permalink]]

Hey you! Do you want access to bleeding-edge Synfig? Well, I have good news. Anonymous access to the Synfig Subversion repository for Synfig is now enabled! Here are the URLs to the respective repositories:

* https://synfig.svn.sourceforge.net/svnroot/synfig/ETL/
* https://synfig.svn.sourceforge.net/svnroot/synfig/synfig-core/
* https://synfig.svn.sourceforge.net/svnroot/synfig/synfig-studio/

Sourceforge provides a web interface to [http://synfig.svn.sourceforge.net/viewvc/synfig/ browse the Subversion repository].

From the command line, to check out ETL, synfig-core and synfig-studio, you would type:

svn co https://synfig.svn.sourceforge.net/svnroot/synfig/ETL/trunk/ etl
svn co https://synfig.svn.sourceforge.net/svnroot/synfig/synfig-core/trunk/ synfig-core
svn co https://synfig.svn.sourceforge.net/svnroot/synfig/synfig-studio/trunk/ synfig-studio

You can also download a [http://synfig.org/code/synfig-svn-checkout.tar.gz daily updated svn checkout] that you can update using svn up. This was created using a [[Subversion|procedure]] by [[User:Dooglus|dooglus]].

You can also download daily updated svn exports for [http://synfig.org/code/ETL-svn.tar.gz ETL], [http://synfig.org/code/synfig-svn.tar.gz synfig], [http://synfig.org/code/synfigstudio-svn.tar.gz synfigstudio].

Once you grab the code, you will need to bootstrap the build environment and then [[Build instructions|build the code]].

Commit notifications are sent to [http://cia.vc/stats/project/synfig CIA] and show up in the [[Contact|IRC channel]].

While you are browsing the code, you may wish to refer to these links:

* [[Source Outline|source code outline]]
* [[Source Glossary|source code glossary]]
* [http://synfig.org/api/ API documentation]
* [[Source:ETL_make_check|ETL make check failures]]
* [[Source:Layers|Mapping between layer types, classes and .cpp files]]
* [[Source:class_ValueNode|ValueNode types]]
* [[Source:BlendMethods|Blend Method enumeration values]]

== GIT ==

We are trialling [http://git.or.cz/ git] and may switch to it:

git clone git://synfig.org/git/ETL.git
git clone git://synfig.org/git/synfig.git
git clone git://synfig.org/git/synfigstudio.git

People behind restrictive firewalls may be able to use these instead:

git clone http://synfig.org/git/ETL.git
git clone http://synfig.org/git/synfig.git
git clone http://synfig.org/git/synfigstudio.git

People with commit access should use these commands instead:

git clone git@synfig.org:ETL.git
git clone git@synfig.org:synfig.git
git clone git@synfig.org:synfigstudio.git

You can also check out the [http://synfig.org/gitweb/ web interface] to these repositories.

Also, dooglus maintains a git-svn repository of synfig and has a [http://kibi.dyndns.org:8083/~dooglus/gitweb.pl?p=synfig;a=summary gitweb interface] for it.

Proposed git workflow:

* Do all work on the '''master''' branch
* Latest stable releases should be tagged with '''stable-release'''.
* Latest development releases should be tagged with '''devel-release'''.
* All releases should be tagged with their version number (with no extra chars): '''0.61.08'''.
* For now, we don't need a stable release branch, when/if we do:
** Branch the '''stable-release''' tag (or whatever is appropriate) to something like '''0.62'''.
** Cherry-pick commits from the '''master''' branch to the stable branch where possible.
** Commit directly to the stable branch only when cherry-picks are not possible.
* Work on new non-trivial features/fixes on public topic branches where possible
* Obviously commit trivial fixes straight to the '''master''' or the stable branch.
* Rebase & rework branches to keep history more sane, linear and atomic

Proposed set of git repositories:

* admin.git - gitosis admin settings - holds groups, repos and users
* code/* - direct conversions from SVN
** code/ETL.git - ETL
** code/synfig.git - synfig
** code/synfigstudio.git - synfigstudio
* pkg/* - bits for various packaging systems
** pkg/windows.git - Windows packaging (needs separating from the code repos)
** pkg/macos.git - MacOS packaging (needs separating from the code repos)
** pkg/jhbuild.git - JHBuild moduleset (needs writing)
** pkg/autopackage.git - Autopackage bits (needs writing)
* web/* - various bits used to maintain the website
** web/skin.git - skin for the website
** web/content.git - content for the website (pending switch to ikiwiki)
* misc/* - various stuff needed
** misc/svn2git.git - the scripts used to convert the SVN repo to git

Environment Variables

2008-11-10T16:50:09Z

Dooglus: /* Environment Variables */ add SYNFIG_FORCE_TILE_RENDER

== Environment Variables ==

Several environment variables can be set to affect the behavior of Synfig Studio:

{| border="1" cellspacing="0"
|'''variable'''||'''description'''
|-
| SYNFIG_DISABLE_AUTOMATIC_DOCUMENT_CREATION || If no documents are specified when synfig is run, it will create a new blank document unless this variable is set.
|-
| SYNFIG_ENABLE_NEW_CANVAS_EDIT_PROPERTIES || When a new document is created, the [[Canvas Properties Dialog]] will only be shown if this variable is set.
|-
| SYNFIG_DISABLE_OPTIMIZE<br/>SYNFIG_DISABLE_OPTIMIZE_TRANS<br/>SYNFIG_DISABLE_REMOVE_DUPS || These three variables, when set, disable various steps of the animated gif optimization process in the magick++ module. Namely: disable optimization completely, disable optimization of transparent pixels, and disable the removal of adjacent duplicate frames respectively.
|-
| SYNFIG_DISABLE_DRAW<br/>SYNFIG_DISABLE_POLYGON<br/>SYNFIG_DISABLE_SKETCH || These can be used to disable the named tools from being shown in the toolbox.
|-
| SYNFIG_ENABLE_WIDTH || If set, this enables the (mostly broken) width tool in the toolbox.
|-
| SYNFIG_TIMETRACK_HEADER_HEIGHT<br/>SYNFIG_TIMETRACK_ROW_HEIGHT || These are used to change the header and row heights in the timetrack panel. This is sometimes needed to make the timetrack panel rows line up with the parameter panel's rows.
|-
| SYNFIG_DISABLE_POPUP_WINDOWS || When set, this makes the splash screen and "one moment please" popup windows behave like regular windows - ie. they can be minimized, and covered by other windows.
|-
| SYNFIG_DISABLE_TILE_RENDER || When set, the workarea is always rendered using the scanline renderer, rather than being broken up into small square tiles which are rendered separately. This is overridden by SYNFIG_FORCE_TILE_RENDER.
|-
| SYNFIG_FORCE_TILE_RENDER || When set, the workarea is always rendered using the tile renderer, rather than being rendered in a single block. This overrides SYNFIG_DISABLE_TILE_RENDER. (added in SVN r2180)
|-
| SYNFIG_SHOW_TILE_OUTLINES || For debugging, this draws a red outline around each tile when using the tile renderer.
|-
| SYNFIG_ENABLE_POPUP_MENU_IN_ALL_TOOLS || Allow the right-click context menu to be used in all the various tool states.
|-
| SYNFIG_MODULE_LIST || Specifies where to load the list of dynamic modules from.
|-
| SYNFIG_ROOT || Specifies the path to the synfig resources. It should be the directory which contains share/pixmaps/synfigstudio/ - usually /usr or /usr/local.
|-
| SYNFIG_TOOLS_CLEAR_SELECTION || When set, unselect all layers before creating a new layer in any of the tools (other than the draw tool, which always leaves selected layers selected so that their ducks can be linked to).
|-
| SYNFIG_TRANSIENT_DIALOGS || Some window managers fail to associate synfig's panels with the toolbox. Setting this can help. It seems to work quite well on Windows too, preventing the panels from taking up space on the task bar, but be careful not to minimize any of the panels, it can cause problems.
|-
| SYNFIG_DEBUG_DESTRUCTORS || Logs the sequence of destructions that go on when closing things down.
|-
| SYNFIG_SHOW_FULL_TIME_ON_FOCUS || When editing a Time field, start with the full formatted time, ie. "0h 0m 1s 0f" rather than "1s".
|-
| SYNFIG_WINDOW_POSITION_X_OFFSET<br/>SYNFIG_WINDOW_POSITION_Y_OFFSET || Added on to the stored position of each panel when studio starts up. Used to combat the pixel-by-pixel drifting that happens with some window managers.
|-
| SYNFIG_SHOW_CANVAS_PARAM_WAYPOINTS || In PasteCanvas layers, show waypoints for the Canvas parameter itself, rather than for the canvas that is the parameter's value. Experimental. From SVN r1628.
|-
| SYNFIG_KEEP_ABORTED_DRAW_LINES || In the draw tool, if you make a very fast stroke, it's not used. Studio always used to leave the unused stroke on the display until a longer stroke was made. SVN r1689 changed things so that these short strokes are immediately hidden. Setting this variable restores the previous behavior.
|-
| SYNFIG_DISABLE_OPTIMIZE_LAYER_TREE || Before starting to render a tree of layers, Synfig makes an optimized copy of the layer tree, omitting any layers that currently have an amount of 0. The aim is to make the render go faster, but it may introduce some instability into the application. Set this variable to disable the optimization step.
|}

In older versions of studio, the polygon, draw, and sketch tools were disabled by default. The following can be used to re-enable <br>
<code>export SYNFIG_ENABLE_POLYGON=1<br>
export SYNFIG_ENABLE_DRAW=1<br>
export SYNFIG_ENABLE_SKETCH=1<br>
export SYNFIG_ENABLE_WIDTH=1</code>

Suggested starting values to try when attempting to line up the timetrack and parameter panels:<br>
<code>export SYNFIG_TIMETRACK_ROW_HEIGHT=21<br>
export SYNFIG_TIMETRACK_HEADER_HEIGHT=25</code>

Beginning with SVN version r1127<br>
Addressing bug 1829182: the popup caret menu has been disabled for several
tools. There's no comment in the code saying why. Dooglus has added an environment variable which re-enables the popup menu when set. Export
SYNFIG_ENABLE_POPUP_MENU_IN_ALL_TOOLS=1 to try it, and report your findings back
to the bug report as to whether this should be the default or not.

Dev:Build Instructions

2008-11-07T22:44:15Z

Dooglus: /* synfig */ mention the libtool incompatibility

[[Category:Building]]

== Notes ==

If you are using the released versions instead of SVN, none of the libtoolize or autoreconf steps are necessary. For released versions, "./configure && make && sudo make install" should be enough.

If you are using packages for synfig's dependencies, you want the '''development packages''' not the main packages. Check below for your distribution's packages.

Please read the [[Source code|source code]] page to check out the latest code. Please also check the [[Download|download page]] and the [[FAQ]] to find out about any issues that you may run into along the way.

Some Linux/BSD distros have a pkg-config that doesn't look in /usr/local/lib/pkgconfig by default. So if you are installing in anywhere other than the system pkg-config path, please run "export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig" or similar before building or installing anything.

Don't use automake 1.4, there are problems with it.

Using automake 1.9, 'make install' seems to re-link and re-install all the synfig core modules every time whether they have changed or not. [http://dooglus.rincevent.net/synfig/automake.html here] is an ugly workaround - it's only worth using if you intend to rebuild synfig repeatedly

The instructions below result in 3 separate subversion working directories being created. This is inconvenient to work with - you'll need to 'svn commit' in 3 different places to send changes, 'svn update' in 3 different places to get the latest updates, etc. [[Subversion|This page]] shows how to arrange for the code to be checked out into a single working directory. You can also download a daily updated tarball that uses this from the [[Source code|source code]] page.

The CVS requirement is only because the autopoint program run by autoreconf needs CVS. You can avoid the need for CVS by disabling the translation/gettext stuff in configure.ac.

If you don't want to install to a system-wide directory using sudo, run something like these commands before starting:

<pre>
export PREFIX="$HOME/opt"
export PKG_CONFIG_PATH="$PKG_CONFIG_PATH:$PREFIX/lib/pkgconfig"
export PATH="$PATH:$PREFIX/bin"
</pre>

And when you run ./configure, run it with --prefix="$PREFIX" and don't use sudo when you do make install.

=== Automatic build/update script ===

You can use [http://zelgadis.profusehost.net/files/synfig/synfigstudio-svn-build this] script to quickly build/update synfigstudio from SVN (software installed in ~/synfig-svn by default).

To use the script just execute following single command in terminal:
<pre>cd && \
wget http://zelgadis.profusehost.net/files/synfig/synfigstudio-svn-build && \
chmod +x synfigstudio-svn-build && \
./synfigstudio-svn-build initialize</pre>

'''WARNING:''' Your system must satisfy synfig's build requiments, the sript won't do it for you.

=== System-specific instructions ===

* Gentoo: SVN [[Gentoo Ebuilds|ebuilds]] are available
* MacOS X: [[Building_On_Mac_OS_X|instructions for building]] with the GTK+ Aqua port are available.
* Windows: [[Windows build instructions|instructions for building]] in [[Mingw_installation|mingw]] are available.

== ETL ==

ETL is a template library, there is nothing to build really, it just needed to be installed.

Requires: autoconf automake<br>
* Debian: build-essential autoconf automake

''Type the following commands at the directory that holds '''ETL:'''''
<pre>
$ autoreconf --install --force
$ ./configure
$ sudo make install
</pre>

== synfig ==

Requires: ETL, libxml++, libsigc++, libltdl, libtool, gettext, cvs<br>
* Debian: etl-dev libxml++2.6-dev libsigc++-2.0-dev libltdl3-dev libtool gettext cvs
* Gentoo: virtual/ETL dev-cpp/libxmlpp dev-libs/libsigc++ dev-util/cvs
** If you are using ./configure --prefix="$PREFIX" to configure synfig, do not install virtual/ETL.

Note: libpng isn't required to build synfig, but if you build synfig without PNG support and go on to build synfigstudio, that step will fail (because the build process for synfigstudio uses synfig to create .png icon files). The package is libpng12-dev on Debian or media-libs/libpng on Gentoo.

Note: the 'configure.ac' file in the synfig-core directory doesn't work with libtool version 2, as shipped with ubuntu 8.10. To work around the problem until a proper fix is found, comment out line 622 (it says "AC_CONFIG_SUBDIRS(libltdl)") by putting a "#" at the front of the line. The line is required for older versions of libtool, as shipped with other distributions.

Optional: libpng, libmng, libjpeg, libfreetype, libfontconfig, libopenexr, libavcodec, libmagick++, vimage (MacOS only, proprietary)<br>
* Debian: libpng12-dev libmng-dev libjpeg62-dev libfreetype6-dev libfontconfig1-dev libopenexr-dev libavcodec-dev libavformat-dev libmagick++9-dev
* Gentoo: sys-devel/libtool media-libs/libpng media-libs/libmng media-libs/jpeg media-libs/freetype media-libs/fontconfig media-libs/openexr media-libs/libavcodec
Runtime: encodedv (from libdv), ffmpeg, convert (from imagemagick)
* Debian: libdv-bin ffmpeg imagemagick
* Gentoo: media-libs/libdv media-video/ffmpeg media-gfx/imagemagick

''Type the following commands at the directory that holds '''synfig-core:'''''
<pre>
$ libtoolize --ltdl --copy --force
$ autoreconf --install --force
$ ./configure
$ make
$ sudo make install
</pre>

Notes:

* Don't use --enable-half, it is slow.

== synfigstudio ==

Requires: ETL, synfig, gtkmm >= 2.4, gtk >= 2.0, glibmm, libsigc++, libltdl, libtool, gettext, cvs<br>
* Debian: etl-dev libsynfig-dev libgtkmm-2.4-dev libgtk2.0-dev libglibmm-2.4-dev libsigc++-2.0-dev libltdl3-dev libtool gettext cvs
* Gentoo: virtual/ETL virtual/synfig dev-cpp/gtkmm-2.4 dev-libs/libsigc++ sys-devel/libtool
** If you are using ./configure --prefix="$PREFIX" to configure synfigstudio, do not install virtual/ETL or virtual/synfig.
Optional: fonts (for the images), [http://www.fmod.org FMOD] (version 3.x, proprietary)
* Debian: ttf-freefont ttf-dejavu ttf-dustin
* Gentoo: freefonts dejavu

''Type the following commands at the directory that holds '''synfig-studio:'''''
<pre>
$ autoreconf --install --force
$ ./configure
$ make
$ sudo make install
</pre>



== finalizing ==

Depending on where you installed synfig to, you might have to tell your system where the libraries can be found. That can be done via the following command:

<pre>
$ sudo ldconfig
</pre>

Dev:Build Instructions

2008-11-05T21:53:05Z

Dooglus: /* Notes */ "the first three steps" probably dates back to "bootstrap" times? if not, which 3 steps does it mean?

[[Category:Building]]

== Notes ==

If you are using the released versions instead of SVN, none of the libtoolize or autoreconf steps are necessary. For released versions, "./configure && make && sudo make install" should be enough.

If you are using packages for synfig's dependencies, you want the '''development packages''' not the main packages. Check below for your distribution's packages.

Please read the [[Source code|source code]] page to check out the latest code. Please also check the [[Download|download page]] and the [[FAQ]] to find out about any issues that you may run into along the way.

Some Linux/BSD distros have a pkg-config that doesn't look in /usr/local/lib/pkgconfig by default. So if you are installing in anywhere other than the system pkg-config path, please run "export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig" or similar before building or installing anything.

Don't use automake 1.4, there are problems with it.

Using automake 1.9, 'make install' seems to re-link and re-install all the synfig core modules every time whether they have changed or not. [http://dooglus.rincevent.net/synfig/automake.html here] is an ugly workaround - it's only worth using if you intend to rebuild synfig repeatedly

The instructions below result in 3 separate subversion working directories being created. This is inconvenient to work with - you'll need to 'svn commit' in 3 different places to send changes, 'svn update' in 3 different places to get the latest updates, etc. [[Subversion|This page]] shows how to arrange for the code to be checked out into a single working directory. You can also download a daily updated tarball that uses this from the [[Source code|source code]] page.

The CVS requirement is only because the autopoint program run by autoreconf needs CVS. You can avoid the need for CVS by disabling the translation/gettext stuff in configure.ac.

If you don't want to install to a system-wide directory using sudo, run something like these commands before starting:

<pre>
export PREFIX="$HOME/opt"
export PKG_CONFIG_PATH="$PKG_CONFIG_PATH:$PREFIX/lib/pkgconfig"
export PATH="$PATH:$PREFIX/bin"
</pre>

And when you run ./configure, run it with --prefix="$PREFIX" and don't use sudo when you do make install.

=== Automatic build/update script ===

You can use [http://zelgadis.profusehost.net/files/synfig/synfigstudio-svn-build this] script to quickly build/update synfigstudio from SVN (software installed in ~/synfig-svn by default).

To use the script just execute following single command in terminal:
<pre>cd && \
wget http://zelgadis.profusehost.net/files/synfig/synfigstudio-svn-build && \
chmod +x synfigstudio-svn-build && \
./synfigstudio-svn-build initialize</pre>

'''WARNING:''' Your system must satisfy synfig's build requiments, the sript won't do it for you.

=== System-specific instructions ===

* Gentoo: SVN [[Gentoo Ebuilds|ebuilds]] are available
* MacOS X: [[Building_On_Mac_OS_X|instructions for building]] with the GTK+ Aqua port are available.
* Windows: [[Windows build instructions|instructions for building]] in [[Mingw_installation|mingw]] are available.

== ETL ==

ETL is a template library, there is nothing to build really, it just needed to be installed.

Requires: autoconf automake<br>
* Debian: build-essential autoconf automake

''Type the following commands at the directory that holds '''ETL:'''''
<pre>
$ autoreconf --install --force
$ ./configure
$ sudo make install
</pre>

== synfig ==

Requires: ETL, libxml++, libsigc++, libltdl, libtool, gettext, cvs<br>
* Debian: etl-dev libxml++2.6-dev libsigc++-2.0-dev libltdl3-dev libtool gettext cvs
* Gentoo: virtual/ETL dev-cpp/libxmlpp dev-libs/libsigc++ dev-util/cvs
** If you are using ./configure --prefix="$PREFIX" to configure synfig, do not install virtual/ETL.

Note: libpng isn't required to build synfig, but if you build synfig without PNG support and go on to build synfigstudio, that step will fail (because the build process for synfigstudio uses synfig to create .png icon files). The package is libpng12-dev on Debian or media-libs/libpng on Gentoo.

Optional: libpng, libmng, libjpeg, libfreetype, libfontconfig, libopenexr, libavcodec, libmagick++, vimage (MacOS only, proprietary)<br>
* Debian: libpng12-dev libmng-dev libjpeg62-dev libfreetype6-dev libfontconfig1-dev libopenexr-dev libavcodec-dev libavformat-dev libmagick++9-dev
* Gentoo: sys-devel/libtool media-libs/libpng media-libs/libmng media-libs/jpeg media-libs/freetype media-libs/fontconfig media-libs/openexr media-libs/libavcodec
Runtime: encodedv (from libdv), ffmpeg, convert (from imagemagick)
* Debian: libdv-bin ffmpeg imagemagick
* Gentoo: media-libs/libdv media-video/ffmpeg media-gfx/imagemagick

''Type the following commands at the directory that holds '''synfig-core:'''''
<pre>
$ libtoolize --ltdl --copy --force
$ autoreconf --install --force
$ ./configure
$ make
$ sudo make install
</pre>

Notes:

* Don't use --enable-half, it is slow.

== synfigstudio ==

Requires: ETL, synfig, gtkmm >= 2.4, gtk >= 2.0, glibmm, libsigc++, libltdl, libtool, gettext, cvs<br>
* Debian: etl-dev libsynfig-dev libgtkmm-2.4-dev libgtk2.0-dev libglibmm-2.4-dev libsigc++-2.0-dev libltdl3-dev libtool gettext cvs
* Gentoo: virtual/ETL virtual/synfig dev-cpp/gtkmm-2.4 dev-libs/libsigc++ sys-devel/libtool
** If you are using ./configure --prefix="$PREFIX" to configure synfigstudio, do not install virtual/ETL or virtual/synfig.
Optional: fonts (for the images), [http://www.fmod.org FMOD] (version 3.x, proprietary)
* Debian: ttf-freefont ttf-dejavu ttf-dustin
* Gentoo: freefonts dejavu

''Type the following commands at the directory that holds '''synfig-studio:'''''
<pre>
$ autoreconf --install --force
$ ./configure
$ make
$ sudo make install
</pre>



== finalizing ==

Depending on where you installed synfig to, you might have to tell your system where the libraries can be found. That can be done via the following command:

<pre>
$ sudo ldconfig
</pre>

Releases/0.61.09

2008-10-08T19:29:27Z

Dooglus: /* Curves Panel */

Released October XX 2008

== General ==
* Forum use nows phpBB3.
* We have migrated from the Voria server to a new VPS server.
* We moved our subversion repository to sourceforge
* We are testing Review Board for patches in synfig. http://patches.synfig.org/

== ETL ==
* Improved the derivative class for hermites.

== Layers ==
* Don't let feather be negative for any Shape layers or Circle layers.
* Fix handling of segments so that the examples/walk/walk.sifz file will load correctly.
* Use 0 for the index if the closest point is on the segment which closes the loop. This keeps the final 'amount' value in the range 0..1.
* Fix a bug in the plant layer: when the plant is so small that we can't calculate the perpendicular to its bline, skip trying to branch it.
* Improve a warning message when we find an unknown layer parameter.
* Rename all 'pos' and 'offset' parameters to 'origin'.
* Add parameter 'add_width' to the [[Plant Layer|plant layer]]. It's on by default, and means to scale the velocity of a plant's shoot by the width of the bline at that point.
* Now circles with large feather and zero radius are visible. Only shortcut zero-radius circles if they're not inverted and have no feathering. [http://sf.net/support/tracker.php?aid=2120629 2120629]
* Leave previously selected layers selected when creating a new one. Environment variable SYNFIG_TOOLS_CLEAR_SELECTION toggles this option.
* Add "select all layers" (S-C-a) and "unselect all ducks" (C-d). Move "unselect all layers" onto S-C-d.
* When multiple layers are selected, only show parameters which are present in all selected layers *with the same type*.

== Value Nodes ==
*Add new types:
** [[Convert#Logarithm|Logarithm]]: To convert to a natural logarithm
** [[Convert#Int String|Int String]]: To convert to a string from an integer
** [[Convert#Angle String|Angle String]] : To convert to a string from an angle
** [[Convert#Joined List|Joined List]]: Join two strings
** [[Convert#Real String|Real String]]: To convert to a string from a real
** [[Convert#Time String|Time String]]: To convert to a string from a time
** [[Convert#Dot Product|Dot Product]]: Convert to a real from the dot product of two vectors
** [[Convert#Gradient Color|Gradient Color]]: Convert to a color from a gradient
** [[Convert#Vector X|Vector X]]: Convert to a real from a vector (get its X)
** [[Convert#Vector Y|Vector Y]]: Convert to a real from a vector (get its Y)
** [[Convert#Vector Length|Vector Length]]: Convert to a real from a vector (get its length)
** [[Convert#Vector Angle|Vector Angle]]: Convert to an angle from a vector (get its angle)
* Add "Loop" link to the "Gradient Color" ValueNode.

== Targets ==
* Unless OpenEXR half mode is used, don't ask synfigstudio to depend on it.
* Fix build problem with newer versions of libavformat due to the pb member of AVFormatContext changing from a structure to a pointer. [http://sf.net/support/tracker.php?aid=11877061 11877061]
* Fix Debian 487639: for mod_libav, allow the use of libswscale instead of the depreciated img_convert function. Apply [http://sf.net/support/tracker.php?aid=2036627 2036627]
* Fix the libjpeg configure test to look for the right function.
* Windows builds now include OpenEXR version 1.6.
* Configure now uses pkg-config to find libswscale. [http://sf.net/support/tracker.php?aid=2108984 2108984]
* Cope with some changes in the locations of the libavformat and libswscale headers.
* Add a configure flag to switch on/off jpeg support. Apply [http://patches.synfig.org/r/5/ 5]

== Blend Methods ==
* Fix this bug: when a layer was composed 'straight onto' a context with which its bounding box had no overlap, the context was being displayed as if the 'straight onto' layer wasn't there. [http://sf.net/support/tracker.php?aid=1960543 1960543]

== Canvases ==
* To allow backward compatibility, canvas version has been set to 0.6.

== Files ==
* In the 'open > recent files' menu entry, only show files which still exist. Previously, it was saving documents into /tmp. After rebooting /tmp had been emptied, but the files were still showing up in the menu.
* Modified the Help menu due to the Communication page on the website being renamed to Contact.
* Fix error when trying to change value of Filename property. [http://sf.net/support/tracker.php?aid=1988939 1988939]

== Settings ==
* Added a new tab in the [[Setup Dialog|Setup Dialog]] to allow user set the preferences for: X and Y sizes for new documents, the new Document filename prefix and a selector for predefined resolutions.

== Linking ==
Added new feature [[Linking to Blines| Link to Bline]]: allow the user link vertexes, tangents and widths to a parametrized position of a bline. Also inverse manipulation is allowed. This makes easier to build complex figures without need to have a vertex on the joining point.

== Waypoints ==
* [[TCB|TENSION and TEMPORAL TENSION]] were the same; use the 'temporal' version everywhere.
* Don't render waypoints that lie outside the bounds of the timetrack's adjustment. [http://sf.net/support/tracker.php?aid=1888863 1888863]
* Don't offer 'Manual' as an interpolation type. It's not clear what it is supposed to do, and looks like the code to implement it was never written. Attempting to use it causes uninitialized memory to be read.

== Time ==
* Fix bad time entry when format is set to FFf. Apply [http://patches.synfig.org/r/4/ 4]
* Show time 3.0 as "3s" in the default (FORMAT_NORMAL) time display mode, rather than sometimes showing "3s 0f".

== Windows ==
=== Console Window ===
* Make the file selector dialogs print less output to the console.
* Show the 'fifo_activity' message less.
* Show commands as they are received over the FIFO.
* Don't show debugging messages about saving preference directories.

=== Toolbox Window ===
* Add new icon for the reset colors button and change the code to use it.
The size of the foreground color and background color picker has been modified to allow the display of the reverse FG and BG colors and set FG and BG colors buttons properly in all GTK themes. Apply [http://patches.synfig.org/r/2/ 2]

=== Workarea Window ===
* Fix zoom fit so it really does zoom the canvas to fit the window. [http://sf.net/support/tracker.php?aid=1901244 1901244]
* Show a 'zoom to fit' icon in the zoomdial as well as a 'zoom 100%' icon.
* Fix "zoom to fit" so that it centers the fitted canvas on the screen, and always zooms back to the previous zoom level and position if clicked a second time.

=== Canvas Properties Dialog ===
* When calculating the start and end frames, round to the nearest integer rather than always rounding down.
* Editing the name, description, or id of a canvas should mark the canvas as needing to be saved, and should also be undoable. [http://sf.net/support/tracker.php?aid=1924592 1924592]

=== Color Editor Dialog ===
* Allow clicking or scrolling on colour sliders to change the colour.

=== Gradient Editor Dialog ===
* Properly manage the situation when all CPoints of a gradient are removed. [http://sf.net/support/tracker.php?aid=2096641 2096641]

=== Time Track Panel ===
* Update the timeline scrollbars' major step size when zooming time in and out. [http://sf.net/support/tracker.php?aid=1914874 1914874]
* Allow scrolling left and right in time widgets.
* Fix a bug that was causing the time slider to not be displayed in certain circumstances.

=== Curves Panel ===
* Don't show an incorrect error message when selecting a filename or canvas parameter. The error message was due these types not being representable in the Curves panel, but this isn't an error. [http://sf.net/support/tracker.php?aid=2060732 2060732]

=== Splash Screen ===
* Remove the build information and use a new image by Yaco & Genete

== Tools ==
* Text, Plant, Polyline and Star have new icons.
* [[Circle Tool|Circle tool]] allows now make Blined circles too. Regions, Outlines, Gradients and Plants are included.
* [[ Rectangle Tool|Rectangle tool]] now does the same.
* New [[Text Tool| Text tool]] has been added to the [[Toolbox|ToolBox]].
* New [[Star Tool|Star Tool]] has been added to the tool palette. It allows now make blined stars too. Regions, Outlines, Gradients and Plants are included.
* Now [[Eyedrop Tool|eyedropper]] works correctly with straight blends for all types of layers. [http://sf.net/support/tracker.php?aid=2119764 2119764]
* The "Link Offsets" option in the [[BLine Tool|BLine tool]] now only links offsets if we're creating more than one layer at a time.
* Added options to the circle tool for creation of bline approximations to circles. Number of points and points angle offset.
* Use the 'feather' and 'invert' tool options when creating outline or region layers in the circle tool.
* Remove the "blend method" option from the tool options panel for the circle and gradient tools (unless the BLEND_METHOD_IN_TOOL_OPTIONS #define in toolbox.h is uncommented).
* Add 'inner tangent', 'outer tangent' and 'radius ratio' options to the star tool for creating rounded stars and different ratios stars.
* Show the name of the current tool in the tool options panel if it has any options. For the zoom tool, show the message that it doesn't have any options, instead of just showing a blank panel.
* Replace "Gradient" check button with "Create Gradient BLine", etc., like in the other tools.
* Using the Circle tool over an existing duck now doesn't crash. [http://sf.net/support/tracker.php?aid=1959064 1959064]

== Ducks ==
* Fixed infinite error message loop on split tangents. [http://sf.net/support/tracker.php?aid=1947076 1947076]

== Miscellaneous ==
* Improve Segment Tangent and Bline Tangent calculations. Now they give more accurate results.
* If only one of -w and -h is specified on the command line, calculate the other in order to keep the aspect ratio fixed.
* Check for Gtk::AboutDialog::set_wrap_license, which was added in Gtkmm 2.8. Allows synfigstudio to build on the fink distribution.
* Update configure.ac as suggested by autoupdate.
* Improved GUI for the sound file selection dialog. [http://sf.net/support/tracker.php?aid=1932525 1932525]
* Alt-D = draw, Alt-W = width. Previously there were 2 different definitions for Alt-T.
* More strings has been extracted to be marked as translatable. Spanish, French and Catalan translations Updated.
* Add multiple sizes and a scalable version of synfig_icon installed in freedesktop.org icon directories. [http://sf.net/support/tracker.php?aid=2109095 2109095]

Releases/0.61.09

2008-10-08T19:25:31Z

Dooglus: /* Toolbox Window */

Released October XX 2008

== General ==
* Forum use nows phpBB3.
* We have migrated from the Voria server to a new VPS server.
* We moved our subversion repository to sourceforge
* We are testing Review Board for patches in synfig. http://patches.synfig.org/

== ETL ==
* Improved the derivative class for hermites.

== Layers ==
* Don't let feather be negative for any Shape layers or Circle layers.
* Fix handling of segments so that the examples/walk/walk.sifz file will load correctly.
* Use 0 for the index if the closest point is on the segment which closes the loop. This keeps the final 'amount' value in the range 0..1.
* Fix a bug in the plant layer: when the plant is so small that we can't calculate the perpendicular to its bline, skip trying to branch it.
* Improve a warning message when we find an unknown layer parameter.
* Rename all 'pos' and 'offset' parameters to 'origin'.
* Add parameter 'add_width' to the [[Plant Layer|plant layer]]. It's on by default, and means to scale the velocity of a plant's shoot by the width of the bline at that point.
* Now circles with large feather and zero radius are visible. Only shortcut zero-radius circles if they're not inverted and have no feathering. [http://sf.net/support/tracker.php?aid=2120629 2120629]
* Leave previously selected layers selected when creating a new one. Environment variable SYNFIG_TOOLS_CLEAR_SELECTION toggles this option.
* Add "select all layers" (S-C-a) and "unselect all ducks" (C-d). Move "unselect all layers" onto S-C-d.
* When multiple layers are selected, only show parameters which are present in all selected layers *with the same type*.

== Value Nodes ==
*Add new types:
** [[Convert#Logarithm|Logarithm]]: To convert to a natural logarithm
** [[Convert#Int String|Int String]]: To convert to a string from an integer
** [[Convert#Angle String|Angle String]] : To convert to a string from an angle
** [[Convert#Joined List|Joined List]]: Join two strings
** [[Convert#Real String|Real String]]: To convert to a string from a real
** [[Convert#Time String|Time String]]: To convert to a string from a time
** [[Convert#Dot Product|Dot Product]]: Convert to a real from the dot product of two vectors
** [[Convert#Gradient Color|Gradient Color]]: Convert to a color from a gradient
** [[Convert#Vector X|Vector X]]: Convert to a real from a vector (get its X)
** [[Convert#Vector Y|Vector Y]]: Convert to a real from a vector (get its Y)
** [[Convert#Vector Length|Vector Length]]: Convert to a real from a vector (get its length)
** [[Convert#Vector Angle|Vector Angle]]: Convert to an angle from a vector (get its angle)
* Add "Loop" link to the "Gradient Color" ValueNode.

== Targets ==
* Unless OpenEXR half mode is used, don't ask synfigstudio to depend on it.
* Fix build problem with newer versions of libavformat due to the pb member of AVFormatContext changing from a structure to a pointer. [http://sf.net/support/tracker.php?aid=11877061 11877061]
* Fix Debian 487639: for mod_libav, allow the use of libswscale instead of the depreciated img_convert function. Apply [http://sf.net/support/tracker.php?aid=2036627 2036627]
* Fix the libjpeg configure test to look for the right function.
* Windows builds now include OpenEXR version 1.6.
* Configure now uses pkg-config to find libswscale. [http://sf.net/support/tracker.php?aid=2108984 2108984]
* Cope with some changes in the locations of the libavformat and libswscale headers.
* Add a configure flag to switch on/off jpeg support. Apply [http://patches.synfig.org/r/5/ 5]

== Blend Methods ==
* Fix this bug: when a layer was composed 'straight onto' a context with which its bounding box had no overlap, the context was being displayed as if the 'straight onto' layer wasn't there. [http://sf.net/support/tracker.php?aid=1960543 1960543]

== Canvases ==
* To allow backward compatibility, canvas version has been set to 0.6.

== Files ==
* In the 'open > recent files' menu entry, only show files which still exist. Previously, it was saving documents into /tmp. After rebooting /tmp had been emptied, but the files were still showing up in the menu.
* Modified the Help menu due to the Communication page on the website being renamed to Contact.
* Fix error when trying to change value of Filename property. [http://sf.net/support/tracker.php?aid=1988939 1988939]

== Settings ==
* Added a new tab in the [[Setup Dialog|Setup Dialog]] to allow user set the preferences for: X and Y sizes for new documents, the new Document filename prefix and a selector for predefined resolutions.

== Linking ==
Added new feature [[Linking to Blines| Link to Bline]]: allow the user link vertexes, tangents and widths to a parametrized position of a bline. Also inverse manipulation is allowed. This makes easier to build complex figures without need to have a vertex on the joining point.

== Waypoints ==
* [[TCB|TENSION and TEMPORAL TENSION]] were the same; use the 'temporal' version everywhere.
* Don't render waypoints that lie outside the bounds of the timetrack's adjustment. [http://sf.net/support/tracker.php?aid=1888863 1888863]
* Don't offer 'Manual' as an interpolation type. It's not clear what it is supposed to do, and looks like the code to implement it was never written. Attempting to use it causes uninitialized memory to be read.

== Time ==
* Fix bad time entry when format is set to FFf. Apply [http://patches.synfig.org/r/4/ 4]
* Show time 3.0 as "3s" in the default (FORMAT_NORMAL) time display mode, rather than sometimes showing "3s 0f".

== Windows ==
=== Console Window ===
* Make the file selector dialogs print less output to the console.
* Show the 'fifo_activity' message less.
* Show commands as they are received over the FIFO.
* Don't show debugging messages about saving preference directories.

=== Toolbox Window ===
* Add new icon for the reset colors button and change the code to use it.
The size of the foreground color and background color picker has been modified to allow the display of the reverse FG and BG colors and set FG and BG colors buttons properly in all GTK themes. Apply [http://patches.synfig.org/r/2/ 2]

=== Workarea Window ===
* Fix zoom fit so it really does zoom the canvas to fit the window. [http://sf.net/support/tracker.php?aid=1901244 1901244]
* Show a 'zoom to fit' icon in the zoomdial as well as a 'zoom 100%' icon.
* Fix "zoom to fit" so that it centers the fitted canvas on the screen, and always zooms back to the previous zoom level and position if clicked a second time.

=== Canvas Properties Dialog ===
* When calculating the start and end frames, round to the nearest integer rather than always rounding down.
* Editing the name, description, or id of a canvas should mark the canvas as needing to be saved, and should also be undoable. [http://sf.net/support/tracker.php?aid=1924592 1924592]

=== Color Editor Dialog ===
* Allow clicking or scrolling on colour sliders to change the colour.

=== Gradient Editor Dialog ===
* Properly manage the situation when all CPoints of a gradient are removed. [http://sf.net/support/tracker.php?aid=2096641 2096641]

=== Time Track Panel ===
* Update the timeline scrollbars' major step size when zooming time in and out. [http://sf.net/support/tracker.php?aid=1914874 1914874]
* Allow scrolling left and right in time widgets.
* Fix a bug that was causing the time slider to not be displayed in certain circumstances.

=== Curves Panel ===
* Don't show incorrect error message when selecting a filename or canvas parameter due the parameter is not representable in the Curves panel. [http://sf.net/support/tracker.php?aid=2060732 2060732]

=== Splash Screen ===
* Remove the build information and use a new image by Yaco & Genete

== Tools ==
* Text, Plant, Polyline and Star have new icons.
* [[Circle Tool|Circle tool]] allows now make Blined circles too. Regions, Outlines, Gradients and Plants are included.
* [[ Rectangle Tool|Rectangle tool]] now does the same.
* New [[Text Tool| Text tool]] has been added to the [[Toolbox|ToolBox]].
* New [[Star Tool|Star Tool]] has been added to the tool palette. It allows now make blined stars too. Regions, Outlines, Gradients and Plants are included.
* Now [[Eyedrop Tool|eyedropper]] works correctly with straight blends for all types of layers. [http://sf.net/support/tracker.php?aid=2119764 2119764]
* The "Link Offsets" option in the [[BLine Tool|BLine tool]] now only links offsets if we're creating more than one layer at a time.
* Added options to the circle tool for creation of bline approximations to circles. Number of points and points angle offset.
* Use the 'feather' and 'invert' tool options when creating outline or region layers in the circle tool.
* Remove the "blend method" option from the tool options panel for the circle and gradient tools (unless the BLEND_METHOD_IN_TOOL_OPTIONS #define in toolbox.h is uncommented).
* Add 'inner tangent', 'outer tangent' and 'radius ratio' options to the star tool for creating rounded stars and different ratios stars.
* Show the name of the current tool in the tool options panel if it has any options. For the zoom tool, show the message that it doesn't have any options, instead of just showing a blank panel.
* Replace "Gradient" check button with "Create Gradient BLine", etc., like in the other tools.
* Using the Circle tool over an existing duck now doesn't crash. [http://sf.net/support/tracker.php?aid=1959064 1959064]

== Ducks ==
* Fixed infinite error message loop on split tangents. [http://sf.net/support/tracker.php?aid=1947076 1947076]

== Miscellaneous ==
* Improve Segment Tangent and Bline Tangent calculations. Now they give more accurate results.
* If only one of -w and -h is specified on the command line, calculate the other in order to keep the aspect ratio fixed.
* Check for Gtk::AboutDialog::set_wrap_license, which was added in Gtkmm 2.8. Allows synfigstudio to build on the fink distribution.
* Update configure.ac as suggested by autoupdate.
* Improved GUI for the sound file selection dialog. [http://sf.net/support/tracker.php?aid=1932525 1932525]
* Alt-D = draw, Alt-W = width. Previously there were 2 different definitions for Alt-T.
* More strings has been extracted to be marked as translatable. Spanish, French and Catalan translations Updated.
* Add multiple sizes and a scalable version of synfig_icon installed in freedesktop.org icon directories. [http://sf.net/support/tracker.php?aid=2109095 2109095]

Releases/0.61.09

2008-10-08T19:22:54Z

Dooglus: /* Files */

Released October XX 2008

== General ==
* Forum use nows phpBB3.
* We have migrated from the Voria server to a new VPS server.
* We moved our subversion repository to sourceforge
* We are testing Review Board for patches in synfig. http://patches.synfig.org/

== ETL ==
* Improved the derivative class for hermites.

== Layers ==
* Don't let feather be negative for any Shape layers or Circle layers.
* Fix handling of segments so that the examples/walk/walk.sifz file will load correctly.
* Use 0 for the index if the closest point is on the segment which closes the loop. This keeps the final 'amount' value in the range 0..1.
* Fix a bug in the plant layer: when the plant is so small that we can't calculate the perpendicular to its bline, skip trying to branch it.
* Improve a warning message when we find an unknown layer parameter.
* Rename all 'pos' and 'offset' parameters to 'origin'.
* Add parameter 'add_width' to the [[Plant Layer|plant layer]]. It's on by default, and means to scale the velocity of a plant's shoot by the width of the bline at that point.
* Now circles with large feather and zero radius are visible. Only shortcut zero-radius circles if they're not inverted and have no feathering. [http://sf.net/support/tracker.php?aid=2120629 2120629]
* Leave previously selected layers selected when creating a new one. Environment variable SYNFIG_TOOLS_CLEAR_SELECTION toggles this option.
* Add "select all layers" (S-C-a) and "unselect all ducks" (C-d). Move "unselect all layers" onto S-C-d.
* When multiple layers are selected, only show parameters which are present in all selected layers *with the same type*.

== Value Nodes ==
*Add new types:
** [[Convert#Logarithm|Logarithm]]: To convert to a natural logarithm
** [[Convert#Int String|Int String]]: To convert to a string from an integer
** [[Convert#Angle String|Angle String]] : To convert to a string from an angle
** [[Convert#Joined List|Joined List]]: Join two strings
** [[Convert#Real String|Real String]]: To convert to a string from a real
** [[Convert#Time String|Time String]]: To convert to a string from a time
** [[Convert#Dot Product|Dot Product]]: Convert to a real from the dot product of two vectors
** [[Convert#Gradient Color|Gradient Color]]: Convert to a color from a gradient
** [[Convert#Vector X|Vector X]]: Convert to a real from a vector (get its X)
** [[Convert#Vector Y|Vector Y]]: Convert to a real from a vector (get its Y)
** [[Convert#Vector Length|Vector Length]]: Convert to a real from a vector (get its length)
** [[Convert#Vector Angle|Vector Angle]]: Convert to an angle from a vector (get its angle)
* Add "Loop" link to the "Gradient Color" ValueNode.

== Targets ==
* Unless OpenEXR half mode is used, don't ask synfigstudio to depend on it.
* Fix build problem with newer versions of libavformat due to the pb member of AVFormatContext changing from a structure to a pointer. [http://sf.net/support/tracker.php?aid=11877061 11877061]
* Fix Debian 487639: for mod_libav, allow the use of libswscale instead of the depreciated img_convert function. Apply [http://sf.net/support/tracker.php?aid=2036627 2036627]
* Fix the libjpeg configure test to look for the right function.
* Windows builds now include OpenEXR version 1.6.
* Configure now uses pkg-config to find libswscale. [http://sf.net/support/tracker.php?aid=2108984 2108984]
* Cope with some changes in the locations of the libavformat and libswscale headers.
* Add a configure flag to switch on/off jpeg support. Apply [http://patches.synfig.org/r/5/ 5]

== Blend Methods ==
* Fix this bug: when a layer was composed 'straight onto' a context with which its bounding box had no overlap, the context was being displayed as if the 'straight onto' layer wasn't there. [http://sf.net/support/tracker.php?aid=1960543 1960543]

== Canvases ==
* To allow backward compatibility, canvas version has been set to 0.6.

== Files ==
* In the 'open > recent files' menu entry, only show files which still exist. Previously, it was saving documents into /tmp. After rebooting /tmp had been emptied, but the files were still showing up in the menu.
* Modified the Help menu due to the Communication page on the website being renamed to Contact.
* Fix error when trying to change value of Filename property. [http://sf.net/support/tracker.php?aid=1988939 1988939]

== Settings ==
* Added a new tab in the [[Setup Dialog|Setup Dialog]] to allow user set the preferences for: X and Y sizes for new documents, the new Document filename prefix and a selector for predefined resolutions.

== Linking ==
Added new feature [[Linking to Blines| Link to Bline]]: allow the user link vertexes, tangents and widths to a parametrized position of a bline. Also inverse manipulation is allowed. This makes easier to build complex figures without need to have a vertex on the joining point.

== Waypoints ==
* [[TCB|TENSION and TEMPORAL TENSION]] were the same; use the 'temporal' version everywhere.
* Don't render waypoints that lie outside the bounds of the timetrack's adjustment. [http://sf.net/support/tracker.php?aid=1888863 1888863]
* Don't offer 'Manual' as an interpolation type. It's not clear what it is supposed to do, and looks like the code to implement it was never written. Attempting to use it causes uninitialized memory to be read.

== Time ==
* Fix bad time entry when format is set to FFf. Apply [http://patches.synfig.org/r/4/ 4]
* Show time 3.0 as "3s" in the default (FORMAT_NORMAL) time display mode, rather than sometimes showing "3s 0f".

== Windows ==
=== Console Window ===
* Make the file selector dialogs print less output to the console.
* Show the 'fifo_activity' message less.
* Show commands as they are received over the FIFO.
* Don't show debugging messages about saving preference directories.

=== Toolbox Window ===
* Add new icon for the reset colors button and change the code to use it.
Sizes of foreground color and background color picker has been modified to allow some GTK themes show the reverse FG and BG colors and set FG and BG colors buttons properly. Apply [http://patches.synfig.org/r/2/ 2]

=== Workarea Window ===
* Fix zoom fit so it really does zoom the canvas to fit the window. [http://sf.net/support/tracker.php?aid=1901244 1901244]
* Show a 'zoom to fit' icon in the zoomdial as well as a 'zoom 100%' icon.
* Fix "zoom to fit" so that it centers the fitted canvas on the screen, and always zooms back to the previous zoom level and position if clicked a second time.

=== Canvas Properties Dialog ===
* When calculating the start and end frames, round to the nearest integer rather than always rounding down.
* Editing the name, description, or id of a canvas should mark the canvas as needing to be saved, and should also be undoable. [http://sf.net/support/tracker.php?aid=1924592 1924592]

=== Color Editor Dialog ===
* Allow clicking or scrolling on colour sliders to change the colour.

=== Gradient Editor Dialog ===
* Properly manage the situation when all CPoints of a gradient are removed. [http://sf.net/support/tracker.php?aid=2096641 2096641]

=== Time Track Panel ===
* Update the timeline scrollbars' major step size when zooming time in and out. [http://sf.net/support/tracker.php?aid=1914874 1914874]
* Allow scrolling left and right in time widgets.
* Fix a bug that was causing the time slider to not be displayed in certain circumstances.

=== Curves Panel ===
* Don't show incorrect error message when selecting a filename or canvas parameter due the parameter is not representable in the Curves panel. [http://sf.net/support/tracker.php?aid=2060732 2060732]

=== Splash Screen ===
* Remove the build information and use a new image by Yaco & Genete

== Tools ==
* Text, Plant, Polyline and Star have new icons.
* [[Circle Tool|Circle tool]] allows now make Blined circles too. Regions, Outlines, Gradients and Plants are included.
* [[ Rectangle Tool|Rectangle tool]] now does the same.
* New [[Text Tool| Text tool]] has been added to the [[Toolbox|ToolBox]].
* New [[Star Tool|Star Tool]] has been added to the tool palette. It allows now make blined stars too. Regions, Outlines, Gradients and Plants are included.
* Now [[Eyedrop Tool|eyedropper]] works correctly with straight blends for all types of layers. [http://sf.net/support/tracker.php?aid=2119764 2119764]
* The "Link Offsets" option in the [[BLine Tool|BLine tool]] now only links offsets if we're creating more than one layer at a time.
* Added options to the circle tool for creation of bline approximations to circles. Number of points and points angle offset.
* Use the 'feather' and 'invert' tool options when creating outline or region layers in the circle tool.
* Remove the "blend method" option from the tool options panel for the circle and gradient tools (unless the BLEND_METHOD_IN_TOOL_OPTIONS #define in toolbox.h is uncommented).
* Add 'inner tangent', 'outer tangent' and 'radius ratio' options to the star tool for creating rounded stars and different ratios stars.
* Show the name of the current tool in the tool options panel if it has any options. For the zoom tool, show the message that it doesn't have any options, instead of just showing a blank panel.
* Replace "Gradient" check button with "Create Gradient BLine", etc., like in the other tools.
* Using the Circle tool over an existing duck now doesn't crash. [http://sf.net/support/tracker.php?aid=1959064 1959064]

== Ducks ==
* Fixed infinite error message loop on split tangents. [http://sf.net/support/tracker.php?aid=1947076 1947076]

== Miscellaneous ==
* Improve Segment Tangent and Bline Tangent calculations. Now they give more accurate results.
* If only one of -w and -h is specified on the command line, calculate the other in order to keep the aspect ratio fixed.
* Check for Gtk::AboutDialog::set_wrap_license, which was added in Gtkmm 2.8. Allows synfigstudio to build on the fink distribution.
* Update configure.ac as suggested by autoupdate.
* Improved GUI for the sound file selection dialog. [http://sf.net/support/tracker.php?aid=1932525 1932525]
* Alt-D = draw, Alt-W = width. Previously there were 2 different definitions for Alt-T.
* More strings has been extracted to be marked as translatable. Spanish, French and Catalan translations Updated.
* Add multiple sizes and a scalable version of synfig_icon installed in freedesktop.org icon directories. [http://sf.net/support/tracker.php?aid=2109095 2109095]

Releases/0.61.09

2008-10-08T19:21:53Z

Dooglus: /* Targets */

Released October XX 2008

== General ==
* Forum use nows phpBB3.
* We have migrated from the Voria server to a new VPS server.
* We moved our subversion repository to sourceforge
* We are testing Review Board for patches in synfig. http://patches.synfig.org/

== ETL ==
* Improved the derivative class for hermites.

== Layers ==
* Don't let feather be negative for any Shape layers or Circle layers.
* Fix handling of segments so that the examples/walk/walk.sifz file will load correctly.
* Use 0 for the index if the closest point is on the segment which closes the loop. This keeps the final 'amount' value in the range 0..1.
* Fix a bug in the plant layer: when the plant is so small that we can't calculate the perpendicular to its bline, skip trying to branch it.
* Improve a warning message when we find an unknown layer parameter.
* Rename all 'pos' and 'offset' parameters to 'origin'.
* Add parameter 'add_width' to the [[Plant Layer|plant layer]]. It's on by default, and means to scale the velocity of a plant's shoot by the width of the bline at that point.
* Now circles with large feather and zero radius are visible. Only shortcut zero-radius circles if they're not inverted and have no feathering. [http://sf.net/support/tracker.php?aid=2120629 2120629]
* Leave previously selected layers selected when creating a new one. Environment variable SYNFIG_TOOLS_CLEAR_SELECTION toggles this option.
* Add "select all layers" (S-C-a) and "unselect all ducks" (C-d). Move "unselect all layers" onto S-C-d.
* When multiple layers are selected, only show parameters which are present in all selected layers *with the same type*.

== Value Nodes ==
*Add new types:
** [[Convert#Logarithm|Logarithm]]: To convert to a natural logarithm
** [[Convert#Int String|Int String]]: To convert to a string from an integer
** [[Convert#Angle String|Angle String]] : To convert to a string from an angle
** [[Convert#Joined List|Joined List]]: Join two strings
** [[Convert#Real String|Real String]]: To convert to a string from a real
** [[Convert#Time String|Time String]]: To convert to a string from a time
** [[Convert#Dot Product|Dot Product]]: Convert to a real from the dot product of two vectors
** [[Convert#Gradient Color|Gradient Color]]: Convert to a color from a gradient
** [[Convert#Vector X|Vector X]]: Convert to a real from a vector (get its X)
** [[Convert#Vector Y|Vector Y]]: Convert to a real from a vector (get its Y)
** [[Convert#Vector Length|Vector Length]]: Convert to a real from a vector (get its length)
** [[Convert#Vector Angle|Vector Angle]]: Convert to an angle from a vector (get its angle)
* Add "Loop" link to the "Gradient Color" ValueNode.

== Targets ==
* Unless OpenEXR half mode is used, don't ask synfigstudio to depend on it.
* Fix build problem with newer versions of libavformat due to the pb member of AVFormatContext changing from a structure to a pointer. [http://sf.net/support/tracker.php?aid=11877061 11877061]
* Fix Debian 487639: for mod_libav, allow the use of libswscale instead of the depreciated img_convert function. Apply [http://sf.net/support/tracker.php?aid=2036627 2036627]
* Fix the libjpeg configure test to look for the right function.
* Windows builds now include OpenEXR version 1.6.
* Configure now uses pkg-config to find libswscale. [http://sf.net/support/tracker.php?aid=2108984 2108984]
* Cope with some changes in the locations of the libavformat and libswscale headers.
* Add a configure flag to switch on/off jpeg support. Apply [http://patches.synfig.org/r/5/ 5]

== Blend Methods ==
* Fix this bug: when a layer was composed 'straight onto' a context with which its bounding box had no overlap, the context was being displayed as if the 'straight onto' layer wasn't there. [http://sf.net/support/tracker.php?aid=1960543 1960543]

== Canvases ==
* To allow backward compatibility, canvas version has been set to 0.6.

== Files ==
* In the 'open > recent files' menu entry, only show files which still exist. Previously, it was saving documents into /tmp. After rebooting /tmp had been emptied, but the files were still showing up in the menu.
* Modified the Help menu due to Communication page on the website was renamed to Contact.
* Fix error when trying to change value of Filename property. [http://sf.net/support/tracker.php?aid=1988939 1988939]

== Settings ==
* Added a new tab in the [[Setup Dialog|Setup Dialog]] to allow user set the preferences for: X and Y sizes for new documents, the new Document filename prefix and a selector for predefined resolutions.

== Linking ==
Added new feature [[Linking to Blines| Link to Bline]]: allow the user link vertexes, tangents and widths to a parametrized position of a bline. Also inverse manipulation is allowed. This makes easier to build complex figures without need to have a vertex on the joining point.

== Waypoints ==
* [[TCB|TENSION and TEMPORAL TENSION]] were the same; use the 'temporal' version everywhere.
* Don't render waypoints that lie outside the bounds of the timetrack's adjustment. [http://sf.net/support/tracker.php?aid=1888863 1888863]
* Don't offer 'Manual' as an interpolation type. It's not clear what it is supposed to do, and looks like the code to implement it was never written. Attempting to use it causes uninitialized memory to be read.

== Time ==
* Fix bad time entry when format is set to FFf. Apply [http://patches.synfig.org/r/4/ 4]
* Show time 3.0 as "3s" in the default (FORMAT_NORMAL) time display mode, rather than sometimes showing "3s 0f".

== Windows ==
=== Console Window ===
* Make the file selector dialogs print less output to the console.
* Show the 'fifo_activity' message less.
* Show commands as they are received over the FIFO.
* Don't show debugging messages about saving preference directories.

=== Toolbox Window ===
* Add new icon for the reset colors button and change the code to use it.
Sizes of foreground color and background color picker has been modified to allow some GTK themes show the reverse FG and BG colors and set FG and BG colors buttons properly. Apply [http://patches.synfig.org/r/2/ 2]

=== Workarea Window ===
* Fix zoom fit so it really does zoom the canvas to fit the window. [http://sf.net/support/tracker.php?aid=1901244 1901244]
* Show a 'zoom to fit' icon in the zoomdial as well as a 'zoom 100%' icon.
* Fix "zoom to fit" so that it centers the fitted canvas on the screen, and always zooms back to the previous zoom level and position if clicked a second time.

=== Canvas Properties Dialog ===
* When calculating the start and end frames, round to the nearest integer rather than always rounding down.
* Editing the name, description, or id of a canvas should mark the canvas as needing to be saved, and should also be undoable. [http://sf.net/support/tracker.php?aid=1924592 1924592]

=== Color Editor Dialog ===
* Allow clicking or scrolling on colour sliders to change the colour.

=== Gradient Editor Dialog ===
* Properly manage the situation when all CPoints of a gradient are removed. [http://sf.net/support/tracker.php?aid=2096641 2096641]

=== Time Track Panel ===
* Update the timeline scrollbars' major step size when zooming time in and out. [http://sf.net/support/tracker.php?aid=1914874 1914874]
* Allow scrolling left and right in time widgets.
* Fix a bug that was causing the time slider to not be displayed in certain circumstances.

=== Curves Panel ===
* Don't show incorrect error message when selecting a filename or canvas parameter due the parameter is not representable in the Curves panel. [http://sf.net/support/tracker.php?aid=2060732 2060732]

=== Splash Screen ===
* Remove the build information and use a new image by Yaco & Genete

== Tools ==
* Text, Plant, Polyline and Star have new icons.
* [[Circle Tool|Circle tool]] allows now make Blined circles too. Regions, Outlines, Gradients and Plants are included.
* [[ Rectangle Tool|Rectangle tool]] now does the same.
* New [[Text Tool| Text tool]] has been added to the [[Toolbox|ToolBox]].
* New [[Star Tool|Star Tool]] has been added to the tool palette. It allows now make blined stars too. Regions, Outlines, Gradients and Plants are included.
* Now [[Eyedrop Tool|eyedropper]] works correctly with straight blends for all types of layers. [http://sf.net/support/tracker.php?aid=2119764 2119764]
* The "Link Offsets" option in the [[BLine Tool|BLine tool]] now only links offsets if we're creating more than one layer at a time.
* Added options to the circle tool for creation of bline approximations to circles. Number of points and points angle offset.
* Use the 'feather' and 'invert' tool options when creating outline or region layers in the circle tool.
* Remove the "blend method" option from the tool options panel for the circle and gradient tools (unless the BLEND_METHOD_IN_TOOL_OPTIONS #define in toolbox.h is uncommented).
* Add 'inner tangent', 'outer tangent' and 'radius ratio' options to the star tool for creating rounded stars and different ratios stars.
* Show the name of the current tool in the tool options panel if it has any options. For the zoom tool, show the message that it doesn't have any options, instead of just showing a blank panel.
* Replace "Gradient" check button with "Create Gradient BLine", etc., like in the other tools.
* Using the Circle tool over an existing duck now doesn't crash. [http://sf.net/support/tracker.php?aid=1959064 1959064]

== Ducks ==
* Fixed infinite error message loop on split tangents. [http://sf.net/support/tracker.php?aid=1947076 1947076]

== Miscellaneous ==
* Improve Segment Tangent and Bline Tangent calculations. Now they give more accurate results.
* If only one of -w and -h is specified on the command line, calculate the other in order to keep the aspect ratio fixed.
* Check for Gtk::AboutDialog::set_wrap_license, which was added in Gtkmm 2.8. Allows synfigstudio to build on the fink distribution.
* Update configure.ac as suggested by autoupdate.
* Improved GUI for the sound file selection dialog. [http://sf.net/support/tracker.php?aid=1932525 1932525]
* Alt-D = draw, Alt-W = width. Previously there were 2 different definitions for Alt-T.
* More strings has been extracted to be marked as translatable. Spanish, French and Catalan translations Updated.
* Add multiple sizes and a scalable version of synfig_icon installed in freedesktop.org icon directories. [http://sf.net/support/tracker.php?aid=2109095 2109095]

Releases/0.61.09

2008-10-08T19:18:12Z

Dooglus: /* Value Nodes */

Released October XX 2008

== General ==
* Forum use nows phpBB3.
* We have migrated from the Voria server to a new VPS server.
* We moved our subversion repository to sourceforge
* We are testing Review Board for patches in synfig. http://patches.synfig.org/

== ETL ==
* Improved the derivative class for hermites.

== Layers ==
* Don't let feather be negative for any Shape layers or Circle layers.
* Fix handling of segments so that the examples/walk/walk.sifz file will load correctly.
* Use 0 for the index if the closest point is on the segment which closes the loop. This keeps the final 'amount' value in the range 0..1.
* Fix a bug in the plant layer: when the plant is so small that we can't calculate the perpendicular to its bline, skip trying to branch it.
* Improve a warning message when we find an unknown layer parameter.
* Rename all 'pos' and 'offset' parameters to 'origin'.
* Add parameter 'add_width' to the [[Plant Layer|plant layer]]. It's on by default, and means to scale the velocity of a plant's shoot by the width of the bline at that point.
* Now circles with large feather and zero radius are visible. Only shortcut zero-radius circles if they're not inverted and have no feathering. [http://sf.net/support/tracker.php?aid=2120629 2120629]
* Leave previously selected layers selected when creating a new one. Environment variable SYNFIG_TOOLS_CLEAR_SELECTION toggles this option.
* Add "select all layers" (S-C-a) and "unselect all ducks" (C-d). Move "unselect all layers" onto S-C-d.
* When multiple layers are selected, only show parameters which are present in all selected layers *with the same type*.

== Value Nodes ==
*Add new types:
** [[Convert#Logarithm|Logarithm]]: To convert to a natural logarithm
** [[Convert#Int String|Int String]]: To convert to a string from an integer
** [[Convert#Angle String|Angle String]] : To convert to a string from an angle
** [[Convert#Joined List|Joined List]]: Join two strings
** [[Convert#Real String|Real String]]: To convert to a string from a real
** [[Convert#Time String|Time String]]: To convert to a string from a time
** [[Convert#Dot Product|Dot Product]]: Convert to a real from the dot product of two vectors
** [[Convert#Gradient Color|Gradient Color]]: Convert to a color from a gradient
** [[Convert#Vector X|Vector X]]: Convert to a real from a vector (get its X)
** [[Convert#Vector Y|Vector Y]]: Convert to a real from a vector (get its Y)
** [[Convert#Vector Length|Vector Length]]: Convert to a real from a vector (get its length)
** [[Convert#Vector Angle|Vector Angle]]: Convert to an angle from a vector (get its angle)
* Add "Loop" link to the "Gradient Color" ValueNode.

== Targets ==
* Unless OpenEXR half mode is used, don't ask synfigstudio to depend on it.
* Fix build problem with newer versions of libavformat due to the pb member of AVFormatContext changing from a structure to a pointer. [http://sf.net/support/tracker.php?aid=11877061 11877061]
* Fix Debian 487639: for mod_libav, allow the use of libswscale instead of the depreciated img_convert function. Apply [http://sf.net/support/tracker.php?aid=2036627 2036627]
* Fix the libjpeg configure test to look for the right function.
* Windows builds now include OpenEXR version 1.6.
* Configure now use pkg-config to find libswscale. [http://sf.net/support/tracker.php?aid=2108984 2108984]
* Cope with some changes in the locations of the libavformat and libswscale headers.
* Add a configure flag to switch on/off jpeg support. Apply [http://patches.synfig.org/r/5/ 5]

== Blend Methods ==
* Fix this bug: when a layer was composed 'straight onto' a context with which its bounding box had no overlap, the context was being displayed as if the 'straight onto' layer wasn't there. [http://sf.net/support/tracker.php?aid=1960543 1960543]

== Canvases ==
* To allow backward compatibility, canvas version has been set to 0.6.

== Files ==
* In the 'open > recent files' menu entry, only show files which still exist. Previously, it was saving documents into /tmp. After rebooting /tmp had been emptied, but the files were still showing up in the menu.
* Modified the Help menu due to Communication page on the website was renamed to Contact.
* Fix error when trying to change value of Filename property. [http://sf.net/support/tracker.php?aid=1988939 1988939]

== Settings ==
* Added a new tab in the [[Setup Dialog|Setup Dialog]] to allow user set the preferences for: X and Y sizes for new documents, the new Document filename prefix and a selector for predefined resolutions.

== Linking ==
Added new feature [[Linking to Blines| Link to Bline]]: allow the user link vertexes, tangents and widths to a parametrized position of a bline. Also inverse manipulation is allowed. This makes easier to build complex figures without need to have a vertex on the joining point.

== Waypoints ==
* [[TCB|TENSION and TEMPORAL TENSION]] were the same; use the 'temporal' version everywhere.
* Don't render waypoints that lie outside the bounds of the timetrack's adjustment. [http://sf.net/support/tracker.php?aid=1888863 1888863]
* Don't offer 'Manual' as an interpolation type. It's not clear what it is supposed to do, and looks like the code to implement it was never written. Attempting to use it causes uninitialized memory to be read.

== Time ==
* Fix bad time entry when format is set to FFf. Apply [http://patches.synfig.org/r/4/ 4]
* Show time 3.0 as "3s" in the default (FORMAT_NORMAL) time display mode, rather than sometimes showing "3s 0f".

== Windows ==
=== Console Window ===
* Make the file selector dialogs print less output to the console.
* Show the 'fifo_activity' message less.
* Show commands as they are received over the FIFO.
* Don't show debugging messages about saving preference directories.

=== Toolbox Window ===
* Add new icon for the reset colors button and change the code to use it.
Sizes of foreground color and background color picker has been modified to allow some GTK themes show the reverse FG and BG colors and set FG and BG colors buttons properly. Apply [http://patches.synfig.org/r/2/ 2]

=== Workarea Window ===
* Fix zoom fit so it really does zoom the canvas to fit the window. [http://sf.net/support/tracker.php?aid=1901244 1901244]
* Show a 'zoom to fit' icon in the zoomdial as well as a 'zoom 100%' icon.
* Fix "zoom to fit" so that it centers the fitted canvas on the screen, and always zooms back to the previous zoom level and position if clicked a second time.

=== Canvas Properties Dialog ===
* When calculating the start and end frames, round to the nearest integer rather than always rounding down.
* Editing the name, description, or id of a canvas should mark the canvas as needing to be saved, and should also be undoable. [http://sf.net/support/tracker.php?aid=1924592 1924592]

=== Color Editor Dialog ===
* Allow clicking or scrolling on colour sliders to change the colour.

=== Gradient Editor Dialog ===
* Properly manage the situation when all CPoints of a gradient are removed. [http://sf.net/support/tracker.php?aid=2096641 2096641]

=== Time Track Panel ===
* Update the timeline scrollbars' major step size when zooming time in and out. [http://sf.net/support/tracker.php?aid=1914874 1914874]
* Allow scrolling left and right in time widgets.
* Fix a bug that was causing the time slider to not be displayed in certain circumstances.

=== Curves Panel ===
* Don't show incorrect error message when selecting a filename or canvas parameter due the parameter is not representable in the Curves panel. [http://sf.net/support/tracker.php?aid=2060732 2060732]

=== Splash Screen ===
* Remove the build information and use a new image by Yaco & Genete

== Tools ==
* Text, Plant, Polyline and Star have new icons.
* [[Circle Tool|Circle tool]] allows now make Blined circles too. Regions, Outlines, Gradients and Plants are included.
* [[ Rectangle Tool|Rectangle tool]] now does the same.
* New [[Text Tool| Text tool]] has been added to the [[Toolbox|ToolBox]].
* New [[Star Tool|Star Tool]] has been added to the tool palette. It allows now make blined stars too. Regions, Outlines, Gradients and Plants are included.
* Now [[Eyedrop Tool|eyedropper]] works correctly with straight blends for all types of layers. [http://sf.net/support/tracker.php?aid=2119764 2119764]
* The "Link Offsets" option in the [[BLine Tool|BLine tool]] now only links offsets if we're creating more than one layer at a time.
* Added options to the circle tool for creation of bline approximations to circles. Number of points and points angle offset.
* Use the 'feather' and 'invert' tool options when creating outline or region layers in the circle tool.
* Remove the "blend method" option from the tool options panel for the circle and gradient tools (unless the BLEND_METHOD_IN_TOOL_OPTIONS #define in toolbox.h is uncommented).
* Add 'inner tangent', 'outer tangent' and 'radius ratio' options to the star tool for creating rounded stars and different ratios stars.
* Show the name of the current tool in the tool options panel if it has any options. For the zoom tool, show the message that it doesn't have any options, instead of just showing a blank panel.
* Replace "Gradient" check button with "Create Gradient BLine", etc., like in the other tools.
* Using the Circle tool over an existing duck now doesn't crash. [http://sf.net/support/tracker.php?aid=1959064 1959064]

== Ducks ==
* Fixed infinite error message loop on split tangents. [http://sf.net/support/tracker.php?aid=1947076 1947076]

== Miscellaneous ==
* Improve Segment Tangent and Bline Tangent calculations. Now they give more accurate results.
* If only one of -w and -h is specified on the command line, calculate the other in order to keep the aspect ratio fixed.
* Check for Gtk::AboutDialog::set_wrap_license, which was added in Gtkmm 2.8. Allows synfigstudio to build on the fink distribution.
* Update configure.ac as suggested by autoupdate.
* Improved GUI for the sound file selection dialog. [http://sf.net/support/tracker.php?aid=1932525 1932525]
* Alt-D = draw, Alt-W = width. Previously there were 2 different definitions for Alt-T.
* More strings has been extracted to be marked as translatable. Spanish, French and Catalan translations Updated.
* Add multiple sizes and a scalable version of synfig_icon installed in freedesktop.org icon directories. [http://sf.net/support/tracker.php?aid=2109095 2109095]

Releases/0.61.09

2008-10-08T19:17:12Z

Dooglus: /* Layers */

Released October XX 2008

== General ==
* Forum use nows phpBB3.
* We have migrated from the Voria server to a new VPS server.
* We moved our subversion repository to sourceforge
* We are testing Review Board for patches in synfig. http://patches.synfig.org/

== ETL ==
* Improved the derivative class for hermites.

== Layers ==
* Don't let feather be negative for any Shape layers or Circle layers.
* Fix handling of segments so that the examples/walk/walk.sifz file will load correctly.
* Use 0 for the index if the closest point is on the segment which closes the loop. This keeps the final 'amount' value in the range 0..1.
* Fix a bug in the plant layer: when the plant is so small that we can't calculate the perpendicular to its bline, skip trying to branch it.
* Improve a warning message when we find an unknown layer parameter.
* Rename all 'pos' and 'offset' parameters to 'origin'.
* Add parameter 'add_width' to the [[Plant Layer|plant layer]]. It's on by default, and means to scale the velocity of a plant's shoot by the width of the bline at that point.
* Now circles with large feather and zero radius are visible. Only shortcut zero-radius circles if they're not inverted and have no feathering. [http://sf.net/support/tracker.php?aid=2120629 2120629]
* Leave previously selected layers selected when creating a new one. Environment variable SYNFIG_TOOLS_CLEAR_SELECTION toggles this option.
* Add "select all layers" (S-C-a) and "unselect all ducks" (C-d). Move "unselect all layers" onto S-C-d.
* When multiple layers are selected, only show parameters which are present in all selected layers *with the same type*.

== Value Nodes ==
*Add new types:
** [[Convert#Logarithm|Logarithm]]: To convert to a natural logarithm
** [[Convert#Int String|Int String]]: To convert to a string form an integer
** [[Convert#Angle String|Angle String]] : To convert to a string form an angle
** [[Convert#Joined List|Joined List]]: Join two strings
** [[Convert#Real String|Real String]]: To convert to a string form a real
** [[Convert#Time String|Time String]]: To convert to a string form a time
** [[Convert#Dot Product|Dot Product]]: Convert to a real from the dot product of two vectors
** [[Convert#Gradient Color|Gradient Color]]: Convert to a color from a gradient
** [[Convert#Vector X|Vector X]]: Convert to a real from a vector (get its X)
** [[Convert#Vector Y|Vector Y]]: Convert to a real from a vector (get its Y)
** [[Convert#Vector Length|Vector Length]]: Convert to a real from a vector (get its length)
** [[Convert#Vector Angle|Vector Angle]]: Convert to an angle from a vector (get its angle)
* Add "Loop" link to the "Gradient Color" ValueNode.

== Targets ==
* Unless OpenEXR half mode is used, don't ask synfigstudio to depend on it.
* Fix build problem with newer versions of libavformat due to the pb member of AVFormatContext changing from a structure to a pointer. [http://sf.net/support/tracker.php?aid=11877061 11877061]
* Fix Debian 487639: for mod_libav, allow the use of libswscale instead of the depreciated img_convert function. Apply [http://sf.net/support/tracker.php?aid=2036627 2036627]
* Fix the libjpeg configure test to look for the right function.
* Windows builds now include OpenEXR version 1.6.
* Configure now use pkg-config to find libswscale. [http://sf.net/support/tracker.php?aid=2108984 2108984]
* Cope with some changes in the locations of the libavformat and libswscale headers.
* Add a configure flag to switch on/off jpeg support. Apply [http://patches.synfig.org/r/5/ 5]

== Blend Methods ==
* Fix this bug: when a layer was composed 'straight onto' a context with which its bounding box had no overlap, the context was being displayed as if the 'straight onto' layer wasn't there. [http://sf.net/support/tracker.php?aid=1960543 1960543]

== Canvases ==
* To allow backward compatibility, canvas version has been set to 0.6.

== Files ==
* In the 'open > recent files' menu entry, only show files which still exist. Previously, it was saving documents into /tmp. After rebooting /tmp had been emptied, but the files were still showing up in the menu.
* Modified the Help menu due to Communication page on the website was renamed to Contact.
* Fix error when trying to change value of Filename property. [http://sf.net/support/tracker.php?aid=1988939 1988939]

== Settings ==
* Added a new tab in the [[Setup Dialog|Setup Dialog]] to allow user set the preferences for: X and Y sizes for new documents, the new Document filename prefix and a selector for predefined resolutions.

== Linking ==
Added new feature [[Linking to Blines| Link to Bline]]: allow the user link vertexes, tangents and widths to a parametrized position of a bline. Also inverse manipulation is allowed. This makes easier to build complex figures without need to have a vertex on the joining point.

== Waypoints ==
* [[TCB|TENSION and TEMPORAL TENSION]] were the same; use the 'temporal' version everywhere.
* Don't render waypoints that lie outside the bounds of the timetrack's adjustment. [http://sf.net/support/tracker.php?aid=1888863 1888863]
* Don't offer 'Manual' as an interpolation type. It's not clear what it is supposed to do, and looks like the code to implement it was never written. Attempting to use it causes uninitialized memory to be read.

== Time ==
* Fix bad time entry when format is set to FFf. Apply [http://patches.synfig.org/r/4/ 4]
* Show time 3.0 as "3s" in the default (FORMAT_NORMAL) time display mode, rather than sometimes showing "3s 0f".

== Windows ==
=== Console Window ===
* Make the file selector dialogs print less output to the console.
* Show the 'fifo_activity' message less.
* Show commands as they are received over the FIFO.
* Don't show debugging messages about saving preference directories.

=== Toolbox Window ===
* Add new icon for the reset colors button and change the code to use it.
Sizes of foreground color and background color picker has been modified to allow some GTK themes show the reverse FG and BG colors and set FG and BG colors buttons properly. Apply [http://patches.synfig.org/r/2/ 2]

=== Workarea Window ===
* Fix zoom fit so it really does zoom the canvas to fit the window. [http://sf.net/support/tracker.php?aid=1901244 1901244]
* Show a 'zoom to fit' icon in the zoomdial as well as a 'zoom 100%' icon.
* Fix "zoom to fit" so that it centers the fitted canvas on the screen, and always zooms back to the previous zoom level and position if clicked a second time.

=== Canvas Properties Dialog ===
* When calculating the start and end frames, round to the nearest integer rather than always rounding down.
* Editing the name, description, or id of a canvas should mark the canvas as needing to be saved, and should also be undoable. [http://sf.net/support/tracker.php?aid=1924592 1924592]

=== Color Editor Dialog ===
* Allow clicking or scrolling on colour sliders to change the colour.

=== Gradient Editor Dialog ===
* Properly manage the situation when all CPoints of a gradient are removed. [http://sf.net/support/tracker.php?aid=2096641 2096641]

=== Time Track Panel ===
* Update the timeline scrollbars' major step size when zooming time in and out. [http://sf.net/support/tracker.php?aid=1914874 1914874]
* Allow scrolling left and right in time widgets.
* Fix a bug that was causing the time slider to not be displayed in certain circumstances.

=== Curves Panel ===
* Don't show incorrect error message when selecting a filename or canvas parameter due the parameter is not representable in the Curves panel. [http://sf.net/support/tracker.php?aid=2060732 2060732]

=== Splash Screen ===
* Remove the build information and use a new image by Yaco & Genete

== Tools ==
* Text, Plant, Polyline and Star have new icons.
* [[Circle Tool|Circle tool]] allows now make Blined circles too. Regions, Outlines, Gradients and Plants are included.
* [[ Rectangle Tool|Rectangle tool]] now does the same.
* New [[Text Tool| Text tool]] has been added to the [[Toolbox|ToolBox]].
* New [[Star Tool|Star Tool]] has been added to the tool palette. It allows now make blined stars too. Regions, Outlines, Gradients and Plants are included.
* Now [[Eyedrop Tool|eyedropper]] works correctly with straight blends for all types of layers. [http://sf.net/support/tracker.php?aid=2119764 2119764]
* The "Link Offsets" option in the [[BLine Tool|BLine tool]] now only links offsets if we're creating more than one layer at a time.
* Added options to the circle tool for creation of bline approximations to circles. Number of points and points angle offset.
* Use the 'feather' and 'invert' tool options when creating outline or region layers in the circle tool.
* Remove the "blend method" option from the tool options panel for the circle and gradient tools (unless the BLEND_METHOD_IN_TOOL_OPTIONS #define in toolbox.h is uncommented).
* Add 'inner tangent', 'outer tangent' and 'radius ratio' options to the star tool for creating rounded stars and different ratios stars.
* Show the name of the current tool in the tool options panel if it has any options. For the zoom tool, show the message that it doesn't have any options, instead of just showing a blank panel.
* Replace "Gradient" check button with "Create Gradient BLine", etc., like in the other tools.
* Using the Circle tool over an existing duck now doesn't crash. [http://sf.net/support/tracker.php?aid=1959064 1959064]

== Ducks ==
* Fixed infinite error message loop on split tangents. [http://sf.net/support/tracker.php?aid=1947076 1947076]

== Miscellaneous ==
* Improve Segment Tangent and Bline Tangent calculations. Now they give more accurate results.
* If only one of -w and -h is specified on the command line, calculate the other in order to keep the aspect ratio fixed.
* Check for Gtk::AboutDialog::set_wrap_license, which was added in Gtkmm 2.8. Allows synfigstudio to build on the fink distribution.
* Update configure.ac as suggested by autoupdate.
* Improved GUI for the sound file selection dialog. [http://sf.net/support/tracker.php?aid=1932525 1932525]
* Alt-D = draw, Alt-W = width. Previously there were 2 different definitions for Alt-T.
* More strings has been extracted to be marked as translatable. Spanish, French and Catalan translations Updated.
* Add multiple sizes and a scalable version of synfig_icon installed in freedesktop.org icon directories. [http://sf.net/support/tracker.php?aid=2109095 2109095]

Releases/0.61.09

2008-10-08T19:15:24Z

Dooglus: /* General */

Released October XX 2008

== General ==
* Forum use nows phpBB3.
* We have migrated from the Voria server to a new VPS server.
* We moved our subversion repository to sourceforge
* We are testing Review Board for patches in synfig. http://patches.synfig.org/

== ETL ==
* Improved the derivative class for hermites.

== Layers ==
* Don't let feather be negative for any Shape layers or Circle layers.
* Fix handling of segments so that the examples/walk/walk.sifz file will load correctly.
* Use 0 for the index if the closest point is on the segment which closes the loop. This keeps the final 'amount' value in the range 0..1.
* Fix a bug in the plant layer: when the plant is so small that we can't calculate the perpendicular to its bline, skip trying to branch it.
* Improve a warning message when we find an unknown layer parameter.
* Rename all 'pos' and 'offset' parameters to 'origin'.
* Add parameter 'add_width' to the [[Plant Layer|plant layer]]. It's on by default, and means to scale the velocity of a plant's shoot by the width of the bline at that point.
* Now circles with large feather and zero radius are visible. Only shortcut zero-radius circles if they're not inverted and have no feathering. [http://sf.net/support/tracker.php?aid=2120629 2120629]
* Leave previously selected layers selected when create a new one. SYNFIG_TOOLS_CLEAR_SELECTION toggle this option.
* Add "select all layers" (S-C-a) and "unselect all ducks" (C-d). Move "unselect all layers" onto S-C-d.
* When multiple layers are selected, only show parameters which are present in all selected layers *with the same type*.

== Value Nodes ==
*Add new types:
** [[Convert#Logarithm|Logarithm]]: To convert to a natural logarithm
** [[Convert#Int String|Int String]]: To convert to a string form an integer
** [[Convert#Angle String|Angle String]] : To convert to a string form an angle
** [[Convert#Joined List|Joined List]]: Join two strings
** [[Convert#Real String|Real String]]: To convert to a string form a real
** [[Convert#Time String|Time String]]: To convert to a string form a time
** [[Convert#Dot Product|Dot Product]]: Convert to a real from the dot product of two vectors
** [[Convert#Gradient Color|Gradient Color]]: Convert to a color from a gradient
** [[Convert#Vector X|Vector X]]: Convert to a real from a vector (get its X)
** [[Convert#Vector Y|Vector Y]]: Convert to a real from a vector (get its Y)
** [[Convert#Vector Length|Vector Length]]: Convert to a real from a vector (get its length)
** [[Convert#Vector Angle|Vector Angle]]: Convert to an angle from a vector (get its angle)
* Add "Loop" link to the "Gradient Color" ValueNode.

== Targets ==
* Unless OpenEXR half mode is used, don't ask synfigstudio to depend on it.
* Fix build problem with newer versions of libavformat due to the pb member of AVFormatContext changing from a structure to a pointer. [http://sf.net/support/tracker.php?aid=11877061 11877061]
* Fix Debian 487639: for mod_libav, allow the use of libswscale instead of the depreciated img_convert function. Apply [http://sf.net/support/tracker.php?aid=2036627 2036627]
* Fix the libjpeg configure test to look for the right function.
* Windows builds now include OpenEXR version 1.6.
* Configure now use pkg-config to find libswscale. [http://sf.net/support/tracker.php?aid=2108984 2108984]
* Cope with some changes in the locations of the libavformat and libswscale headers.
* Add a configure flag to switch on/off jpeg support. Apply [http://patches.synfig.org/r/5/ 5]

== Blend Methods ==
* Fix this bug: when a layer was composed 'straight onto' a context with which its bounding box had no overlap, the context was being displayed as if the 'straight onto' layer wasn't there. [http://sf.net/support/tracker.php?aid=1960543 1960543]

== Canvases ==
* To allow backward compatibility, canvas version has been set to 0.6.

== Files ==
* In the 'open > recent files' menu entry, only show files which still exist. Previously, it was saving documents into /tmp. After rebooting /tmp had been emptied, but the files were still showing up in the menu.
* Modified the Help menu due to Communication page on the website was renamed to Contact.
* Fix error when trying to change value of Filename property. [http://sf.net/support/tracker.php?aid=1988939 1988939]

== Settings ==
* Added a new tab in the [[Setup Dialog|Setup Dialog]] to allow user set the preferences for: X and Y sizes for new documents, the new Document filename prefix and a selector for predefined resolutions.

== Linking ==
Added new feature [[Linking to Blines| Link to Bline]]: allow the user link vertexes, tangents and widths to a parametrized position of a bline. Also inverse manipulation is allowed. This makes easier to build complex figures without need to have a vertex on the joining point.

== Waypoints ==
* [[TCB|TENSION and TEMPORAL TENSION]] were the same; use the 'temporal' version everywhere.
* Don't render waypoints that lie outside the bounds of the timetrack's adjustment. [http://sf.net/support/tracker.php?aid=1888863 1888863]
* Don't offer 'Manual' as an interpolation type. It's not clear what it is supposed to do, and looks like the code to implement it was never written. Attempting to use it causes uninitialized memory to be read.

== Time ==
* Fix bad time entry when format is set to FFf. Apply [http://patches.synfig.org/r/4/ 4]
* Show time 3.0 as "3s" in the default (FORMAT_NORMAL) time display mode, rather than sometimes showing "3s 0f".

== Windows ==
=== Console Window ===
* Make the file selector dialogs print less output to the console.
* Show the 'fifo_activity' message less.
* Show commands as they are received over the FIFO.
* Don't show debugging messages about saving preference directories.

=== Toolbox Window ===
* Add new icon for the reset colors button and change the code to use it.
Sizes of foreground color and background color picker has been modified to allow some GTK themes show the reverse FG and BG colors and set FG and BG colors buttons properly. Apply [http://patches.synfig.org/r/2/ 2]

=== Workarea Window ===
* Fix zoom fit so it really does zoom the canvas to fit the window. [http://sf.net/support/tracker.php?aid=1901244 1901244]
* Show a 'zoom to fit' icon in the zoomdial as well as a 'zoom 100%' icon.
* Fix "zoom to fit" so that it centers the fitted canvas on the screen, and always zooms back to the previous zoom level and position if clicked a second time.

=== Canvas Properties Dialog ===
* When calculating the start and end frames, round to the nearest integer rather than always rounding down.
* Editing the name, description, or id of a canvas should mark the canvas as needing to be saved, and should also be undoable. [http://sf.net/support/tracker.php?aid=1924592 1924592]

=== Color Editor Dialog ===
* Allow clicking or scrolling on colour sliders to change the colour.

=== Gradient Editor Dialog ===
* Properly manage the situation when all CPoints of a gradient are removed. [http://sf.net/support/tracker.php?aid=2096641 2096641]

=== Time Track Panel ===
* Update the timeline scrollbars' major step size when zooming time in and out. [http://sf.net/support/tracker.php?aid=1914874 1914874]
* Allow scrolling left and right in time widgets.
* Fix a bug that was causing the time slider to not be displayed in certain circumstances.

=== Curves Panel ===
* Don't show incorrect error message when selecting a filename or canvas parameter due the parameter is not representable in the Curves panel. [http://sf.net/support/tracker.php?aid=2060732 2060732]

=== Splash Screen ===
* Remove the build information and use a new image by Yaco & Genete

== Tools ==
* Text, Plant, Polyline and Star have new icons.
* [[Circle Tool|Circle tool]] allows now make Blined circles too. Regions, Outlines, Gradients and Plants are included.
* [[ Rectangle Tool|Rectangle tool]] now does the same.
* New [[Text Tool| Text tool]] has been added to the [[Toolbox|ToolBox]].
* New [[Star Tool|Star Tool]] has been added to the tool palette. It allows now make blined stars too. Regions, Outlines, Gradients and Plants are included.
* Now [[Eyedrop Tool|eyedropper]] works correctly with straight blends for all types of layers. [http://sf.net/support/tracker.php?aid=2119764 2119764]
* The "Link Offsets" option in the [[BLine Tool|BLine tool]] now only links offsets if we're creating more than one layer at a time.
* Added options to the circle tool for creation of bline approximations to circles. Number of points and points angle offset.
* Use the 'feather' and 'invert' tool options when creating outline or region layers in the circle tool.
* Remove the "blend method" option from the tool options panel for the circle and gradient tools (unless the BLEND_METHOD_IN_TOOL_OPTIONS #define in toolbox.h is uncommented).
* Add 'inner tangent', 'outer tangent' and 'radius ratio' options to the star tool for creating rounded stars and different ratios stars.
* Show the name of the current tool in the tool options panel if it has any options. For the zoom tool, show the message that it doesn't have any options, instead of just showing a blank panel.
* Replace "Gradient" check button with "Create Gradient BLine", etc., like in the other tools.
* Using the Circle tool over an existing duck now doesn't crash. [http://sf.net/support/tracker.php?aid=1959064 1959064]

== Ducks ==
* Fixed infinite error message loop on split tangents. [http://sf.net/support/tracker.php?aid=1947076 1947076]

== Miscellaneous ==
* Improve Segment Tangent and Bline Tangent calculations. Now they give more accurate results.
* If only one of -w and -h is specified on the command line, calculate the other in order to keep the aspect ratio fixed.
* Check for Gtk::AboutDialog::set_wrap_license, which was added in Gtkmm 2.8. Allows synfigstudio to build on the fink distribution.
* Update configure.ac as suggested by autoupdate.
* Improved GUI for the sound file selection dialog. [http://sf.net/support/tracker.php?aid=1932525 1932525]
* Alt-D = draw, Alt-W = width. Previously there were 2 different definitions for Alt-T.
* More strings has been extracted to be marked as translatable. Spanish, French and Catalan translations Updated.
* Add multiple sizes and a scalable version of synfig_icon installed in freedesktop.org icon directories. [http://sf.net/support/tracker.php?aid=2109095 2109095]

Doc talk:Gimp2synfig

2008-04-26T20:39:09Z

Dooglus:

vonhalenbach on IRC was using GIMP 2.2 and Python 2.5.1 and found that his generated sif output was ending after 20 lines:

19 <param name="canvas">
20 <canvas xres="10.000000" yres="10.000000">

whereas for me (with Python 2.5.2 and Gimp 2.4.5) it continues:

19 <param name="canvas">
20 <canvas xres="10.000000" yres="10.000000">
21 <layer type="import" active="true" version="0.1" desc="Background.png">
22 <param name="z_depth">
23 [...]

Yes, this script was writen for 2.4.*. I have no 2.2.* to test it. So I'll try to fix this problem if you give me information from gimp-2.2.* console with backtrace. --[[User:AkhIL|AkhIL]] 12:42, 26 April 2008 (EDT)

$ gimp /tmp/111.xcf
/usr/local/lib/gimp/2.0/python/gimpfu.py:428: GtkDeprecationWarning: gtk.FALSE is deprecated, use False instead
hbox = gtk.HBox(gtk.FALSE, 5)
/usr/local/lib/gimp/2.0/python/gimpfu.py:430: GtkDeprecationWarning: gtk.FALSE is deprecated, use False instead
dialog.vbox.pack_start(hbox, expand=gtk.FALSE)
/usr/local/lib/gimp/2.0/python/gimpfu.py:433: GtkDeprecationWarning: gtk.FALSE is deprecated, use False instead
table = gtk.Table(len(params), 2, gtk.FALSE)
/usr/local/lib/gimp/2.0/python/gimpfu.py:437: GtkDeprecationWarning: gtk.FALSE is deprecated, use False instead
hbox.pack_end(table, expand=gtk.FALSE)
/usr/local/lib/gimp/2.0/python/gimpfu.py:440: GtkDeprecationWarning: gtk.FALSE is deprecated, use False instead
vbox = gtk.VBox(gtk.FALSE, 10)
/usr/local/lib/gimp/2.0/python/gimpfu.py:441: GtkDeprecationWarning: gtk.FALSE is deprecated, use False instead
hbox.pack_start(vbox, expand=gtk.FALSE)
/usr/local/lib/gimp/2.0/python/gimpfu.py:446: GtkDeprecationWarning: gtk.FALSE is deprecated, use False instead
vbox.pack_start(pix, expand=gtk.FALSE)
/usr/local/lib/gimp/2.0/python/gimpfu.py:450: GtkDeprecationWarning: gtk.TRUE is deprecated, use True instead
label.set_line_wrap(gtk.TRUE)
/usr/local/lib/gimp/2.0/python/gimpfu.py:453: GtkDeprecationWarning: gtk.FALSE is deprecated, use False instead
vbox.pack_start(label, expand=gtk.FALSE)
Traceback (most recent call last):
File "/usr/local/lib/gimp/2.0/python/gimpfu.py", line 469, in response
dialog.res = run_script(params)
File "/usr/local/lib/gimp/2.0/python/gimpfu.py", line 257, in run_script
return apply(function, params)
File "/home/chris/.gimp-2.2/plug-ins/synfigexport.py", line 248, in python_fu_exportsynfig
newlayer = gimp.Layer(newimg, l.name, l.width, l.height, l.type)
TypeError: gimp.Layer.__init__() takes exactly 7 arguments (5 given)

http://dooglus.rincevent.net/random/synfigexport.py is a fixed version. In GIMP 2.2, all the arguments to Layer.__init__ are required, so I specify the opacity and blend method. -- [[User:Dooglus|dooglus]] 16:39, 26 April 2008 (EDT)

Doc:Gimp2synfig

2008-04-26T20:38:00Z

Dooglus:

To simplify the work of animating my cartoon about a mouse, a plug-in for the [http://gimp.org/ GIMP] raster editor has been written to allow the direct exporting of multi-layered images to corresponding layers of the 2D animation package Synfig.

The plug-in registers itself in the GIMP image menu <image>-> File-> Export-> Synfig.

[http://img246.imageshack.us/my.php?image=gimp2synfigmenuxh9.jpg http://img246.imageshack.us/img246/4126/gimp2synfigmenuxh9.th.jpg]

There are export options you can choose. If the field "output path" is empty, the synfig canvas will be kept in the same directory as the initial GIMP document.

[http://img292.imageshack.us/my.php?image=gimp2synfigsettingsvs3.jpg http://img292.imageshack.us/img292/269/gimp2synfigsettingsvs3.th.jpg]

Here is the result:

[http://img201.imageshack.us/my.php?image=gimp2synfig003yn6.jpg http://img201.imageshack.us/img201/9369/gimp2synfig003yn6.th.jpg]

On the left you can see the initial image in Gimp, and on the right the same image imported into Synfig.

After adding a scale layer, the images cannot be distinguished.

[http://img151.imageshack.us/my.php?image=gimp2synfig003withgammafd6.jpg http://img151.imageshack.us/img151/5450/gimp2synfig003withgammafd6.th.jpg]

You can download the [http://akhil.nm.ru/tools/pygimp/synfigexport.py GIMP2synfig plugin]. Or a [http://dooglus.rincevent.net/random/synfigexport.py fixed version] that also works with GIMP 2.2.

For it to work, GIMP must support Python, and the most recent version of Python must be fully installed.

To install it, simply place the file in ~/.gimp-*/plug-ins/ and make it executable (chmod +x synfigexport.py), then restart The GIMP.

This program is licensed under Creative Commons Attribution 3.0 Unported License. Distribution and updating of the code is welcomed.

Doc talk:Gimp2synfig

2008-04-26T19:23:25Z

Dooglus:

Doc talk:Gimp2synfig

2008-04-26T15:03:33Z

Dooglus: New page: vonhalenbach on IRC was using GIMP 2.2 and Python 2.5.1 and found that his generated sif output was ending after 20 lines: 19 <param name="canvas"> 20 <canvas xres="10.000000" y...

Talk:Main Page

2008-04-17T07:01:39Z

Dooglus:

== New Layout ==

The new layout does look a lot better, but before deleting the old layout, can we make sure we're not losing any useful links? For example, currently the "Special:Allpages" link is only in the old layout. -- [[User:Dooglus|dooglus]] 12:27, 26 December 2007 (EST)
:We can add al that links in the left bar if you think its ok.
::Yaco

The 0.61.08 download image needs to say "Synfig Animation Studio" instead of "Synfig"
:[[User:PaulWise|pabs]] 04:27, 6 April 2008 (EDT)

I saw there's a way to remove the toolbox for un-connected people, maybe we could do that, as the links in the toolbox are only usefull to connected persons.<br>
And then, add the "Sidebar" back to the left side, with much more links in it (like, the ones from the bottom of the main page, that I even removed on the [[Main_Page.fr]]), that would be great. <br>
And have a "Topbar" page or just some fixed link for the topbar, with only "Home / About / Download / Gallery / Screenshots / Tutorials / Forums " in a smaller font, and a lighter color (not-visited pages are #2A4D66 on #030336 and they're hardly visible at 1st sight).
:[[User:Rore|Rore]] 02:49, 7 April 2008 (EDT)

Upper image overlaps search bar and user menu on 1024x768 screen resolution. Tested with opera. --[[User:AkhIL|AkhIL]] 22:45, 8 April 2008 (EDT)

There's a thick black nothing between the left hand boxes and the main central page content. -- [[User:Dooglus|dooglus]] 15:31, 11 April 2008 (EDT)

I'd like to see more links in the left hand boxes - at least "all pages" should be there, and things like "people", "bugs", "press", etc from the top would be better at the side. There are too many links across the top. We should just have the most useful ones there. -- [[User:Dooglus|dooglus]] 15:31, 11 April 2008 (EDT)

[http://dooglus.rincevent.net/random/mainpage.png] shows some remaining problems:
* the border of the top image is different widths on the two sides
* the text links and search box on the right are hidden by the image
* the image text isn't readable
* the image text mis-spells "beatiful"

Dev:Adding a Layer

2008-04-16T17:53:12Z

Dooglus:

Here's an example of how to add a simple layer to an existing module. For this example I picked something very easy: a layer which removes all colour from the layers beneath it. I will call this creation "Desaturate", and add it to the mod_filter module.

Section 1, "The Code" will present the entire source, uninterrupted, and section 2, "The Description" will break it up into small chunks and discuss it.

== The Code ==

We need to create two new files (one header (.h) file, and one implementation (.cpp) file), and edit two existing files (the module's main.cpp, and the Makefile.am), all in the synfig/src/modules/mod_filter/ folder:

=== <module>/desaturate.h ===

/* === S Y N F I G ========================================================= */
/*! \file desaturate.h
** \brief Header file for implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === S T A R T =========================================================== */

#ifndef __SYNFIG_DESATURATE_H
#define __SYNFIG_DESATURATE_H

/* === H E A D E R S ======================================================= */

#include <synfig/layer.h>

/* === C L A S S E S & S T R U C T S ======================================= */

class Desaturate : public synfig::Layer
{
SYNFIG_LAYER_MODULE_EXT
public:
virtual synfig::ValueBase get_param(const synfig::String&)const;
virtual Vocab get_param_vocab()const;
virtual synfig::Color get_color(synfig::Context, const synfig::Point&)const;
virtual bool accelerated_render(synfig::Context,synfig::Surface*,int,
const synfig::RendDesc &, synfig::ProgressCallback *)const;
}; // END of class Desaturate

#endif

=== <module>/desaturate.cpp ===

/* === S Y N F I G ========================================================= */
/*! \file desaturate.cpp
** \brief Implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === H E A D E R S ======================================================= */

#ifdef USING_PCH
# include "pch.h"
#else
#ifdef HAVE_CONFIG_H
# include <config.h>
#endif

#include "desaturate.h"

#include <synfig/context.h>
#include <synfig/paramdesc.h>
#include <synfig/renddesc.h>
#include <synfig/surface.h>
#include <synfig/value.h>

#endif

using namespace synfig;

/* === G L O B A L S ======================================================= */

SYNFIG_LAYER_INIT(Desaturate);
SYNFIG_LAYER_SET_NAME(Desaturate,"desaturate");
SYNFIG_LAYER_SET_LOCAL_NAME(Desaturate,N_("Desaturate"));
SYNFIG_LAYER_SET_CATEGORY(Desaturate,N_("Filters"));
SYNFIG_LAYER_SET_VERSION(Desaturate,"0.1");
SYNFIG_LAYER_SET_CVS_ID(Desaturate,"$Id$");

/* === M E T H O D S ======================================================= */

ValueBase
Desaturate::get_param(const String &param)const
{
EXPORT_NAME();
EXPORT_VERSION();

return ValueBase();
}

Layer::Vocab
Desaturate::get_param_vocab()const
{
return Layer::Vocab();
}

Color
Desaturate::get_color(Context context, const Point &getpos)const
{
Color tmp(context.get_color(getpos));
return tmp.set_s(0);
}

bool
Desaturate::accelerated_render(Context context,
Surface* surface,
int quality,
const RendDesc& renddesc,
ProgressCallback* cb
)const
{
SuperCallback supercb(cb,0,9500,10000);

// render the context onto the given surface
if(!context.accelerated_render(surface,quality,renddesc,&supercb))
return false;

// set the saturation of each pixel to zero
int x,y;
Surface::pen pen(surface->begin());
for(y=0;y<renddesc.get_h();y++,pen.inc_y(),pen.dec_x(x))
for(x=0;x<renddesc.get_w();x++,pen.inc_x())
{
Color tmp(pen.get_value());
pen.put_value(tmp.set_s(0));
}

// mark our progress as finished
if(cb && !cb->amount_complete(10000,10000)) return false;
return true;
}

=== <module>/Makefile.am ===

Then I need to edit modules/mod_filter/Makefile.am and add these two files to the list of source files (maintain alphabetical order please):

libmod_filter_la_SOURCES = blur.cpp blur.h colorcorrect.cpp colorcorrect.h desaturate.cpp desaturate.h halftone2.cpp halftone2.h lumakey.cpp lumakey.h radialblur.cpp radialblur.h main.cpp halftone.cpp halftone.h halftone3.cpp halftone3.h

=== <module>/main.cpp ===

And finally we edit modules/mod_filter/main.cpp. Add this with the other #include lines:

#include "desaturate.h"

and add this with the other LAYER(...) lines:

LAYER(Desaturate)

then rebuild (including the autoreconf, ./configure, etc., to get the new files added to the Makefile) and we're done.

== The Description ==

I'll break the header up into sections, describing each part:

=== The initial comment ===

This contains basic documentation and legal stuff. Just copy, paste, and edit from another file.

/* === S Y N F I G ========================================================= */
/*! \file desaturate.h
** \brief Header file for implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === S T A R T =========================================================== */

=== Protection against Multiple Inclusion ===

This #ifndef is a standard way to make sure the header is only compiled once, even if it happens to be included multiple times. Use a unique symbol, based on the file name.

#ifndef __SYNFIG_DESATURATE_H
#define __SYNFIG_DESATURATE_H

=== Headers ===

Include files which are needed. We're not doing anything much, so all we need to include is layer.h, which defines the Layer class that all layers inherit from.

/* === H E A D E R S ======================================================= */

#include <synfig/layer.h>

=== The Class ===

Define the class which implements our layer. We inherit from the Layer class. For this simple example we only define four methods. The rest will be inherited from the Layer class.

/* === C L A S S E S & S T R U C T S ======================================= */

class Desaturate : public synfig::Layer
{

=== SYNFIG_LAYER_MODULE_EXT ===

This is standard. Just use it for every layer. It declares members to hold the layer's name, version, category, etc., and also declares a method to create() the layer. See synfig/src/synfig/layer.h for its definition.

SYNFIG_LAYER_MODULE_EXT

=== The Methods ===

Then we declare the four methods we're going to implement. First "get_param()". Since our layer isn't going to have any parameters, all it needs to do is make the layer's name and
version available.

==== get_param ====

public:
virtual synfig::ValueBase get_param(const synfig::String&)const;

==== get_param_vocab ====

This one returns a list of the layer's parameters. We have no parameters, so we return an empty list.

virtual Vocab get_param_vocab()const;

==== get_color ====

This one is used to find the color of a single given pixel. It's used by the "Info" panel to display the R,G,B values as you mouse over the canvas. It's also used if our layer has any transformation layers over the top of it. The absence of a working implementation of this method in the "Text" layer is why distorting text currently causes render artifacts.

virtual synfig::Color get_color(synfig::Context, const synfig::Point&)const;

==== accelerated_render ====

This one is used to render a large rectangular piece of our layer in one go. It typically calls the accelerated_render() method for the layers under our layer (the 'context') and then modifies the results of that call in some way:

virtual bool accelerated_render(synfig::Context,synfig::Surface*,int,
const synfig::RendDesc &, synfig::ProgressCallback *)const;
}; // END of class Desaturate

#endif

== Implementation ==

I won't reproduce the whole of the .cpp file here and go through it. The only two methods which are really interesting here are get_color() and accelerated_render():

Note the "G L O B A L S" section of the code defines the layer's name (lower case, used in .sif files), its "local" name (this is the string which is translated, and is capitalized), which category the layer belongs in (this determines where it appears in the 'new layer' menu), the layer's version (0.1 for new layers), etc.

=== get_color() ===

Given the context, and a point, get_color() should return the color of the pixel at the given point. The context has a get_color() method, so we use that to look up the color of the pixel before our layer has had a chance to affect it, and store that in 'tmp'. Then we set its saturation to zero using [http://synfig.org/api/synfig/classsynfig_1_1Color.html#b62c2069fc43baa97fba17b33ff4d32d color.set_s()] and return it. That's all:

Color
Desaturate::get_color(Context context, const Point &getpos)const
{
Color tmp(context.get_color(getpos));
return tmp.set_s(0);
}

=== accelerated_render() ===

We accept five arguments:

The context (ie. the layers under us):

bool
Desaturate::accelerated_render(Context context,

The surface we are supposed to write our results onto:

Surface* surface,

The quality at which we are to render:

int quality,

A description of the area to render - width, height, top left corner, resolution, etc, etc:

const RendDesc& renddesc,

An object which is used to monitor our progress. It's used for calculating the expected remaining time while rendering:

ProgressCallback* cb
)const
{

I didn't get around to looking at the way the 'cb' ProgressCallback is used. But this code is in pretty much all layers:

SuperCallback supercb(cb,0,9500,10000);

We call accelerated_render() on the context, to render the layers under us. We just pass on the arguments we received for surface, quality and renddesc, along with the new callback we just made. If that render fails, then we fail too:

// render the context onto the given surface
if(!context.accelerated_render(surface,quality,renddesc,&supercb))
return false;

Now we do the real work of this layer. We define integers to do the looping, and a 'pen' which we can walk over the rectangle we're working on:

// set the saturation of each pixel to zero
int x,y;
Surface::pen pen(surface->begin());

We loop through every pixel on every row of the rectangle we're working on. The 'renddesc' gives us the width and height of the rectangle. The pen has methods inc_x(), dec_x(), inc_y(), dec_y() which move it a given amount:

for(y=0;y<renddesc.get_h();y++,pen.inc_y(),pen.dec_x(x))
for(x=0;x<renddesc.get_w();x++,pen.inc_x())

At each pixel, we get the color as rendered from the context, set its saturation to zero, and write it back to the same surface:

{
Color tmp(pen.get_value());
pen.put_value(tmp.set_s(0));
}

And that's about it.

// mark our progress as finished
if(cb && !cb->amount_complete(10000,10000)) return false;
return true;
}

== Adding Parameters ==

Suppose now we want to add a parameter to the layer. Let's add a Real valued parameter called "scale". It will let the user set a value to scale the saturation by. It will default to zero, meaning to scale the saturation down to zero. When adding parameters, it's a good idea to set the default value to its effective previous value, so that old .sif files will continue to be rendered the same as before.

To add this parameter, we need to do the following:

=== desaturate.h ===

In the desaturate.h header file, include real.h (the parameter is Real valued, so we need the typedef for Real):

#include <synfig/real.h>

Add a private member to the class, type Real:

private:
synfig::Real scale;

Declare a default constructor. This is where we will set the default value of the new parameter:

Desaturate();

Declare set_param(). This will allow our layer to accept new values for the parameter:

virtual bool set_param(const synfig::String&, const synfig::ValueBase&);

=== desaturate.cpp ===

In the implementation file, we need to:

write a simple default constructor, which initializes the value of 'scale' to zero:

Desaturate::Desaturate():
scale(0)
{}

Add a line to supply the value of 'scale' in get_param():

ValueBase
Desaturate::get_param(const String &param)const
{
EXPORT_NAME();
EXPORT_VERSION();

EXPORT(scale);

return ValueBase();
}

Add new method set_param():

bool
Desaturate::set_param(const String &param, const ValueBase &value)
{
IMPORT(scale);

return false;
}

Replace the definition of get_param_vocab():

Layer::Vocab
Desaturate::get_param_vocab()const
{
Layer::Vocab ret;

ret.push_back(ParamDesc("scale")
.set_local_name(_("Scale"))
.set_description(_("Factor to scale the saturation by"))
);

return ret;
}

And change the two places where the saturation is set. In get_color():

return tmp.set_s(scale * tmp.get_s());

And in accelerated_render():

pen.put_value(tmp.set_s(scale * tmp.get_s()));

Dev:Adding a Layer

2008-04-16T17:03:37Z

Dooglus: adding a parameter - wip.

Here's an example of how to add a simple layer to an existing module. For this example I picked something very easy: a layer which removes all colour from the layers beneath it. I will call this creation "Desaturate", and add it to the mod_filter module.

Section 1, "The Code" will present the entire source, uninterrupted, and section 2, "The Description" will break it up into small chunks and discuss it.

== The Code ==

We need to create two new files (one header (.h) file, and one implementation (.cpp) file), and edit two existing files (the module's main.cpp, and the Makefile.am), all in the synfig/src/modules/mod_filter/ folder:

=== <module>/desaturate.h ===

/* === S Y N F I G ========================================================= */
/*! \file desaturate.h
** \brief Header file for implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === S T A R T =========================================================== */

#ifndef __SYNFIG_DESATURATE_H
#define __SYNFIG_DESATURATE_H

/* === H E A D E R S ======================================================= */

#include <synfig/layer.h>

/* === C L A S S E S & S T R U C T S ======================================= */

class Desaturate : public synfig::Layer
{
SYNFIG_LAYER_MODULE_EXT
public:
virtual synfig::ValueBase get_param(const synfig::String&)const;
virtual Vocab get_param_vocab()const;
virtual synfig::Color get_color(synfig::Context, const synfig::Point&)const;
virtual bool accelerated_render(synfig::Context,synfig::Surface*,int,
const synfig::RendDesc &, synfig::ProgressCallback *)const;
}; // END of class Desaturate

#endif

=== <module>/desaturate.cpp ===

/* === S Y N F I G ========================================================= */
/*! \file desaturate.cpp
** \brief Implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === H E A D E R S ======================================================= */

#ifdef USING_PCH
# include "pch.h"
#else
#ifdef HAVE_CONFIG_H
# include <config.h>
#endif

#include "desaturate.h"

#include <synfig/context.h>
#include <synfig/paramdesc.h>
#include <synfig/renddesc.h>
#include <synfig/surface.h>
#include <synfig/value.h>

#endif

using namespace synfig;

/* === G L O B A L S ======================================================= */

SYNFIG_LAYER_INIT(Desaturate);
SYNFIG_LAYER_SET_NAME(Desaturate,"desaturate");
SYNFIG_LAYER_SET_LOCAL_NAME(Desaturate,N_("Desaturate"));
SYNFIG_LAYER_SET_CATEGORY(Desaturate,N_("Filters"));
SYNFIG_LAYER_SET_VERSION(Desaturate,"0.1");
SYNFIG_LAYER_SET_CVS_ID(Desaturate,"$Id$");

/* === M E T H O D S ======================================================= */

ValueBase
Desaturate::get_param(const String &param)const
{
EXPORT_NAME();
EXPORT_VERSION();

return ValueBase();
}

Layer::Vocab
Desaturate::get_param_vocab()const
{
return Layer::Vocab();
}

Color
Desaturate::get_color(Context context, const Point &getpos)const
{
Color tmp(context.get_color(getpos));
return tmp.set_s(0);
}

bool
Desaturate::accelerated_render(Context context,
Surface* surface,
int quality,
const RendDesc& renddesc,
ProgressCallback* cb
)const
{
SuperCallback supercb(cb,0,9500,10000);

// render the context onto the given surface
if(!context.accelerated_render(surface,quality,renddesc,&supercb))
return false;

// set the saturation of each pixel to zero
int x,y;
Surface::pen pen(surface->begin());
for(y=0;y<renddesc.get_h();y++,pen.inc_y(),pen.dec_x(x))
for(x=0;x<renddesc.get_w();x++,pen.inc_x())
{
Color tmp(pen.get_value());
pen.put_value(tmp.set_s(0));
}

// mark our progress as finished
if(cb && !cb->amount_complete(10000,10000)) return false;
return true;
}

=== <module>/Makefile.am ===

Then I need to edit modules/mod_filter/Makefile.am and add these two files to the list of source files (maintain alphabetical order please):

libmod_filter_la_SOURCES = blur.cpp blur.h colorcorrect.cpp colorcorrect.h desaturate.cpp desaturate.h halftone2.cpp halftone2.h lumakey.cpp lumakey.h radialblur.cpp radialblur.h main.cpp halftone.cpp halftone.h halftone3.cpp halftone3.h

=== <module>/main.cpp ===

And finally we edit modules/mod_filter/main.cpp. Add this with the other #include lines:

#include "desaturate.h"

and add this with the other LAYER(...) lines:

LAYER(Desaturate)

then rebuild (including the autoreconf, ./configure, etc., to get the new files added to the Makefile) and we're done.

== The Description ==

I'll break the header up into sections, describing each part:

=== The initial comment ===

This contains basic documentation and legal stuff. Just copy, paste, and edit from another file.

/* === S Y N F I G ========================================================= */
/*! \file desaturate.h
** \brief Header file for implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === S T A R T =========================================================== */

=== Protection against Multiple Inclusion ===

This #ifndef is a standard way to make sure the header is only compiled once, even if it happens to be included multiple times. Use a unique symbol, based on the file name.

#ifndef __SYNFIG_DESATURATE_H
#define __SYNFIG_DESATURATE_H

=== Headers ===

Include files which are needed. We're not doing anything much, so all we need to include is layer.h, which defines the Layer class that all layers inherit from.

/* === H E A D E R S ======================================================= */

#include <synfig/layer.h>

=== The Class ===

Define the class which implements our layer. We inherit from the Layer class. For this simple example we only define four methods. The rest will be inherited from the Layer class.

/* === C L A S S E S & S T R U C T S ======================================= */

class Desaturate : public synfig::Layer
{

=== SYNFIG_LAYER_MODULE_EXT ===

This is standard. Just use it for every layer. It declares members to hold the layer's name, version, category, etc., and also declares a method to create() the layer. See synfig/src/synfig/layer.h for its definition.

SYNFIG_LAYER_MODULE_EXT

=== The Methods ===

Then we declare the four methods we're going to implement. First "get_param()". Since our layer isn't going to have any parameters, all it needs to do is make the layer's name and
version available.

==== get_param ====

public:
virtual synfig::ValueBase get_param(const synfig::String&)const;

==== get_param_vocab ====

This one returns a list of the layer's parameters. We have no parameters, so we return an empty list.

virtual Vocab get_param_vocab()const;

==== get_color ====

This one is used to find the color of a single given pixel. It's used by the "Info" panel to display the R,G,B values as you mouse over the canvas. It's also used if our layer has any transformation layers over the top of it. The absence of a working implementation of this method in the "Text" layer is why distorting text currently causes render artifacts.

virtual synfig::Color get_color(synfig::Context, const synfig::Point&)const;

==== accelerated_render ====

This one is used to render a large rectangular piece of our layer in one go. It typically calls the accelerated_render() method for the layers under our layer (the 'context') and then modifies the results of that call in some way:

virtual bool accelerated_render(synfig::Context,synfig::Surface*,int,
const synfig::RendDesc &, synfig::ProgressCallback *)const;
}; // END of class Desaturate

#endif

== Implementation ==

I won't reproduce the whole of the .cpp file here and go through it. The only two methods which are really interesting here are get_color() and accelerated_render():

Note the "G L O B A L S" section of the code defines the layer's name (lower case, used in .sif files), its "local" name (this is the string which is translated, and is capitalized), which category the layer belongs in (this determines where it appears in the 'new layer' menu), the layer's version (0.1 for new layers), etc.

=== get_color() ===

Given the context, and a point, get_color() should return the color of the pixel at the given point. The context has a get_color() method, so we use that to look up the color of the pixel before our layer has had a chance to affect it, and store that in 'tmp'. Then we set its saturation to zero using [http://synfig.org/api/synfig/classsynfig_1_1Color.html#b62c2069fc43baa97fba17b33ff4d32d color.set_s()] and return it. That's all:

Color
Desaturate::get_color(Context context, const Point &getpos)const
{
Color tmp(context.get_color(getpos));
return tmp.set_s(0);
}

=== accelerated_render() ===

We accept five arguments:

The context (ie. the layers under us):

bool
Desaturate::accelerated_render(Context context,

The surface we are supposed to write our results onto:

Surface* surface,

The quality at which we are to render:

int quality,

A description of the area to render - width, height, top left corner, resolution, etc, etc:

const RendDesc& renddesc,

An object which is used to monitor our progress. It's used for calculating the expected remaining time while rendering:

ProgressCallback* cb
)const
{

I didn't get around to looking at the way the 'cb' ProgressCallback is used. But this code is in pretty much all layers:

SuperCallback supercb(cb,0,9500,10000);

We call accelerated_render() on the context, to render the layers under us. We just pass on the arguments we received for surface, quality and renddesc, along with the new callback we just made. If that render fails, then we fail too:

// render the context onto the given surface
if(!context.accelerated_render(surface,quality,renddesc,&supercb))
return false;

Now we do the real work of this layer. We define integers to do the looping, and a 'pen' which we can walk over the rectangle we're working on:

// set the saturation of each pixel to zero
int x,y;
Surface::pen pen(surface->begin());

We loop through every pixel on every row of the rectangle we're working on. The 'renddesc' gives us the width and height of the rectangle. The pen has methods inc_x(), dec_x(), inc_y(), dec_y() which move it a given amount:

for(y=0;y<renddesc.get_h();y++,pen.inc_y(),pen.dec_x(x))
for(x=0;x<renddesc.get_w();x++,pen.inc_x())

At each pixel, we get the color as rendered from the context, set its saturation to zero, and write it back to the same surface:

{
Color tmp(pen.get_value());
pen.put_value(tmp.set_s(0));
}

And that's about it.

// mark our progress as finished
if(cb && !cb->amount_complete(10000,10000)) return false;
return true;
}

== Adding Parameters ==

Suppose now we want to add a parameter to the layer. Let's add a Real valued parameter called "scale". It will let the user set a value to scale the saturation by. It will default to zero, meaning to scale the saturation down to zero. When adding parameters, it's a good idea to set the default value to its effective previous value, so that old .sif files will continue to be rendered the same as before.

To add this parameter, we need to do the following:

=== desaturate.h ===

In the desaturate.h header file, include real.h (the parameter is Real valued, so we need the typedef for Real):

#include <synfig/real.h>

Add a private member to the class, type Real:

private:
synfig::Real scale;

Declare a default constructor. This is where we will set the default value of the new parameter:

Desaturate();

Declare set_param(). This will allow our layer to accept new values for the parameter:

virtual bool set_param(const synfig::String&, const synfig::ValueBase&);

=== desaturate.cpp ===

In the implementation file, we need to:

write a simple default constructor, which initializes the value of 'scale' to zero:

Desaturate::Desaturate():
scale(0)
{}

> EXPORT(scale);
>
60a67,74
> bool
> Desaturate::set_param(const String &param, const ValueBase &value)
> {
> IMPORT(scale);
>
> return false;
> }
>
64c78,85
< return Layer::Vocab();
---
> Layer::Vocab ret;
>
> ret.push_back(ParamDesc("scale")
> .set_local_name(_("Scale"))
> .set_description(_("Factor to scale the saturation by"))
> );
>
> return ret;
71c92
< return tmp.set_s(0);
---
> return tmp.set_s(scale * tmp.get_s());
95c116
< pen.put_value(tmp.set_s(0));
---
> pen.put_value(tmp.set_s(scale * tmp.get_s()));

Dev:Adding a Layer

2008-04-16T16:27:26Z

Dooglus:

Dev:Adding a Layer

2008-04-16T16:24:08Z

Dooglus:

Here's an example of how to add a simple layer to an existing module. For this example I picked something very easy: a layer which removes all colour from the layers beneath it. I will call this creation "Desaturate", and add it to the mod_filter module.

Section 1, "The Code" will present the entire source, uninterrupted, and section 2, "The Description" will break it up into small chunks and discuss it.

== The Code ==

We need to create two new files (one header (.h) file, and one implementation (.cpp) file), and edit two existing files (the module's main.cpp, and the Makefile.am), all in the synfig/src/modules/mod_filter/ folder:

=== <module>/desaturate.h ===

/* === S Y N F I G ========================================================= */
/*! \file desaturate.h
** \brief Header file for implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === S T A R T =========================================================== */

#ifndef __SYNFIG_DESATURATE_H
#define __SYNFIG_DESATURATE_H

/* === H E A D E R S ======================================================= */

#include <synfig/layer.h>

/* === C L A S S E S & S T R U C T S ======================================= */

class Desaturate : public synfig::Layer
{
SYNFIG_LAYER_MODULE_EXT
public:
virtual synfig::ValueBase get_param(const synfig::String&)const;
virtual Vocab get_param_vocab()const;
virtual synfig::Color get_color(synfig::Context, const synfig::Point&)const;
virtual bool accelerated_render(synfig::Context,synfig::Surface*,int,
const synfig::RendDesc &, synfig::ProgressCallback *)const;
}; // END of class Desaturate

#endif

=== <module>/desaturate.cpp ===

/* === S Y N F I G ========================================================= */
/*! \file desaturate.cpp
** \brief Implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === H E A D E R S ======================================================= */

#ifdef USING_PCH
# include "pch.h"
#else
#ifdef HAVE_CONFIG_H
# include <config.h>
#endif

#include "desaturate.h"

#include <synfig/context.h>
#include <synfig/paramdesc.h>
#include <synfig/renddesc.h>
#include <synfig/surface.h>
#include <synfig/value.h>

#endif

using namespace synfig;

/* === G L O B A L S ======================================================= */

SYNFIG_LAYER_INIT(Desaturate);
SYNFIG_LAYER_SET_NAME(Desaturate,"desaturate");
SYNFIG_LAYER_SET_LOCAL_NAME(Desaturate,N_("Desaturate"));
SYNFIG_LAYER_SET_CATEGORY(Desaturate,N_("Filters"));
SYNFIG_LAYER_SET_VERSION(Desaturate,"0.1");
SYNFIG_LAYER_SET_CVS_ID(Desaturate,"$Id$");

/* === M E T H O D S ======================================================= */

ValueBase
Desaturate::get_param(const String &param)const
{
EXPORT_NAME();
EXPORT_VERSION();

return ValueBase();
}

Layer::Vocab
Desaturate::get_param_vocab()const
{
return Layer::Vocab();
}

Color
Desaturate::get_color(Context context, const Point &getpos)const
{
Color tmp(context.get_color(getpos));
return tmp.set_s(0);
}

bool
Desaturate::accelerated_render(Context context,
Surface* surface,
int quality,
const RendDesc& renddesc,
ProgressCallback* cb
)const
{
SuperCallback supercb(cb,0,9500,10000);

// render the context onto the given surface
if(!context.accelerated_render(surface,quality,renddesc,&supercb))
return false;

// set the saturation of each pixel to zero
int x,y;
Surface::pen pen(surface->begin());
for(y=0;y<renddesc.get_h();y++,pen.inc_y(),pen.dec_x(x))
for(x=0;x<renddesc.get_w();x++,pen.inc_x())
{
Color tmp(pen.get_value());
pen.put_value(tmp.set_s(0));
}

// mark our progress as finished
if(cb && !cb->amount_complete(10000,10000)) return false;
return true;
}

=== <module>/Makefile.am ===

Then I need to edit modules/mod_filter/Makefile.am and add these two files to the list of source files (maintain alphabetical order please):

libmod_filter_la_SOURCES = blur.cpp blur.h colorcorrect.cpp colorcorrect.h desaturate.cpp desaturate.h halftone2.cpp halftone2.h lumakey.cpp lumakey.h radialblur.cpp radialblur.h main.cpp halftone.cpp halftone.h halftone3.cpp halftone3.h

=== <module>/main.cpp ===

And finally we edit modules/mod_filter/main.cpp. Add this with the other #include lines:

#include "desaturate.h"

and add this with the other LAYER(...) lines:

LAYER(Desaturate)

then rebuild (including the autoreconf, ./configure, etc., to get the new files added to the Makefile) and we're done.

== The Description ==

I'll break the header up into sections, describing each part:

=== The initial comment ===

This contains basic documentation and legal stuff. Just copy, paste, and edit from another file.

/* === S Y N F I G ========================================================= */
/*! \file desaturate.h
** \brief Header file for implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === S T A R T =========================================================== */

=== Protection against Multiple Inclusion ===

This #ifndef is a standard way to make sure the header is only compiled once, even if it happens to be included multiple times. Use a unique symbol, based on the file name.

#ifndef __SYNFIG_DESATURATE_H
#define __SYNFIG_DESATURATE_H

=== Headers ===

Include files which are needed. We're not doing anything much, so all we need to include is layer.h, which defines the Layer class that all layers inherit from.

/* === H E A D E R S ======================================================= */

#include <synfig/layer.h>

=== The Class ===

Define the class which implements our layer. We inherit from the Layer class. For this simple example we only define four methods. The rest will be inherited from the Layer class.

/* === C L A S S E S & S T R U C T S ======================================= */

class Desaturate : public synfig::Layer
{

=== SYNFIG_LAYER_MODULE_EXT ===

This is standard. Just use it for every layer. It declares members to hold the layer's name, version, category, etc., and also declares a method to create() the layer. See synfig/src/synfig/layer.h for its definition.

SYNFIG_LAYER_MODULE_EXT

=== The Methods ===

Then we declare the four methods we're going to implement. First "get_param()". Since our layer isn't going to have any parameters, all it needs to do is make the layer's name and
version available.

==== get_param ====

public:
virtual synfig::ValueBase get_param(const synfig::String&)const;

==== get_param_vocab ====

This one returns a list of the layer's parameters. We have no parameters, so we return an empty list.

virtual Vocab get_param_vocab()const;

==== get_color ====

This one is used to find the color of a single given pixel. It's used by the "Info" panel to display the R,G,B values as you mouse over the canvas. It's also used if our layer has any transformation layers over the top of it. The absence of a working implementation of this method in the "Text" layer is why distorting text currently causes render artifacts.

virtual synfig::Color get_color(synfig::Context, const synfig::Point&)const;

==== accelerated_render ====

This one is used to render a large rectangular piece of our layer in one go. It typically calls the accelerated_render() method for the layers under our layer (the 'context') and then modifies the results of that call in some way:

virtual bool accelerated_render(synfig::Context,synfig::Surface*,int,
const synfig::RendDesc &, synfig::ProgressCallback *)const;
}; // END of class Desaturate

#endif

I won't reproduce the whole of the .cpp file here and go through it. The only two methods which are really interesting here are get_color() and accelerated_render():

== Implementation ==

=== get_color() ===

Given the context, and a point, get_color() should return the color of the pixel at the given point. The context has a get_color() method, so we use that to look up the color of the pixel before our layer has had a chance to affect it, and store that in 'tmp'. Then we set its saturation to zero using [http://synfig.org/api/synfig/classsynfig_1_1Color.html#b62c2069fc43baa97fba17b33ff4d32d color.set_s()] and return it. That's all:

Color
Desaturate::get_color(Context context, const Point &getpos)const
{
Color tmp(context.get_color(getpos));
return tmp.set_s(0);
}

=== accelerated_render() ===

We accept five arguments:

The context (ie. the layers under us):

bool
Desaturate::accelerated_render(Context context,

The surface we are supposed to write our results onto:

Surface* surface,

The quality at which we are to render:

int quality,

A description of the area to render - width, height, top left corner, resolution, etc, etc:

const RendDesc& renddesc,

An object which is used to monitor our progress. It's used for calculating the expected remaining time while rendering:

ProgressCallback* cb
)const
{

I didn't get around to looking at the way the 'cb' ProgressCallback is used. But this code is in pretty much all layers:

SuperCallback supercb(cb,0,9500,10000);

We call accelerated_render() on the context, to render the layers under us. We just pass on the arguments we received for surface, quality and renddesc, along with the new callback we just made. If that render fails, then we fail too:

// render the context onto the given surface
if(!context.accelerated_render(surface,quality,renddesc,&supercb))
return false;

Now we do the real work of this layer. We define integers to do the looping, and a 'pen' which we can walk over the rectangle we're working on:

// set the saturation of each pixel to zero
int x,y;
Surface::pen pen(surface->begin());

We loop through every pixel on every row of the rectangle we're working on. The 'renddesc' gives us the width and height of the rectangle. The pen has methods inc_x(), dec_x(), inc_y(), dec_y() which move it a given amount:

for(y=0;y<renddesc.get_h();y++,pen.inc_y(),pen.dec_x(x))
for(x=0;x<renddesc.get_w();x++,pen.inc_x())

At each pixel, we get the color as rendered from the context, set its saturation to zero, and write it back to the same surface:

{
Color tmp(pen.get_value());
pen.put_value(tmp.set_s(0));
}

And that's about it.

// mark our progress as finished
if(cb && !cb->amount_complete(10000,10000)) return false;
return true;
}

Dev:Adding a Layer

2008-04-16T16:19:08Z

Dooglus:

Here's an example of how to add a simple layer to an existing module. For this example I picked something very easy: a layer which removes all colour from the layers beneath it. I will call this creation "Desaturate", and add it to the mod_filter module.

Section 1, "The Code" will present the entire source, uninterrupted, and section 2, "The Description" will break it up into small chunks and discuss it.

== The Code ==

We need to create two new files (one header (.h) file, and one implementation (.cpp) file), and edit two existing files (the module's main.cpp, and the Makefile.am), all in the synfig/src/modules/mod_filter/ folder:

=== <module>/desaturate.h ===

/* === S Y N F I G ========================================================= */
/*! \file desaturate.h
** \brief Header file for implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === S T A R T =========================================================== */

#ifndef __SYNFIG_DESATURATE_H
#define __SYNFIG_DESATURATE_H

/* === H E A D E R S ======================================================= */

#include <synfig/layer.h>

/* === C L A S S E S & S T R U C T S ======================================= */

class Desaturate : public synfig::Layer
{
SYNFIG_LAYER_MODULE_EXT
public:
virtual synfig::ValueBase get_param(const synfig::String&)const;
virtual Vocab get_param_vocab()const;
virtual synfig::Color get_color(synfig::Context, const synfig::Point&)const;
virtual bool accelerated_render(synfig::Context,synfig::Surface*,int,
const synfig::RendDesc &, synfig::ProgressCallback *)const;
virtual bool reads_context()const { return true; }
}; // END of class Desaturate

#endif

=== <module>/desaturate.cpp ===

/* === S Y N F I G ========================================================= */
/*! \file desaturate.cpp
** \brief Implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === H E A D E R S ======================================================= */

#ifdef USING_PCH
# include "pch.h"
#else
#ifdef HAVE_CONFIG_H
# include <config.h>
#endif

#include "desaturate.h"

#include <synfig/context.h>
#include <synfig/paramdesc.h>
#include <synfig/renddesc.h>
#include <synfig/surface.h>
#include <synfig/value.h>

#endif

using namespace synfig;

/* === G L O B A L S ======================================================= */

SYNFIG_LAYER_INIT(Desaturate);
SYNFIG_LAYER_SET_NAME(Desaturate,"desaturate");
SYNFIG_LAYER_SET_LOCAL_NAME(Desaturate,N_("Desaturate"));
SYNFIG_LAYER_SET_CATEGORY(Desaturate,N_("Filters"));
SYNFIG_LAYER_SET_VERSION(Desaturate,"0.1");
SYNFIG_LAYER_SET_CVS_ID(Desaturate,"$Id$");

/* === M E T H O D S ======================================================= */

ValueBase
Desaturate::get_param(const String &param)const
{
EXPORT_NAME();
EXPORT_VERSION();

return ValueBase();
}

Layer::Vocab
Desaturate::get_param_vocab()const
{
return Layer::Vocab();
}

Color
Desaturate::get_color(Context context, const Point &getpos)const
{
Color tmp(context.get_color(getpos));
return tmp.set_s(0);
}

bool
Desaturate::accelerated_render(Context context,
Surface* surface,
int quality,
const RendDesc& renddesc,
ProgressCallback* cb
)const
{
SuperCallback supercb(cb,0,9500,10000);

// render the context onto the given surface
if(!context.accelerated_render(surface,quality,renddesc,&supercb))
return false;

// set the saturation of each pixel to zero
int x,y;
Surface::pen pen(surface->begin());
for(y=0;y<renddesc.get_h();y++,pen.inc_y(),pen.dec_x(x))
for(x=0;x<renddesc.get_w();x++,pen.inc_x())
{
Color tmp(pen.get_value());
pen.put_value(tmp.set_s(0));
}

// mark our progress as finished
if(cb && !cb->amount_complete(10000,10000)) return false;
return true;
}

=== <module>/Makefile.am ===

Then I need to edit modules/mod_filter/Makefile.am and add these two files to the list of source files (maintain alphabetical order please):

libmod_filter_la_SOURCES = blur.cpp blur.h colorcorrect.cpp colorcorrect.h desaturate.cpp desaturate.h halftone2.cpp halftone2.h lumakey.cpp lumakey.h radialblur.cpp radialblur.h main.cpp halftone.cpp halftone.h halftone3.cpp halftone3.h

=== <module>/main.cpp ===

And finally we edit modules/mod_filter/main.cpp. Add this with the other #include lines:

#include "desaturate.h"

and add this with the other LAYER(...) lines:

LAYER(Desaturate)

then rebuild (including the autoreconf, ./configure, etc., to get the new files added to the Makefile) and we're done.

== The Description ==

I'll break the header up into sections, describing each part:

=== The initial comment ===

This contains basic documentation and legal stuff. Just copy, paste, and edit from another file.

/* === S Y N F I G ========================================================= */
/*! \file desaturate.h
** \brief Header file for implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === S T A R T =========================================================== */

=== Protection against Multiple Inclusion ===

This #ifndef is a standard way to make sure the header is only compiled once, even if it happens to be included multiple times. Use a unique symbol, based on the file name.

#ifndef __SYNFIG_DESATURATE_H
#define __SYNFIG_DESATURATE_H

=== Headers ===

Include files which are needed. We're not doing anything much, so all we need to include is layer.h, which defines the Layer class that all layers inherit from.

/* === H E A D E R S ======================================================= */

#include <synfig/layer.h>

=== The Class ===

Define the class which implements our layer. We inherit from the Layer class. For this simple example we only define five methods. The rest will be inherited from the Layer class.

/* === C L A S S E S & S T R U C T S ======================================= */

class Desaturate : public synfig::Layer
{

=== SYNFIG_LAYER_MODULE_EXT ===

This is standard. Just use it for every layer. It declares members to hold the layer's name, version, category, etc., and also declares a method to create() the layer. See synfig/src/synfig/layer.h for its definition.

SYNFIG_LAYER_MODULE_EXT

=== The Methods ===

Then we declare the five methods we're going to implement. First "get_param()". Since our layer isn't going to have any parameters, all it needs to do is make the layer's name and
version available.

==== get_param ====

public:
virtual synfig::ValueBase get_param(const synfig::String&)const;

==== get_param_vocab ====

This one returns a list of the layer's parameters. We have no parameters, so we return an empty list.

virtual Vocab get_param_vocab()const;

==== get_color ====

This one is used to find the color of a single given pixel. It's used by the "Info" panel to display the R,G,B values as you mouse over the canvas. It's also used if our layer has any transformation layers over the top of it. The absence of a working implementation of this method in the "Text" layer is why distorting text currently causes render artifacts.

virtual synfig::Color get_color(synfig::Context, const synfig::Point&)const;

==== accelerated_render ====

This one is used to render a large rectangular piece of our layer in one go. It typically calls the accelerated_render() method for the layers under our layer (the 'context') and then modifies the results of that call in some way:

virtual bool accelerated_render(synfig::Context,synfig::Surface*,int,
const synfig::RendDesc &, synfig::ProgressCallback *)const;

==== reads_context ====

This one returns true always, meaning that this layer's output depends on the layers under it (the 'context'):

virtual bool reads_context()const { return true; }
}; // END of class Desaturate

#endif

I won't reproduce the whole of the .cpp file here and go through it. The only two methods which are really interesting here are get_color() and accelerated_render():

== Implementation ==

=== get_color() ===

Given the context, and a point, get_color() should return the color of the pixel at the given point. The context has a get_color() method, so we use that to look up the color of the pixel before our layer has had a chance to affect it, and store that in 'tmp'. Then we set its saturation to zero using [http://synfig.org/api/synfig/classsynfig_1_1Color.html#b62c2069fc43baa97fba17b33ff4d32d color.set_s()] and return it. That's all:

Color
Desaturate::get_color(Context context, const Point &getpos)const
{
Color tmp(context.get_color(getpos));
return tmp.set_s(0);
}

=== accelerated_render() ===

We accept five arguments:

The context (ie. the layers under us):

bool
Desaturate::accelerated_render(Context context,

The surface we are supposed to write our results onto:

Surface* surface,

The quality at which we are to render:

int quality,

A description of the area to render - width, height, top left corner, resolution, etc, etc:

const RendDesc& renddesc,

An object which is used to monitor our progress. It's used for calculating the expected remaining time while rendering:

ProgressCallback* cb
)const
{

I didn't get around to looking at the way the 'cb' ProgressCallback is used. But this code is in pretty much all layers:

SuperCallback supercb(cb,0,9500,10000);

We call accelerated_render() on the context, to render the layers under us. We just pass on the arguments we received for surface, quality and renddesc, along with the new callback we just made. If that render fails, then we fail too:

// render the context onto the given surface
if(!context.accelerated_render(surface,quality,renddesc,&supercb))
return false;

Now we do the real work of this layer. We define integers to do the looping, and a 'pen' which we can walk over the rectangle we're working on:

// set the saturation of each pixel to zero
int x,y;
Surface::pen pen(surface->begin());

We loop through every pixel on every row of the rectangle we're working on. The 'renddesc' gives us the width and height of the rectangle. The pen has methods inc_x(), dec_x(), inc_y(), dec_y() which move it a given amount:

for(y=0;y<renddesc.get_h();y++,pen.inc_y(),pen.dec_x(x))
for(x=0;x<renddesc.get_w();x++,pen.inc_x())

At each pixel, we get the color as rendered from the context, set its saturation to zero, and write it back to the same surface:

{
Color tmp(pen.get_value());
pen.put_value(tmp.set_s(0));
}

And that's about it.

// mark our progress as finished
if(cb && !cb->amount_complete(10000,10000)) return false;
return true;
}

Dev:Adding a Layer

2008-04-16T16:17:38Z

Dooglus: /* The Code */

Here's an example of how to add a simple layer to an existing module. For this example I picked something very easy: a layer which removes all colour from the layers beneath it. I will call this creation "Desaturate", and add it to the mod_filter module.

== The Code ==

We need to create two new files (one header (.h) file, and one implementation (.cpp) file), and edit two existing files (the module's main.cpp, and the Makefile.am), all in the synfig/src/modules/mod_filter/ folder:

=== <module>/desaturate.h ===

/* === S Y N F I G ========================================================= */
/*! \file desaturate.h
** \brief Header file for implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === S T A R T =========================================================== */

#ifndef __SYNFIG_DESATURATE_H
#define __SYNFIG_DESATURATE_H

/* === H E A D E R S ======================================================= */

#include <synfig/layer.h>

/* === C L A S S E S & S T R U C T S ======================================= */

class Desaturate : public synfig::Layer
{
SYNFIG_LAYER_MODULE_EXT
public:
virtual synfig::ValueBase get_param(const synfig::String&)const;
virtual Vocab get_param_vocab()const;
virtual synfig::Color get_color(synfig::Context, const synfig::Point&)const;
virtual bool accelerated_render(synfig::Context,synfig::Surface*,int,
const synfig::RendDesc &, synfig::ProgressCallback *)const;
virtual bool reads_context()const { return true; }
}; // END of class Desaturate

#endif

=== <module>/desaturate.cpp ===

/* === S Y N F I G ========================================================= */
/*! \file desaturate.cpp
** \brief Implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === H E A D E R S ======================================================= */

#ifdef USING_PCH
# include "pch.h"
#else
#ifdef HAVE_CONFIG_H
# include <config.h>
#endif

#include "desaturate.h"

#include <synfig/context.h>
#include <synfig/paramdesc.h>
#include <synfig/renddesc.h>
#include <synfig/surface.h>
#include <synfig/value.h>

#endif

using namespace synfig;

/* === G L O B A L S ======================================================= */

SYNFIG_LAYER_INIT(Desaturate);
SYNFIG_LAYER_SET_NAME(Desaturate,"desaturate");
SYNFIG_LAYER_SET_LOCAL_NAME(Desaturate,N_("Desaturate"));
SYNFIG_LAYER_SET_CATEGORY(Desaturate,N_("Filters"));
SYNFIG_LAYER_SET_VERSION(Desaturate,"0.1");
SYNFIG_LAYER_SET_CVS_ID(Desaturate,"$Id$");

/* === M E T H O D S ======================================================= */

ValueBase
Desaturate::get_param(const String &param)const
{
EXPORT_NAME();
EXPORT_VERSION();

return ValueBase();
}

Layer::Vocab
Desaturate::get_param_vocab()const
{
return Layer::Vocab();
}

Color
Desaturate::get_color(Context context, const Point &getpos)const
{
Color tmp(context.get_color(getpos));
return tmp.set_s(0);
}

bool
Desaturate::accelerated_render(Context context,
Surface* surface,
int quality,
const RendDesc& renddesc,
ProgressCallback* cb
)const
{
SuperCallback supercb(cb,0,9500,10000);

// render the context onto the given surface
if(!context.accelerated_render(surface,quality,renddesc,&supercb))
return false;

// set the saturation of each pixel to zero
int x,y;
Surface::pen pen(surface->begin());
for(y=0;y<renddesc.get_h();y++,pen.inc_y(),pen.dec_x(x))
for(x=0;x<renddesc.get_w();x++,pen.inc_x())
{
Color tmp(pen.get_value());
pen.put_value(tmp.set_s(0));
}

// mark our progress as finished
if(cb && !cb->amount_complete(10000,10000)) return false;
return true;
}

=== <module>/Makefile.am ===

Then I need to edit modules/mod_filter/Makefile.am and add these two files to the list of source files (maintain alphabetical order please):

libmod_filter_la_SOURCES = blur.cpp blur.h colorcorrect.cpp colorcorrect.h desaturate.cpp desaturate.h halftone2.cpp halftone2.h lumakey.cpp lumakey.h radialblur.cpp radialblur.h main.cpp halftone.cpp halftone.h halftone3.cpp halftone3.h

=== <module>/main.cpp ===

And finally we edit modules/mod_filter/main.cpp. Add this with the other #include lines:

#include "desaturate.h"

and add this with the other LAYER(...) lines:

LAYER(Desaturate)

then rebuild (including the autoreconf, ./configure, etc., to get the new files added to the Makefile) and we're done.

== The Description ==

I'll break the header up into sections, describing each part:

=== The initial comment ===

This contains basic documentation and legal stuff. Just copy, paste, and edit from another file.

/* === S Y N F I G ========================================================= */
/*! \file desaturate.h
** \brief Header file for implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === S T A R T =========================================================== */

=== Protection against Multiple Inclusion ===

This #ifndef is a standard way to make sure the header is only compiled once, even if it happens to be included multiple times. Use a unique symbol, based on the file name.

#ifndef __SYNFIG_DESATURATE_H
#define __SYNFIG_DESATURATE_H

=== Headers ===

Include files which are needed. We're not doing anything much, so all we need to include is layer.h, which defines the Layer class that all layers inherit from.

/* === H E A D E R S ======================================================= */

#include <synfig/layer.h>

=== The Class ===

Define the class which implements our layer. We inherit from the Layer class. For this simple example we only define five methods. The rest will be inherited from the Layer class.

/* === C L A S S E S & S T R U C T S ======================================= */

class Desaturate : public synfig::Layer
{

=== SYNFIG_LAYER_MODULE_EXT ===

This is standard. Just use it for every layer. It declares members to hold the layer's name, version, category, etc., and also declares a method to create() the layer. See synfig/src/synfig/layer.h for its definition.

SYNFIG_LAYER_MODULE_EXT

=== The Methods ===

Then we declare the five methods we're going to implement. First "get_param()". Since our layer isn't going to have any parameters, all it needs to do is make the layer's name and
version available.

==== get_param ====

public:
virtual synfig::ValueBase get_param(const synfig::String&)const;

==== get_param_vocab ====

This one returns a list of the layer's parameters. We have no parameters, so we return an empty list.

virtual Vocab get_param_vocab()const;

==== get_color ====

This one is used to find the color of a single given pixel. It's used by the "Info" panel to display the R,G,B values as you mouse over the canvas. It's also used if our layer has any transformation layers over the top of it. The absence of a working implementation of this method in the "Text" layer is why distorting text currently causes render artifacts.

virtual synfig::Color get_color(synfig::Context, const synfig::Point&)const;

==== accelerated_render ====

This one is used to render a large rectangular piece of our layer in one go. It typically calls the accelerated_render() method for the layers under our layer (the 'context') and then modifies the results of that call in some way:

virtual bool accelerated_render(synfig::Context,synfig::Surface*,int,
const synfig::RendDesc &, synfig::ProgressCallback *)const;

==== reads_context ====

This one returns true always, meaning that this layer's output depends on the layers under it (the 'context'):

virtual bool reads_context()const { return true; }
}; // END of class Desaturate

#endif

I won't reproduce the whole of the .cpp file here and go through it. The only two methods which are really interesting here are get_color() and accelerated_render():

== Implementation ==

=== get_color() ===

Given the context, and a point, get_color() should return the color of the pixel at the given point. The context has a get_color() method, so we use that to look up the color of the pixel before our layer has had a chance to affect it, and store that in 'tmp'. Then we set its saturation to zero using [http://synfig.org/api/synfig/classsynfig_1_1Color.html#b62c2069fc43baa97fba17b33ff4d32d color.set_s()] and return it. That's all:

Color
Desaturate::get_color(Context context, const Point &getpos)const
{
Color tmp(context.get_color(getpos));
return tmp.set_s(0);
}

=== accelerated_render() ===

We accept five arguments:

The context (ie. the layers under us):

bool
Desaturate::accelerated_render(Context context,

The surface we are supposed to write our results onto:

Surface* surface,

The quality at which we are to render:

int quality,

A description of the area to render - width, height, top left corner, resolution, etc, etc:

const RendDesc& renddesc,

An object which is used to monitor our progress. It's used for calculating the expected remaining time while rendering:

ProgressCallback* cb
)const
{

I didn't get around to looking at the way the 'cb' ProgressCallback is used. But this code is in pretty much all layers:

SuperCallback supercb(cb,0,9500,10000);

We call accelerated_render() on the context, to render the layers under us. We just pass on the arguments we received for surface, quality and renddesc, along with the new callback we just made. If that render fails, then we fail too:

// render the context onto the given surface
if(!context.accelerated_render(surface,quality,renddesc,&supercb))
return false;

Now we do the real work of this layer. We define integers to do the looping, and a 'pen' which we can walk over the rectangle we're working on:

// set the saturation of each pixel to zero
int x,y;
Surface::pen pen(surface->begin());

We loop through every pixel on every row of the rectangle we're working on. The 'renddesc' gives us the width and height of the rectangle. The pen has methods inc_x(), dec_x(), inc_y(), dec_y() which move it a given amount:

for(y=0;y<renddesc.get_h();y++,pen.inc_y(),pen.dec_x(x))
for(x=0;x<renddesc.get_w();x++,pen.inc_x())

At each pixel, we get the color as rendered from the context, set its saturation to zero, and write it back to the same surface:

{
Color tmp(pen.get_value());
pen.put_value(tmp.set_s(0));
}

And that's about it.

// mark our progress as finished
if(cb && !cb->amount_complete(10000,10000)) return false;
return true;
}

Dev:Adding a Layer

2008-04-16T16:15:54Z

Dooglus: /* desaturate.h */

Here's an example of how to add a simple layer to an existing module. For this example I picked something very easy: a layer which removes all colour from the layers beneath it. I will call this creation "Desaturate", and add it to the mod_filter module.

== The Code ==

So first I need to create desaturate.h and desaturate.cpp in the synfig/src/modules/mod_filter/ folder:

=== <module>/desaturate.h ===

/* === S Y N F I G ========================================================= */
/*! \file desaturate.h
** \brief Header file for implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === S T A R T =========================================================== */

#ifndef __SYNFIG_DESATURATE_H
#define __SYNFIG_DESATURATE_H

/* === H E A D E R S ======================================================= */

#include <synfig/layer.h>

/* === C L A S S E S & S T R U C T S ======================================= */

class Desaturate : public synfig::Layer
{
SYNFIG_LAYER_MODULE_EXT
public:
virtual synfig::ValueBase get_param(const synfig::String&)const;
virtual Vocab get_param_vocab()const;
virtual synfig::Color get_color(synfig::Context, const synfig::Point&)const;
virtual bool accelerated_render(synfig::Context,synfig::Surface*,int,
const synfig::RendDesc &, synfig::ProgressCallback *)const;
virtual bool reads_context()const { return true; }
}; // END of class Desaturate

#endif

=== <module>/desaturate.cpp ===

/* === S Y N F I G ========================================================= */
/*! \file desaturate.cpp
** \brief Implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === H E A D E R S ======================================================= */

#ifdef USING_PCH
# include "pch.h"
#else
#ifdef HAVE_CONFIG_H
# include <config.h>
#endif

#include "desaturate.h"

#include <synfig/context.h>
#include <synfig/paramdesc.h>
#include <synfig/renddesc.h>
#include <synfig/surface.h>
#include <synfig/value.h>

#endif

using namespace synfig;

/* === G L O B A L S ======================================================= */

SYNFIG_LAYER_INIT(Desaturate);
SYNFIG_LAYER_SET_NAME(Desaturate,"desaturate");
SYNFIG_LAYER_SET_LOCAL_NAME(Desaturate,N_("Desaturate"));
SYNFIG_LAYER_SET_CATEGORY(Desaturate,N_("Filters"));
SYNFIG_LAYER_SET_VERSION(Desaturate,"0.1");
SYNFIG_LAYER_SET_CVS_ID(Desaturate,"$Id$");

/* === M E T H O D S ======================================================= */

ValueBase
Desaturate::get_param(const String &param)const
{
EXPORT_NAME();
EXPORT_VERSION();

return ValueBase();
}

Layer::Vocab
Desaturate::get_param_vocab()const
{
return Layer::Vocab();
}

Color
Desaturate::get_color(Context context, const Point &getpos)const
{
Color tmp(context.get_color(getpos));
return tmp.set_s(0);
}

bool
Desaturate::accelerated_render(Context context,
Surface* surface,
int quality,
const RendDesc& renddesc,
ProgressCallback* cb
)const
{
SuperCallback supercb(cb,0,9500,10000);

// render the context onto the given surface
if(!context.accelerated_render(surface,quality,renddesc,&supercb))
return false;

// set the saturation of each pixel to zero
int x,y;
Surface::pen pen(surface->begin());
for(y=0;y<renddesc.get_h();y++,pen.inc_y(),pen.dec_x(x))
for(x=0;x<renddesc.get_w();x++,pen.inc_x())
{
Color tmp(pen.get_value());
pen.put_value(tmp.set_s(0));
}

// mark our progress as finished
if(cb && !cb->amount_complete(10000,10000)) return false;
return true;
}

=== <module>/Makefile.am ===

Then I need to edit modules/mod_filter/Makefile.am and add these two files to the list of source files (maintain alphabetical order please):

libmod_filter_la_SOURCES = blur.cpp blur.h colorcorrect.cpp colorcorrect.h desaturate.cpp desaturate.h halftone2.cpp halftone2.h lumakey.cpp lumakey.h radialblur.cpp radialblur.h main.cpp halftone.cpp halftone.h halftone3.cpp halftone3.h

=== <module>/main.cpp ===

And finally we edit modules/mod_filter/main.cpp. Add this with the other #include lines:

#include "desaturate.h"

and add this with the other LAYER(...) lines:

LAYER(Desaturate)

then rebuild (including the autoreconf, ./configure, etc., to get the new files added to the Makefile) and we're done.

== The Description ==

I'll break the header up into sections, describing each part:

=== The initial comment ===

This contains basic documentation and legal stuff. Just copy, paste, and edit from another file.

/* === S Y N F I G ========================================================= */
/*! \file desaturate.h
** \brief Header file for implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === S T A R T =========================================================== */

=== Protection against Multiple Inclusion ===

This #ifndef is a standard way to make sure the header is only compiled once, even if it happens to be included multiple times. Use a unique symbol, based on the file name.

#ifndef __SYNFIG_DESATURATE_H
#define __SYNFIG_DESATURATE_H

=== Headers ===

Include files which are needed. We're not doing anything much, so all we need to include is layer.h, which defines the Layer class that all layers inherit from.

/* === H E A D E R S ======================================================= */

#include <synfig/layer.h>

=== The Class ===

Define the class which implements our layer. We inherit from the Layer class. For this simple example we only define five methods. The rest will be inherited from the Layer class.

/* === C L A S S E S & S T R U C T S ======================================= */

class Desaturate : public synfig::Layer
{

=== SYNFIG_LAYER_MODULE_EXT ===

This is standard. Just use it for every layer. It declares members to hold the layer's name, version, category, etc., and also declares a method to create() the layer. See synfig/src/synfig/layer.h for its definition.

SYNFIG_LAYER_MODULE_EXT

=== The Methods ===

Then we declare the five methods we're going to implement. First "get_param()". Since our layer isn't going to have any parameters, all it needs to do is make the layer's name and
version available.

==== get_param ====

public:
virtual synfig::ValueBase get_param(const synfig::String&)const;

==== get_param_vocab ====

This one returns a list of the layer's parameters. We have no parameters, so we return an empty list.

virtual Vocab get_param_vocab()const;

==== get_color ====

This one is used to find the color of a single given pixel. It's used by the "Info" panel to display the R,G,B values as you mouse over the canvas. It's also used if our layer has any transformation layers over the top of it. The absence of a working implementation of this method in the "Text" layer is why distorting text currently causes render artifacts.

virtual synfig::Color get_color(synfig::Context, const synfig::Point&)const;

==== accelerated_render ====

This one is used to render a large rectangular piece of our layer in one go. It typically calls the accelerated_render() method for the layers under our layer (the 'context') and then modifies the results of that call in some way:

virtual bool accelerated_render(synfig::Context,synfig::Surface*,int,
const synfig::RendDesc &, synfig::ProgressCallback *)const;

==== reads_context ====

This one returns true always, meaning that this layer's output depends on the layers under it (the 'context'):

virtual bool reads_context()const { return true; }
}; // END of class Desaturate

#endif

I won't reproduce the whole of the .cpp file here and go through it. The only two methods which are really interesting here are get_color() and accelerated_render():

== Implementation ==

=== get_color() ===

Given the context, and a point, get_color() should return the color of the pixel at the given point. The context has a get_color() method, so we use that to look up the color of the pixel before our layer has had a chance to affect it, and store that in 'tmp'. Then we set its saturation to zero using [http://synfig.org/api/synfig/classsynfig_1_1Color.html#b62c2069fc43baa97fba17b33ff4d32d color.set_s()] and return it. That's all:

Color
Desaturate::get_color(Context context, const Point &getpos)const
{
Color tmp(context.get_color(getpos));
return tmp.set_s(0);
}

=== accelerated_render() ===

We accept five arguments:

The context (ie. the layers under us):

bool
Desaturate::accelerated_render(Context context,

The surface we are supposed to write our results onto:

Surface* surface,

The quality at which we are to render:

int quality,

A description of the area to render - width, height, top left corner, resolution, etc, etc:

const RendDesc& renddesc,

An object which is used to monitor our progress. It's used for calculating the expected remaining time while rendering:

ProgressCallback* cb
)const
{

I didn't get around to looking at the way the 'cb' ProgressCallback is used. But this code is in pretty much all layers:

SuperCallback supercb(cb,0,9500,10000);

We call accelerated_render() on the context, to render the layers under us. We just pass on the arguments we received for surface, quality and renddesc, along with the new callback we just made. If that render fails, then we fail too:

// render the context onto the given surface
if(!context.accelerated_render(surface,quality,renddesc,&supercb))
return false;

Now we do the real work of this layer. We define integers to do the looping, and a 'pen' which we can walk over the rectangle we're working on:

// set the saturation of each pixel to zero
int x,y;
Surface::pen pen(surface->begin());

We loop through every pixel on every row of the rectangle we're working on. The 'renddesc' gives us the width and height of the rectangle. The pen has methods inc_x(), dec_x(), inc_y(), dec_y() which move it a given amount:

for(y=0;y<renddesc.get_h();y++,pen.inc_y(),pen.dec_x(x))
for(x=0;x<renddesc.get_w();x++,pen.inc_x())

At each pixel, we get the color as rendered from the context, set its saturation to zero, and write it back to the same surface:

{
Color tmp(pen.get_value());
pen.put_value(tmp.set_s(0));
}

And that's about it.

// mark our progress as finished
if(cb && !cb->amount_complete(10000,10000)) return false;
return true;
}

Dev:Adding a Layer

2008-04-16T16:15:39Z

Dooglus: /* desaturate.cpp */

Here's an example of how to add a simple layer to an existing module. For this example I picked something very easy: a layer which removes all colour from the layers beneath it. I will call this creation "Desaturate", and add it to the mod_filter module.

== The Code ==

So first I need to create desaturate.h and desaturate.cpp in the synfig/src/modules/mod_filter/ folder:

=== desaturate.h ===

/* === S Y N F I G ========================================================= */
/*! \file desaturate.h
** \brief Header file for implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === S T A R T =========================================================== */

#ifndef __SYNFIG_DESATURATE_H
#define __SYNFIG_DESATURATE_H

/* === H E A D E R S ======================================================= */

#include <synfig/layer.h>

/* === C L A S S E S & S T R U C T S ======================================= */

class Desaturate : public synfig::Layer
{
SYNFIG_LAYER_MODULE_EXT
public:
virtual synfig::ValueBase get_param(const synfig::String&)const;
virtual Vocab get_param_vocab()const;
virtual synfig::Color get_color(synfig::Context, const synfig::Point&)const;
virtual bool accelerated_render(synfig::Context,synfig::Surface*,int,
const synfig::RendDesc &, synfig::ProgressCallback *)const;
virtual bool reads_context()const { return true; }
}; // END of class Desaturate

#endif

=== <module>/desaturate.cpp ===

/* === S Y N F I G ========================================================= */
/*! \file desaturate.cpp
** \brief Implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === H E A D E R S ======================================================= */

#ifdef USING_PCH
# include "pch.h"
#else
#ifdef HAVE_CONFIG_H
# include <config.h>
#endif

#include "desaturate.h"

#include <synfig/context.h>
#include <synfig/paramdesc.h>
#include <synfig/renddesc.h>
#include <synfig/surface.h>
#include <synfig/value.h>

#endif

using namespace synfig;

/* === G L O B A L S ======================================================= */

SYNFIG_LAYER_INIT(Desaturate);
SYNFIG_LAYER_SET_NAME(Desaturate,"desaturate");
SYNFIG_LAYER_SET_LOCAL_NAME(Desaturate,N_("Desaturate"));
SYNFIG_LAYER_SET_CATEGORY(Desaturate,N_("Filters"));
SYNFIG_LAYER_SET_VERSION(Desaturate,"0.1");
SYNFIG_LAYER_SET_CVS_ID(Desaturate,"$Id$");

/* === M E T H O D S ======================================================= */

ValueBase
Desaturate::get_param(const String &param)const
{
EXPORT_NAME();
EXPORT_VERSION();

return ValueBase();
}

Layer::Vocab
Desaturate::get_param_vocab()const
{
return Layer::Vocab();
}

Color
Desaturate::get_color(Context context, const Point &getpos)const
{
Color tmp(context.get_color(getpos));
return tmp.set_s(0);
}

bool
Desaturate::accelerated_render(Context context,
Surface* surface,
int quality,
const RendDesc& renddesc,
ProgressCallback* cb
)const
{
SuperCallback supercb(cb,0,9500,10000);

// render the context onto the given surface
if(!context.accelerated_render(surface,quality,renddesc,&supercb))
return false;

// set the saturation of each pixel to zero
int x,y;
Surface::pen pen(surface->begin());
for(y=0;y<renddesc.get_h();y++,pen.inc_y(),pen.dec_x(x))
for(x=0;x<renddesc.get_w();x++,pen.inc_x())
{
Color tmp(pen.get_value());
pen.put_value(tmp.set_s(0));
}

// mark our progress as finished
if(cb && !cb->amount_complete(10000,10000)) return false;
return true;
}

=== <module>/Makefile.am ===

Then I need to edit modules/mod_filter/Makefile.am and add these two files to the list of source files (maintain alphabetical order please):

libmod_filter_la_SOURCES = blur.cpp blur.h colorcorrect.cpp colorcorrect.h desaturate.cpp desaturate.h halftone2.cpp halftone2.h lumakey.cpp lumakey.h radialblur.cpp radialblur.h main.cpp halftone.cpp halftone.h halftone3.cpp halftone3.h

=== <module>/main.cpp ===

And finally we edit modules/mod_filter/main.cpp. Add this with the other #include lines:

#include "desaturate.h"

and add this with the other LAYER(...) lines:

LAYER(Desaturate)

then rebuild (including the autoreconf, ./configure, etc., to get the new files added to the Makefile) and we're done.

== The Description ==

I'll break the header up into sections, describing each part:

=== The initial comment ===

This contains basic documentation and legal stuff. Just copy, paste, and edit from another file.

/* === S Y N F I G ========================================================= */
/*! \file desaturate.h
** \brief Header file for implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === S T A R T =========================================================== */

=== Protection against Multiple Inclusion ===

This #ifndef is a standard way to make sure the header is only compiled once, even if it happens to be included multiple times. Use a unique symbol, based on the file name.

#ifndef __SYNFIG_DESATURATE_H
#define __SYNFIG_DESATURATE_H

=== Headers ===

Include files which are needed. We're not doing anything much, so all we need to include is layer.h, which defines the Layer class that all layers inherit from.

/* === H E A D E R S ======================================================= */

#include <synfig/layer.h>

=== The Class ===

Define the class which implements our layer. We inherit from the Layer class. For this simple example we only define five methods. The rest will be inherited from the Layer class.

/* === C L A S S E S & S T R U C T S ======================================= */

class Desaturate : public synfig::Layer
{

=== SYNFIG_LAYER_MODULE_EXT ===

This is standard. Just use it for every layer. It declares members to hold the layer's name, version, category, etc., and also declares a method to create() the layer. See synfig/src/synfig/layer.h for its definition.

SYNFIG_LAYER_MODULE_EXT

=== The Methods ===

Then we declare the five methods we're going to implement. First "get_param()". Since our layer isn't going to have any parameters, all it needs to do is make the layer's name and
version available.

==== get_param ====

public:
virtual synfig::ValueBase get_param(const synfig::String&)const;

==== get_param_vocab ====

This one returns a list of the layer's parameters. We have no parameters, so we return an empty list.

virtual Vocab get_param_vocab()const;

==== get_color ====

This one is used to find the color of a single given pixel. It's used by the "Info" panel to display the R,G,B values as you mouse over the canvas. It's also used if our layer has any transformation layers over the top of it. The absence of a working implementation of this method in the "Text" layer is why distorting text currently causes render artifacts.

virtual synfig::Color get_color(synfig::Context, const synfig::Point&)const;

==== accelerated_render ====

This one is used to render a large rectangular piece of our layer in one go. It typically calls the accelerated_render() method for the layers under our layer (the 'context') and then modifies the results of that call in some way:

virtual bool accelerated_render(synfig::Context,synfig::Surface*,int,
const synfig::RendDesc &, synfig::ProgressCallback *)const;

==== reads_context ====

This one returns true always, meaning that this layer's output depends on the layers under it (the 'context'):

virtual bool reads_context()const { return true; }
}; // END of class Desaturate

#endif

I won't reproduce the whole of the .cpp file here and go through it. The only two methods which are really interesting here are get_color() and accelerated_render():

== Implementation ==

=== get_color() ===

Given the context, and a point, get_color() should return the color of the pixel at the given point. The context has a get_color() method, so we use that to look up the color of the pixel before our layer has had a chance to affect it, and store that in 'tmp'. Then we set its saturation to zero using [http://synfig.org/api/synfig/classsynfig_1_1Color.html#b62c2069fc43baa97fba17b33ff4d32d color.set_s()] and return it. That's all:

Color
Desaturate::get_color(Context context, const Point &getpos)const
{
Color tmp(context.get_color(getpos));
return tmp.set_s(0);
}

=== accelerated_render() ===

We accept five arguments:

The context (ie. the layers under us):

bool
Desaturate::accelerated_render(Context context,

The surface we are supposed to write our results onto:

Surface* surface,

The quality at which we are to render:

int quality,

A description of the area to render - width, height, top left corner, resolution, etc, etc:

const RendDesc& renddesc,

An object which is used to monitor our progress. It's used for calculating the expected remaining time while rendering:

ProgressCallback* cb
)const
{

I didn't get around to looking at the way the 'cb' ProgressCallback is used. But this code is in pretty much all layers:

SuperCallback supercb(cb,0,9500,10000);

We call accelerated_render() on the context, to render the layers under us. We just pass on the arguments we received for surface, quality and renddesc, along with the new callback we just made. If that render fails, then we fail too:

// render the context onto the given surface
if(!context.accelerated_render(surface,quality,renddesc,&supercb))
return false;

Now we do the real work of this layer. We define integers to do the looping, and a 'pen' which we can walk over the rectangle we're working on:

// set the saturation of each pixel to zero
int x,y;
Surface::pen pen(surface->begin());

We loop through every pixel on every row of the rectangle we're working on. The 'renddesc' gives us the width and height of the rectangle. The pen has methods inc_x(), dec_x(), inc_y(), dec_y() which move it a given amount:

for(y=0;y<renddesc.get_h();y++,pen.inc_y(),pen.dec_x(x))
for(x=0;x<renddesc.get_w();x++,pen.inc_x())

At each pixel, we get the color as rendered from the context, set its saturation to zero, and write it back to the same surface:

{
Color tmp(pen.get_value());
pen.put_value(tmp.set_s(0));
}

And that's about it.

// mark our progress as finished
if(cb && !cb->amount_complete(10000,10000)) return false;
return true;
}

Dev:Adding a Layer

2008-04-16T16:14:24Z

Dooglus: /* The Code */

Here's an example of how to add a simple layer to an existing module. For this example I picked something very easy: a layer which removes all colour from the layers beneath it. I will call this creation "Desaturate", and add it to the mod_filter module.

== The Code ==

So first I need to create desaturate.h and desaturate.cpp in the synfig/src/modules/mod_filter/ folder:

=== desaturate.h ===

/* === S Y N F I G ========================================================= */
/*! \file desaturate.h
** \brief Header file for implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === S T A R T =========================================================== */

#ifndef __SYNFIG_DESATURATE_H
#define __SYNFIG_DESATURATE_H

/* === H E A D E R S ======================================================= */

#include <synfig/layer.h>

/* === C L A S S E S & S T R U C T S ======================================= */

class Desaturate : public synfig::Layer
{
SYNFIG_LAYER_MODULE_EXT
public:
virtual synfig::ValueBase get_param(const synfig::String&)const;
virtual Vocab get_param_vocab()const;
virtual synfig::Color get_color(synfig::Context, const synfig::Point&)const;
virtual bool accelerated_render(synfig::Context,synfig::Surface*,int,
const synfig::RendDesc &, synfig::ProgressCallback *)const;
virtual bool reads_context()const { return true; }
}; // END of class Desaturate

#endif

=== desaturate.cpp ===

/* === S Y N F I G ========================================================= */
/*! \file desaturate.cpp
** \brief Implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === H E A D E R S ======================================================= */

#ifdef USING_PCH
# include "pch.h"
#else
#ifdef HAVE_CONFIG_H
# include <config.h>
#endif

#include "desaturate.h"

#include <synfig/context.h>
#include <synfig/paramdesc.h>
#include <synfig/renddesc.h>
#include <synfig/surface.h>
#include <synfig/value.h>

#endif

using namespace synfig;

/* === G L O B A L S ======================================================= */

SYNFIG_LAYER_INIT(Desaturate);
SYNFIG_LAYER_SET_NAME(Desaturate,"desaturate");
SYNFIG_LAYER_SET_LOCAL_NAME(Desaturate,N_("Desaturate"));
SYNFIG_LAYER_SET_CATEGORY(Desaturate,N_("Filters"));
SYNFIG_LAYER_SET_VERSION(Desaturate,"0.1");
SYNFIG_LAYER_SET_CVS_ID(Desaturate,"$Id$");

/* === M E T H O D S ======================================================= */

ValueBase
Desaturate::get_param(const String &param)const
{
EXPORT_NAME();
EXPORT_VERSION();

return ValueBase();
}

Layer::Vocab
Desaturate::get_param_vocab()const
{
return Layer::Vocab();
}

Color
Desaturate::get_color(Context context, const Point &getpos)const
{
Color tmp(context.get_color(getpos));
return tmp.set_s(0);
}

bool
Desaturate::accelerated_render(Context context,
Surface* surface,
int quality,
const RendDesc& renddesc,
ProgressCallback* cb
)const
{
SuperCallback supercb(cb,0,9500,10000);

// render the context onto the given surface
if(!context.accelerated_render(surface,quality,renddesc,&supercb))
return false;

// set the saturation of each pixel to zero
int x,y;
Surface::pen pen(surface->begin());
for(y=0;y<renddesc.get_h();y++,pen.inc_y(),pen.dec_x(x))
for(x=0;x<renddesc.get_w();x++,pen.inc_x())
{
Color tmp(pen.get_value());
pen.put_value(tmp.set_s(0));
}

// mark our progress as finished
if(cb && !cb->amount_complete(10000,10000)) return false;
return true;
}

Then I need to edit modules/mod_filter/Makefile.am and add these two files to the list of source files (maintain alphabetical order please):

libmod_filter_la_SOURCES = blur.cpp blur.h colorcorrect.cpp colorcorrect.h desaturate.cpp desaturate.h halftone2.cpp halftone2.h lumakey.cpp lumakey.h radialblur.cpp radialblur.h main.cpp halftone.cpp halftone.h halftone3.cpp halftone3.h

And finally we edit modules/mod_filter/main.cpp. Add this with the other #include lines:

#include "desaturate.h"

and add this with the other LAYER(...) lines:

LAYER(Desaturate)

then rebuild (including the autoreconf, ./configure, etc., to get the new files added to the Makefile) and we're done.

== The Description ==

I'll break the header up into sections, describing each part:

=== The initial comment ===

This contains basic documentation and legal stuff. Just copy, paste, and edit from another file.

/* === S Y N F I G ========================================================= */
/*! \file desaturate.h
** \brief Header file for implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === S T A R T =========================================================== */

=== Protection against Multiple Inclusion ===

This #ifndef is a standard way to make sure the header is only compiled once, even if it happens to be included multiple times. Use a unique symbol, based on the file name.

#ifndef __SYNFIG_DESATURATE_H
#define __SYNFIG_DESATURATE_H

=== Headers ===

Include files which are needed. We're not doing anything much, so all we need to include is layer.h, which defines the Layer class that all layers inherit from.

/* === H E A D E R S ======================================================= */

#include <synfig/layer.h>

=== The Class ===

Define the class which implements our layer. We inherit from the Layer class. For this simple example we only define five methods. The rest will be inherited from the Layer class.

/* === C L A S S E S & S T R U C T S ======================================= */

class Desaturate : public synfig::Layer
{

=== SYNFIG_LAYER_MODULE_EXT ===

This is standard. Just use it for every layer. It declares members to hold the layer's name, version, category, etc., and also declares a method to create() the layer. See synfig/src/synfig/layer.h for its definition.

SYNFIG_LAYER_MODULE_EXT

=== The Methods ===

Then we declare the five methods we're going to implement. First "get_param()". Since our layer isn't going to have any parameters, all it needs to do is make the layer's name and
version available.

==== get_param ====

public:
virtual synfig::ValueBase get_param(const synfig::String&)const;

==== get_param_vocab ====

This one returns a list of the layer's parameters. We have no parameters, so we return an empty list.

virtual Vocab get_param_vocab()const;

==== get_color ====

This one is used to find the color of a single given pixel. It's used by the "Info" panel to display the R,G,B values as you mouse over the canvas. It's also used if our layer has any transformation layers over the top of it. The absence of a working implementation of this method in the "Text" layer is why distorting text currently causes render artifacts.

virtual synfig::Color get_color(synfig::Context, const synfig::Point&)const;

==== accelerated_render ====

This one is used to render a large rectangular piece of our layer in one go. It typically calls the accelerated_render() method for the layers under our layer (the 'context') and then modifies the results of that call in some way:

virtual bool accelerated_render(synfig::Context,synfig::Surface*,int,
const synfig::RendDesc &, synfig::ProgressCallback *)const;

==== reads_context ====

This one returns true always, meaning that this layer's output depends on the layers under it (the 'context'):

virtual bool reads_context()const { return true; }
}; // END of class Desaturate

#endif

I won't reproduce the whole of the .cpp file here and go through it. The only two methods which are really interesting here are get_color() and accelerated_render():

== Implementation ==

=== get_color() ===

Given the context, and a point, get_color() should return the color of the pixel at the given point. The context has a get_color() method, so we use that to look up the color of the pixel before our layer has had a chance to affect it, and store that in 'tmp'. Then we set its saturation to zero using [http://synfig.org/api/synfig/classsynfig_1_1Color.html#b62c2069fc43baa97fba17b33ff4d32d color.set_s()] and return it. That's all:

Color
Desaturate::get_color(Context context, const Point &getpos)const
{
Color tmp(context.get_color(getpos));
return tmp.set_s(0);
}

=== accelerated_render() ===

We accept five arguments:

The context (ie. the layers under us):

bool
Desaturate::accelerated_render(Context context,

The surface we are supposed to write our results onto:

Surface* surface,

The quality at which we are to render:

int quality,

A description of the area to render - width, height, top left corner, resolution, etc, etc:

const RendDesc& renddesc,

An object which is used to monitor our progress. It's used for calculating the expected remaining time while rendering:

ProgressCallback* cb
)const
{

I didn't get around to looking at the way the 'cb' ProgressCallback is used. But this code is in pretty much all layers:

SuperCallback supercb(cb,0,9500,10000);

We call accelerated_render() on the context, to render the layers under us. We just pass on the arguments we received for surface, quality and renddesc, along with the new callback we just made. If that render fails, then we fail too:

// render the context onto the given surface
if(!context.accelerated_render(surface,quality,renddesc,&supercb))
return false;

Now we do the real work of this layer. We define integers to do the looping, and a 'pen' which we can walk over the rectangle we're working on:

// set the saturation of each pixel to zero
int x,y;
Surface::pen pen(surface->begin());

We loop through every pixel on every row of the rectangle we're working on. The 'renddesc' gives us the width and height of the rectangle. The pen has methods inc_x(), dec_x(), inc_y(), dec_y() which move it a given amount:

for(y=0;y<renddesc.get_h();y++,pen.inc_y(),pen.dec_x(x))
for(x=0;x<renddesc.get_w();x++,pen.inc_x())

At each pixel, we get the color as rendered from the context, set its saturation to zero, and write it back to the same surface:

{
Color tmp(pen.get_value());
pen.put_value(tmp.set_s(0));
}

And that's about it.

// mark our progress as finished
if(cb && !cb->amount_complete(10000,10000)) return false;
return true;
}

Dev:Adding a Layer

2008-04-16T16:13:26Z

Dooglus: /* get_color() */

Here's an example of how to add a simple layer to an existing module. For this example I picked something very easy: a layer which removes all colour from the layers beneath it. I will call this creation "Desaturate", and add it to the mod_filter module.

== The Code ==

So first I need to create desaturate.h and desaturate.cpp in the synfig/src/modules/mod_filter/ folder:

desaturate.h:

/* === S Y N F I G ========================================================= */
/*! \file desaturate.h
** \brief Header file for implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === S T A R T =========================================================== */

#ifndef __SYNFIG_DESATURATE_H
#define __SYNFIG_DESATURATE_H

/* === H E A D E R S ======================================================= */

#include <synfig/layer.h>

/* === C L A S S E S & S T R U C T S ======================================= */

class Desaturate : public synfig::Layer
{
SYNFIG_LAYER_MODULE_EXT
public:
virtual synfig::ValueBase get_param(const synfig::String&)const;
virtual Vocab get_param_vocab()const;
virtual synfig::Color get_color(synfig::Context, const synfig::Point&)const;
virtual bool accelerated_render(synfig::Context,synfig::Surface*,int,
const synfig::RendDesc &, synfig::ProgressCallback *)const;
virtual bool reads_context()const { return true; }
}; // END of class Desaturate

#endif

desaturate.cpp:

/* === S Y N F I G ========================================================= */
/*! \file desaturate.cpp
** \brief Implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === H E A D E R S ======================================================= */

#ifdef USING_PCH
# include "pch.h"
#else
#ifdef HAVE_CONFIG_H
# include <config.h>
#endif

#include "desaturate.h"

#include <synfig/context.h>
#include <synfig/paramdesc.h>
#include <synfig/renddesc.h>
#include <synfig/surface.h>
#include <synfig/value.h>

#endif

using namespace synfig;

/* === G L O B A L S ======================================================= */

SYNFIG_LAYER_INIT(Desaturate);
SYNFIG_LAYER_SET_NAME(Desaturate,"desaturate");
SYNFIG_LAYER_SET_LOCAL_NAME(Desaturate,N_("Desaturate"));
SYNFIG_LAYER_SET_CATEGORY(Desaturate,N_("Filters"));
SYNFIG_LAYER_SET_VERSION(Desaturate,"0.1");
SYNFIG_LAYER_SET_CVS_ID(Desaturate,"$Id$");

/* === M E T H O D S ======================================================= */

ValueBase
Desaturate::get_param(const String &param)const
{
EXPORT_NAME();
EXPORT_VERSION();

return ValueBase();
}

Layer::Vocab
Desaturate::get_param_vocab()const
{
return Layer::Vocab();
}

Color
Desaturate::get_color(Context context, const Point &getpos)const
{
Color tmp(context.get_color(getpos));
return tmp.set_s(0);
}

bool
Desaturate::accelerated_render(Context context,
Surface* surface,
int quality,
const RendDesc& renddesc,
ProgressCallback* cb
)const
{
SuperCallback supercb(cb,0,9500,10000);

// render the context onto the given surface
if(!context.accelerated_render(surface,quality,renddesc,&supercb))
return false;

// set the saturation of each pixel to zero
int x,y;
Surface::pen pen(surface->begin());
for(y=0;y<renddesc.get_h();y++,pen.inc_y(),pen.dec_x(x))
for(x=0;x<renddesc.get_w();x++,pen.inc_x())
{
Color tmp(pen.get_value());
pen.put_value(tmp.set_s(0));
}

// mark our progress as finished
if(cb && !cb->amount_complete(10000,10000)) return false;
return true;
}

Then I need to edit modules/mod_filter/Makefile.am and add these two files to the list of source files (maintain alphabetical order please):

libmod_filter_la_SOURCES = blur.cpp blur.h colorcorrect.cpp colorcorrect.h desaturate.cpp desaturate.h halftone2.cpp halftone2.h lumakey.cpp lumakey.h radialblur.cpp radialblur.h main.cpp halftone.cpp halftone.h halftone3.cpp halftone3.h

And finally we edit modules/mod_filter/main.cpp. Add this with the other #include lines:

#include "desaturate.h"

and add this with the other LAYER(...) lines:

LAYER(Desaturate)

then rebuild (including the autoreconf, ./configure, etc., to get the new files added to the Makefile) and we're done.

== The Description ==

I'll break the header up into sections, describing each part:

=== The initial comment ===

This contains basic documentation and legal stuff. Just copy, paste, and edit from another file.

/* === S Y N F I G ========================================================= */
/*! \file desaturate.h
** \brief Header file for implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === S T A R T =========================================================== */

=== Protection against Multiple Inclusion ===

This #ifndef is a standard way to make sure the header is only compiled once, even if it happens to be included multiple times. Use a unique symbol, based on the file name.

#ifndef __SYNFIG_DESATURATE_H
#define __SYNFIG_DESATURATE_H

=== Headers ===

Include files which are needed. We're not doing anything much, so all we need to include is layer.h, which defines the Layer class that all layers inherit from.

/* === H E A D E R S ======================================================= */

#include <synfig/layer.h>

=== The Class ===

Define the class which implements our layer. We inherit from the Layer class. For this simple example we only define five methods. The rest will be inherited from the Layer class.

/* === C L A S S E S & S T R U C T S ======================================= */

class Desaturate : public synfig::Layer
{

=== SYNFIG_LAYER_MODULE_EXT ===

This is standard. Just use it for every layer. It declares members to hold the layer's name, version, category, etc., and also declares a method to create() the layer. See synfig/src/synfig/layer.h for its definition.

SYNFIG_LAYER_MODULE_EXT

=== The Methods ===

Then we declare the five methods we're going to implement. First "get_param()". Since our layer isn't going to have any parameters, all it needs to do is make the layer's name and
version available.

==== get_param ====

public:
virtual synfig::ValueBase get_param(const synfig::String&)const;

==== get_param_vocab ====

This one returns a list of the layer's parameters. We have no parameters, so we return an empty list.

virtual Vocab get_param_vocab()const;

==== get_color ====

This one is used to find the color of a single given pixel. It's used by the "Info" panel to display the R,G,B values as you mouse over the canvas. It's also used if our layer has any transformation layers over the top of it. The absence of a working implementation of this method in the "Text" layer is why distorting text currently causes render artifacts.

virtual synfig::Color get_color(synfig::Context, const synfig::Point&)const;

==== accelerated_render ====

This one is used to render a large rectangular piece of our layer in one go. It typically calls the accelerated_render() method for the layers under our layer (the 'context') and then modifies the results of that call in some way:

virtual bool accelerated_render(synfig::Context,synfig::Surface*,int,
const synfig::RendDesc &, synfig::ProgressCallback *)const;

==== reads_context ====

This one returns true always, meaning that this layer's output depends on the layers under it (the 'context'):

virtual bool reads_context()const { return true; }
}; // END of class Desaturate

#endif

I won't reproduce the whole of the .cpp file here and go through it. The only two methods which are really interesting here are get_color() and accelerated_render():

== Implementation ==

=== get_color() ===

Given the context, and a point, get_color() should return the color of the pixel at the given point. The context has a get_color() method, so we use that to look up the color of the pixel before our layer has had a chance to affect it, and store that in 'tmp'. Then we set its saturation to zero using [http://synfig.org/api/synfig/classsynfig_1_1Color.html#b62c2069fc43baa97fba17b33ff4d32d color.set_s()] and return it. That's all:

Color
Desaturate::get_color(Context context, const Point &getpos)const
{
Color tmp(context.get_color(getpos));
return tmp.set_s(0);
}

=== accelerated_render() ===

We accept five arguments:

The context (ie. the layers under us):

bool
Desaturate::accelerated_render(Context context,

The surface we are supposed to write our results onto:

Surface* surface,

The quality at which we are to render:

int quality,

A description of the area to render - width, height, top left corner, resolution, etc, etc:

const RendDesc& renddesc,

An object which is used to monitor our progress. It's used for calculating the expected remaining time while rendering:

ProgressCallback* cb
)const
{

I didn't get around to looking at the way the 'cb' ProgressCallback is used. But this code is in pretty much all layers:

SuperCallback supercb(cb,0,9500,10000);

We call accelerated_render() on the context, to render the layers under us. We just pass on the arguments we received for surface, quality and renddesc, along with the new callback we just made. If that render fails, then we fail too:

// render the context onto the given surface
if(!context.accelerated_render(surface,quality,renddesc,&supercb))
return false;

Now we do the real work of this layer. We define integers to do the looping, and a 'pen' which we can walk over the rectangle we're working on:

// set the saturation of each pixel to zero
int x,y;
Surface::pen pen(surface->begin());

We loop through every pixel on every row of the rectangle we're working on. The 'renddesc' gives us the width and height of the rectangle. The pen has methods inc_x(), dec_x(), inc_y(), dec_y() which move it a given amount:

for(y=0;y<renddesc.get_h();y++,pen.inc_y(),pen.dec_x(x))
for(x=0;x<renddesc.get_w();x++,pen.inc_x())

At each pixel, we get the color as rendered from the context, set its saturation to zero, and write it back to the same surface:

{
Color tmp(pen.get_value());
pen.put_value(tmp.set_s(0));
}

And that's about it.

// mark our progress as finished
if(cb && !cb->amount_complete(10000,10000)) return false;
return true;
}

Dev:Adding a Layer

2008-04-16T16:02:35Z

Dooglus: /* accelerated_render() */

Here's an example of how to add a simple layer to an existing module. For this example I picked something very easy: a layer which removes all colour from the layers beneath it. I will call this creation "Desaturate", and add it to the mod_filter module.

== The Code ==

So first I need to create desaturate.h and desaturate.cpp in the synfig/src/modules/mod_filter/ folder:

desaturate.h:

/* === S Y N F I G ========================================================= */
/*! \file desaturate.h
** \brief Header file for implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === S T A R T =========================================================== */

#ifndef __SYNFIG_DESATURATE_H
#define __SYNFIG_DESATURATE_H

/* === H E A D E R S ======================================================= */

#include <synfig/layer.h>

/* === C L A S S E S & S T R U C T S ======================================= */

class Desaturate : public synfig::Layer
{
SYNFIG_LAYER_MODULE_EXT
public:
virtual synfig::ValueBase get_param(const synfig::String&)const;
virtual Vocab get_param_vocab()const;
virtual synfig::Color get_color(synfig::Context, const synfig::Point&)const;
virtual bool accelerated_render(synfig::Context,synfig::Surface*,int,
const synfig::RendDesc &, synfig::ProgressCallback *)const;
virtual bool reads_context()const { return true; }
}; // END of class Desaturate

#endif

desaturate.cpp:

/* === S Y N F I G ========================================================= */
/*! \file desaturate.cpp
** \brief Implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === H E A D E R S ======================================================= */

#ifdef USING_PCH
# include "pch.h"
#else
#ifdef HAVE_CONFIG_H
# include <config.h>
#endif

#include "desaturate.h"

#include <synfig/context.h>
#include <synfig/paramdesc.h>
#include <synfig/renddesc.h>
#include <synfig/surface.h>
#include <synfig/value.h>

#endif

using namespace synfig;

/* === G L O B A L S ======================================================= */

SYNFIG_LAYER_INIT(Desaturate);
SYNFIG_LAYER_SET_NAME(Desaturate,"desaturate");
SYNFIG_LAYER_SET_LOCAL_NAME(Desaturate,N_("Desaturate"));
SYNFIG_LAYER_SET_CATEGORY(Desaturate,N_("Filters"));
SYNFIG_LAYER_SET_VERSION(Desaturate,"0.1");
SYNFIG_LAYER_SET_CVS_ID(Desaturate,"$Id$");

/* === M E T H O D S ======================================================= */

ValueBase
Desaturate::get_param(const String &param)const
{
EXPORT_NAME();
EXPORT_VERSION();

return ValueBase();
}

Layer::Vocab
Desaturate::get_param_vocab()const
{
return Layer::Vocab();
}

Color
Desaturate::get_color(Context context, const Point &getpos)const
{
Color tmp(context.get_color(getpos));
return tmp.set_s(0);
}

bool
Desaturate::accelerated_render(Context context,
Surface* surface,
int quality,
const RendDesc& renddesc,
ProgressCallback* cb
)const
{
SuperCallback supercb(cb,0,9500,10000);

// render the context onto the given surface
if(!context.accelerated_render(surface,quality,renddesc,&supercb))
return false;

// set the saturation of each pixel to zero
int x,y;
Surface::pen pen(surface->begin());
for(y=0;y<renddesc.get_h();y++,pen.inc_y(),pen.dec_x(x))
for(x=0;x<renddesc.get_w();x++,pen.inc_x())
{
Color tmp(pen.get_value());
pen.put_value(tmp.set_s(0));
}

// mark our progress as finished
if(cb && !cb->amount_complete(10000,10000)) return false;
return true;
}

Then I need to edit modules/mod_filter/Makefile.am and add these two files to the list of source files (maintain alphabetical order please):

libmod_filter_la_SOURCES = blur.cpp blur.h colorcorrect.cpp colorcorrect.h desaturate.cpp desaturate.h halftone2.cpp halftone2.h lumakey.cpp lumakey.h radialblur.cpp radialblur.h main.cpp halftone.cpp halftone.h halftone3.cpp halftone3.h

And finally we edit modules/mod_filter/main.cpp. Add this with the other #include lines:

#include "desaturate.h"

and add this with the other LAYER(...) lines:

LAYER(Desaturate)

then rebuild (including the autoreconf, ./configure, etc., to get the new files added to the Makefile) and we're done.

== The Description ==

I'll break the header up into sections, describing each part:

=== The initial comment ===

This contains basic documentation and legal stuff. Just copy, paste, and edit from another file.

/* === S Y N F I G ========================================================= */
/*! \file desaturate.h
** \brief Header file for implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === S T A R T =========================================================== */

=== Protection against Multiple Inclusion ===

This #ifndef is a standard way to make sure the header is only compiled once, even if it happens to be included multiple times. Use a unique symbol, based on the file name.

#ifndef __SYNFIG_DESATURATE_H
#define __SYNFIG_DESATURATE_H

=== Headers ===

Include files which are needed. We're not doing anything much, so all we need to include is layer.h, which defines the Layer class that all layers inherit from.

/* === H E A D E R S ======================================================= */

#include <synfig/layer.h>

=== The Class ===

Define the class which implements our layer. We inherit from the Layer class. For this simple example we only define five methods. The rest will be inherited from the Layer class.

/* === C L A S S E S & S T R U C T S ======================================= */

class Desaturate : public synfig::Layer
{

=== SYNFIG_LAYER_MODULE_EXT ===

This is standard. Just use it for every layer. It declares members to hold the layer's name, version, category, etc., and also declares a method to create() the layer. See synfig/src/synfig/layer.h for its definition.

SYNFIG_LAYER_MODULE_EXT

=== The Methods ===

Then we declare the five methods we're going to implement. First "get_param()". Since our layer isn't going to have any parameters, all it needs to do is make the layer's name and
version available.

==== get_param ====

public:
virtual synfig::ValueBase get_param(const synfig::String&)const;

==== get_param_vocab ====

This one returns a list of the layer's parameters. We have no parameters, so we return an empty list.

virtual Vocab get_param_vocab()const;

==== get_color ====

This one is used to find the color of a single given pixel. It's used by the "Info" panel to display the R,G,B values as you mouse over the canvas. It's also used if our layer has any transformation layers over the top of it. The absence of a working implementation of this method in the "Text" layer is why distorting text currently causes render artifacts.

virtual synfig::Color get_color(synfig::Context, const synfig::Point&)const;

==== accelerated_render ====

This one is used to render a large rectangular piece of our layer in one go. It typically calls the accelerated_render() method for the layers under our layer (the 'context') and then modifies the results of that call in some way:

virtual bool accelerated_render(synfig::Context,synfig::Surface*,int,
const synfig::RendDesc &, synfig::ProgressCallback *)const;

==== reads_context ====

This one returns true always, meaning that this layer's output depends on the layers under it (the 'context'):

virtual bool reads_context()const { return true; }
}; // END of class Desaturate

#endif

I won't reproduce the whole of the .cpp file here and go through it. The only two methods which are really interesting here are get_color() and accelerated_render():

== Implementation ==

=== get_color() ===

Given the context, and a point, get_color() should return the color of the pixel at the given point. The context has a get_color() method, so we use that to look up the color of the pixel before our layer has had a chance to affect it, and store that in 'tmp'. Then we set its saturation to zero and return it. That's all:

Color
Desaturate::get_color(Context context, const Point &getpos)const
{
Color tmp(context.get_color(getpos));
return tmp.set_s(0);
}

=== accelerated_render() ===

We accept five arguments:

The context (ie. the layers under us):

bool
Desaturate::accelerated_render(Context context,

The surface we are supposed to write our results onto:

Surface* surface,

The quality at which we are to render:

int quality,

A description of the area to render - width, height, top left corner, resolution, etc, etc:

const RendDesc& renddesc,

An object which is used to monitor our progress. It's used for calculating the expected remaining time while rendering:

ProgressCallback* cb
)const
{

I didn't get around to looking at the way the 'cb' ProgressCallback is used. But this code is in pretty much all layers:

SuperCallback supercb(cb,0,9500,10000);

We call accelerated_render() on the context, to render the layers under us. We just pass on the arguments we received for surface, quality and renddesc, along with the new callback we just made. If that render fails, then we fail too:

// render the context onto the given surface
if(!context.accelerated_render(surface,quality,renddesc,&supercb))
return false;

Now we do the real work of this layer. We define integers to do the looping, and a 'pen' which we can walk over the rectangle we're working on:

// set the saturation of each pixel to zero
int x,y;
Surface::pen pen(surface->begin());

We loop through every pixel on every row of the rectangle we're working on. The 'renddesc' gives us the width and height of the rectangle. The pen has methods inc_x(), dec_x(), inc_y(), dec_y() which move it a given amount:

for(y=0;y<renddesc.get_h();y++,pen.inc_y(),pen.dec_x(x))
for(x=0;x<renddesc.get_w();x++,pen.inc_x())

At each pixel, we get the color as rendered from the context, set its saturation to zero, and write it back to the same surface:

{
Color tmp(pen.get_value());
pen.put_value(tmp.set_s(0));
}

And that's about it.

// mark our progress as finished
if(cb && !cb->amount_complete(10000,10000)) return false;
return true;
}

Dev:Adding a Layer

2008-04-16T16:02:19Z

Dooglus: /* get_color() */

Here's an example of how to add a simple layer to an existing module. For this example I picked something very easy: a layer which removes all colour from the layers beneath it. I will call this creation "Desaturate", and add it to the mod_filter module.

== The Code ==

So first I need to create desaturate.h and desaturate.cpp in the synfig/src/modules/mod_filter/ folder:

desaturate.h:

/* === S Y N F I G ========================================================= */
/*! \file desaturate.h
** \brief Header file for implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === S T A R T =========================================================== */

#ifndef __SYNFIG_DESATURATE_H
#define __SYNFIG_DESATURATE_H

/* === H E A D E R S ======================================================= */

#include <synfig/layer.h>

/* === C L A S S E S & S T R U C T S ======================================= */

class Desaturate : public synfig::Layer
{
SYNFIG_LAYER_MODULE_EXT
public:
virtual synfig::ValueBase get_param(const synfig::String&)const;
virtual Vocab get_param_vocab()const;
virtual synfig::Color get_color(synfig::Context, const synfig::Point&)const;
virtual bool accelerated_render(synfig::Context,synfig::Surface*,int,
const synfig::RendDesc &, synfig::ProgressCallback *)const;
virtual bool reads_context()const { return true; }
}; // END of class Desaturate

#endif

desaturate.cpp:

/* === S Y N F I G ========================================================= */
/*! \file desaturate.cpp
** \brief Implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === H E A D E R S ======================================================= */

#ifdef USING_PCH
# include "pch.h"
#else
#ifdef HAVE_CONFIG_H
# include <config.h>
#endif

#include "desaturate.h"

#include <synfig/context.h>
#include <synfig/paramdesc.h>
#include <synfig/renddesc.h>
#include <synfig/surface.h>
#include <synfig/value.h>

#endif

using namespace synfig;

/* === G L O B A L S ======================================================= */

SYNFIG_LAYER_INIT(Desaturate);
SYNFIG_LAYER_SET_NAME(Desaturate,"desaturate");
SYNFIG_LAYER_SET_LOCAL_NAME(Desaturate,N_("Desaturate"));
SYNFIG_LAYER_SET_CATEGORY(Desaturate,N_("Filters"));
SYNFIG_LAYER_SET_VERSION(Desaturate,"0.1");
SYNFIG_LAYER_SET_CVS_ID(Desaturate,"$Id$");

/* === M E T H O D S ======================================================= */

ValueBase
Desaturate::get_param(const String &param)const
{
EXPORT_NAME();
EXPORT_VERSION();

return ValueBase();
}

Layer::Vocab
Desaturate::get_param_vocab()const
{
return Layer::Vocab();
}

Color
Desaturate::get_color(Context context, const Point &getpos)const
{
Color tmp(context.get_color(getpos));
return tmp.set_s(0);
}

bool
Desaturate::accelerated_render(Context context,
Surface* surface,
int quality,
const RendDesc& renddesc,
ProgressCallback* cb
)const
{
SuperCallback supercb(cb,0,9500,10000);

// render the context onto the given surface
if(!context.accelerated_render(surface,quality,renddesc,&supercb))
return false;

// set the saturation of each pixel to zero
int x,y;
Surface::pen pen(surface->begin());
for(y=0;y<renddesc.get_h();y++,pen.inc_y(),pen.dec_x(x))
for(x=0;x<renddesc.get_w();x++,pen.inc_x())
{
Color tmp(pen.get_value());
pen.put_value(tmp.set_s(0));
}

// mark our progress as finished
if(cb && !cb->amount_complete(10000,10000)) return false;
return true;
}

Then I need to edit modules/mod_filter/Makefile.am and add these two files to the list of source files (maintain alphabetical order please):

libmod_filter_la_SOURCES = blur.cpp blur.h colorcorrect.cpp colorcorrect.h desaturate.cpp desaturate.h halftone2.cpp halftone2.h lumakey.cpp lumakey.h radialblur.cpp radialblur.h main.cpp halftone.cpp halftone.h halftone3.cpp halftone3.h

And finally we edit modules/mod_filter/main.cpp. Add this with the other #include lines:

#include "desaturate.h"

and add this with the other LAYER(...) lines:

LAYER(Desaturate)

then rebuild (including the autoreconf, ./configure, etc., to get the new files added to the Makefile) and we're done.

== The Description ==

I'll break the header up into sections, describing each part:

=== The initial comment ===

This contains basic documentation and legal stuff. Just copy, paste, and edit from another file.

/* === S Y N F I G ========================================================= */
/*! \file desaturate.h
** \brief Header file for implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === S T A R T =========================================================== */

=== Protection against Multiple Inclusion ===

This #ifndef is a standard way to make sure the header is only compiled once, even if it happens to be included multiple times. Use a unique symbol, based on the file name.

#ifndef __SYNFIG_DESATURATE_H
#define __SYNFIG_DESATURATE_H

=== Headers ===

Include files which are needed. We're not doing anything much, so all we need to include is layer.h, which defines the Layer class that all layers inherit from.

/* === H E A D E R S ======================================================= */

#include <synfig/layer.h>

=== The Class ===

Define the class which implements our layer. We inherit from the Layer class. For this simple example we only define five methods. The rest will be inherited from the Layer class.

/* === C L A S S E S & S T R U C T S ======================================= */

class Desaturate : public synfig::Layer
{

=== SYNFIG_LAYER_MODULE_EXT ===

This is standard. Just use it for every layer. It declares members to hold the layer's name, version, category, etc., and also declares a method to create() the layer. See synfig/src/synfig/layer.h for its definition.

SYNFIG_LAYER_MODULE_EXT

=== The Methods ===

Then we declare the five methods we're going to implement. First "get_param()". Since our layer isn't going to have any parameters, all it needs to do is make the layer's name and
version available.

==== get_param ====

public:
virtual synfig::ValueBase get_param(const synfig::String&)const;

==== get_param_vocab ====

This one returns a list of the layer's parameters. We have no parameters, so we return an empty list.

virtual Vocab get_param_vocab()const;

==== get_color ====

This one is used to find the color of a single given pixel. It's used by the "Info" panel to display the R,G,B values as you mouse over the canvas. It's also used if our layer has any transformation layers over the top of it. The absence of a working implementation of this method in the "Text" layer is why distorting text currently causes render artifacts.

virtual synfig::Color get_color(synfig::Context, const synfig::Point&)const;

==== accelerated_render ====

This one is used to render a large rectangular piece of our layer in one go. It typically calls the accelerated_render() method for the layers under our layer (the 'context') and then modifies the results of that call in some way:

virtual bool accelerated_render(synfig::Context,synfig::Surface*,int,
const synfig::RendDesc &, synfig::ProgressCallback *)const;

==== reads_context ====

This one returns true always, meaning that this layer's output depends on the layers under it (the 'context'):

virtual bool reads_context()const { return true; }
}; // END of class Desaturate

#endif

I won't reproduce the whole of the .cpp file here and go through it. The only two methods which are really interesting here are get_color() and accelerated_render():

== Implementation ==

=== get_color() ===

Given the context, and a point, get_color() should return the color of the pixel at the given point. The context has a get_color() method, so we use that to look up the color of the pixel before our layer has had a chance to affect it, and store that in 'tmp'. Then we set its saturation to zero and return it. That's all:

Color
Desaturate::get_color(Context context, const Point &getpos)const
{
Color tmp(context.get_color(getpos));
return tmp.set_s(0);
}

== accelerated_render() ==

We accept five arguments:

The context (ie. the layers under us):

bool
Desaturate::accelerated_render(Context context,

The surface we are supposed to write our results onto:

Surface* surface,

The quality at which we are to render:

int quality,

A description of the area to render - width, height, top left corner, resolution, etc, etc:

const RendDesc& renddesc,

An object which is used to monitor our progress. It's used for calculating the expected remaining time while rendering:

ProgressCallback* cb
)const
{

I didn't get around to looking at the way the 'cb' ProgressCallback is used. But this code is in pretty much all layers:

SuperCallback supercb(cb,0,9500,10000);

We call accelerated_render() on the context, to render the layers under us. We just pass on the arguments we received for surface, quality and renddesc, along with the new callback we just made. If that render fails, then we fail too:

// render the context onto the given surface
if(!context.accelerated_render(surface,quality,renddesc,&supercb))
return false;

Now we do the real work of this layer. We define integers to do the looping, and a 'pen' which we can walk over the rectangle we're working on:

// set the saturation of each pixel to zero
int x,y;
Surface::pen pen(surface->begin());

We loop through every pixel on every row of the rectangle we're working on. The 'renddesc' gives us the width and height of the rectangle. The pen has methods inc_x(), dec_x(), inc_y(), dec_y() which move it a given amount:

for(y=0;y<renddesc.get_h();y++,pen.inc_y(),pen.dec_x(x))
for(x=0;x<renddesc.get_w();x++,pen.inc_x())

At each pixel, we get the color as rendered from the context, set its saturation to zero, and write it back to the same surface:

{
Color tmp(pen.get_value());
pen.put_value(tmp.set_s(0));
}

And that's about it.

// mark our progress as finished
if(cb && !cb->amount_complete(10000,10000)) return false;
return true;
}

Dev:Adding a Layer

2008-04-16T16:01:45Z

Dooglus: /* The Methods */

Here's an example of how to add a simple layer to an existing module. For this example I picked something very easy: a layer which removes all colour from the layers beneath it. I will call this creation "Desaturate", and add it to the mod_filter module.

== The Code ==

So first I need to create desaturate.h and desaturate.cpp in the synfig/src/modules/mod_filter/ folder:

desaturate.h:

/* === S Y N F I G ========================================================= */
/*! \file desaturate.h
** \brief Header file for implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === S T A R T =========================================================== */

#ifndef __SYNFIG_DESATURATE_H
#define __SYNFIG_DESATURATE_H

/* === H E A D E R S ======================================================= */

#include <synfig/layer.h>

/* === C L A S S E S & S T R U C T S ======================================= */

class Desaturate : public synfig::Layer
{
SYNFIG_LAYER_MODULE_EXT
public:
virtual synfig::ValueBase get_param(const synfig::String&)const;
virtual Vocab get_param_vocab()const;
virtual synfig::Color get_color(synfig::Context, const synfig::Point&)const;
virtual bool accelerated_render(synfig::Context,synfig::Surface*,int,
const synfig::RendDesc &, synfig::ProgressCallback *)const;
virtual bool reads_context()const { return true; }
}; // END of class Desaturate

#endif

desaturate.cpp:

/* === S Y N F I G ========================================================= */
/*! \file desaturate.cpp
** \brief Implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === H E A D E R S ======================================================= */

#ifdef USING_PCH
# include "pch.h"
#else
#ifdef HAVE_CONFIG_H
# include <config.h>
#endif

#include "desaturate.h"

#include <synfig/context.h>
#include <synfig/paramdesc.h>
#include <synfig/renddesc.h>
#include <synfig/surface.h>
#include <synfig/value.h>

#endif

using namespace synfig;

/* === G L O B A L S ======================================================= */

SYNFIG_LAYER_INIT(Desaturate);
SYNFIG_LAYER_SET_NAME(Desaturate,"desaturate");
SYNFIG_LAYER_SET_LOCAL_NAME(Desaturate,N_("Desaturate"));
SYNFIG_LAYER_SET_CATEGORY(Desaturate,N_("Filters"));
SYNFIG_LAYER_SET_VERSION(Desaturate,"0.1");
SYNFIG_LAYER_SET_CVS_ID(Desaturate,"$Id$");

/* === M E T H O D S ======================================================= */

ValueBase
Desaturate::get_param(const String &param)const
{
EXPORT_NAME();
EXPORT_VERSION();

return ValueBase();
}

Layer::Vocab
Desaturate::get_param_vocab()const
{
return Layer::Vocab();
}

Color
Desaturate::get_color(Context context, const Point &getpos)const
{
Color tmp(context.get_color(getpos));
return tmp.set_s(0);
}

bool
Desaturate::accelerated_render(Context context,
Surface* surface,
int quality,
const RendDesc& renddesc,
ProgressCallback* cb
)const
{
SuperCallback supercb(cb,0,9500,10000);

// render the context onto the given surface
if(!context.accelerated_render(surface,quality,renddesc,&supercb))
return false;

// set the saturation of each pixel to zero
int x,y;
Surface::pen pen(surface->begin());
for(y=0;y<renddesc.get_h();y++,pen.inc_y(),pen.dec_x(x))
for(x=0;x<renddesc.get_w();x++,pen.inc_x())
{
Color tmp(pen.get_value());
pen.put_value(tmp.set_s(0));
}

// mark our progress as finished
if(cb && !cb->amount_complete(10000,10000)) return false;
return true;
}

Then I need to edit modules/mod_filter/Makefile.am and add these two files to the list of source files (maintain alphabetical order please):

libmod_filter_la_SOURCES = blur.cpp blur.h colorcorrect.cpp colorcorrect.h desaturate.cpp desaturate.h halftone2.cpp halftone2.h lumakey.cpp lumakey.h radialblur.cpp radialblur.h main.cpp halftone.cpp halftone.h halftone3.cpp halftone3.h

And finally we edit modules/mod_filter/main.cpp. Add this with the other #include lines:

#include "desaturate.h"

and add this with the other LAYER(...) lines:

LAYER(Desaturate)

then rebuild (including the autoreconf, ./configure, etc., to get the new files added to the Makefile) and we're done.

== The Description ==

I'll break the header up into sections, describing each part:

=== The initial comment ===

This contains basic documentation and legal stuff. Just copy, paste, and edit from another file.

/* === S Y N F I G ========================================================= */
/*! \file desaturate.h
** \brief Header file for implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === S T A R T =========================================================== */

=== Protection against Multiple Inclusion ===

This #ifndef is a standard way to make sure the header is only compiled once, even if it happens to be included multiple times. Use a unique symbol, based on the file name.

#ifndef __SYNFIG_DESATURATE_H
#define __SYNFIG_DESATURATE_H

=== Headers ===

Include files which are needed. We're not doing anything much, so all we need to include is layer.h, which defines the Layer class that all layers inherit from.

/* === H E A D E R S ======================================================= */

#include <synfig/layer.h>

=== The Class ===

Define the class which implements our layer. We inherit from the Layer class. For this simple example we only define five methods. The rest will be inherited from the Layer class.

/* === C L A S S E S & S T R U C T S ======================================= */

class Desaturate : public synfig::Layer
{

=== SYNFIG_LAYER_MODULE_EXT ===

This is standard. Just use it for every layer. It declares members to hold the layer's name, version, category, etc., and also declares a method to create() the layer. See synfig/src/synfig/layer.h for its definition.

SYNFIG_LAYER_MODULE_EXT

=== The Methods ===

Then we declare the five methods we're going to implement. First "get_param()". Since our layer isn't going to have any parameters, all it needs to do is make the layer's name and
version available.

==== get_param ====

public:
virtual synfig::ValueBase get_param(const synfig::String&)const;

==== get_param_vocab ====

This one returns a list of the layer's parameters. We have no parameters, so we return an empty list.

virtual Vocab get_param_vocab()const;

==== get_color ====

This one is used to find the color of a single given pixel. It's used by the "Info" panel to display the R,G,B values as you mouse over the canvas. It's also used if our layer has any transformation layers over the top of it. The absence of a working implementation of this method in the "Text" layer is why distorting text currently causes render artifacts.

virtual synfig::Color get_color(synfig::Context, const synfig::Point&)const;

==== accelerated_render ====

This one is used to render a large rectangular piece of our layer in one go. It typically calls the accelerated_render() method for the layers under our layer (the 'context') and then modifies the results of that call in some way:

virtual bool accelerated_render(synfig::Context,synfig::Surface*,int,
const synfig::RendDesc &, synfig::ProgressCallback *)const;

==== reads_context ====

This one returns true always, meaning that this layer's output depends on the layers under it (the 'context'):

virtual bool reads_context()const { return true; }
}; // END of class Desaturate

#endif

I won't reproduce the whole of the .cpp file here and go through it. The only two methods which are really interesting here are get_color() and accelerated_render():

== get_color() ==

Given the context, and a point, get_color() should return the color of the pixel at the given point. The context has a get_color() method, so we use that to look up the color of the pixel before our layer has had a chance to affect it, and store that in 'tmp'. Then we set its saturation to zero and return it. That's all:

Color
Desaturate::get_color(Context context, const Point &getpos)const
{
Color tmp(context.get_color(getpos));
return tmp.set_s(0);
}

== accelerated_render() ==

We accept five arguments:

The context (ie. the layers under us):

bool
Desaturate::accelerated_render(Context context,

The surface we are supposed to write our results onto:

Surface* surface,

The quality at which we are to render:

int quality,

A description of the area to render - width, height, top left corner, resolution, etc, etc:

const RendDesc& renddesc,

An object which is used to monitor our progress. It's used for calculating the expected remaining time while rendering:

ProgressCallback* cb
)const
{

I didn't get around to looking at the way the 'cb' ProgressCallback is used. But this code is in pretty much all layers:

SuperCallback supercb(cb,0,9500,10000);

We call accelerated_render() on the context, to render the layers under us. We just pass on the arguments we received for surface, quality and renddesc, along with the new callback we just made. If that render fails, then we fail too:

// render the context onto the given surface
if(!context.accelerated_render(surface,quality,renddesc,&supercb))
return false;

Now we do the real work of this layer. We define integers to do the looping, and a 'pen' which we can walk over the rectangle we're working on:

// set the saturation of each pixel to zero
int x,y;
Surface::pen pen(surface->begin());

We loop through every pixel on every row of the rectangle we're working on. The 'renddesc' gives us the width and height of the rectangle. The pen has methods inc_x(), dec_x(), inc_y(), dec_y() which move it a given amount:

for(y=0;y<renddesc.get_h();y++,pen.inc_y(),pen.dec_x(x))
for(x=0;x<renddesc.get_w();x++,pen.inc_x())

At each pixel, we get the color as rendered from the context, set its saturation to zero, and write it back to the same surface:

{
Color tmp(pen.get_value());
pen.put_value(tmp.set_s(0));
}

And that's about it.

// mark our progress as finished
if(cb && !cb->amount_complete(10000,10000)) return false;
return true;
}

Dev:Adding a Layer

2008-04-16T16:00:44Z

Dooglus: /* The Class */

Here's an example of how to add a simple layer to an existing module. For this example I picked something very easy: a layer which removes all colour from the layers beneath it. I will call this creation "Desaturate", and add it to the mod_filter module.

== The Code ==

So first I need to create desaturate.h and desaturate.cpp in the synfig/src/modules/mod_filter/ folder:

desaturate.h:

/* === S Y N F I G ========================================================= */
/*! \file desaturate.h
** \brief Header file for implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === S T A R T =========================================================== */

#ifndef __SYNFIG_DESATURATE_H
#define __SYNFIG_DESATURATE_H

/* === H E A D E R S ======================================================= */

#include <synfig/layer.h>

/* === C L A S S E S & S T R U C T S ======================================= */

class Desaturate : public synfig::Layer
{
SYNFIG_LAYER_MODULE_EXT
public:
virtual synfig::ValueBase get_param(const synfig::String&)const;
virtual Vocab get_param_vocab()const;
virtual synfig::Color get_color(synfig::Context, const synfig::Point&)const;
virtual bool accelerated_render(synfig::Context,synfig::Surface*,int,
const synfig::RendDesc &, synfig::ProgressCallback *)const;
virtual bool reads_context()const { return true; }
}; // END of class Desaturate

#endif

desaturate.cpp:

/* === S Y N F I G ========================================================= */
/*! \file desaturate.cpp
** \brief Implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === H E A D E R S ======================================================= */

#ifdef USING_PCH
# include "pch.h"
#else
#ifdef HAVE_CONFIG_H
# include <config.h>
#endif

#include "desaturate.h"

#include <synfig/context.h>
#include <synfig/paramdesc.h>
#include <synfig/renddesc.h>
#include <synfig/surface.h>
#include <synfig/value.h>

#endif

using namespace synfig;

/* === G L O B A L S ======================================================= */

SYNFIG_LAYER_INIT(Desaturate);
SYNFIG_LAYER_SET_NAME(Desaturate,"desaturate");
SYNFIG_LAYER_SET_LOCAL_NAME(Desaturate,N_("Desaturate"));
SYNFIG_LAYER_SET_CATEGORY(Desaturate,N_("Filters"));
SYNFIG_LAYER_SET_VERSION(Desaturate,"0.1");
SYNFIG_LAYER_SET_CVS_ID(Desaturate,"$Id$");

/* === M E T H O D S ======================================================= */

ValueBase
Desaturate::get_param(const String &param)const
{
EXPORT_NAME();
EXPORT_VERSION();

return ValueBase();
}

Layer::Vocab
Desaturate::get_param_vocab()const
{
return Layer::Vocab();
}

Color
Desaturate::get_color(Context context, const Point &getpos)const
{
Color tmp(context.get_color(getpos));
return tmp.set_s(0);
}

bool
Desaturate::accelerated_render(Context context,
Surface* surface,
int quality,
const RendDesc& renddesc,
ProgressCallback* cb
)const
{
SuperCallback supercb(cb,0,9500,10000);

// render the context onto the given surface
if(!context.accelerated_render(surface,quality,renddesc,&supercb))
return false;

// set the saturation of each pixel to zero
int x,y;
Surface::pen pen(surface->begin());
for(y=0;y<renddesc.get_h();y++,pen.inc_y(),pen.dec_x(x))
for(x=0;x<renddesc.get_w();x++,pen.inc_x())
{
Color tmp(pen.get_value());
pen.put_value(tmp.set_s(0));
}

// mark our progress as finished
if(cb && !cb->amount_complete(10000,10000)) return false;
return true;
}

Then I need to edit modules/mod_filter/Makefile.am and add these two files to the list of source files (maintain alphabetical order please):

libmod_filter_la_SOURCES = blur.cpp blur.h colorcorrect.cpp colorcorrect.h desaturate.cpp desaturate.h halftone2.cpp halftone2.h lumakey.cpp lumakey.h radialblur.cpp radialblur.h main.cpp halftone.cpp halftone.h halftone3.cpp halftone3.h

And finally we edit modules/mod_filter/main.cpp. Add this with the other #include lines:

#include "desaturate.h"

and add this with the other LAYER(...) lines:

LAYER(Desaturate)

then rebuild (including the autoreconf, ./configure, etc., to get the new files added to the Makefile) and we're done.

== The Description ==

I'll break the header up into sections, describing each part:

=== The initial comment ===

This contains basic documentation and legal stuff. Just copy, paste, and edit from another file.

/* === S Y N F I G ========================================================= */
/*! \file desaturate.h
** \brief Header file for implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === S T A R T =========================================================== */

=== Protection against Multiple Inclusion ===

This #ifndef is a standard way to make sure the header is only compiled once, even if it happens to be included multiple times. Use a unique symbol, based on the file name.

#ifndef __SYNFIG_DESATURATE_H
#define __SYNFIG_DESATURATE_H

=== Headers ===

Include files which are needed. We're not doing anything much, so all we need to include is layer.h, which defines the Layer class that all layers inherit from.

/* === H E A D E R S ======================================================= */

#include <synfig/layer.h>

=== The Class ===

Define the class which implements our layer. We inherit from the Layer class. For this simple example we only define five methods. The rest will be inherited from the Layer class.

/* === C L A S S E S & S T R U C T S ======================================= */

class Desaturate : public synfig::Layer
{

=== SYNFIG_LAYER_MODULE_EXT ===

This is standard. Just use it for every layer. It declares members to hold the layer's name, version, category, etc., and also declares a method to create() the layer. See synfig/src/synfig/layer.h for its definition.

SYNFIG_LAYER_MODULE_EXT

=== The Methods ===

Then we declare the five methods we're going to implement. First "get_param()". Since our layer isn't going to have any parameters, all it needs to do is make the layer's name and
version available.

public:
virtual synfig::ValueBase get_param(const synfig::String&)const;

This one returns a list of the layer's parameters. We have no parameters, so we return an empty list.

virtual Vocab get_param_vocab()const;

This one is used to find the color of a single given pixel. It's used by the "Info" panel to display the R,G,B values as you mouse over the canvas. It's also used if our layer has any transformation layers over the top of it. The absence of a working implementation of this method in the "Text" layer is why distorting text currently causes render artifacts.

virtual synfig::Color get_color(synfig::Context, const synfig::Point&)const;

This one is used to render a large rectangular piece of our layer in one go. It typically calls the accelerated_render() method for the layers under our layer (the 'context') and then modifies the results of that call in some way:

virtual bool accelerated_render(synfig::Context,synfig::Surface*,int,
const synfig::RendDesc &, synfig::ProgressCallback *)const;

This one returns true always, meaning that this layer's output depends on the layers under it (the 'context'):

virtual bool reads_context()const { return true; }
}; // END of class Desaturate

#endif

I won't reproduce the whole of the .cpp file here and go through it. The only two methods which are really interesting here are get_color() and accelerated_render():

== get_color() ==

Given the context, and a point, get_color() should return the color of the pixel at the given point. The context has a get_color() method, so we use that to look up the color of the pixel before our layer has had a chance to affect it, and store that in 'tmp'. Then we set its saturation to zero and return it. That's all:

Color
Desaturate::get_color(Context context, const Point &getpos)const
{
Color tmp(context.get_color(getpos));
return tmp.set_s(0);
}

== accelerated_render() ==

We accept five arguments:

The context (ie. the layers under us):

bool
Desaturate::accelerated_render(Context context,

The surface we are supposed to write our results onto:

Surface* surface,

The quality at which we are to render:

int quality,

A description of the area to render - width, height, top left corner, resolution, etc, etc:

const RendDesc& renddesc,

An object which is used to monitor our progress. It's used for calculating the expected remaining time while rendering:

ProgressCallback* cb
)const
{

I didn't get around to looking at the way the 'cb' ProgressCallback is used. But this code is in pretty much all layers:

SuperCallback supercb(cb,0,9500,10000);

We call accelerated_render() on the context, to render the layers under us. We just pass on the arguments we received for surface, quality and renddesc, along with the new callback we just made. If that render fails, then we fail too:

// render the context onto the given surface
if(!context.accelerated_render(surface,quality,renddesc,&supercb))
return false;

Now we do the real work of this layer. We define integers to do the looping, and a 'pen' which we can walk over the rectangle we're working on:

// set the saturation of each pixel to zero
int x,y;
Surface::pen pen(surface->begin());

We loop through every pixel on every row of the rectangle we're working on. The 'renddesc' gives us the width and height of the rectangle. The pen has methods inc_x(), dec_x(), inc_y(), dec_y() which move it a given amount:

for(y=0;y<renddesc.get_h();y++,pen.inc_y(),pen.dec_x(x))
for(x=0;x<renddesc.get_w();x++,pen.inc_x())

At each pixel, we get the color as rendered from the context, set its saturation to zero, and write it back to the same surface:

{
Color tmp(pen.get_value());
pen.put_value(tmp.set_s(0));
}

And that's about it.

// mark our progress as finished
if(cb && !cb->amount_complete(10000,10000)) return false;
return true;
}

Dev:Adding a Layer

2008-04-16T16:00:16Z

Dooglus: /* Protection against Multiple Inclusion */

Here's an example of how to add a simple layer to an existing module. For this example I picked something very easy: a layer which removes all colour from the layers beneath it. I will call this creation "Desaturate", and add it to the mod_filter module.

== The Code ==

So first I need to create desaturate.h and desaturate.cpp in the synfig/src/modules/mod_filter/ folder:

desaturate.h:

/* === S Y N F I G ========================================================= */
/*! \file desaturate.h
** \brief Header file for implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === S T A R T =========================================================== */

#ifndef __SYNFIG_DESATURATE_H
#define __SYNFIG_DESATURATE_H

/* === H E A D E R S ======================================================= */

#include <synfig/layer.h>

/* === C L A S S E S & S T R U C T S ======================================= */

class Desaturate : public synfig::Layer
{
SYNFIG_LAYER_MODULE_EXT
public:
virtual synfig::ValueBase get_param(const synfig::String&)const;
virtual Vocab get_param_vocab()const;
virtual synfig::Color get_color(synfig::Context, const synfig::Point&)const;
virtual bool accelerated_render(synfig::Context,synfig::Surface*,int,
const synfig::RendDesc &, synfig::ProgressCallback *)const;
virtual bool reads_context()const { return true; }
}; // END of class Desaturate

#endif

desaturate.cpp:

/* === S Y N F I G ========================================================= */
/*! \file desaturate.cpp
** \brief Implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === H E A D E R S ======================================================= */

#ifdef USING_PCH
# include "pch.h"
#else
#ifdef HAVE_CONFIG_H
# include <config.h>
#endif

#include "desaturate.h"

#include <synfig/context.h>
#include <synfig/paramdesc.h>
#include <synfig/renddesc.h>
#include <synfig/surface.h>
#include <synfig/value.h>

#endif

using namespace synfig;

/* === G L O B A L S ======================================================= */

SYNFIG_LAYER_INIT(Desaturate);
SYNFIG_LAYER_SET_NAME(Desaturate,"desaturate");
SYNFIG_LAYER_SET_LOCAL_NAME(Desaturate,N_("Desaturate"));
SYNFIG_LAYER_SET_CATEGORY(Desaturate,N_("Filters"));
SYNFIG_LAYER_SET_VERSION(Desaturate,"0.1");
SYNFIG_LAYER_SET_CVS_ID(Desaturate,"$Id$");

/* === M E T H O D S ======================================================= */

ValueBase
Desaturate::get_param(const String &param)const
{
EXPORT_NAME();
EXPORT_VERSION();

return ValueBase();
}

Layer::Vocab
Desaturate::get_param_vocab()const
{
return Layer::Vocab();
}

Color
Desaturate::get_color(Context context, const Point &getpos)const
{
Color tmp(context.get_color(getpos));
return tmp.set_s(0);
}

bool
Desaturate::accelerated_render(Context context,
Surface* surface,
int quality,
const RendDesc& renddesc,
ProgressCallback* cb
)const
{
SuperCallback supercb(cb,0,9500,10000);

// render the context onto the given surface
if(!context.accelerated_render(surface,quality,renddesc,&supercb))
return false;

// set the saturation of each pixel to zero
int x,y;
Surface::pen pen(surface->begin());
for(y=0;y<renddesc.get_h();y++,pen.inc_y(),pen.dec_x(x))
for(x=0;x<renddesc.get_w();x++,pen.inc_x())
{
Color tmp(pen.get_value());
pen.put_value(tmp.set_s(0));
}

// mark our progress as finished
if(cb && !cb->amount_complete(10000,10000)) return false;
return true;
}

Then I need to edit modules/mod_filter/Makefile.am and add these two files to the list of source files (maintain alphabetical order please):

libmod_filter_la_SOURCES = blur.cpp blur.h colorcorrect.cpp colorcorrect.h desaturate.cpp desaturate.h halftone2.cpp halftone2.h lumakey.cpp lumakey.h radialblur.cpp radialblur.h main.cpp halftone.cpp halftone.h halftone3.cpp halftone3.h

And finally we edit modules/mod_filter/main.cpp. Add this with the other #include lines:

#include "desaturate.h"

and add this with the other LAYER(...) lines:

LAYER(Desaturate)

then rebuild (including the autoreconf, ./configure, etc., to get the new files added to the Makefile) and we're done.

== The Description ==

I'll break the header up into sections, describing each part:

=== The initial comment ===

This contains basic documentation and legal stuff. Just copy, paste, and edit from another file.

/* === S Y N F I G ========================================================= */
/*! \file desaturate.h
** \brief Header file for implementation of the "Desaturate" layer
**
** \legal
** Copyright (c) 2008 Chris Moore
**
** This package is free software; you can redistribute it and/or
** modify it under the terms of the GNU General Public License as
** published by the Free Software Foundation; either version 2 of
** the License, or (at your option) any later version.
**
** This package is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** General Public License for more details.
** \endlegal
** ========================================================================= */

/* === S T A R T =========================================================== */

=== Protection against Multiple Inclusion ===

This #ifndef is a standard way to make sure the header is only compiled once, even if it happens to be included multiple times. Use a unique symbol, based on the file name.

#ifndef __SYNFIG_DESATURATE_H
#define __SYNFIG_DESATURATE_H

=== Headers ===

Include files which are needed. We're not doing anything much, so all we need to include is layer.h, which defines the Layer class that all layers inherit from.

/* === H E A D E R S ======================================================= */

#include <synfig/layer.h>

=== The Class ===

Define the class which implements our layer. We inherit from the Layer class. For this simple example we only define five methods. The rest will be inherited from the Layer class.

/* === C L A S S E S & S T R U C T S ======================================= */

class Desaturate : public synfig::Layer
{

This is standard. Just use it for every layer. It declares members to hold the layer's name, version, category, etc., and also declares a method to create() the layer. See synfig/src/synfig/layer.h for its definition.

SYNFIG_LAYER_MODULE_EXT

=== The Methods ===

Then we declare the five methods we're going to implement. First "get_param()". Since our layer isn't going to have any parameters, all it needs to do is make the layer's name and
version available.

public:
virtual synfig::ValueBase get_param(const synfig::String&)const;

This one returns a list of the layer's parameters. We have no parameters, so we return an empty list.

virtual Vocab get_param_vocab()const;

This one is used to find the color of a single given pixel. It's used by the "Info" panel to display the R,G,B values as you mouse over the canvas. It's also used if our layer has any transformation layers over the top of it. The absence of a working implementation of this method in the "Text" layer is why distorting text currently causes render artifacts.

virtual synfig::Color get_color(synfig::Context, const synfig::Point&)const;

This one is used to render a large rectangular piece of our layer in one go. It typically calls the accelerated_render() method for the layers under our layer (the 'context') and then modifies the results of that call in some way:

virtual bool accelerated_render(synfig::Context,synfig::Surface*,int,
const synfig::RendDesc &, synfig::ProgressCallback *)const;

This one returns true always, meaning that this layer's output depends on the layers under it (the 'context'):

virtual bool reads_context()const { return true; }
}; // END of class Desaturate

#endif

I won't reproduce the whole of the .cpp file here and go through it. The only two methods which are really interesting here are get_color() and accelerated_render():

== get_color() ==

Given the context, and a point, get_color() should return the color of the pixel at the given point. The context has a get_color() method, so we use that to look up the color of the pixel before our layer has had a chance to affect it, and store that in 'tmp'. Then we set its saturation to zero and return it. That's all:

Color
Desaturate::get_color(Context context, const Point &getpos)const
{
Color tmp(context.get_color(getpos));
return tmp.set_s(0);
}

== accelerated_render() ==

We accept five arguments:

The context (ie. the layers under us):

bool
Desaturate::accelerated_render(Context context,

The surface we are supposed to write our results onto:

Surface* surface,

The quality at which we are to render:

int quality,

A description of the area to render - width, height, top left corner, resolution, etc, etc:

const RendDesc& renddesc,

An object which is used to monitor our progress. It's used for calculating the expected remaining time while rendering:

ProgressCallback* cb
)const
{

I didn't get around to looking at the way the 'cb' ProgressCallback is used. But this code is in pretty much all layers:

SuperCallback supercb(cb,0,9500,10000);

We call accelerated_render() on the context, to render the layers under us. We just pass on the arguments we received for surface, quality and renddesc, along with the new callback we just made. If that render fails, then we fail too:

// render the context onto the given surface
if(!context.accelerated_render(surface,quality,renddesc,&supercb))
return false;

Now we do the real work of this layer. We define integers to do the looping, and a 'pen' which we can walk over the rectangle we're working on:

// set the saturation of each pixel to zero
int x,y;
Surface::pen pen(surface->begin());

We loop through every pixel on every row of the rectangle we're working on. The 'renddesc' gives us the width and height of the rectangle. The pen has methods inc_x(), dec_x(), inc_y(), dec_y() which move it a given amount:

for(y=0;y<renddesc.get_h();y++,pen.inc_y(),pen.dec_x(x))
for(x=0;x<renddesc.get_w();x++,pen.inc_x())

At each pixel, we get the color as rendered from the context, set its saturation to zero, and write it back to the same surface:

{
Color tmp(pen.get_value());
pen.put_value(tmp.set_s(0));
}

And that's about it.

// mark our progress as finished
if(cb && !cb->amount_complete(10000,10000)) return false;
return true;
}