                 TinyPTC/x11 0.7.3 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
  * DGA considerations
  * XVideo considerations
  * Python extension
  * 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 XLib, providing only a few functionalities you may
need when working with framebuffer devices.

* What TinyPTC has to offer

TinyPTC will simplify your programs that are using X11 to output
graphics. It does all the grunt work for you, so your life will be easier :)

Actually TinyPTC features:

- Automatic display management
  * XLib, DBE, XVideo, and Mit-Shm window management
  * DGA 1.x support, including videomode switch and fullscreen emulation
  * DGA 2.x support, including videomode/videodepth switch and fullscreen
    emulation.

- Automatic color conversion
  * Detects and converts the internal 32bpp ARGB buffer to 15, 16 and
    24 bpp modes, both RGB and BGR. Two versions are supplied, one featuring
    MMX conversions and one that doesn't.

- 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)

Raw XLib                                      7388 bytes
Raw XLib+Color conversion                     7580 bytes (*)
Mit-Shm                                       8252 bytes
Mit-Shm+Color conversion                      8421 bytes (*)
DBE                                           8380 bytes
DBE+Color conversion                          8604 bytes (*)
DGA 1.x                                      20860 bytes (**)
DGA 1.x+Best Videomode                       21084 bytes (**)
DGA 1.x+Color conversion                     20924 bytes (*) (**)
DGA 1.x+Color conversion+Best Videomode      21404 bytes (*) (**)
DGA 2.x                                       8028 bytes
DGA 2.x+Best Videomode                        8220 bytes
DGA 2.x+Color conversion                      8252 bytes (*)
DGA 2.x+Color conversion+Best Videomode       9244 bytes (*)
XVideo+Mit-Shm                               22352 bytes
XVideo+Mit-Shm+MMX conversion                19152 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/]

(*) The color conversion modules were included all at once, you will
    get a smaller executable if you include only the ones you need.

(**) The DGA 1.x executables are so big because the library that manages
     DGA+Videomode switch extensions is linked statically. If you look
     at the object file you get from x11.c you'll notice the absence
     of all those control strings like "Video memory protecting" and
     such. I tried to link the library dynamically but the
     executables were bigger due to the library loading code being
     added. Hopefully with DGA 2.x those two libraries are dynamically linked.

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.sf.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(void);

 (It can't get any simpler, can it?)

 - ptc_open(char *title, int width, int height)

   ptc_open() either opens the window that your application needs for blitting
   data on the screen or it will go fullscreen. 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
   PTC_FAILURE if it fails, otherwise it will return PTC_SUCCESS.

 - ptc_update(void *buffer)

   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 PTC_SUCCESS if the buffer was blitted and nothing else happened,
   else it will return PTC_FAILURE.

 - ptc_close(void)

   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

First of all, Laurent Mascherpa (laurent.mascherpa@epita.fr) managed to compile
TinyPTC with the mmx converters under NetBSD. As he told me, NetBSD uses a
slightly different a.out object format, so the files generated by nasm are
useless. Anyway, the workaround consists in modifying the AFLAGS variable in
the makefile:

  From:

         AFLAGS = -f elf

  to:

         AFLAGS = -f aoutb --PREFIX _

(Next time I'm going to add some sort of "autoconf"-like scripts ;))
Please note that you'll also get a static library called libtinyptc.a, ready to
be included in your own programs...

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

 - Callback usage

    __PTC_CLEANUP_CALLBACK__

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

 - MMX usage

    __PTC_MMX__

   Enables the use of MMX code.

 - 32 bpp blit type

    __PTC_MEMCPY__

   If this is defined, a single memcpy() call will be used to blit the buffer
   (Only for 32bpp RGB modes only).

 - Color conversion modules

    __PTC_CONVERTER_32_TO_32_RGB888
    __PTC_CONVERTER_32_TO_32_BGR888
    __PTC_CONVERTER_32_TO_24_RGB888
    __PTC_CONVERTER_32_TO_24_BGR888
    __PTC_CONVERTER_32_TO_16_RGB565
    __PTC_CONVERTER_32_TO_16_BGR565
    __PTC_CONVERTER_32_TO_16_RGB555
    __PTC_CONVERTER_32_TO_16_BGR555

    __PTC_MMX_CONVERT_32_TO_32_BGR888
    __PTC_MMX_CONVERT_32_TO_32_RGB888
    __PTC_MMX_CONVERT_32_TO_24_BGR888
    __PTC_MMX_CONVERT_32_TO_24_RGB888
    __PTC_MMX_CONVERT_32_TO_16_BGR565
    __PTC_MMX_CONVERT_32_TO_16_RGB565
    __PTC_MMX_CONVERT_32_TO_16_BGR555
    __PTC_MMX_CONVERT_32_TO_16_RGB555

   Those #define lines, if added, enable the described color conversion module.
   Please note that you can't just enable an MMX converter without enabling the
   standard converter as well. It doesn't hurt performance or size because the 
   standard code isn't added if there is an MMX version avaliable.

 - Output targets

   The output target can be chosen by defining one of these #defines in
   tinyptc.h:
   
   __PTC_XLIB__       * This is the raw XLib target.
   __PTC_XSHM__       * This is the Mit-Shm target.
   __PTC_XDBE__       * This is the X DBE target.
   __PTC_XDGA1__      * This is the X DGA 1.x target.
   __PTC_XDGA2__      * This is the X DGA 2.x target.
   __PTC_XVSHM__      * This is the XVideo+Mit-Shm target.

 - 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. Ignored for the XVideo+Mit-Shm target.

   __PTC_BEST_VIDEOMODE__

   Enables the best-fit videomode switching for the requested window size. This
   works only for fullscreen executables.

 - Endianness considerations

   __PTC_LITTLE_ENDIAN__

   Selects the right converter for 24bpp and 32bpp conversion code. Pretty
   useless if you don't plan to support those videomodes or little endian
   architectures. It has not been tested extensively, so don't assume it's
   100% working. Ignored for the XVideo+Mit-Shm target.

* DGA considerations

Although TinyPTC is fairly portable, the DGA mode is a XFree86-only extension
to the X Windowing system. So if you try to compile the fullscreen support on
a non-i386 machine it will complain. Anyway, Mit-Shm and DBE are portable as
far as I know, so is "raw" XLib mode. Please note that you will need either be
root in order to run fullscreen-enabled applications or set the executable as
suid root.

* XVideo considerations

The XVideo support has been tested on NVidia (with binary-only drivers), ATI,
and Matrox cards under XFree 4.x. It's totally untested on S3 Savage-based
cards. If you happen to have such a card and want to test it out, tell us! =)

* Python extension

Since version 0.7.2, a python extension can be built out of TinyPTC. In order
to get that you've got to use the python target in the makefile and copy the
_TinyPTC.so file whereever is appropriate for your program. The python API
replicates almost entirely the C/C++ one except for pointer management. You
have to use the provided TinyPTC.pixel_array method to allocate the buffers
you'll pass to TinyPTC.ptc_update. The objects returned by TinyPTC.pixel_array
act almost like normal python arrays. In case of doubt, take a look at the
supplied python_test.py file.

Note that you need SWIG 1.3 or newer to generate the wrapper code.

* How to contact the authors

Alessandro Gatti (Rigel) can be reached at a.gatti@tiscali.it
Fred Howell (Fred) can be reached at foohoo@shaw.ca
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 of the x11 and SDL versions is now hosted on sourceforge at
the following URL: http://www.sourceforge.net/projects/tinyptc/. The main page
still remains http://www.gaffer.org/tinyptc.
