example scripts in freej manualfreej

build system for examples and more cleanups

17 files changed, 310 insertions, 247 deletions

diff --git a/config.mk b/config.mk
index 9856b8c..c31d8e6 100644
--- a/config.mk
+++ b/config.mk
@@ -1,5 +1,5 @@
 # configure the language of the manual
 # all available translated chapters will be completed
 
-man-language ?= ES
+man-language ?= EN
 
diff --git a/freej/EN/examples.sgml b/freej/EN/examples.sgml
new file mode 100644
index 0000000..0eb8c5b
--- a/dev/null
+++ b/freej/EN/examples.sgml
@@ -0,0 +1,78 @@
+
+<section>
+<title>Play and apply an effect</title>
+
+%playeffect
+
+<para>
+This script creates and initialises a context, that is an instance of
+FreeJ, with a size of 400 by 300; the size can also be adjusted
+interactively later, with screen implementations that support it. It
+then completes initialisation of plugin effects refreshing the list of
+those present on the system
+using <emphasis>plugger.refresh</emphasis>.
+</para>
+
+<para>
+It then opens the file given at commandline as first argument (argv)
+and starts it in a layer, adds the visual effect "vertigo" to the
+layer created, adds the layer to the screen and runs.
+</para>
+
+<para>
+However, the above example is not all you can already do with FreeJ:
+all the C++ API is mapped to various languages and you can use it as
+it is done in its code, which right now is the main documentation
+source, already reasonably documented via doxygen. For example,
+studying the header of the video_encoder implementation and how it is
+used in the C++ code, you can recognize the classes that are
+accessible from Python and script the encoding and streaming
+capabilities. There are many possibilities out there ;^)
+</para>
+</section>
+
+<section>
+<title>Controllers</title>
+
+<para>
+Controllers in FreeJ are listeners which will dispatch asynchronous
+messages from input channels, that is for example a keyboard that will
+activate callbacks every time keys are pressed, informing the running
+script that something is happening. The script then can overload
+the <emphasis>dispatch()</emphasis> function of the instantiated
+controller, to execute arbitrary code when events occur for that
+controller.
+
+</para>
+
+<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:
+</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
+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.
+</para>
+
+<para>
+Once initialized this simple script will call our dispatch function,
+executing all its contents, every time a frame is processed: so far
+that is every time that cafudda() is called.
+</para>
+
+</section>
+
diff --git a/freej/EN/intro.sgml b/freej/EN/intro.sgml
index 1adcd24..5e9615c 100644
--- a/freej/EN/intro.sgml
+++ b/freej/EN/intro.sgml
@@ -42,6 +42,38 @@ the <ulink url="http://freej.dyne.org">FreeJ website</ulink>.
 </para>
 
 
+
+<section>
+<title>This is Free software</title>
+
+<para>
+Nobody should be restricted by the software they use. There are four
+freedoms that every user should have:
+</para>
+
+<simplelist>
+ <member>the freedom to use the software for any purpose,</member>
+ <member>the freedom to change the software to suit your needs,</member>
+ <member>the freedom to share the software with your friends and neighbors, and</member>
+ <member>the freedom to share the changes you make.</member>
+</simplelist>
+
+<para>
+When a program offers users all of these freedoms, we call it free software.
+</para>
+
+<para>
+Developers who write software can release it under the terms of the
+GNU GPL. When they do, it will be free software and stay free
+software, no matter who changes or distributes the program. We call
+this copyleft: the software is copyrighted, but instead of using those
+rights to restrict users like proprietary software does, we use them
+to ensure that every user has freedom.
+</para>
+
+</section>
+
+
 <section>
 <title>This is Rasta software</title>
 
@@ -136,35 +168,6 @@ Selah.
 
 </section>
 
-<section>
-<title>This is Free software</title>
-
-<para>
-Nobody should be restricted by the software they use. There are four
-freedoms that every user should have:
-</para>
-
-<simplelist>
- <member>the freedom to use the software for any purpose,</member>
- <member>the freedom to change the software to suit your needs,</member>
- <member>the freedom to share the software with your friends and neighbors, and</member>
- <member>the freedom to share the changes you make.</member>
-</simplelist>
-
-<para>
-When a program offers users all of these freedoms, we call it free software.
-</para>
-
-<para>
-Developers who write software can release it under the terms of the
-GNU GPL. When they do, it will be free software and stay free
-software, no matter who changes or distributes the program. We call
-this copyleft: the software is copyrighted, but instead of using those
-rights to restrict users like proprietary software does, we use them
-to ensure that every user has freedom.
-</para>
-
-</section>
 
 <section>
 <title>Disclaimer</title>
