Anatomy of a Synfig animation


First, let me say thanks to everyone who has put so much time and effort into both the code and documentation of Synfig. It is all very well done!

I recently worked my way through the tutorials and read the rest of the wiki so that I could learn all of Synfig’s capabilities. Unfortunately, it wasn’t until about 2/3 to 3/4 of the way through that process that I really felt like I started to understand how all of the pieces fit together and I found myself wishing I’d had that basic understanding earlier. So I’ve added a wiki page which attempts to fill the gap. It is currently at:

IMHO, this page or something similar would be useful to include in the Introduction section of the manual.

Please let me know what you think.


Hello DeanBrettle and welcome to Synfig!

It is a good idea to try and describe the concept of the different aspects of Synfig. Well worth a place in the introductionary section of the wiki.

However I think your text is problematic in some ways.

First, calling an Synfig animation a canvas is plain wrong. The canvas is the canvas, ie. the stage or the paper in front of you onto which you do your animation.
Animation in Synfig is called animation.
Can you give examples on where animation is called canvas?

I think your description of the layer workflow is a bit confusing.
Also the whole text is a bit heavy. Long sentences without paragraphs. It is a bit hard to follow your reasoning.

I’m sorry to be so critical about your text but information in the wiki, especially targeted towards absolute beginners needs to be clear and concise and above all, right.
Again, it is a good idea with such an introduction but it needs some work with information, cleaning up and structure.

A quick read of the article reveals some concepts that should be reviewed:

  • The blending is made from top to down and paste canvas layer limits the effect of blending of its children layers to its own scope.
  • Inline Canvas is the name of the canvas parameter when it is not exported. Paste Canvas layer holds effectively one animation inside the main root document but can simply be understood like a layer’s scope limiter (that is the inline canvas).
  • Keyframes concept is a little more complex. See Keyframe
  • You can improve the document by adding links to the wiki pages so expand the user larning.
  • To allow this page to be added to the manual, it should be categorized. Please see any manual page and its header.

It is a good introduction anyway.
It could be much better with a little of rework.


Thanks for the feedback!
As far as I can tell, the word “canvas” has 2 separate but related meanings. It can refer to the Canvas Window as you describe or it can refer to a list of layers as described here. That definition is important for understanding Inline/Pasted canvases. An inline or pasted canvas is more than just a list of layers though. It can have it’s own start and end time, framerate, and image dimensions. This can be seen when using canvases as scenes as described in the Switching Scenes tutorial. If a canvas can be an entire scene, then I’d argue that it is closer to an animation than the paper on which it is drawn. That said, I don’t think “animation” is a perfect term either because it can also refer to the .sifz file or to the rendered movie.

The confusion I experienced surrounding the term canvas was one of the main reasons I wrote the page. I would have been much less confused when learning Synfig if the term canvas was only used to refer to the Canvas Window, and all other uses of the term canvas within the user interface and the documentation had been replaced with the term “animation” (or something similar). Assuming such a change of terminology is impractical, I thought it would be helpful to more clearly define the term upfront.

Can you be more specific? Where did it lose you?

I agree that my writing tends be rather dense (i.e. a lot of information in relatively few words, with little repetition). Is that what you mean by “heavy”? Or did you mean “too many big words” or something else? I can take a shot at breaking up some of the longer sentences, but I’m not sure what you mean by “without paragraphs”.

No need to apologize! I totally agree. Until it is at least correct I’ve added a warning at the top of the page concerning possible inaccuracies.

Thanks again for the feedback!

I’m not sure what you mean by that. When a layer has a blend method, it controls how that layer is blended with what was produced by (non-child) layers with higher Z order. Right? Did I say or imply something else?

Hmm… perhaps describing layers as a “list” of instructions seems backwards because the Layers Panel (by default) displays them with the first layer/instruction at the bottom and the last at the top. Is that it?

Understood. My hope was that by describing a paste canvas layer as “blending a frame from another animation into the current frame” it would be clear that any blending done to create the other animation could not effect the other layers in the current animation. This avoids needing to use jargon like “scope” which are clear to a developer like myself, but not necessarily to an artist. BTW, my understanding is that those “children layers” of a Paste Layer can be in a completely different .sifz file. Right?

Understood. The more I think about this, the more I think that we just shouldn’t use the terms Inline Canvas and Paste Canvas on this page. Perhaps it would be better to just say that there is a kind of layer that can blend in a frame from another animation and then describe the uses of such a layer (encapsulation, switching scenes, using animations in other files, etc). What do you think?

