TinyPTC/x11 0.4 Readme file This is the only documentation you can find in this package because the library is pretty straightforward to use. So, here it goes: * 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 XLib. It does all the grunt work for you, so your life will be easier :) Actually TinyPTC features: - Automatic display management * XLib and Mit-Shm window management * DGA support, including videomode 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. - 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) XLib 5728 bytes XLib+Color conversion 6528 bytes (*) Mit-Shm 6656 bytes Mit-Shm+Color conversion 7360 bytes (*) DGA 20272 bytes (**) DGA+Color conversion 20912 bytes (*) (**) DGA+Best videomode 20528 bytes (**) DGA+Best videomode+Color conversion 21136 bytes (*) (**) The executables were stripped with: strip --strip-all ./executable strip --remove-section=".comment" ./executable strip --remove-section=".note" ./executable (*) 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 executables are so big because the library that manages DGA+Videomode switch extension 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. If you pack them with UPX 1.0 you'll get a 10%-50% size reduction, at least on my box... (I'm talking about the supplied example, of course). Please note that your mileage may vary, so don't blame me. * 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. * How to compile TinyPTC TinyPTC's behaviour can be set with a few #define lines in the include files. Here's a list: - 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 Those #define lines, if added, enable the described color conversion module. - Output driver __PTC_XSHM__ It enables Mit-Shm support if it is added. Please note that if you add this line, __PTC_WINDOWED__ will be automatically defined. __PTC_WINDOWED__ Sets a windowed mode as output driver. If you don't add both this line and __PTC_XSHM__, 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_BEST_VIDEOMODE__ Enables the best-fit videomode switching for the requested window size. This works only for fullscreen executables. - Endianness considerations __PTC_LITTLE_ENDIAN__ Select the right converter for 24bpp conversion code. Pretty useless if you don't plan to support such a videomode. It has not been tested at all, so you're warned. * 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 is portable as far as I know, so is common XLib mode. Please note that you will need to be root in order to run fullscreen-enabled applications, or the executable needs to be suid root. It's a DGA limitation, not my fault :). Please also note that I didn't compile TinyPTC on anything different than my two linux/i386 boxes, so please send me any incompatibility/compiling error reports. * How to contact the authors Glenn Fiedler (Gaffer) can be reached at ptc@gaffer.org Alessandro Gatti (Rigel) can be reached at a.gatti@tiscalinet.it 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 can be found at http://www.gaffer.org/tinyptc. Here you can also find all the previous versions (all my flawed versions, though =)) and the other ports for other platforms.