.. _format:

.. index::
   pair: file; format

File Format
===========

.. highlight:: scheme

This section describes the format used by XaoS for animations, configuration
files and saved positions. All these files have a common format, designed to be
easily readable, to allow manual editing of files and easy conversion by other
programs.

I also taken care to make it easily extensible for future versions of XaoS so I
hope there will not be many incompatibilities between various XaoS versions.

The format is a simple set of commands executed sequentially. XaoS does not
provide any variables/cycles as usual scripting languages do, but future
extension to full-blown Scheme should be easy since the format uses Scheme-like
syntax. The syntax of every command is::

	(command_name [param1] [param2])

where parameters are optional and separated by whitespace (an arbitrary number
of spaces, tabs and newlines). The parameters can have the following types:

integer
    number w/o decimal point (123)

float
    floating point number in decimal notation with optional exponent (1.23E2)

keyword
    text started by quote '. It is used to pass various string constants like
    formula name ('mandel) Quote is required for scheme compatibility

string
    Text inside double quotes. The only parameter that should contain
    whitespace

boolean
    #t for true or #f for false

There is a complete description of all XaoS functions (with some examples) and
an index of functions in the :ref:`XaoS registry <menus>`. You may particularly want to
read about the :ref:`animation functions <animf>`. Also, the following functions are
significant:

load
    This function loads and interprets a file. It works similarly to #include
    in C.

initstate
    Available in version 3.0 and above, this function resets XaoS's state to
    default values. This command should be at the beginning of each animation
    file, since otherwise some stuff previously enabled by user could cause
    unexpected effects. State is not reset by default before playing animations
    since it would make it impossible to write macros. Current versions don't
    really need macros, but in future versions, when the Scheme programming
    language will be available, this should be a much more interesting subject.

usleep
    This function waits for a selected amount of time(in usec) before
    processing the next command. The screen is recalculated and displayed at
    the beginning of the sleep if necessary. The remaining time is spent by
    waiting, calculating if necessary, or performing any animation you entered
    via animation commands.

wait
    Waits until the animation or image rendering is complete. Do not call this
    function when zoom, or continuous rotation is active otherwise deadlock
    happens. It is a good idea to call it immediately before text subtitles are
    displayed, since it looks ugly when they are displayed over a blocky
    unfinished fractal. Because the degree of blockiness at a given instant is
    a function of your machine speed, it may look nice for you but ugly for
    others with slower machines. Also you should call this after an animation
    is performed, before the switch to another fractal happens; since the
    switch involves calculation, the screen is stopped for a while and an
    unfinished fractal there looks ugly. You should also call it, when you want
    to do something as soon as possible.

Example::

	;configure everything for the first frame
	(inistate)
	(palette 1 1163254293 0) ;custom palette
	(cycling #t) ;enable cycling
	(cyclingspeed 7)
	(maxiter 276) ;higher number of iterations
	(range 3) ;default range for solid guessing
	(usleep 1000000) ;second frame starts here
	(moveview -1.8101154154614007889 -8.2687205907162041209E-05)
	;just move the image
	(usleep 1000000) ;third frame
	(morphview -1.8101154154614007889 -8.2687205907162041209E-05
	6.277210971069452361E-10 6.2772109785334669875E-10)
	;10 seconds of zooming into selected
	rectangle
	(usleep 100000000)

The best way to learn XaoS command language is probably to read position files
and modify them. For example, to create zooming animation from the original
file::

	(initstate)
	(defaultpalette 0)
	(formula 'mandel)
	(view -1.64128273713 -5.50393226816E-05 9.69332308848E-08 9.69332308834E-08)

Just change the view command to morphview, and add usleep::

	(initstate)
	(defaultpalette 0)
	(formula 'mandel)
	(morphview -1.64128273713 -5.50393226816E-05 9.69332308848E-08 9.69332308834E-08)
	(usleep 10000000)

The following code produces Julia morphing in the real axis::

	(initstate)
	(fastjulia #t)
	(juliaseed -2 0)
	(morphjulia 2 0)
	(usleep 2000000)

And following is the "rotozooming" animation::

	(initstate)
	(fastrotate #t)
	(morphview -1.64128273713 -5.50393226816E-05 9.69332308848E-08 9.69332308834E-08)
	(morphangle 300)
	(usleep 10000000)
	(wait)
	(fastrotate #f)