FREEJ SCRIPT INTRODUCTION

$Id: freej_scripting.txt 255 2004-11-26 17:44:42Z jaromil $

FreeJ is an asynchronous video rendering engine, it can be scripted
using javascript syntax in an object oriented way, to control its
operations thru a procedural list of commands and actions.

This way we can start talking about "procedural video" as an evolution
of the current non/linear paradigm widely spread in video production.

Far from starting with such an high theoretical approach, this document
aims to be a small and effective introduction to the first free software
implementation of such a powerful functionality.
It will not cover the programming syntax, but simply describe the
objects that are made available to script FreeJ.
Knowledge of generic object oriented programming syntax is suggested but
not strictly necessary to make the first steps in the wonderful world of
Procedural Video Scripting.

Now let's get started!

FreeJ scripting is completely object oriented, meaning that almost every
operation is provided by objects that can be created: there are no global
functions, but commands that are strictly related to a certain object.

Layers and Effects are the object classes we can deal with. Once they
exist, they will provide methods to control their operations.

 EXAMPLE:

my_text_layer = new TxtLayer();      // create an new TxtLayer object (1)

add_layer(my_text_layer);            // make the new layer shown (2)

my_text_layer.print("hello world!"); // print a message on the layer (3) 

In this example (1) we first create a new instance of the TxtLayer() class,
which provides the Truetype rendering text layer; (2) then we add it to
the list of layers processed by the engine; (3) at last we use the print()
specific method to print something on the screen.

Now try your first script by writing the three lines above in a file and
then execute the file with 'freej -j myfile'

there you are?

then consider in *NIX systems you can use the interpreter header
#!/usr/local/bin/freej -j
at the beginning of your script, then by making it executable you'll have
a self executing freej script!

Generic and Specific methods:

Every layer class inherits methods from the Layer superclass, providing
generic methods common to all of them.
Generic methods are available to change Layer attributes like: position,
blit method, rotation, zoom, spin etc.

Specific methods are found only on their layer, they can control special
operations that a specific layer provides, like: printing a word on the
text layer, appending a line to the scroll layer, skipping to a keyframe
in a movie layer, etc.

Here we go with a reference of all the methods made available by FreeJ:

 GENERIC METHODS common to all layers
 
Layer.set_position(int x, int y) // coords of the upper left corner
     .set_blit("name") // must be an existing layer
     .set_blit_val(int val) // usually a value between 0 and 255
     .rotate(double val) // usually between 0 and 360
     .zoom(double x, double y) // floating point multiplier,
                              // 1.0 means no zoom, 2.0 means double size
     .spin(double rotation, double zoom) // the layer will start rotating
                                         // and/or zooming (0 means stop)

 SPECIFIC LAYER TYPES:
new CamLayer("/dev/video")
new TextLayer("poetry.txt") (*)
new MovieLayer("movie.avi")
new ImageLayer("photo.png")
new VScrollLayer("book.txt") (*)
new ParticleLayer() // doesn't need a file

(*) = the filename can be also omitted, the layer is then used with
      its own methods to feed the data to be processed.
      i.e. TxtLayer.print("string") or VScrollLayer.append("phrase")


the constructor initialization consists of an open() on the file
and it can return NULL in case of failure.
In case the object returned is not NULL, it can be initialized using
the init() call.

...to be continued...

see the script example in doc/freejscript-example.js