Synfig File format
m (Better headings) |
m (sfg grammar & rephrase) |
||
(14 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
− | A .sif file is the XML representation of a {{L|Canvas|canvas}}. | + | <!-- Page info --> |
− | It holds the canvas's metadata, such as width and height, as well as information about its {{L|Layer|layers}}. | + | {{Title|Synfig File format}} |
+ | {{NewTerminology}} | ||
+ | {{TOCright}} | ||
+ | <!-- Page info end --> | ||
+ | A {{literal|.sif}} file is the [https://en.wikipedia.org/wiki/XML XML] representation of a {{L|Canvas|canvas}}. | ||
+ | It holds the canvas's {{l|Canvas_MetaData_Panel|metadata}}, such as width and height, as well as information about its {{L|Layer|layers}}. | ||
Typically, a Synfig production comprises many .sif files joined in a sequence or nested within each other. | Typically, a Synfig production comprises many .sif files joined in a sequence or nested within each other. | ||
Line 13: | Line 18: | ||
https://github.com/synfig/synfig/blob/master/synfig-core/src/synfig/loadcanvas.cpp | https://github.com/synfig/synfig/blob/master/synfig-core/src/synfig/loadcanvas.cpp | ||
− | == | + | == Concepts == |
− | === | + | === Linking / Exporting === |
.sif files aren't always self-contained. | .sif files aren't always self-contained. | ||
− | They can | + | They can link to parts of other .sif files, which creates a dependency of one on the other. |
− | This may seem strange to animators who use Flash because, in Flash, | + | This may seem strange to animators who use Flash because, in Flash, animation files are usually self-contained. |
− | One drawback of Synfig's approach is that .sif dependencies | + | One drawback of Synfig's approach is that .sif dependencies are hard to track. |
A tool called [https://github.com/morevnaproject/RenderChan RenderChan] solves this problem. | A tool called [https://github.com/morevnaproject/RenderChan RenderChan] solves this problem. | ||
+ | |||
+ | === Recursion === | ||
Recursion of .sif files is prohibited. | Recursion of .sif files is prohibited. | ||
− | === | + | === Compression === |
− | Synfig recognizes .sifz as the extension of gzip-compressed .sif files. | + | Synfig recognizes {{literal|.sifz}} as the extension of gzip-compressed .sif files. |
New and alternate implementations of .sif are urged to support this compression, although it is not required. | New and alternate implementations of .sif are urged to support this compression, although it is not required. | ||
− | + | Synfig recognizes the {{literal|.sfg}} file format as an archival file format. A .sfg is a ZIP archive that bundles a .sif and its resources together. In Synfig Studio, images and sounds can be packed using {{l|Import_Image_Layer}} or {{l|Sound Layer}}. | |
− | + | == <canvas> == | |
+ | |||
+ | === Overview === | ||
The top element of a .sif file is always a <canvas>. | The top element of a .sif file is always a <canvas>. | ||
Line 39: | Line 48: | ||
<pre> | <pre> | ||
<?xml version="1.0"?> | <?xml version="1.0"?> | ||
+ | |||
<canvas version="0.1" width="300" height="350" xres="2952.7559" | <canvas version="0.1" width="300" height="350" xres="2952.7559" | ||
yres="2952.7559" view-box="-1.5 2.5 1.5 -1" antialias="2" | yres="2952.7559" view-box="-1.5 2.5 1.5 -1" antialias="2" | ||
Line 47: | Line 57: | ||
{|border="1" cellpadding="5" cellspacing="0" | {|border="1" cellpadding="5" cellspacing="0" | ||
− | |'''Attribute'''||'''Default'''||''' | + | |'''Attribute'''||'''Default'''||'''What it is''' |
|- | |- | ||
|version||'''no default''', this attribute is required||0.1, always | |version||'''no default''', this attribute is required||0.1, always | ||
|- | |- | ||
− | |width||[https://github.com/synfig/synfig/blob/master/synfig-core/src/synfig/renddesc.h#L130 | + | |width||[https://github.com/synfig/synfig/blob/master/synfig-core/src/synfig/renddesc.h#L130 480]||the width of the canvas in pixels |
|- | |- | ||
− | |height||[https://github.com/synfig/synfig/blob/master/synfig-core/src/synfig/renddesc.h#L131 | + | |height||[https://github.com/synfig/synfig/blob/master/synfig-core/src/synfig/renddesc.h#L131 270]||the height of the canvas in pixels |
|- | |- | ||
|xres||[https://github.com/synfig/synfig/blob/master/synfig-core/src/synfig/renddesc.h#L132 2835]||the width of the canvas in pixels per meter | |xres||[https://github.com/synfig/synfig/blob/master/synfig-core/src/synfig/renddesc.h#L132 2835]||the width of the canvas in pixels per meter | ||
Line 70: | Line 80: | ||
|- | |- | ||
|bgcolor||[https://github.com/synfig/synfig/blob/master/synfig-core/src/synfig/renddesc.h#L138 0.5 0.5 0.5 1.0]||the color of the background in RGBA | |bgcolor||[https://github.com/synfig/synfig/blob/master/synfig-core/src/synfig/renddesc.h#L138 0.5 0.5 0.5 1.0]||the color of the background in RGBA | ||
+ | |- | ||
+ | |focus||[https://github.com/synfig/synfig/blob/master/synfig-core/src/synfig/renddesc.h#L136 0 0]||the anchor point for changing the view-box | ||
|} | |} | ||
− | |||
− | |||
Inside a <canvas> you can find the following elements: | Inside a <canvas> you can find the following elements: | ||
− | |||
− | |||
* <name> | * <name> | ||
− | * < | + | * <meta> |
* <author> | * <author> | ||
+ | * <desc> | ||
* <layer> | * <layer> | ||
+ | * <defs> | ||
* <bones> | * <bones> | ||
* <keyframe> | * <keyframe> | ||
+ | |||
+ | === <name> === | ||
+ | |||
+ | The short name of the canvas. | ||
+ | |||
+ | <pre> | ||
+ | <canvas version="0.1"> | ||
+ | ... | ||
+ | <name>Aqua Sphere</name> | ||
+ | ... | ||
+ | </canvas> | ||
+ | </pre> | ||
+ | |||
+ | === <meta> === | ||
+ | |||
+ | Metadata for the Synfig Studio editor. | ||
+ | These can be safely ignored by other implementations. | ||
+ | |||
+ | <pre> | ||
+ | <canvas version="0.1"> | ||
+ | ... | ||
+ | <meta name="grid_show" content="1" /> | ||
+ | ... | ||
+ | </canvas> | ||
+ | </pre> | ||
+ | |||
+ | Synfig Studio recognizes these <meta> names ([https://github.com/synfig/synfig/blob/master/synfig-studio/src/gui/workarea.cpp#L881 source]): | ||
+ | |||
+ | * grid_size | ||
+ | * grid_color | ||
+ | * grid_snap | ||
+ | * grid_show | ||
+ | * onion_skin | ||
+ | * onion_skin_past | ||
+ | * onion_skin_future | ||
+ | * guide_color | ||
+ | * guide_snap | ||
+ | * guide_show | ||
+ | * guide_x | ||
+ | * guide_y | ||
+ | * sketch | ||
+ | * solid_lines | ||
+ | * background_size | ||
+ | * background_first_color | ||
+ | * background_second_color | ||
+ | |||
+ | === <author> === | ||
+ | |||
+ | The name of the canvas's author. | ||
+ | |||
+ | <pre> | ||
+ | <canvas version="0.1"> | ||
+ | ... | ||
+ | <author>King Arthur</author> | ||
+ | ... | ||
+ | </canvas> | ||
+ | </pre> | ||
+ | |||
+ | === <desc> === | ||
+ | |||
+ | A human-readable description of the canvas. | ||
+ | |||
+ | <pre> | ||
+ | <canvas version="0.1"> | ||
+ | ... | ||
+ | <desc>This aqua-colored sphere reminds me of something from Mac OS X.</desc> | ||
+ | ... | ||
+ | </canvas> | ||
+ | </pre> | ||
+ | |||
+ | === <layer> === | ||
+ | |||
+ | ==== Overview ==== | ||
+ | |||
+ | Layers describe the shapes and effects on a canvas. | ||
+ | |||
+ | <pre> | ||
+ | <canvas version="0.1"> | ||
+ | ... | ||
+ | <layer type="solid_color" version="0.1" | ||
+ | ... | ||
+ | </canvas> | ||
+ | </pre> | ||
+ | |||
+ | {|border="1" cellpadding="5" cellspacing="0" | ||
+ | |'''Attribute'''||'''Default'''||'''What it is''' | ||
+ | |- | ||
+ | |type||'''no default'''||see the list of types | ||
+ | |- | ||
+ | |version||'''no default'''||depends on the layer type | ||
+ | |- | ||
+ | |group||||the name of the group that this layer belongs to | ||
+ | |- | ||
+ | |desc||||a human-readable description | ||
+ | |- | ||
+ | |active||true||whether the layer is selected (?) | ||
+ | |- | ||
+ | |exclude_from_rendering||false||whether it should be rendered | ||
+ | |} |
Latest revision as of 00:14, 11 February 2016
A ".sif" file is the XML representation of a canvas. It holds the canvas's metadata, such as width and height, as well as information about its layers. Typically, a Synfig production comprises many .sif files joined in a sequence or nested within each other.
The .sif format is formidably complex and evolving. It is implementation-defined rather than spec-defined. Therefore, you should take everything on this page with a grain of salt. Indeed, the implementation can change at any point.
There are no plans to freeze the format.
Source code
The .sif format is implemented by the following file:
https://github.com/synfig/synfig/blob/master/synfig-core/src/synfig/loadcanvas.cpp
Concepts
Linking / Exporting
.sif files aren't always self-contained. They can link to parts of other .sif files, which creates a dependency of one on the other. This may seem strange to animators who use Flash because, in Flash, animation files are usually self-contained.
One drawback of Synfig's approach is that .sif dependencies are hard to track. A tool called RenderChan solves this problem.
Recursion
Recursion of .sif files is prohibited.
Compression
Synfig recognizes ".sifz" as the extension of gzip-compressed .sif files. New and alternate implementations of .sif are urged to support this compression, although it is not required.
Synfig recognizes the ".sfg" file format as an archival file format. A .sfg is a ZIP archive that bundles a .sif and its resources together. In Synfig Studio, images and sounds can be packed using Import Image Layer or Sound Layer.
<canvas>
Overview
The top element of a .sif file is always a <canvas>.
<?xml version="1.0"?> <canvas version="0.1" width="300" height="350" xres="2952.7559" yres="2952.7559" view-box="-1.5 2.5 1.5 -1" antialias="2" fps="12" begin-time="0f" end-time="0f" bgcolor="0.5 0.5 0.5 1"> ... </canvas>
Attribute | Default | What it is |
version | no default, this attribute is required | 0.1, always |
width | 480 | the width of the canvas in pixels |
height | 270 | the height of the canvas in pixels |
xres | 2835 | the width of the canvas in pixels per meter |
yres | 2835 | the height of the canvas in pixels per meter |
view-box | -4 2.25 4 -2.25 | the bounding coordinates of the canvas (left top right bottom) |
antialias | 2 | how hard Synfig should try to antialias the image |
fps | 24 | frames per second |
begin-time | 0 | where on the timetrack should rendering start |
end-time | 0 | what on the timetrack should rendering end |
bgcolor | 0.5 0.5 0.5 1.0 | the color of the background in RGBA |
focus | 0 0 | the anchor point for changing the view-box |
Inside a <canvas> you can find the following elements:
- <name>
- <meta>
- <author>
- <desc>
- <layer>
- <defs>
- <bones>
- <keyframe>
<name>
The short name of the canvas.
<canvas version="0.1"> ... <name>Aqua Sphere</name> ... </canvas>
<meta>
Metadata for the Synfig Studio editor. These can be safely ignored by other implementations.
<canvas version="0.1"> ... <meta name="grid_show" content="1" /> ... </canvas>
Synfig Studio recognizes these <meta> names (source):
- grid_size
- grid_color
- grid_snap
- grid_show
- onion_skin
- onion_skin_past
- onion_skin_future
- guide_color
- guide_snap
- guide_show
- guide_x
- guide_y
- sketch
- solid_lines
- background_size
- background_first_color
- background_second_color
<author>
The name of the canvas's author.
<canvas version="0.1"> ... <author>King Arthur</author> ... </canvas>
<desc>
A human-readable description of the canvas.
<canvas version="0.1"> ... <desc>This aqua-colored sphere reminds me of something from Mac OS X.</desc> ... </canvas>
<layer>
Overview
Layers describe the shapes and effects on a canvas.
<canvas version="0.1"> ... <layer type="solid_color" version="0.1" ... </canvas>
Attribute | Default | What it is |
type | no default | see the list of types |
version | no default | depends on the layer type |
group | the name of the group that this layer belongs to | |
desc | a human-readable description | |
active | true | whether the layer is selected (?) |
exclude_from_rendering | false | whether it should be rendered |