Warp - Realtime picture 'gooing' GGI demo. Version 1.1.5 (sep. 27, 1998)

This program is intended to be a demonstration of GGI, the General Graphics
Interface.

For best performance, this demo should be tried fullscreen on a target
with direct access to the framebuffer.
Refer to the GGI installation for that. If you don't want to, or your
operating system doesn't support it, you can compile LibGGI for X under
any *nix system and try this demo on a regular X server :)

version 1.1.5 (09/27/1998)
 Warp now supports the new LibGGI DirectBuffer API. The description of
 screen modes is now more consistant and other minor changes have happened
 too, breaking the program. Now fixed. Works with LibGGI 1.4.99 (soon
 to be 2.0beta).
 
 Trying to use a Targa image (with Jaromir's loader) saved from the Gimp,
 I noticed his loader doesn't handle file IDs (comments) properly. Fixed.
 Also noticed it didn't set the depth correctly in some cases, fixed as
 well.

 Wrote proper arguments parsing, so you can set the depth without giving
 out a filename for instance; the old quick parsing was really dumb.
 Now doing warp mypicture, warp -d 16 mypicture, warp mypicture -d 24
 or warp -d 32 all works.

 Sourcecode cosmetic changes: changed from hard tabs (\t) to soft-tabs
 (ie. spaces, and 3 spaces instead of 8 as for real tabs) making the
 source really more readable. Some cosmetic changes here and there too.
 
 License changed from GPL to Public Domain, following the decision
 made among GGI developers to release GGI demos as public domain so
 that they can be used as examples of LibGGI programming for any purpose.

 Checked in GGI CVS repository as DirectBuffer usage example. This demo
 has never been checked in, and there is no DirectBuffer demo in the
 GGI repository, so I check it in hoping it'll be useful.

version 1.1.4 (sometime in spring 1998)
 Jaromir Koutek added support for Targa (.TGA) pictures. He packaged
 this version into RPM, but I never really worked anything from it until
 now. Thanks Jaromir!

version 1.1.3 (11/12/1997)
 Moved color depth conversion code to color.c - cleaner.

version 1.1.2 (11/10/1997)

 Bug fixed in readpcx.c: didn't work on big-endian architectures, stupid
 me. Successfully compiled and tested with my port of LibGGI to Silicon
 Graphics IRIX(tm) 6.3 - tested on a 32-bit R5000 O2 workstation. Woo !!

 Forgot to default 24-bit pictures to 16-bit display. Fixed.

version 1.1 (11/9/1997)

 Warp now supports all resolutions and color depths. See below for more
 information. It has successfully been tested with both KGI display and
 X display targets (with 8 to 32-bit color display).

How to compile :

The Makefile will get Warp to successfully compile on any Linux system.
However, you will need to edit it if you have a different system.

Owners of a pentium (or better) x86 based system, and using
the egcs pentium-optimizing compiler (that you can find at
http://www.cygnus.com/egcs) will want to edit the Makefile, comment
the working-everywhere options out, and uncomment the egcs options line.

SGI IRIX users, comment the Linux options out, and uncomment the
IRIX options line.

If you are compiling Warp on yet another architecture, you will
have to add compilation options for your system. Please do so,
and send me a diff so that I can include your system in future
versions of Warp.

Running the demo :

Once the program is compiled, just run "warp" and enjoy. As GGI project
leaders love to say : you *don't need root privileges* to compile and even
run this demo, once GGI is up and running.

Because I wanted the program to stay small and independant of any other
dynamic library installed in the system (e.g. libjpeg, libpng..), it reads
PCX and Targa picture files. You can use The Gimp to save to that format, or
you can always implement another loader, but this will grow the code beyond
necessity. Anyway, if you have another picture, you can do :

warp picturefile.pcx (or warp picturefile.tga)

to use this picture instead of the default one (leeloo.pcx ;). The file
type isn't recognized from the name, but from the contents, so it can
be called anything.

You can specify the color depth you want with -d colordepth.

If you load a truecolor picture (15,16,24,32 bits theoritically, but pcx only
support 8 and 24 bits and the tga loader currently only 24 bits),
color depth will be selected automatically.

The demo will do color depth conversion if requested (except if you
loaded a truecolor picture and want to display it in 8bpp.. that would
require color quantization, dithering etc and that's beyond the scope
of this small program).

For example, if you are trying Warp on a regular X server in 16 bpp, or
you are loading a 24 bits picture but want to display it in 16-bit color
for better performance, do :

warp picturefile -d 16

The program will convert the image to 16 bpp and then display it
appropriately.

*IMPORTANT NOTES*

1) 24-bit color is slower than 32-bit, and way slower than
16 and 8-bit, because this is the only mode where pixels can't
be transferred with a single cpu instruction. If possible, avoid
it.

2) by default, 24-bit pictures will be displayed in 16-bit.
Specify 24bpp explicitly if you really want to see it slow :)