Yeah, I’d read that and was intentionally trying to hide all of that complexity. While keyframes are obviously a fundamental part of the animation editing process, they don’t seem to be a particularly important part of what a Synfig animation actually is and how a movie is generated from it. So for the purpose of creating a mental model of what is being edited, I think a more detailed description of keyframes isn’t necessary. I’m actually tempted to just remove all mention of keyframes from the page since nothing else on the page requires an understanding of the concept. Thoughts?

OK. I left such links off initially because I was concerned that the reader would get sidetracked and confused by not having read the rest of the page first. How about adding the links at the bottom of the page in some sort of “See also” section or “For more information…” paragraph?

Done. I haven’t actually added it to the Manual’s Table of Contents yet because it sounds like it still needs work. Let me know if/when you want it added.

BTW, what is your opinion on whether it is correct to to say that a Synfig animation description is called a canvas?

Thanks for all the feedback!

It’s not just the window, it’s the stage, the paper, the canvas. See it as the analogy canvas for a painting. It’s a defined workspace with or without artwork drawn on it. With it’s defined measures and borders.
The animation is the motion of your artwork which is displayed on top of your canvas. It is tightly intetgrated with the canvas but a separate concept.
Calling the animation canvas is like calling an illustration a pad of paper or a play a theatre stage.

Yes a sifz can be called an animation file meaning it contains your animation (on top of your canvas) and a rendered movie can be called an animation which is a shortening of animated film or movie. They are all closely related. Only if your not at all familiar with the concept of animation these different usage of the word might be confusing I think.

I agree that the terminology of Synfig can be a bit confusing sometimes and that an easy explanation is useful. Myself I was confused by Synfigs usage of keyframes and waypoints when I started using it as what Synfig called waypoints is what in many other applications is called kayframes. Keyframes in Synfig is used differently but goes back to original use of the work where it defines a key pose. In that analogy waypoints corresponds to what is usually called breakdown keys and inbetweens.

While it may be technically right to call a layer an instruction I think it is an odd way of describing them which is not used anywhere else in Synfigs help files or terminology.

How do you mean here? Do you have an example?

Again, while technically right I think talking about how blending composits every pixel on top of layers below is confusing new users. I think it would be sufficient to say layers is visible on top of layers lower than them in the stack.

I mean dense. Sorry if I was unclear.
Much information packed after each other. Ok, you do use paragraphs but I think you can use it a bit more. And use line breaks more. It will be easier to follow then I think. Now you read and read and get packed with new information with too few pauses for digestion and understanding of what you’ve read.
Also, as Genete pointed out, it would be useful with links to the manual and perhaps images.