diff --git a/freej/EN/python.sgml b/freej/EN/python.sgml
deleted file mode 100644
index 1649164..0000000
--- a/freej/EN/python.sgml
+++ b/dev/null
@@ -1,126 +0,0 @@
-<chapter>
- <title>Use in Python</title>
-
- <indexterm><primary>Python</primary></indexterm>
- <indexterm><primary>PyGame</primary></indexterm>
- <indexterm><primary>Crystal Space</primary></indexterm>
-
-<mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/python_logo" format="jpg">
- </imageobject>
-</mediaobject>
-
-
-<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.
-</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.
-</para>
-
-<para>
-The following script will set you rolling, you can then start it with
-an argument: a file to open, be it an image or video or any other
-input layer supported by your installation.
-
-<screen>
-import freej
-import time
-import sys
-</screen>
-
-will import the FreeJ engine and some python basics
-
-<screen>
-freej.set_debug(3)
-</screen>
-
-you can safely omit it, altough will show more details about actions
-the freej engine does, for debugging purposes.
-
-<screen>
-cx = freej.Context()
-cx.init(400,300,0,0)
-</screen>
-
-creates and initialises a context, that is an instance of FreeJ, with
-a size of 400 by 300; the size can also be adjusted interactively
-later, with screen implementations that support it.
-
-<screen>
-cx.plugger.refresh(cx)
-</screen>
-
-refresh the list of plugins present on the system (so far frei0r and
-freeframe video plugins are supported and some distributed by default
-in FreeJ)
-
-<screen>
-lay = freej.create_layer(cx,sys.argv[1])
-lay.start()
-</screen>
-
-opens the file given at commandline and starts it in a layer
-
-<screen>
-lay.add_filter(cx.filters["vertigo"])
-lay.active = True
-</screen>
-
-adds the visual effect "vertigo" to the layer created
-
-<screen>
-cx.add_layer(lay)
-</screen>
-
-adds the layer to the screen
-
-<screen>
-# main loop
-while True:
- cx.cafudda(1.0)
- time.sleep(0.04)
-time.sleep(10)
-</screen>
-
-a slightly sloppy way to run the engine :) this is being worked on, we
-basically want to offer two ways to handle freej: via setting its
-running time by steps as here, or via registering callbacks.
-
-</para>
-
-<para>
-If you arrived until here with Python bindings you are on the bleeding
-edge and ready to contribute, the engine basically works now and until
-mid-2009 we'll be very active in making it stable: completely
-non-blocking and with lower latency in layer manipulation.
-</para>
-
-<para>
-However, the above example is not all you can already do with FreeJ:
-all the C++ API is mapped to Python and you can use it as it is done
-in its code, which right now is the main documentation source, already
-reasonably documented via doxygen. For example, studying the header of
-the video_encoder implementation and how it is used in the C++ code,
-you can recognize the classes that are accessible from Python and
-script the encoding and streaming capabilities. There are many
-possibilities out there ;^)
-</para>
-
-
-</chapter>
-
-
diff --git a/freej/EN/python_intro.sgml b/freej/EN/python_intro.sgml
new file mode 100644
index 0000000..0f043d4
--- a/dev/null
+++ b/freej/EN/python_intro.sgml
@@ -0,0 +1,32 @@
+<chapter>
+ <title>Use in Python</title>
+
+ <indexterm><primary>Python</primary></indexterm>
+ <indexterm><primary>PyGame</primary></indexterm>
+ <indexterm><primary>Crystal Space</primary></indexterm>
+
+<mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/python_logo" format="jpg">
+ </imageobject>
+</mediaobject>
+
+
+<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.
+</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.
+</para>
diff --git a/freej/EN/ruby.sgml b/freej/EN/ruby.sgml
deleted file mode 100644
index 0321421..0000000
--- a/freej/EN/ruby.sgml
+++ b/dev/null
@@ -1,90 +0,0 @@
-<chapter>
-<title>Use in Ruby</title>
-
-<indexterm><primary>Ruby</primary></indexterm>
-
-<mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/ruby_logo" format="jpg">
- </imageobject>
-</mediaobject>
-
-
-<para>
-There are bindings to use FreeJ in Ruby, these are at an early stage
-of development, actually ready for the first explorers :) make sure
-you installed FreeJ complete with Swig to wrap Ruby bindings. Here
-below is a quick example of usage:
-
-<screen>
-require 'Freej'
-</screen>
-
-loads the Freej extension in Ruby
-
-<screen>
-cx = Freej::Context.new
-cx.init(400,300,0,0)
-</screen>
-
-creates and initialises a context, that is an instance of FreeJ, with
-a size of 400 by 300; the size can also be adjusted interactively
-later, with screen implementations that support it.
-
-<screen>
-cx.plugger.refresh(cx)
-</screen>
-
-refresh the list of plugins present on the system (so far frei0r and
-freeframe video plugins are supported and some distributed by default
-in FreeJ)
-
-<screen>
-lay = Freej::create_layer(cx,"/home/jaromil/Videos/Lesyeuxnoirs.mp4")
-# lay.start()
-</screen>
-
-opens the file path given and starts it in a layer (change the file
-name to your own data)
-
-<screen>
-filter = cx.filters.search("vertigo")[0]
-lay.add_filter(filter)
-</screen>
-
-adds the visual effect "vertigo" to the layer created
-
-<screen>
-# lay.active = 1
-cx.add_layer(lay)
-</screen>
-
-adds the layer to the screen
-
-<screen>
-# main loop
-while 1
- cx.cafudda(0.0)
- sleep 0.04
-end
-sleep 10
-</screen>
-
-a slightly sloppy way to run the engine :) this is being worked on, we
-basically want to offer two ways to handle freej: via setting its
-running time by steps as here, or via registering callbacks.
-
-</para>
-
-<para>
-However, the above example is not all you can already do with FreeJ:
-all the C++ API is mapped to Ruby and you can use it as it is done in
-its code, which right now is the main documentation source, already
-reasonably documented via doxygen. For example, studying the header of
-the video_encoder implementation and how it is used in the C++ code,
-you can recognize the classes that are accessible from Python and
-script the encoding and streaming capabilities. There are many
-possibilities out there ;^)
-</para>
-
-</chapter>
diff --git a/freej/EN/ruby_intro.sgml b/freej/EN/ruby_intro.sgml
new file mode 100644
index 0000000..1ef46a9
--- a/dev/null
+++ b/freej/EN/ruby_intro.sgml
@@ -0,0 +1,20 @@
+<chapter>
+<title>Ruby</title>
+
+<indexterm><primary>Ruby</primary></indexterm>
+
+<mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/ruby_logo" format="jpg">
+ </imageobject>
+</mediaobject>
+
+
+<para>
+There are bindings to use FreeJ in Ruby, these are at an early stage
+of development, actually ready for the first explorers :) make sure
+you installed FreeJ complete with Swig to wrap Ruby bindings
+</para>
+
+<!-- the above is generated by collate.sh and should not be processed
+ directly -->
diff --git a/freej/EN/stream.sgml b/freej/EN/stream.sgml
index d70e61f..6f2daab 100644
--- a/freej/EN/stream.sgml
+++ b/freej/EN/stream.sgml
@@ -43,5 +43,43 @@ documentation wiki</ulink>, where you'll also find links to free
 broadcasting servers and clients to playback.
 </para>
 
