git.sesse.net Git - ccbs/blob - 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.