summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJaromil <jaromil@dyne.org>2009-06-09 20:58:06 (GMT)
committer Jaromil <jaromil@dyne.org>2009-06-09 20:58:37 (GMT)
commit362c376136bb8c3268170eb46805e763c4beb4da (patch)
tree51e7ecdcb5d81ad57b33cf5662c4880d7cfae2fc
parentefcfcbb5882a11d2956e972839b3d9245e76e520 (diff)
updates to the install section and the python scripts
debugged to work smoothly with what we have so far
-rw-r--r--freej/EN/examples.sgml49
-rw-r--r--freej/EN/install.sgml323
-rw-r--r--freej/EN/intro.sgml4
-rw-r--r--freej/EN/python_intro.sgml23
-rw-r--r--freej/python/controller.src33
-rw-r--r--freej/python/helloworld.src28
-rw-r--r--freej/python/playeffect.src18
7 files changed, 408 insertions, 70 deletions
diff --git a/freej/EN/examples.sgml b/freej/EN/examples.sgml
index 0eb8c5b..0191d63 100644
--- a/freej/EN/examples.sgml
+++ b/freej/EN/examples.sgml
@@ -1,7 +1,37 @@
+<section>
+<title>Hello World</title>
+
+<indexterm><primary>TextLayer</primary></indexterm>
+
+<para>
+Here below the classical "Hello World" script that simply opens up a
+FreeJ output window and a Text Layer, writing into it,
+</para>
+
+%helloworld
+
+<para>
+After initialisation of <emphasis>cx</emphasis> as a FreeJ context
+a <emphasis>TextLayer</emphasis> is initialised and added to
+it. Please note the sequence for creating the layer is fixed: first
+the constructor, then <emphasis>init()</emphasis> is called passing
+the context as an argument, some text is written into it using
+the <emphasis>write()</emphasis> method, the layer is then started and
+added to the context.
+</para>
+</section>
<section>
<title>Play and apply an effect</title>
+<indexterm><primary>Plugger</primary></indexterm>
+<indexterm><primary>Filters</primary></indexterm>
+
+<para>
+The following script should be run with an argument: an image or video
+file that will be reproduced with a filter effect applied on it.
+</para>
+
%playeffect
<para>
@@ -34,6 +64,9 @@ capabilities. There are many possibilities out there ;^)
<section>
<title>Controllers</title>
+<indexterm><primary>Controller</primary></indexterm>
+<indexterm><primary>TriggerController</primary></indexterm>
+
<para>
Controllers in FreeJ are listeners which will dispatch asynchronous
messages from input channels, that is for example a keyboard that will
@@ -47,25 +80,25 @@ controller.
<para>
Here below an example of this use with the most basic controller: the
-<emphasis>TriggerCtrl</emphasis>, once created and registered, will
-call dispatch() every time a frame is processed:
+<emphasis>TriggerController</emphasis>, once created and registered,
+will call dispatch() every time a frame is processed:
</para>
%controller
<para>
It initializes a new FreeJ instance as usual, then declares the new
-class <emphasis>Frame</emphasis> overloading the TriggerCtrl. With
-this new class we overload the <emphasis>dispatch</emphasis> function
-to print out some output every time is called, that is every
+class <emphasis>Frame</emphasis> overloading the TriggerController.
+With this new class we overload the <emphasis>dispatch</emphasis>
+function to print out some output every time is called, that is every
frame.
</para>
<para>
At last the script creates an instance of the new Frame class
-(inheriting all methods from TriggerCtrl) registers it to be called by
-the engine with the <emphasis>register_controller()</emphasis> method
-in the Context.
+(inheriting all methods from TriggerController) registers it to be
+called by the engine with
+the <emphasis>register_controller()</emphasis> method in the Context.
</para>
<para>
diff --git a/freej/EN/install.sgml b/freej/EN/install.sgml
index 5e3a9f4..5d699d1 100644
--- a/freej/EN/install.sgml
+++ b/freej/EN/install.sgml
@@ -1,16 +1,78 @@
<chapter>
<title>Install</title>
+<section>
+<title>Distributed packages</title>
+
+<para>
+FreeJ packages are available on mainstream GNU/Linux distributions as
+Debian, Ubuntu and Fedora, successfully compiled for x86, 64bit, MIPS,
+PPC and even more hardware platforms: to install them you can use your
+favorite software manager like Synaptic or apt-get, something like
+"<emphasis>apt-get install freej</emphasis>" will work.
+</para>
+
+<para>
+FreeJ is made out of multiple components, basically consisting of a
+library, one or more application interfaces and one or more language
+bindings. At the time of this publication the following packages are
+commonly found:
+
+<itemizedlist>
+
+<listitem><para>
+<emphasis>freej</emphasis> main command-line interface (CLI)
+</para></listitem>
+
+<listitem><para>
+<emphasis>freej-dbg</emphasis> CLI debugging symbols
+</para></listitem>
+
+<listitem><para>
+<emphasis>freej-doc</emphasis> documentation and examples
+</para></listitem>
+
+<listitem><para>
+<emphasis>libfreej0</emphasis> run-time library
+</para></listitem>
+
+<listitem><para>
+<emphasis>libfreej-dev</emphasis> development headers
+</para></listitem>
+
+<listitem><para>
+<emphasis>libfreej0-dbg</emphasis> library debugging symbols
+</para></listitem>
+
+<listitem><para>
+<emphasis>python-freej</emphasis> python language bindings
+</para></listitem>
+
+<listitem><para>
+<emphasis>python-freej-dbg</emphasis> python debugging symbols
+</para></listitem>
+
+</itemizedlist>
+
+</para>
+
+</section>
<section>
-<title>Download the source</title>
+<title>Compile from source</title>
<para>
Stable sources for FreeJ are regularly published
on <ulink url="ftp://ftp.dyne.org/freej/releases">ftp.dyne.org</ulink>
-server and its mirrors. You can use stable releases in case you want
-to employ this software in a production environment, although some
-newest features and fixes will be missing.
+server and its mirrors.
+
+<screen>
+ <userinput>ftp://ftp.dyne.org/freej/releases</userinput>
+</screen>
+
+You can use stable releases in case you want to employ this software
+in a production environment, although some newest features and fixes
+will be missing.
</para>
<para>
@@ -29,8 +91,8 @@ system, then run from a terminal:
This will download all the revisioned source repository on your
harddisk, with an occupation lower than 50MB, which you can later
-update running the command 'git pull' from inside the directory
-created.
+update running the command 'git pull --rebase' from inside the
+directory created.
</para>
<para>
@@ -41,21 +103,19 @@ to our way to interact by
the <ulink url="http://lab.dyne.org/Code">Developer's Lounge</ulink>.
</para>
-</section>
+
<section>
-<title>Compile the source</title>
+<title>Dependencies</title>
<para>
To compile FreeJ source code you will need to fulfill a minimum set of
dependencies, while optionally you can link a range of libraries for
extended functionality as video playback, encoding and streaming.
-FreeJ code has been tested to compile on x86 (little-endian), PPC
-(big-endian) and ARM (embedded) architectures.
</para>
<para>
-Minimum requirements:
+The Minimum requirements are:
<indexterm><primary>GCC</primary></indexterm>
<indexterm><primary>SDL</primary></indexterm>
@@ -64,45 +124,226 @@ Minimum requirements:
<member>A sane GNU C++ compiler toolchain</member>
<member>SDL libraries for visualization</member>
</simplelist>
+
+</para>
+
+<para>
+Having just those the source code can be tweaked to compile into a
+minimal version of FreeJ, still missing many features.
</para>
<para>
-Optional extensions:
+The recommended components are:
-<indexterm><primary>SDL</primary></indexterm>
<indexterm><primary>FFmpeg</primary></indexterm>
<indexterm><primary>Swig</primary></indexterm>
<indexterm><primary>Ogg</primary></indexterm>
<indexterm><primary>Vorbis</primary></indexterm>
+<indexterm><primary>Theora</primary></indexterm>
-<simplelist>
- <member>FFmpeg libraries for video playback</member>
- <member>Ogg/Theora/Vorbis libraries for video encoding and streaming</member>
- <member>Swig code wrapper for language bindings</member>
- <member>Python and/or Ruby to use the language bindings</member>
-</simplelist>
+<itemizedlist>
+ <listitem><para><emphasis>FFmpeg</emphasis> libraries for video playback</para></listitem>
+ <listitem><para><emphasis>Ogg/Theora/Vorbis</emphasis> libraries for video encoding and streaming</para></listitem>
+ <listitem><para><emphasis>XUL-runner</emphasis> libraries for a recent javascript interpreter</para></listitem>
+ <listitem><para><emphasis>Jack and FFTW3</emphasis> for audio analysis and parametrization</para></listitem>
+ <listitem><para><emphasis>Swig</emphasis> code wrapper for language bindings</para></listitem>
+ <listitem><para><emphasis>Python</emphasis> (and ipython console) for the language bindings</para></listitem>
+ <listitem><para><emphasis>OpenGL</emphasis> libraries for video output in 3d context</para></listitem>
+</itemizedlist>
+
+</para>
+<para>
In case your building system is a GNU/Linux distribution, then make
-sure you have installed the corresponding -dev packages for the
-aforementioned components.
+sure you have installed the corresponding -dev packages.
+</para>
+
+</section>
+
+
+<section>
+<title>Build on GNU/Linux</title>
+
+<para>
+Once having attained the source code of FreeJ we can proceed to its
+compilation, but first make sure all necessary development packages
+area available, on Debian and Ubuntu operating systems those are:
+
+<itemizedlist>
+
+<listitem><para>
+<emphasis>pkg-config</emphasis> manage compile and link flags for libraries
+</para></listitem>
+
+<listitem><para>
+<emphasis>flex</emphasis> a fast lexical analyzer generator.
+</para></listitem>
+
+<listitem><para>
+<emphasis>bison</emphasis> a parser generator that is compatible with YACC
+</para></listitem>
+
+<listitem><para>
+<emphasis>libsdl-dev</emphasis> Simple Direct Media layer package
+</para></listitem>
+
+<listitem><para>
+<emphasis>libpng-dev</emphasis> Portable Network Graphics package
+</para></listitem>
+
+<listitem><para>
+<emphasis>libjpeg-dev</emphasis> Jpeg image development package
+</para></listitem>
+
+<listitem><para>
+<emphasis>libfreetype6-dev</emphasis> FreeType 2 font engine
+</para></listitem>
+
+<listitem><para>
+<emphasis>libfontconfig-dev</emphasis> font configuration package
+</para></listitem>
+
+<listitem><para>
+<emphasis>libogg-dev</emphasis> Ogg Bitstream Library Development
+</para></listitem>
+
+<listitem><para>
+<emphasis>libvorbis-dev</emphasis> The Vorbis General Audio Compression Codec
+</para></listitem>
+
+<listitem><para>
+<emphasis>libtheora-dev</emphasis> The Theora Video Compression Codec
+</para></listitem>
+
+<listitem><para>
+<emphasis>libslang2-dev</emphasis> The S-Lang programming library
+</para></listitem>
+
+<listitem><para>
+<emphasis>libavcodec-dev</emphasis> FFMpeg development files for libavcodec
+</para></listitem>
+
+<listitem><para>
+<emphasis>libavformat-dev</emphasis> FFMpeg development files for libavformat
+</para></listitem>
+
+<listitem><para>
+<emphasis>libswscale-dev</emphasis> FFMpeg development files for libswscale
+</para></listitem>
+
+<listitem><para>
+<emphasis>libunicap2-dev</emphasis> unified interface to video capture devices
+</para></listitem>
+
+<listitem><para>
+<emphasis>libbluetooth-dev</emphasis> BlueZ Linux Bluetooth library
+</para></listitem>
+
+<listitem><para>
+<emphasis>fftw3-dev</emphasis> Fast Fourier Transform library
+</para></listitem>
+
+<listitem><para>
+<emphasis>libjack-dev</emphasis> JACK Audio Connection Kit
+</para></listitem>
+
+<listitem><para>
+<emphasis>libasound-dev</emphasis> Alsa sound libraries
+</para></listitem>
+
+<listitem><para>
+<emphasis>libmozjs-dev</emphasis> Mozilla SpiderMonkey JavaScript library
+</para></listitem>
+
+<listitem><para>
+<emphasis>xulrunner-dev</emphasis> Gecko engine library
+</para></listitem>
+
+<listitem><para>
+<emphasis>python-all-dev</emphasis> Python development packages
+</para></listitem>
+
+<listitem><para>
+<emphasis>python-central</emphasis> register and build utility for Python packages
+</para></listitem>
+
+<listitem><para>
+<emphasis>swig</emphasis> Generate scripting interfaces to C/C++ code
+</para></listitem>
+
+<listitem><para>
+<emphasis>libhtml-template-perl</emphasis> HTML Templates with Perl for generated documentation
+</para></listitem>
+
+</itemizedlist>
+
+</para>
+
+<para>
+
+After having uncompressed the FreeJ source code into its directory, go
+inside and type:
+
+<screen>
+ <userinput>./configure --enable-python</userinput>
+ <userinput>make</userinput>
+ <userinput>sudo make install</userinput>
+</screen>
+
+If no errors occurred then you should have at this point all FreeJ
+libraries and language bindings compiled and installed
+in <emphasis>/usr/local</emphasis> directories. To test the
+installation type <emphasis>freej</emphasis> in a console and see if
+it starts, or run a python interpreter as <emphasis>ipython</emphasis>
+and give it the command <emphasis>import freej;</emphasis>.
+
</para>
+
+</section>
+
+
+
+<section>
+<title>Build on Apple/OSX</title>
+
<para>
If you are trying to compile this software on OSX, you will need to
-open an account as "Apple Developer" and download the developers
-tools. These are not really free, their use is a concession by the A.
-corporation even if they include the GNU C compiler. Also you will to
-install some free packaged collection of software
-as <ulink url="http://fink.sf.net">Fink</ulink>
-or <ulink url="http://www.macports.org">Macports</ulink> and proceed
-installing the aforementioned components. You'll need good unix skills
-to compile a working executable, if you don't feel daring then we
-suggest the more user-friendly packaging of stable binary releases for
-OSX found on
-the <ulink url="ftp://ftp.dyne.org/freej/binaries">ftp.dyne.org/freej</ulink>
+open an account as "Apple Developer" and download the XCode developers
+tools. These are not really free, their use is a concession by the
+Apple corporation even if they include the GNU C compiler. Also you
+will need to install the free packaged collection of software
+<ulink url="http://www.macports.org">Macports</ulink> and proceed
+installing the needed packages: <emphasis> </emphasis>.
+
+<screen>
+ <userinput>sudo port install slang2 fftw-3 spidermonkey</userinput>
+ <userinput>sudo port install libsdl libsdl_image libsdl_ttf libsdl_gfx</userinput>
+ <userinput>sudo port install ffmpeg-devel +no_nonfree</userinput>
+</screen>
+
</para>
+
+
+<para>If you think you are set, you can open the XCode project for
+FreeJ inside the osx/ directory, where there are implemented native
+Carbon/Cocoa OSX components used internally by our engine, with well
+satisfying results.</para>
+
+<para>You don't need to do all this to run FreeJ on Apple/OSX: the
+user-friendly packaging of stable binary releases for OSX is hosted on
+our web page at the address
+<ulink url="http://freej.dyne.org">freej.dyne.org</ulink>
+</para>
+
+</section>
+
+
+<section>
+<title>Build on Microsoft/Win</title>
+
<para>
No-one of us so far felt like compiling FreeJ on the M$ platform,
while there is a quick and easy way to try this software using the
@@ -117,20 +358,26 @@ should be provided already by
the <ulink url="http://www.mingw.org">MinGW</ulink> project.
</para>
+</section>
+
+<section>
+<title>Build for embedded platforms</title>
+
<para>
Experimental builds of FreeJ have succeeded to work on common game
consoles. If you are trying to compile on embedded ARM, you'll
probably have some fun :) the autoconf/automake setup will work out of
the box with a sane cross-compiling toolchain based
on <ulink url="http://gcc.gnu.org">GCC</ulink>, like the one provided
-by <ulink url="http://www.devkitpro">devkitPro</ulink>: if properly
-linked to the right libraries and with some minor adjustement to code
-this software can run on game consoles like NDS or GP2X, set-top TV
-boxes and some palmar devices as personal managers and new generation
-phones. Let's get in touch: we are interested in further development
-in this direction!
+by <ulink url="http://www.devkitpro.org">devkitPro</ulink>: if
+properly linked to the right libraries and with some minor adjustement
+to code this software can run on game consoles like NDS or GP2X,
+set-top TV boxes and some palmar devices as personal managers and new
+generation phones. Let's get in touch: we are interested in further
+development in this direction!
</para>
+</section>
</section>
</chapter>
diff --git a/freej/EN/intro.sgml b/freej/EN/intro.sgml
index 5e9615c..5f88798 100644
--- a/freej/EN/intro.sgml
+++ b/freej/EN/intro.sgml
@@ -197,9 +197,11 @@ Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
<para>FreeJ is copyleft (GNU GPLv3)
<simplelist>
- <member>2001 - 2008 by Denis Roio</member>
+ <member>2001 - 2009 by Denis Roio</member>
<member>2004 - 2005 by Silvano Galliani</member>
<member>2005 - 2008 by Christoph Rudorff</member>
+ <member>2008 - 2009 by Luca Bigliardi</member>
+ <member>2008 - 2009 by Pablo Martin</member>
</simplelist>
Statically included libraries are copyright of the respective authors
diff --git a/freej/EN/python_intro.sgml b/freej/EN/python_intro.sgml
index 0f043d4..40c762e 100644
--- a/freej/EN/python_intro.sgml
+++ b/freej/EN/python_intro.sgml
@@ -14,19 +14,18 @@
<para>
You can use FreeJ in your python code to playback videos quite
-efficiently, it's API has been designed in C++ and the namespace tends
-to be clear and intuitive. Layer lists map nicely to python arrays and
-can be indexed almost natively, for instance. Altough this feature it
-at its early development stage and being refined (with your help
-please!) it can already give some good satisfaction when used in
-conjunction with frameworks as PyGame and Crystal Space.
+efficiently: it's API has been designed in C++ and the namespace tends
+to be clear and intuitive. Using Python bindings for the FreeJ engine
+can give good results, also when used in conjunction with frameworks
+as PyGame and Crystal Space.
</para>
<para>
-First make sure you have installed a version of FreeJ compiled with
-python bindings: that means a package or fresh source compiled with
-Swig and Python development packages (see the chapter Install, Compile
-from source). FreeJ should have installed freej.py in /usr/lib (or
-/usr/local/lib depending from your installation prefix) inside
-python/site-packages.
+To get started, first make sure you have installed a version of FreeJ
+compiled with python bindings: that means a package
+like <emphasis>python-freej</emphasis> in Debian or Ubuntu (see
+the <emphasis>Install</emphasis> section of this manual), or a fresh
+source compiled with Swig and Python development packages. FreeJ
+should have installed freej.py in /usr/lib (or /usr/local/lib
+depending from your installation prefix) inside python/site-packages.
</para>
diff --git a/freej/python/controller.src b/freej/python/controller.src
index 25de8e4..a0694d3 100644
--- a/freej/python/controller.src
+++ b/freej/python/controller.src
@@ -5,28 +5,43 @@ import freej
cx = freej.Context()
cx.init(400,300,0,0)
+### declare the Trigger Controller
class Frame(freej.TriggerController):
def __init__(self, *args):
super(Frame, self).__init__(*args)
-# to be removed (bugfix of activate in controller)
- def activate(self):
- self.active = True
+ ### the dispatch function is the callback
+ ### it will be called at every frame
def dispatch(self):
- print "dispatch callback activated"
+ ### rotate around 360 degrees, incrementing
+ ### this function is called once every frame
+ if self.i>360: self.i=0
+ self.i += 1
+ self.txt.set_rotate( self.i )
+ return 1
+ # dispatch should always return an integer value
-# please note the following return: is needed
-# at the end of the function, else Ruby will
-# return an exception and bail out
+
- return 1
+### create an instance of our Trigger Controller
+f = Frame()
+### set rotation index to zero
+f.i = 0
+### create a text layer inside the controller
+f.txt = freej.TextLayer()
+f.txt.init(cx);
+f.txt.write("Hello World!")
+f.txt.start();
+cx.add_layer(f.txt);
-f = Frame()
+# register it on the current context
cx.register_controller(f)
+
+# start running freej in a separate thread
th = threading.Thread(target = cx.start , name = "freej")
th.start();
diff --git a/freej/python/helloworld.src b/freej/python/helloworld.src
new file mode 100644
index 0000000..521d2d8
--- /dev/null
+++ b/freej/python/helloworld.src
@@ -0,0 +1,28 @@
+# system wide useful modules
+import threading
+import time
+
+import freej
+
+# creates and initializes the freej context at give size
+cx = freej.Context()
+cx.init(400,300,0,0)
+
+# create an instance of a TextLayer
+txt = freej.TextLayer()
+
+# initializes the new layer with the freej context
+txt.init(cx);
+
+# writes the hello world text inside the layer
+txt.write("Hello World!")
+
+# start the layer
+txt.start();
+
+# add the layer to the screen
+cx.add_layer(txt);
+
+# starts freej in a separate thread
+th = threading.Thread(target = cx.start , name = "freej")
+th.start();
diff --git a/freej/python/playeffect.src b/freej/python/playeffect.src
index 0e49b4d..b9c28db 100644
--- a/freej/python/playeffect.src
+++ b/freej/python/playeffect.src
@@ -1,18 +1,32 @@
+# system wide useful modules
import threading
-import freej
import time
import sys
+import freej
+
+# creates and initializes the freej context at give size
cx = freej.Context()
cx.init(400,300,0,0)
+# refreshes the list of available filter effects
cx.plugger.refresh(cx)
+# opens the file given on commandline as a layer
lay = cx.open(sys.argv[1])
+
+# gets the vertigo filter effect
filt = cx.filters["vertigo"]
+
+# adds the filter to the layer
lay.add_filter(filt)
-lay.active = True
+
+# start the layer thread
+lay.start()
+
+# adds the layer to the freej context
cx.add_layer(lay)
+# starts freej in a separate thread
th = threading.Thread(target = cx.start , name = "freej")
th.start();