+<section>
+<title>Remote Vision Mixer</title>
+
+<para>
+FreeJ can be easily scripted to execute various operations on a remote
+computer, like mixing together video streams, rendering RSS news feeds
+and logos on them and re-stream the result to the public.
+</para>
+
+<para>
+The advantages of running such a setup server-side are several:
+multiple people can manage the system remotely, while the engine will
+keep running an online stream, here below is a scheme:
+
+
+<mediaobject>
+ <imageobject>
+ <imagedata align="center" width="472" depth="350" scale="40"
+ fileref="images/server_backend" format="jpg">
+ </imageobject>
+ <imageobject>
+ <imagedata align="center" scale="40"
+ fileref="images/server_backend" format="eps">
+ </imageobject>
+ <textobject>
+ <phrase>Diagram of server-side setup for a streaming vision
+ mixer</phrase>
+ </textobject>
+ <caption>
+ <para>Server-side setup diagram for FreeJ</para>
+ </caption>
+</mediaobject>
+
+</para>
+
+
+</section>
+
 
 </chapter>
diff --git a/freej/Makefile b/freej/Makefile
index 3518365..111cc8f 100644
--- a/freej/Makefile
+++ b/freej/Makefile
@@ -138,5 +138,8 @@ clean :
 rm -rf $(lang)/html
 rm -ff $(lang)/index.sgml
 rm -ff $(lang)/db2texi.refs
+ rm -rf $(lang)/ruby.sgml
+ rm -rf $(lang)/python.sgml
 rm -rf $(lang)/$(filename).*
 
+
diff --git a/freej/collate.sh b/freej/collate.sh
index 2ae8d83..073bbce 100755
--- a/freej/collate.sh
+++ b/freej/collate.sh
@@ -6,10 +6,36 @@
 # get which language we're compiling
 lang=$1
 
+if ! [ -x $lang ]; then
+ echo "There is no translation of this manual in [$lang]"
+ exit 1
+fi
+
 name=freej-manual
 
