Reset bigscreen on changed groups, not just changed tournaments.
[ccbs] / bigscreen / tinyptc / README
1                  TinyPTC/x11 0.7.3 Readme file
2
3 -------------------------------------------------------------------------------
4
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.
9
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.
14
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
18
19 -------------------------------------------------------------------------------                          
20
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:
23
24    Index:
25
26   * What is TinyPTC
27   * What TinyPTC has to offer
28   * How tiny is TinyPTC
29   * TinyPTC's usage
30   * How to compile TinyPTC
31   * DGA considerations
32   * XVideo considerations
33   * Python extension
34   * How to contact the authors
35   * Where the latest version can be found
36
37 * What is TinyPTC
38
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.
43
44 * What TinyPTC has to offer
45
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 :)
48
49 Actually TinyPTC features:
50
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
55     emulation.
56
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.
61
62 - Automatic event management
63   * It automatically quits when the ESC key is pressed or the window
64     is closed by the user.
65
66 * How tiny is TinyPTC
67
68 TinyPTC is rather small by itself, actually I can give you some
69 information about the test program supplied with the library.
70
71 (I'm talking about UNPACKED executables, once they've been stripped)
72
73 Raw XLib                                      7388 bytes
74 Raw XLib+Color conversion                     7580 bytes (*)
75 Mit-Shm                                       8252 bytes
76 Mit-Shm+Color conversion                      8421 bytes (*)
77 DBE                                           8380 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 (*) (**)
83 DGA 2.x                                       8028 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
89
90 The executables were stripped with:
91
92 strip --strip-all ./executable
93 strip --remove-section=".comment" ./executable
94 strip --remove-section=".note" ./executable
95
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/]
100
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.
103
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.
111
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).
114
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
118
119 * TinyPTC's usage
120
121 TinyPTC exports just three functions you can use:
122
123   *   int ptc_open(char *title, int width, int height);
124   *   int ptc_update(void *buffer);
125   *   void ptc_close(void);
126
127  (It can't get any simpler, can it?)
128
129  - ptc_open(char *title, int width, int height)
130
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.
140
141  - ptc_update(void *buffer)
142
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.
147
148  - ptc_close(void)
149
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.
153
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:
157
158   *   void ptc_cleanup_callback(void);
159
160 * How to compile TinyPTC
161
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
166 the makefile:
167
168   From:
169
170          AFLAGS = -f elf
171
172   to:
173
174          AFLAGS = -f aoutb --PREFIX _
175
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...
179
180 TinyPTC's behaviour can be set with a few #define lines in the include files.
181 Here's a list:
182
183  - Callback usage
184
185     __PTC_CLEANUP_CALLBACK__
186
187    Enables the use of an user-supplied callback function that is called on
188    application's exit.
189
190  - MMX usage
191
192     __PTC_MMX__
193
194    Enables the use of MMX code.
195
196  - 32 bpp blit type
197
198     __PTC_MEMCPY__
199
200    If this is defined, a single memcpy() call will be used to blit the buffer
201    (Only for 32bpp RGB modes only).
202
203  - Color conversion modules
204
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
213
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
222
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.
227
228  - Output targets
229
230    The output target can be chosen by defining one of these #defines in
231    tinyptc.h:
232    
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.
239
240  - Extra behaviour definitions
241
242    __PTC_ENABLE_CONVERSIONS__
243
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.
247
248    __PTC_BEST_VIDEOMODE__
249
250    Enables the best-fit videomode switching for the requested window size. This
251    works only for fullscreen executables.
252
253  - Endianness considerations
254
255    __PTC_LITTLE_ENDIAN__
256
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.
261
262 * DGA considerations
263
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
269 suid root.
270
271 * XVideo considerations
272
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! =)
276
277 * Python extension
278
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.
287
288 Note that you need SWIG 1.3 or newer to generate the wrapper code.
289
290 * How to contact the authors
291
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
295
296 Please send all bug-reports, ideas, fixes, additions, and so on. Don't be
297 shy =).
298
299 * Where the latest version can be found
300
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.