1 TinyPTC/x11 0.7.3 Readme file
3 -------------------------------------------------------------------------------
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Lesser General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Lesser General Public License for more details.
15 You should have received a copy of the GNU Lesser General Public
16 License along with this library; if not, write to the Free Software
17 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
19 -------------------------------------------------------------------------------
21 This is the only documentation you can find in this package because the
22 library is pretty straightforward to use. So, here it goes:
27 * What TinyPTC has to offer
30 * How to compile TinyPTC
32 * XVideo considerations
34 * How to contact the authors
35 * Where the latest version can be found
39 TinyPTC is a reduced subset of OpenPTC, made exclusively with size
40 optimizations in mind. TinyPTC is a somehow "low-level" graphics library
41 that runs on top of XLib, providing only a few functionalities you may
42 need when working with framebuffer devices.
44 * What TinyPTC has to offer
46 TinyPTC will simplify your programs that are using X11 to output
47 graphics. It does all the grunt work for you, so your life will be easier :)
49 Actually TinyPTC features:
51 - Automatic display management
52 * XLib, DBE, XVideo, and Mit-Shm window management
53 * DGA 1.x support, including videomode switch and fullscreen emulation
54 * DGA 2.x support, including videomode/videodepth switch and fullscreen
57 - Automatic color conversion
58 * Detects and converts the internal 32bpp ARGB buffer to 15, 16 and
59 24 bpp modes, both RGB and BGR. Two versions are supplied, one featuring
60 MMX conversions and one that doesn't.
62 - Automatic event management
63 * It automatically quits when the ESC key is pressed or the window
64 is closed by the user.
68 TinyPTC is rather small by itself, actually I can give you some
69 information about the test program supplied with the library.
71 (I'm talking about UNPACKED executables, once they've been stripped)
74 Raw XLib+Color conversion 7580 bytes (*)
76 Mit-Shm+Color conversion 8421 bytes (*)
78 DBE+Color conversion 8604 bytes (*)
79 DGA 1.x 20860 bytes (**)
80 DGA 1.x+Best Videomode 21084 bytes (**)
81 DGA 1.x+Color conversion 20924 bytes (*) (**)
82 DGA 1.x+Color conversion+Best Videomode 21404 bytes (*) (**)
84 DGA 2.x+Best Videomode 8220 bytes
85 DGA 2.x+Color conversion 8252 bytes (*)
86 DGA 2.x+Color conversion+Best Videomode 9244 bytes (*)
87 XVideo+Mit-Shm 22352 bytes
88 XVideo+Mit-Shm+MMX conversion 19152 bytes
90 The executables were stripped with:
92 strip --strip-all ./executable
93 strip --remove-section=".comment" ./executable
94 strip --remove-section=".note" ./executable
96 [By the way, a better "strip" does exist, it's called "sstrip". It was
97 programmed by Brian Raiter, and on his site you can find further information
98 about tricks you can use in order to reduce your programs' size and so on.
99 Brian Raiter's page is http://www.muppetlabs.com/~breadbox/software/tiny/]
101 (*) The color conversion modules were included all at once, you will
102 get a smaller executable if you include only the ones you need.
104 (**) The DGA 1.x executables are so big because the library that manages
105 DGA+Videomode switch extensions is linked statically. If you look
106 at the object file you get from x11.c you'll notice the absence
107 of all those control strings like "Video memory protecting" and
108 such. I tried to link the library dynamically but the
109 executables were bigger due to the library loading code being
110 added. Hopefully with DGA 2.x those two libraries are dynamically linked.
112 If you pack them with UPX 1.2 (or better) you'll get a 10%-50% size reduction,
113 at least on my box... (I'm talking about the supplied example, of course).
115 UPX can be found at: http://upx.sf.net
116 SStrip can be found at:
117 http://www.muppetlabs.com/~breadbox/software/elfkickers.html
121 TinyPTC exports just three functions you can use:
123 * int ptc_open(char *title, int width, int height);
124 * int ptc_update(void *buffer);
125 * void ptc_close(void);
127 (It can't get any simpler, can it?)
129 - ptc_open(char *title, int width, int height)
131 ptc_open() either opens the window that your application needs for blitting
132 data on the screen or it will go fullscreen. It accepts a title for the
133 window that will be created (that title will be discarded for fullscreen
134 mode) and the window size. For fullscreen mode, TinyPTC will try to find a
135 suitable videomode first, and it will emulate a fullscreen mode if it didn't
136 find any (you'll see your application's output in the middle of the screen).
137 If you enabled best-videomode-choice at compile time, the library will set
138 the best videmode that fits the supplied window size. It will return
139 PTC_FAILURE if it fails, otherwise it will return PTC_SUCCESS.
141 - ptc_update(void *buffer)
143 ptc_update() does a mere blitting of your buffer onto the screen. If
144 automatic color conversion was enabled it will do the conversion for you. It
145 will return PTC_SUCCESS if the buffer was blitted and nothing else happened,
146 else it will return PTC_FAILURE.
150 ptc_close() closes the window the library created. If it is in fullscreen
151 mode, it will switch back to normal videomode. ptc_close() is called
152 automatically when the user presses ESC or closes manually the window.
154 Plus, there is an optional callback function that gets called when TinyPTC is
155 about to shut itself down, called ptc_cleanup_callback, that you must supply if
156 you are going to use that callback option. Its prototype is:
158 * void ptc_cleanup_callback(void);
160 * How to compile TinyPTC
162 First of all, Laurent Mascherpa (laurent.mascherpa@epita.fr) managed to compile
163 TinyPTC with the mmx converters under NetBSD. As he told me, NetBSD uses a
164 slightly different a.out object format, so the files generated by nasm are
165 useless. Anyway, the workaround consists in modifying the AFLAGS variable in
174 AFLAGS = -f aoutb --PREFIX _
176 (Next time I'm going to add some sort of "autoconf"-like scripts ;))
177 Please note that you'll also get a static library called libtinyptc.a, ready to
178 be included in your own programs...
180 TinyPTC's behaviour can be set with a few #define lines in the include files.
185 __PTC_CLEANUP_CALLBACK__
187 Enables the use of an user-supplied callback function that is called on
194 Enables the use of MMX code.
200 If this is defined, a single memcpy() call will be used to blit the buffer
201 (Only for 32bpp RGB modes only).
203 - Color conversion modules
205 __PTC_CONVERTER_32_TO_32_RGB888
206 __PTC_CONVERTER_32_TO_32_BGR888
207 __PTC_CONVERTER_32_TO_24_RGB888
208 __PTC_CONVERTER_32_TO_24_BGR888
209 __PTC_CONVERTER_32_TO_16_RGB565
210 __PTC_CONVERTER_32_TO_16_BGR565
211 __PTC_CONVERTER_32_TO_16_RGB555
212 __PTC_CONVERTER_32_TO_16_BGR555
214 __PTC_MMX_CONVERT_32_TO_32_BGR888
215 __PTC_MMX_CONVERT_32_TO_32_RGB888
216 __PTC_MMX_CONVERT_32_TO_24_BGR888
217 __PTC_MMX_CONVERT_32_TO_24_RGB888
218 __PTC_MMX_CONVERT_32_TO_16_BGR565
219 __PTC_MMX_CONVERT_32_TO_16_RGB565
220 __PTC_MMX_CONVERT_32_TO_16_BGR555
221 __PTC_MMX_CONVERT_32_TO_16_RGB555
223 Those #define lines, if added, enable the described color conversion module.
224 Please note that you can't just enable an MMX converter without enabling the
225 standard converter as well. It doesn't hurt performance or size because the
226 standard code isn't added if there is an MMX version avaliable.
230 The output target can be chosen by defining one of these #defines in
233 __PTC_XLIB__ * This is the raw XLib target.
234 __PTC_XSHM__ * This is the Mit-Shm target.
235 __PTC_XDBE__ * This is the X DBE target.
236 __PTC_XDGA1__ * This is the X DGA 1.x target.
237 __PTC_XDGA2__ * This is the X DGA 2.x target.
238 __PTC_XVSHM__ * This is the XVideo+Mit-Shm target.
240 - Extra behaviour definitions
242 __PTC_ENABLE_CONVERSIONS__
244 If it's enabled, it activates the automatic color conversion. If you will
245 run an executable that doesn't have the conversions in on a non-32bpp
246 display, it will silently quit. Ignored for the XVideo+Mit-Shm target.
248 __PTC_BEST_VIDEOMODE__
250 Enables the best-fit videomode switching for the requested window size. This
251 works only for fullscreen executables.
253 - Endianness considerations
255 __PTC_LITTLE_ENDIAN__
257 Selects the right converter for 24bpp and 32bpp conversion code. Pretty
258 useless if you don't plan to support those videomodes or little endian
259 architectures. It has not been tested extensively, so don't assume it's
260 100% working. Ignored for the XVideo+Mit-Shm target.
264 Although TinyPTC is fairly portable, the DGA mode is a XFree86-only extension
265 to the X Windowing system. So if you try to compile the fullscreen support on
266 a non-i386 machine it will complain. Anyway, Mit-Shm and DBE are portable as
267 far as I know, so is "raw" XLib mode. Please note that you will need either be
268 root in order to run fullscreen-enabled applications or set the executable as
271 * XVideo considerations
273 The XVideo support has been tested on NVidia (with binary-only drivers), ATI,
274 and Matrox cards under XFree 4.x. It's totally untested on S3 Savage-based
275 cards. If you happen to have such a card and want to test it out, tell us! =)
279 Since version 0.7.2, a python extension can be built out of TinyPTC. In order
280 to get that you've got to use the python target in the makefile and copy the
281 _TinyPTC.so file whereever is appropriate for your program. The python API
282 replicates almost entirely the C/C++ one except for pointer management. You
283 have to use the provided TinyPTC.pixel_array method to allocate the buffers
284 you'll pass to TinyPTC.ptc_update. The objects returned by TinyPTC.pixel_array
285 act almost like normal python arrays. In case of doubt, take a look at the
286 supplied python_test.py file.
288 Note that you need SWIG 1.3 or newer to generate the wrapper code.
290 * How to contact the authors
292 Alessandro Gatti (Rigel) can be reached at a.gatti@tiscali.it
293 Fred Howell (Fred) can be reached at foohoo@shaw.ca
294 Glenn Fiedler (Gaffer) can be reached at gaffer@gaffer.org
296 Please send all bug-reports, ideas, fixes, additions, and so on. Don't be
299 * Where the latest version can be found
301 The latest version of the x11 and SDL versions is now hosted on sourceforge at
302 the following URL: http://www.sourceforge.net/projects/tinyptc/. The main page
303 still remains http://www.gaffer.org/tinyptc.