+
+# collate the example scripts for language bindings
+
+for l in ruby python; do
+ rm -f $lang/$l.sgml
+ cat $lang/${l}_intro.sgml > $lang/$l.sgml
+ cat $lang/examples.sgml | awk -v lang=$l '
+BEGIN { tmpl = 0 }
+/^%/ { print "<screen>"
+ split($1, file, "%");
+ cmd = sprintf("cat %s/%s.src", lang, file[2]); 
+ system(cmd)
+ print "</screen>"
+ tmpl = 1 }
+ { if(tmpl==0) print $0
+ else tmpl = 0 }
+' >> "$lang/$l.sgml"
+ echo "</chapter>" >> "$lang/$l.sgml"
+done
+
+
 # list all chapter entities for the selected translation
-entities=`ls $lang/*.sgml| grep -v '$(name)'| grep -v 'authors.sgml'`
+entities=`ls $lang/*.sgml| grep -v '$(name)'| grep -v 'authors.sgml' | grep -v '_intro.sgml$'`
 
 # set the known chapters and their order
 ordered="
diff --git a/freej/images/server_backend.png b/freej/images/server_backend.png
new file mode 100644
index 0000000..acd5854
--- a/dev/null
+++ b/freej/images/server_backend.png
diff --git a/freej/python/controller.src b/freej/python/controller.src
new file mode 100644
index 0000000..b9c25b4
--- a/dev/null
+++ b/freej/python/controller.src
@@ -0,0 +1,6 @@
+
+
+
+TODO: still missing
+
+
diff --git a/freej/python/playeffect.src b/freej/python/playeffect.src
new file mode 100644
index 0000000..fe2dd3b
--- a/dev/null
+++ b/freej/python/playeffect.src
@@ -0,0 +1,22 @@
+
+import freej
+import time
+import sys
+
+cx = freej.Context()
+cx.init(400,300,0,0)
+
+cx.plugger.refresh(cx)
+
+lay = freej.create_layer(cx,sys.argv[1])
+
+lay.add_filter(cx.filters["vertigo"])
+
+cx.add_layer(lay)
+
+# main loop
+while True:
+ cx.cafudda(1.0)
+ time.sleep(0.04)
+time.sleep(10)
+
diff --git a/freej/ruby/controller.src b/freej/ruby/controller.src
new file mode 100644
index 0000000..6d459f5
--- a/dev/null
+++ b/freej/ruby/controller.src
@@ -0,0 +1,22 @@
+
+require 'Freej'
+
+cx = Freej::Context.new
+cx.init(400,300,0,0)
+
+class Frame < Freej::TriggerCtrl
+
+def dispatch
+
+ puts("dispatch callback activated")
+
+# please note the following return: is needed
+# at the end of the function, else Ruby will
+# return an exception and bail out
+ return(1)
+
+end
+end
+
+f = Frame.new
+cx.register_controller(f)
diff --git a/freej/ruby/helloworld.src b/freej/ruby/helloworld.src
new file mode 100644
index 0000000..e69de29
--- a/dev/null
+++ b/freej/ruby/helloworld.src
diff --git a/freej/ruby/playeffect.src b/freej/ruby/playeffect.src
new file mode 100644
index 0000000..09b4dda
--- a/dev/null
+++ b/freej/ruby/playeffect.src
@@ -0,0 +1,22 @@
+
+require 'Freej'
+
+cx = Freej::Context.new
+cx.init(400,300,0,0)
+
+cx.plugger.refresh(cx)
+
+lay = Freej::create_layer(cx,ARGV[0])
+
+filter = cx.filters.search("vertigo")[0]
+lay.add_filter(filter)
+
+cx.add_layer(lay)
+
+# main loop
+while 1
+ cx.cafudda(0.0)
+ sleep 0.04
+end
+sleep 10
+
diff --git a/utils/formatimages.sh b/utils/formatimages.sh
index 8108f45..32d577f 100755
--- a/utils/formatimages.sh
+++ b/utils/formatimages.sh
@@ -9,6 +9,7 @@ case $target in
 
 
 html)
+ # png images
 outdir="$lang/html/images"
 mkdir -p $outdir
 for i in `ls images/*.png`; do
@@ -16,10 +17,14 @@ case $target in
 echo "converting $file to jpeg"
 convert $i "$outdir/${file}"
 done
+ # eps images
+ cp -f images/*.eps $outdir/
+
 ;;
 
 
 pdf)
+ # png images
 outdir="$lang/images"
 mkdir -p $outdir
 for i in `ls images/*.png`; do
@@ -27,6 +32,8 @@ case $target in
 echo "converting $file to jpeg"
 convert $i "$outdir/${file}.jpg"
 done
+ # eps images
+ cp -f images/*.eps $outdir/
 
 ;;