--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README.txt	Sat Nov 03 09:19:38 2012 +0200
@@ -0,0 +1,289 @@
+-----------------------------------------------------------------------
+
+                             T   N   S   P
+                        - --==============-- -
+
+                  ######  ###   ## ###    ### ######      
+                # ###  ## #### ### ###    ### ###  ## #   
+              # # ###  ## ######## ###    ### ######  # # 
+                # ###  ## ### # ## ###    ### ###  ## #   
+                  ######  ###   ## ###### ### ######      
+
+            Demo engine / development and utility framework
+
+-----------------------------------------------------------------------
+Programmed by Matti Hämäläinen (ccr/TNSP^PWP)
+(C) Copyright 2002-2012 Tecnic Software productions (TNSP)
+
+Contact
+=======
+IRC    : ccr @ IRCNet, sometimes also Freenode
+e-mail : ccr@tnsp.org
+
+-----------------------------------------------------------------------
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+ 1. Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+
+ 2. Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in
+    the documentation and/or other materials provided with the
+    distribution.
+
+ 3. The name of the author may not be used to endorse or promote
+    products derived from this software without specific prior written
+    permission.
+
+THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR
+IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
+
+-----------------------------------------------------------------------
+
+So, what is this?
+=================
+Basically .. a bunch of more and/or less random stuff. dmlib in
+itself is a library with various things useful in demo programming.
+There is a resource management subsystem, functions for loading
+PNG and JPEG images. Software blitted and scaled sprites, etc.
+Bitmap font routines. A XM module replayer.
+
+And a work-in-progress timeline-supporting demo framework, with
+a Qt based GUI editor.
+
+And graphics converter and displayer for various restricted formats,
+such as C64/VIC-20 characters, bitmaps, sprites, etc.
+
+.. So, yeah. There are many things in here. It's a junkyard of various
+demo- or such development related pieces of code and utilities. Some
+people will probably consider many of these things useless, and I
+could not care less. Some may find useful things .. and in fact,
+you don't _need_ to use everything here.
+
+Most modules can be enabled or disabled, per project basis via
+compile-time configuration in config.mak.
+
+-----------------------------------------------------------------------
+
+Requirements
+============
+The compilation and usage of these utilities requires following
+software packages or functional equivalents installed:
+
+ - GCC 4.x or later (4.6.3 and 4.7.1 used in development.)
+ - GNU binutils
+ - GNU Make
+ - pkg-config
+ - zlib
+
+You probably also want:
+
+ - libSDL 1.2, preferably a current version.
+ - libPNG 1.2 and development headers (more optional,
+   only required for PNG write and read support by some
+   utilities.)
+ - SDL_ttf 2.0 and libfreetype2
+ - Tremor (integer-based Ogg Vorbis decoder) + libogg
+
+And the demo editor framework requires:
+
+ - Qt 4.x framework libraries (tested with 4.7 and 4.8.2)
+ - qmake, moc
+
+
+For Linux -> Win32/64 cross-compilation I have used the standard
+MinGW packages from Debian Testing (wheezy):
+
+gcc-mingw-w64 mingw-w64-i686-dev mingw-w64-x86-64-dev
+
+with the additions of self- cross-compiled libSDL, zlib, Tremor,
+liboff and libPNG. Some of those require a bit of poking to get
+working properly, YMMV.
+
+Please don't ask me for help to get cross-compilation working.
+
+-----------------------------------------------------------------------
+
+How to build
+============
+1) $ cp config.mak.in config.mak
+
+2) Edit config.mak to enable/disable desired options.
+   Make sure you have the required depencies.
+
+3) $ gmake
+   or, if cross-compiling to Win32 via MinGW
+   $ gmake -f Makefile.w32
+
+4) If it works -> Happy fun times \:D\
+
+-----------------------------------------------------------------------
+
+Included utilities
+==================
+
+xm2jss
+------
+Convert XM modules to internal JMOD format. You can optionally
+even strip out various parts, such as complete instruments
+(leaving only pattern data), sample data, sample instruments,
+etc.
+
+
+viewmod
+-------
+Simple XM/JMOD viewer. Dumps selected parts into stdout
+as text format data.
+
+
+ppl
+---
+A simple XM/JMOD player with SDL-based UI.
+
+testpl
+------
+Even simpler player, with no UI at all. Uses SDL for audio.
+
+mod2wav
+-------
+Render XM/JMOD modules into WAV files.
+
+
+packed
+------
+Manipulate DMPACK files. Basically a bit like ZIP archive,
+for glueing resource files into a zlib-compressed blob.
+The dmlib resource subsystem can utilize these files.
+
+fontconv
+--------
+Convert bitmap fonts.
+
+
+objlink
+-------
+Simple, but versatile commandline utility for combining binary
+files into one file. Understands 2-byte loading address PRG
+style files, and raw data. "Loading addresses" can be specified
+and overridden. The utility also checks for overlaps, etc.
+
+data2inc
+--------
+Simple data file to C/ASM source converter.
+
+gfxconv
+-------
+Utility for "dumping" some C64 (and similar) graphics in plain
+ASCII, or ANSI colored output, or into PNG, PCX or PPM files.
+
+Input can be interpreted as bitmap, sprite or character data,
+in multicolor or single color. Colors can be mapped as desired.
+Image file output can be either single image (with chars/sprites
+placed vertically if input is char/sprite data), or in separate
+files.
+
+(Note: PNG support is a compile-time option)
+
+view64
+------
+Compiled only if libSDL support is enabled. Can be used to
+display C64 bitmaps.
+
+-----------------------------------------------------------------------
+
+Examples
+========
+
+data2inc
+--------
+To convert a data file to a C structure using 'uint8_t' as type:
+
+$ data2inc -C -n variable_name -t uint8_t input.bin output.h
+
+
+objlink
+-------
+$ objlink -o intro.tmp -pppp intro.o gfx/dkdlogo2.drp:0x3800 \
+  muzak.prg gfx/chars_4.fnt:0x6800
+
+ - "-o intro.tmp" sets output file
+ - As you can see, short options can be combined, like "-pppp".
+   However, the next parameters must be the corresponding option
+   arguments, in correct order, if any.
+ - It is possible to specify a overriding loading address via
+   ":<addr>" syntax. See the help for more information.
+
+
+gfxconv
+-------
+$ gfxconv chars1.fnt -i char -s 2 -S 10 -c 255:1 -f png -o chars1.png
+
+ - Input file "chars1.fnt" is interpreted as character data (-i char)
+ - "-s 2" skips first two bytes of the input file (loading address)
+ - "-S 10" scales output image to be 10 times larger
+ - "-c 255:1" defines background color (bit value 0) to be transparent
+   (255, only works for PNG) and foreground to be C64 color 1 (white)
+ - "-f png" sets output format to PNG
+
+
+$ gfxconv bub_dump.raw -i s -s 0x5800 -n 20 -f png -o bub \
+  -q -S 3 -m -c 255:2:5:1
+
+  - Input file "bub_dump.raw" is a raw memory dump of Bubble Bobble
+    extracted via VICE in game running mode.
+  - "-i s" sets input to be interpreted as sprite data
+  - "-s 0x5800" skips 0x5800 bytes, basically the memory address as the
+    input is a straight memory dump file.
+  - "-n 20" sets max item count to 20, so 20 sprites will be dumped.
+  - "-o bub" sets filename prefix to "bub"
+  - "-q" selects sequential output (separate files)
+  - "-m" selects multicolor input
+  - "-c 255:2:5:1" sets the multicolor color mappings
+    (255 is the transparency color again)
+
+$ gfxconv chars3.fnt -i c -s 2 -n 3
+
+  Dump as character data into stdout, skipping 2 bytes at start, and
+  limit output to 3 items (characters).
+
+---- : -------------- #0
+0002 : ........
+0003 : ..####..
+0004 : .#....#.
+0005 : #..##..#
+0006 : #.#....#
+0007 : #..##..#
+0008 : .#....#.
+0009 : ..####..
+---- : -------------- #1
+000a : ........
+000b : ...##...
+000c : ..#..#..
+000d : ..####..
+000e : .##..#..
+000f : .##..#..
+0010 : .##..#..
+0011 : ........
+---- : -------------- #2
+0012 : ........
+0013 : ..###...
+0014 : ..#..#..
+0015 : ..###...
+0016 : .##..#..
+0017 : .##..#..
+0018 : .####...
+0019 : ........
+
+-----------------------------------------------------------------------