
                 TinyPTC/SDL 0.3.2 Readme file

-------------------------------------------------------------------------------

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

------------------------------------------------------------------------------

This is the only documentation you can find in this package because the
library is pretty straightforward to use. So, here it goes:

   Index:

  * What is TinyPTC
  * What TinyPTC has to offer
  * How tiny is TinyPTC
  * TinyPTC's usage
  * How to compile TinyPTC
  * How to contact the authors
  * Where the latest version can be found

* What is TinyPTC

TinyPTC is a reduced subset of OpenPTC, made exclusively with size
optimizations in mind. TinyPTC is a somehow "low-level" graphics library
that runs on top of SDL, providing only a few functionalities you may
need when working with framebuffer devices.

* What TinyPTC has to offer

Actually TinyPTC features:

- Automatic display management
  * Windowed and fullscreen management

- Automatic color conversion
  * Detects and converts the internal 32bpp ARGB buffer to 15, 16 and
    24 bpp modes, both RGB and BGR.

- Automatic event management
  * It automatically quits when the ESC key is pressed or the window
    is closed by the user.

* How tiny is TinyPTC

TinyPTC is rather small by itself, actually I can give you some
information about the test program supplied with the library.

(I'm talking about UNPACKED executables, once they've been stripped)

SDL                                           4512 bytes
SDL+Color conversion                          4608 bytes

The executables were stripped with:

strip --strip-all ./executable
strip --remove-section=".comment" ./executable
strip --remove-section=".note" ./executable

[By the way, a better "strip" does exist, it's called "sstrip". It was
programmed by Brian Raiter, and on his site you can find further information
about tricks you can use in order to reduce your programs' size and so on.
Brian Raiter's page is http://www.muppetlabs.com/~breadbox/software/tiny/]

If you pack them with UPX 1.2 (or better) you'll get a 10%-50% size reduction,
at least on my box... (I'm talking about the supplied example, of course).

UPX can be found at: http://upx.sourceforge.net.
SStrip can be found at: 
                  http://www.muppetlabs.com/~breadbox/software/elfkickers.html

* TinyPTC's usage

TinyPTC exports just three functions you can use:

  *   int ptc_open(char *title, int width, int height);
  *   int ptc_update(void *buffer);
  *   void ptc_close();

 - ptc_open()

   ptc_open() opens the window (or goes fullscreen) that your
   application needs for blitting data on the screen. It accepts a
   title for the window that will be created (that title will be
   discarded for fullscreen mode) and the window size. For fullscreen
   mode, TinyPTC will try to find a suitable videomode first, and
   it will emulate a fullscreen mode if it didn't find any (you'll
   see your application's output in the middle of the screen). If
   you enabled best-videomode-choice at compile time, the library will
   set the best videmode that fits the supplied window size. It will
   return 0 if it fails, otherwise it will return 1.

 - ptc_update()

   ptc_update() does a mere blitting of your buffer onto the screen.
   If automatic color conversion was enabled it will do the conversion
   for you. It will return 1 if the buffer was blitted and nothing else
   happened.

 - ptc_close()

   ptc_close() closes the window the library created. If it is in
   fullscreen mode, it will switch back to normal videomode. ptc_close()
   is called automatically when the user presses ESC or closes manually
   the window.

Plus, there is an optional callback function that gets called when TinyPTC is
about to shut itself down, called ptc_cleanup_callback, that you must supply if
you are going to use that callback option. Its prototype is:

  *   void ptc_cleanup_callback(void);

* How to compile TinyPTC

TinyPTC's behaviour can be set with a few #define lines in the include
files. Here's a list:

 - Output driver

   __PTC_WINDOWED__

   Sets a windowed mode as output driver. If you don't add this,
   TinyPTC will switch to fullscreen mode.

 - Extra behaviour definitions

   __PTC_ENABLE_CONVERSIONS__

   If it's enabled, it activates the automatic color conversion. If you
   will run an executable that doesn't have the conversions in on a
   non-32bpp display, it will silently quit.

   __PTC_ENABLE_ALPHA__

   If it's enabled, SDL will automatically process the alpha channels and
   blend the various buffers accordingly to the alpha channel values
   supplied by those buffers.

   __PTC_CENTER_WINDOW__

   If it's enabled, the output window will appear at the center of the
   screen. Ignored if __PTC_WINDOWED__ isn't enabled.

 - Callback usage

   __PTC_CLEANUP_CALLBACK__

   Enables the use of an user-supplied callback function that is called on
   application's exit.

* How to contact the authors

Alessandro Gatti (Rigel) can be reached at a.gatti@tiscali.it
Glenn Fiedler (Gaffer) can be reached at gaffer@gaffer.org

Please send all bug-reports, ideas, fixes, additions, and so on. Don't
be shy =).

* Where the latest version can be found

The latest version is now hosted on sourceforge at the following URL: 
http://www.sourceforge.net/projects/tinyptc/. The home page still remains
http://www.gaffer.org/tinyptc.
