+++ /dev/null
- 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.
projects / ccbs / blobdiff