MNGVideo addition to Swarm
  by R. Stephan, 2001
==========================

General description
-------------------
At the present version, using the class(es) from this package, you can
generate videos in the MNG format[*] from your Swarm model runs, both GUI
and non-GUI, with white pixels for agents and black pixels for background.
Magnification, as in ZoomRaster, is supported and yields significant
space savings with respect to MPEG-1.  To view the videos one could use
the Mozilla[*] or Konqueror[*] browsers, or one of the viewers from the
contrib directory of the libmng package[*].  No additional code is needed
for creation as Swarm already presupposes the existence of libpng.  The
PNG/MNG file formats are patent-free.

[the sad fact being that Swarm+BLT still can be faster RENDERing the videos
than GTK/SDL players/browsers playing them back]

[*]
http://www.libmng.com
http://www.mozilla.org
http://www.konqueror.org
http://www.libpng.org/pub/png/libpng.html

What's in the package
---------------------
All files in this package distributed under GPL2.  It consists of:

- Obj-C classes to create MNG videos from GUI/batch Swarm runs, both
  - for inclusion in your code, either as source or library
  - for addition to Swarm code if so desired
  as there are: MNGVideo.{m,h} mngutil.{c,h}

So these files are all you need if you want to use this package.
You can also build libMNGVideo.a once, and make install it.
The rest of the included source is for testing.

- Obj-C test application code, to be exact:
  - NaSch-single (of trafficdemo fame, for testing 1-bit block videos),
    built from:
    SingleCar.o NaSchSingleCar.o Detector.o SingleHighway.o
    NaSchSingleHighway.o DetectorFeed.o NaSchSingleDemoSwarm.o
    NaSch-single.o
    which are built from respective sources.

In the following, parts of this package are discussed in detail.


MNGVideo
--------
This is a class for writing a single MNG video.
In v.0.1, only 1-bit depth (black-white) is supported.

Ideally, one would create the MNGVideo object by using one
of its constructors after Grid creation in the buildObjects
message of your ObserverSwarm, and not forget to schedule
the takeAFrame message of MNGVideo later.
One could even write a separate VideoObserverSwarm for the task.

The class does not make a screenshot!  So this is different from
other approaches --- it's perfectly possible to build MNG videos
from screenshots --- the reason for this design decision being
possible huge space savings in many circumstances which will be
fully explored in later versions.  Also, some window managers didn't
take the task of making a screen shot lightly, time-wise.  And you
can make MNG files from non-GUI runs.

What's missing is a GUI widget to manually start/stop the video, 
conditionally compiled in dependent on the existence of a macro.

Parameters for creation
-----------------------

+create: aZone 
   Grid: (id <Grid2d>) world 
   MagFactor: (unsigned) m 
   ColorMap: (id <Colormap>) c;

The behaviour of this is to get width and height from the Grid,
and set default framerate (10 fps), number of frames (100), and file 
basename ("swarm" -> "swarm.mng").

+create: aZone 
   Grid: (id <Grid2d>) world 
   MagFactor: (unsigned) m 
   ColorMap: (id <Colormap>) c
   FrameRate: (unsigned) rate
   NFrames: (int) nf 
   Basename: (const char*) name;

This is like above plus you can set fps, n_frames, and basename.

+createBegin: aZone;
-createEnd;
-setGrid: (id <Grid2d>) world;
-setWidth: (int) w;
-setHeight: (int) h;
-setMagnification: (int) mag;
-setColormap: (id <Colormap>) c;  // nil always forces white-on-black
-setFrameRate: (int) fps;
-setNFrames: (int) nf;
-setBaseName: (char*) filebase;

  The most flexibility you have with using createBegin/createEnd and
  setter functions.  The setGrid message also sets w,h from the Grid.

You will get error messages on stderr if values are wrong.

NaSch-single test app
---------------------
This has to be tested manually, for now.  It should produce two MNGs
with the same 100 frames, and framerates of 10 and 50 fps, the latter of
which might not be playable in two seconds.

120-frame video MNG vs. MPEG-1  (1-bit 4-mag)
as is           45k vs. hundreds k
gzipped         35k vs. two hundred k


ralf@ark.in-berlin.de

$Id: README,v 1.7 2001/01/25 13:40:51 ralf Exp $

