view README.txt @ 2298:b5abfff07ca9

Add new DMGrowBuf helper functions dmGrowBufCopyOffsSize() and dmGrowBufConstCopyOffsSize().
author Matti Hamalainen <ccr@tnsp.org>
date Thu, 04 Jul 2019 10:54:16 +0300
parents 05532d716f50
children c801995cbb13
line wrap: on
line source

-----------------------------------------------------------------------------

                               T   N   S   P
                          - --==============-- -

                    ######  ###   ## ###    ### ######      
                  # ###  ## #### ### ###    ### ###  ## #   
                # # ###  ## ######## ###    ### ######  # # 
                  # ###  ## ### # ## ###    ### ###  ## #   
                    ######  ###   ## ###### ### ######      

              Demo engine / development and utility framework

-----------------------------------------------------------------------------

Programmed and designed by Matti Hämäläinen (ccr/TNSP)
(C) Copyright 2002-2019 Tecnic Software productions (TNSP)
Please see the file "COPYING" for license.

Contact
=======
IRC    : ccr @ IRCNet, sometimes also Freenode
e-mail : ccr@tnsp.org


-----------------------------------------------------------------------------


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. Many
parts can be disabled during compile-time from config.mak

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.6 or later
 - GNU binutils
 - GNU Make
 - pkg-config

You will also want these libraries:

 - libSDL 2.0
 - zlib
 - libPNG 1.2 and development headers (more optional,
   only required for PNG write and read support by some
   utilities.)
 - SDL2_ttf for libSDL2 (optional, required for some things)
 - Tremor (integer-based Ogg Vorbis decoder) + libogg

And the demo editor framework requires (but it is not yet
usable anyway, so you may as well skip these):

 - Qt 5.x framework libraries


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 cross-compiled libSDL, zlib, Tremor, libogg
and libPNG. The SDL-related stuff for MinGW can be found from
libSDL's website, though some things you may need to cross-compile
yourself. 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 optimize the
module and even strip out various parts, such as complete instruments
(leaving only pattern data), sample data, sample instruments, etc.


dumpmod
-------
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" and converting various graphics in plain
ASCII, or ANSI colored output, or into various image formats
(including PNG, PCX, PPM, IFF ILBM and RAW/ARAW files).

Input can also 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)

64vw
----
Compiled only if libSDL support is enabled. Can be used to
display various C64 image file formats.


-----------------------------------------------------------------------------


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
-------

Convert IFF ILBM format image to RGBA/32bit PNG:

$ gfxconv -o output.png input.lbm


Convert IFF ILBM format image to indexed/paletted PNG:

$ gfxconv -o output.png input.lbm -P


Convert DrazPaint format C64 bitmap image to indexed/paletted PNG:

$ gfxconv -o output.png input.drp -P


Convert DrazPaint format C64 bitmap image to unpacked Koala Painter format:

$ gfxconv -o output.kla input.drp

NOTE: Desired output format is detected from the filename extension,
but if you wish to use "non-standard" filename(s), you can specify the
output format via option "-f", e.g. "-f kla", "-f png" etc.


Image input to C64 char font conversion:

$ gfxconv font16x16.pcx -o font16x16.chr

 - Input file "font16x16.pcx" is a 2-color indexed/paletted PCX image,
   containing a 16x16 pixel font.

"Chr" (.chr or "-f chr") specifies conversion to c64 char memory format,
gfxconv splits the input image to 8x8 blocks, outputting them in sequence
to the output file.


Convert input image to IFFMaster ARAW + assembler include file,
while remapping some palette entries:

$ gfxconv -R "#000000:0" -f araw -B 3 input.png -o output.raw

 - "-R #000000:0" remaps all input image palette colors matching RGB
   hex triplet #000000 to palette index 0.
 - "-f araw" specifies output format to be IFFMaster ARAW.
 - "-B 3" _clamps_ output to be 3 bitplanes. Any bits above those are
   simply discarded.
 - The assembler include file will be "output.inc" in this case.


Single color C64 char font to PNG image conversion:

$ gfxconv chars1.fnt -i chr:sc -s 2 -S 4 -m 255,1 -n 256 -o chars1.png

 - Input file is "chars1.fnt"
 - "-i chr:sc" specifies that input is interpreted as single color chars.
 - "-s 2" skips first two bytes of the input file (loading address)
 - "-S 4" scales output image to be 5 times larger
 - "-m 255,1" defines background color (bit value 0) to be transparent
   (255, only works for PNG) and foreground to be C64 color 1 (white)
 - "-n 256" specifies that up to 256 items (characters) worth of data
   from input will be processed.

By default the output image will be "vertical", e.g. each character will
be subsequently below previous. If you specify a width via "-w <n>" option,
the output will be <n> items (characters) wide, extending down as many rows
as it will take to fill "-n 256" items.


Extract sprites from a C64 memory dump, convert to PNG:

$ gfxconv bub_dump.raw -i spr:mc -s 0x5800 -n 20 -f png -o bub \
  -q -S 3 -m 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 spr:mc" sets input to be interpreted as multicolor 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.
 - "-f png" sets output format to PNG, required because next option
   does not specify a filename extension.
 - "-o bub" sets filename prefix to "bub"
 - "-q" selects sequential output (separate files)
 - "-m 255:2:5:1" sets the multicolor color mappings
   (255 is the transparency color again)


Dump ANSI colour ASCII output of the same dump file as above:

$ gfxconv bub_dump.raw -i spr:mc -s 0x5800 -n 5 -f ansi

  - "-f ansi" sets output format to ANSI


Dump as character data into stdout, skipping 2 bytes at start, and
limit output to 3 items (characters).

$ gfxconv chars3.fnt -i chr:sc -s 2 -n 3


---- : -------------- #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 : ........


-----------------------------------------------------------------------------