API

=== FreeJ API

In this document i try to summarize the internal organization of FreeJ API
how things are distributed and which functions are more useful to operate.


   | This document is quite short, but technical.
   | If you just want to use FreeJ, you don't need to read it at all.


right now there is a tree organization, here i try to represent it:

                               
Screen---(Blit)______________Layer_____Effect 
      \   vvvv                    \____Effect 
       \-(Blit)____Layer__Effect   \___Effect
        \ vvvv         \__Effect        ...
         (Blit)__Layer  \_Effect
		         \Effect
                           ...

the Context is holding the list of layers, cycling thru them during
FreeJ's execution.

each Layer holds the list of active Filters.

each Filter is a plugin loaded and served by the Plugger.

the Blit Chain consists of blit operations to sum Layers to the
Context.


see how i'm using the API to this engine in freej.cpp

To create Layers providing a filename using javascript:
  Layer foolay = create_layer("path/to/file");
  add_layer(foolay);

then you init your new layer
  if(foolay) {
    foolay->init(&freej); // <- you pass a pointer to freej env
    freej.layers->add(foolay); // and then you add it to the chain
  }


=== Implement a new Layer?

If you are implementing a new Layer you need to implement just a few
methods, the most is inherited from a parent class:

MyLayer inherits the class Layer and implements the following:

 bool open(char *file) /* called to open MyLayer's source
                          returns false if is not accessible */

 bool init(Context *scr) /* if the open was succesful, call this
                            and the Layer will enter the chain */

 bool feed() /* this function is executed by the Context when
                it needs to grab more data in the Layer */

 bool close() /* you need to call this when you want to close
                 the Layer, in case you *initialized* it */
 
If you are implementing a new Layer, you don't need to care about
threading or synchronizing the execution: just be sure to correctly
free all the buffers you malloc ;)
also compile --with-dmalloc to use a good memory fencing library