3) Under X, your server will probably not be running in 8 bpp, what
the default file loaded by the demo (leeloo.pcx) uses. In this case,
as explained, just provide the depth to use. If you get a "Error
switching to..", use for example "warp -d 16" if you're running X in 16 bpp.

3) if you get an "X error" running the program, you are trying to
display a 8-bit picture on a truecolor X server. Specify the right
color depth for your display, and it will work.

The demo runs on its own, you can exit it by pressing any key.

Background :

I wrote this program just after I had started to contribute to the GGI
project, wishing at the time to write drivers for the chips I owned and
for which I had documentation - Matrox 1164SG (Mystique, an awesome board)
and ATI 3D RAGE II (blargh). The idea was to learn more about GGI
internals and to provide the project with a good demo, which was
lacking at the time. Matthias Grimrath wrote the Mystique driver,
the ATI chips didn't motivate anyone that much yet :), and I wrote
the driver for the Cyrix MediaGX chipset, in cooperation with Cyrix
themselves, which was a really interesting project. I did the LibGGI
port to IRIX and I manage the ggi-project domain name and CVS repository
aswell, now, and I want to hope I know GGI quite well. 

This demo has been written in an evening and most of a night (not
knowing anything about GGI when I started :). I hope you will like
the result.

This is actually a routine that I had written in 680x0 assembler
on the Amiga, never used, then ported to 80x86 assembler, then ported
to C++ under BeOS, then ported to Java (you can see the Java version
on http://www.core.netnation.org/pages/warp_anita.html), then ported to
plain C for GGI today. Every time I ported it to a new architecture,
I have optimized some bits. I still think it can be done faster, but
on a P133, and with the demo compiled with egcs as -mpentium -O6, it
runs at full frame rate.

It currently opens a 320x200x256 screen by default, so it should run with
any driver, including IBM VGA. As of version 1.1, you can use a picture of
any resolution and color depth, as long as your display target supports it,
it will work.

The program demonstrates the use of direct frame buffer access by dereferencing
a pointer, and the ability of LibGGI to catch that and redirect it to an X
window, if you compiled LibGGI for X target. It will take most of your CPU
time, since sleeping until a vertical retrace event happens, hasn't STILL been
implemented in GGI yet for all targets (there's a LibGGI extension, but it
never catched so far). And if i do any usleep(), it becomes jaggy. So, don't
run this if you have your multimillion business web server running in the
background :)

There is no KGI-specific or even linux-specific code in the program. It
compiles fine for other display targets, and on ports of LibGGI to other
operating systems and architectures. It has been tested to work on IRIX and
Digital Unix. It now uses GGI datatypes (uint32 instead of int, for example),
for portability.

Feel free to improve this program, having it wait for vertical retrace,
making it interactive, or whatever you like. You are allowed to make any
changes and redistribute this program and not required to send the changes
back to me; but please do, so I can merge them in future versions of
this demo.

Enjoy ;)

Emmanuel Marty <core@ggi-project.org>

web: http://www.core.netnation.org (ggi page, add /ggi to the URL)
irc: core on undernet #linux
icq: uin 1153070 (please bear with my linux restricted icq client :P)