Other aspects that can be explained a bit more is the timeline, parent/child-relations (layers only affects layers below them and layers at same level or below them in the hierarchy (left-right, parent layer is to the very left, children succedingly to the right. You might have noticed that for every paste canvas the layer names jumps a step to the right in the panel, indicating it is below its parent in the hieracrchy), how Synfig uses resolution in work canvas and export, vector artwork and raster images, etc.

Thank you for taking your time and try to explain these aspects of Synfig.

Does your definition of canvas have a time-varying aspect to it? In other words, is it a piece of paper or a flipbook? If it is a flipbook, I think I might have a way to address your concern. If I said something like “a flipbook is called a canvas”, would that work for you?

IMHO, the existing descriptions are helpful for getting started but break down or become confusing when dealing with more complicated layer combinations. Consider the case of a user who draws 2 stars and then adds a rotate layer and wonders why it doesn’t rotate the stars in-place. After all, the rotate layer should just rotate the layers under it, right? Recalling the idea of layers as instructions would help such a user figure out what was going on and find a fix.

Examples include all of the “non-filtering” layers (e.g. circle, rectangle, BLine, Paste Canvas). Strictly speaking, I haven’t looked at the code so I don’t know for certain that this is how these layers are implemented, but it would be a logical way to implement them. Regardless, it is an accurate mental model for what they do.

So, for example, a circle layer draws a circle on a new transparent image and then blends that image with the image resulting from the lower layers according to the blend method. The resulting image is then used by the next higher layer in the layer stack.

That works fine for the Composite blend method, less well for other blend methods, and is completely contradicted when using the Behind blend method. That said, I’ll try to change the page to describe the default Composite blend method before describing the more general case.


With the exception of parent/child layers, I don’t think those other topics really belong in an “Anatomy of a Synfig animation” page because I don’t see them as critical to understanding “what a Synfig animation is, the names of its various parts, and how the parts fit together”.

Thanks again for the feedback!

Yes, the canvas has a time aspect to it. The analogy with a paper is not just strictly flat 2D surface. I mean it’s the medium you have to apply your animation on.
The two concepts, canvas and animation is tightly connected in Synfig but calling one the other is wrong. It is two different concepts.
I think the editing you’ve done with an analogy to a flipbook is much better!

I still think calling layers instruction is confusing to the reader.
There are strictly speaking 2 kind of layers in Synfig, objects, like regions, outlines, stars, circles, gradients, etc., and modifiers like blurs, distortions, colour corrections etc.
Objects are plain visible image layers, I think it’s far stretched to call them instructions.
Modifiers could be called an instruction as it tells how to modify an image, but still I think it’s better not to.
Trying to group the two families of layers into a general “instruction” makes it abstract.
I think it’s better to say there are two kind of layers, object type layers and modifiers.

But please go on with refining your wiki page, clean it up a little and add links etc., I’m sure it will turn out great in the end.

Yes, continuing insisting with layer as instruction is not a good idea.
I would reformulate like this:

Synfig is organized in sif files which are called “document” or simply animation source file in the wiki.
In each Synfig document must be at last one canvas (called root canvas).
One canvas is defined by the dimensions of the default output result (x,y resolutions), the default frequency for sample the contents of the canvas when rendered to the actual animation (the frames per seconds), the animation duration(start and end times), more other parameters, and a stack of layers that are combined on the canvas to produce the output results.
There are two types of layers: Primitives and Filters. Primitives produce content based on its own parameters. Filters produce content based on its own parameters and on the context of the layer.
The context of a layer is the render result of the layers that are stacked behind it.
There is one special kind of layers that is called Paste Canvas layer. It is one “folder like” layer that holds a canvas on it. That canvas can be: one external canvas (the root canvas of an external document), one internal separated canvas (one stored canvas in the synfig document that can be used several times but in different places in the same document, we call it exported canvas), one exported canvas form one outer synfig document, or even one “inline canvas” (one canvas in line) that takes the default definitions (dimensions, fps, etc.) inherited from its parent canvas (it can be any of the previous). We call children layers all the layers inside a Paste Canvas Layer.
The Context of a layer is defined by the canvas where it lives. It is the render result of layers that are behind it. If the layer is in a Paste Canvas layer, its context is the layers behind it until the last children layer.
Treated as a layer, a paste canvas is like a “super layer” which its render result is the resulting of the layer stack it holds. So as a layer, it has parameters that affects how the result is produced (i.e. the amount parameter defines the transparency of the layer).
One layer is per se, static, so when you create one new layer it is the same for all the canvas duration. One layer can be animated by the animation of its parameters. When a parameter is animated it has associated a list of ‘waypoitns’ that is the definition of the parameter value at a certain time. The values of the parameters where there isn’t any waypoint is defined by the interpolation between two waypoints, made automatically by Synfig.
Most of the layers is one special parameter called blend method. The blend method defines how is one layer combined with its context. Normally layers are combined simply composted to its context but there are more possible values of the blend method that allow to do special kind of effects (masks, shading, etc.)
So for a certain time, the render result of a sif file is based on the root canvas dimensions, the frame rate and the result combination of the layers the root canvas holds based on the interpolation value of its parameters at that time.

OK, thanks. I’ve replaced the page with a word-smithed version of Genete’s reply.

Unfortunately, my own mental model is so ingrained at this point that it is hard for me to tell how much reading the page would have helped me. It is certainly much better than nothing at all though, and it is definitely a better fit to the style and terminology of the rest of the manual.

I have to move on to other projects at this point, so I’m afraid others will need to make further improvements. Thank you for your patience and your feedback.


Thank you Dean for taking your time to do this page!
And I’m sorry if you feel we’ve been to harsch with you but we like to see all documentation accurate.

While it’s never easy to accept criticism, I don’t feel that the feedback I received was too harsh or unreasonable.

No hard feelings. Honest. I just have other things that I need to work on.

All the best,

i’m also new on synfig and glad you were working on this, thanks a lot, i didn’t learn much from it, but think it was a place to solidify my recent understanding of synfig… links to other pages could be very useful…

for example, i still didn’t quite get the different types of canvas anyway and this page ( dosen’t help much…