Mercurial > hg > dmlib

comparison README.txt @ 425:aa5f28c2cde1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add README.
author Matti Hamalainen <ccr@tnsp.org>
date Sat, 03 Nov 2012 09:19:38 +0200
parents
children acea24b77bdc
comparison
equal deleted inserted replaced
424:e88b2993801c 425:aa5f28c2cde1
1 -----------------------------------------------------------------------
2
3 T N S P
4 - --==============-- -
5
6 ###### ### ## ### ### ######
7 # ### ## #### ### ### ### ### ## #
8 # # ### ## ######## ### ### ###### # #
9 # ### ## ### # ## ### ### ### ## #
10 ###### ### ## ###### ### ######
11
12 Demo engine / development and utility framework
13
14 -----------------------------------------------------------------------
15 Programmed by Matti Hämäläinen (ccr/TNSP^PWP)
16 (C) Copyright 2002-2012 Tecnic Software productions (TNSP)
17
18 Contact
19 =======
20 IRC : ccr @ IRCNet, sometimes also Freenode
21 e-mail : ccr@tnsp.org
22
23 -----------------------------------------------------------------------
24
25 Redistribution and use in source and binary forms, with or without
26 modification, are permitted provided that the following conditions
27 are met:
28
29 1. Redistributions of source code must retain the above copyright
30 notice, this list of conditions and the following disclaimer.
31
32 2. Redistributions in binary form must reproduce the above copyright
33 notice, this list of conditions and the following disclaimer in
34 the documentation and/or other materials provided with the
35 distribution.
36
37 3. The name of the author may not be used to endorse or promote
38 products derived from this software without specific prior written
39 permission.
40
41 THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR
42 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
43 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
44 ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
45 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
46 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
47 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
48 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
49 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
50 IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
51 POSSIBILITY OF SUCH DAMAGE.
52
53 -----------------------------------------------------------------------
54
55 So, what is this?
56 =================
57 Basically .. a bunch of more and/or less random stuff. dmlib in
58 itself is a library with various things useful in demo programming.
59 There is a resource management subsystem, functions for loading
60 PNG and JPEG images. Software blitted and scaled sprites, etc.
61 Bitmap font routines. A XM module replayer.
62
63 And a work-in-progress timeline-supporting demo framework, with
64 a Qt based GUI editor.
65
66 And graphics converter and displayer for various restricted formats,
67 such as C64/VIC-20 characters, bitmaps, sprites, etc.
68
69 .. So, yeah. There are many things in here. It's a junkyard of various
70 demo- or such development related pieces of code and utilities. Some
71 people will probably consider many of these things useless, and I
72 could not care less. Some may find useful things .. and in fact,
73 you don't _need_ to use everything here.
74
75 Most modules can be enabled or disabled, per project basis via
76 compile-time configuration in config.mak.
77
78 -----------------------------------------------------------------------
79
80 Requirements
81 ============
82 The compilation and usage of these utilities requires following
83 software packages or functional equivalents installed:
84
85 - GCC 4.x or later (4.6.3 and 4.7.1 used in development.)
86 - GNU binutils
87 - GNU Make
88 - pkg-config
89 - zlib
90
91 You probably also want:
92
93 - libSDL 1.2, preferably a current version.
94 - libPNG 1.2 and development headers (more optional,
95 only required for PNG write and read support by some
96 utilities.)
97 - SDL_ttf 2.0 and libfreetype2
98 - Tremor (integer-based Ogg Vorbis decoder) + libogg
99
100 And the demo editor framework requires:
101
102 - Qt 4.x framework libraries (tested with 4.7 and 4.8.2)
103 - qmake, moc
104
105
106 For Linux -> Win32/64 cross-compilation I have used the standard
107 MinGW packages from Debian Testing (wheezy):
108
109 gcc-mingw-w64 mingw-w64-i686-dev mingw-w64-x86-64-dev
110
111 with the additions of self- cross-compiled libSDL, zlib, Tremor,
112 liboff and libPNG. Some of those require a bit of poking to get
113 working properly, YMMV.
114
115 Please don't ask me for help to get cross-compilation working.
116
117 -----------------------------------------------------------------------
118
119 How to build
120 ============
121 1) $ cp config.mak.in config.mak
122
123 2) Edit config.mak to enable/disable desired options.
124 Make sure you have the required depencies.
125
126 3) $ gmake
127 or, if cross-compiling to Win32 via MinGW
128 $ gmake -f Makefile.w32
129
130 4) If it works -> Happy fun times \:D\
131
132 -----------------------------------------------------------------------
133
134 Included utilities
135 ==================
136
137 xm2jss
138 ------
139 Convert XM modules to internal JMOD format. You can optionally
140 even strip out various parts, such as complete instruments
141 (leaving only pattern data), sample data, sample instruments,
142 etc.
143
144
145 viewmod
146 -------
147 Simple XM/JMOD viewer. Dumps selected parts into stdout
148 as text format data.
149
150
151 ppl
152 ---
153 A simple XM/JMOD player with SDL-based UI.
154
155 testpl
156 ------
157 Even simpler player, with no UI at all. Uses SDL for audio.
158
159 mod2wav
160 -------
161 Render XM/JMOD modules into WAV files.
162
163
164 packed
165 ------
166 Manipulate DMPACK files. Basically a bit like ZIP archive,
167 for glueing resource files into a zlib-compressed blob.
168 The dmlib resource subsystem can utilize these files.
169
170 fontconv
171 --------
172 Convert bitmap fonts.
173
174
175 objlink
176 -------
177 Simple, but versatile commandline utility for combining binary
178 files into one file. Understands 2-byte loading address PRG
179 style files, and raw data. "Loading addresses" can be specified
180 and overridden. The utility also checks for overlaps, etc.
181
182 data2inc
183 --------
184 Simple data file to C/ASM source converter.
185
186 gfxconv
187 -------
188 Utility for "dumping" some C64 (and similar) graphics in plain
189 ASCII, or ANSI colored output, or into PNG, PCX or PPM files.
190
191 Input can be interpreted as bitmap, sprite or character data,
192 in multicolor or single color. Colors can be mapped as desired.
193 Image file output can be either single image (with chars/sprites
194 placed vertically if input is char/sprite data), or in separate
195 files.
196
197 (Note: PNG support is a compile-time option)
198
199 view64
200 ------
201 Compiled only if libSDL support is enabled. Can be used to
202 display C64 bitmaps.
203
204 -----------------------------------------------------------------------
205
206 Examples
207 ========
208
209 data2inc
210 --------
211 To convert a data file to a C structure using 'uint8_t' as type:
212
213 $ data2inc -C -n variable_name -t uint8_t input.bin output.h
214
215
216 objlink
217 -------
218 $ objlink -o intro.tmp -pppp intro.o gfx/dkdlogo2.drp:0x3800 \
219 muzak.prg gfx/chars_4.fnt:0x6800
220
221 - "-o intro.tmp" sets output file
222 - As you can see, short options can be combined, like "-pppp".
223 However, the next parameters must be the corresponding option
224 arguments, in correct order, if any.
225 - It is possible to specify a overriding loading address via
226 ":<addr>" syntax. See the help for more information.
227
228
229 gfxconv
230 -------
231 $ gfxconv chars1.fnt -i char -s 2 -S 10 -c 255:1 -f png -o chars1.png
232
233 - Input file "chars1.fnt" is interpreted as character data (-i char)
234 - "-s 2" skips first two bytes of the input file (loading address)
235 - "-S 10" scales output image to be 10 times larger
236 - "-c 255:1" defines background color (bit value 0) to be transparent
237 (255, only works for PNG) and foreground to be C64 color 1 (white)
238 - "-f png" sets output format to PNG
239
240
241 $ gfxconv bub_dump.raw -i s -s 0x5800 -n 20 -f png -o bub \
242 -q -S 3 -m -c 255:2:5:1
243
244 - Input file "bub_dump.raw" is a raw memory dump of Bubble Bobble
245 extracted via VICE in game running mode.
246 - "-i s" sets input to be interpreted as sprite data
247 - "-s 0x5800" skips 0x5800 bytes, basically the memory address as the
248 input is a straight memory dump file.
249 - "-n 20" sets max item count to 20, so 20 sprites will be dumped.
250 - "-o bub" sets filename prefix to "bub"
251 - "-q" selects sequential output (separate files)
252 - "-m" selects multicolor input
253 - "-c 255:2:5:1" sets the multicolor color mappings
254 (255 is the transparency color again)
255
256 $ gfxconv chars3.fnt -i c -s 2 -n 3
257
258 Dump as character data into stdout, skipping 2 bytes at start, and
259 limit output to 3 items (characters).
260
261 ---- : -------------- #0
262 0002 : ........
263 0003 : ..####..
264 0004 : .#....#.
265 0005 : #..##..#
266 0006 : #.#....#
267 0007 : #..##..#
268 0008 : .#....#.
269 0009 : ..####..
270 ---- : -------------- #1
271 000a : ........
272 000b : ...##...
273 000c : ..#..#..
274 000d : ..####..
275 000e : .##..#..
276 000f : .##..#..
277 0010 : .##..#..
278 0011 : ........
279 ---- : -------------- #2
280 0012 : ........
281 0013 : ..###...
282 0014 : ..#..#..
283 0015 : ..###...
284 0016 : .##..#..
285 0017 : .##..#..
286 0018 : .####...
287 0019 : ........
288
289 -----------------------------------------------------------------------