Mercurial > hg > dmlib
annotate README.txt @ 805:fc26ec1d315f
Bump copyright years.
author | Matti Hamalainen <ccr@tnsp.org> |
---|---|
date | Tue, 06 May 2014 09:24:01 +0300 |
parents | a26636faa6b7 |
children | 01f2af5f87b1 |
rev | line source |
---|---|
425 | 1 ----------------------------------------------------------------------- |
2 | |
3 T N S P | |
4 - --==============-- - | |
5 | |
6 ###### ### ## ### ### ###### | |
7 # ### ## #### ### ### ### ### ## # | |
8 # # ### ## ######## ### ### ###### # # | |
9 # ### ## ### # ## ### ### ### ## # | |
10 ###### ### ## ###### ### ###### | |
11 | |
12 Demo engine / development and utility framework | |
13 | |
14 ----------------------------------------------------------------------- | |
470 | 15 Programmed and designed by Matti Hämäläinen (ccr/TNSP) |
805 | 16 (C) Copyright 2002-2014 Tecnic Software productions (TNSP) |
425 | 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 ------- | |
450
acea24b77bdc
Update documentation a bit.
Matti Hamalainen <ccr@tnsp.org>
parents:
425
diff
changeset
|
188 Utility for "dumping" and converting various graphics in plain |
acea24b77bdc
Update documentation a bit.
Matti Hamalainen <ccr@tnsp.org>
parents:
425
diff
changeset
|
189 ASCII, or ANSI colored output, or into various image formats |
458
096dae79ce2e
Add ILBM to supported list.
Matti Hamalainen <ccr@tnsp.org>
parents:
450
diff
changeset
|
190 (including PNG, PCX, PPM, IFF ILBM and ARAW files). |
425 | 191 |
192 Input can be interpreted as bitmap, sprite or character data, | |
193 in multicolor or single color. Colors can be mapped as desired. | |
194 Image file output can be either single image (with chars/sprites | |
195 placed vertically if input is char/sprite data), or in separate | |
196 files. | |
197 | |
198 (Note: PNG support is a compile-time option) | |
199 | |
200 view64 | |
201 ------ | |
202 Compiled only if libSDL support is enabled. Can be used to | |
203 display C64 bitmaps. | |
204 | |
205 ----------------------------------------------------------------------- | |
206 | |
207 Examples | |
208 ======== | |
209 | |
210 data2inc | |
211 -------- | |
212 To convert a data file to a C structure using 'uint8_t' as type: | |
213 | |
214 $ data2inc -C -n variable_name -t uint8_t input.bin output.h | |
215 | |
216 | |
217 objlink | |
218 ------- | |
219 $ objlink -o intro.tmp -pppp intro.o gfx/dkdlogo2.drp:0x3800 \ | |
220 muzak.prg gfx/chars_4.fnt:0x6800 | |
221 | |
222 - "-o intro.tmp" sets output file | |
223 - As you can see, short options can be combined, like "-pppp". | |
224 However, the next parameters must be the corresponding option | |
225 arguments, in correct order, if any. | |
226 - It is possible to specify a overriding loading address via | |
227 ":<addr>" syntax. See the help for more information. | |
228 | |
229 | |
230 gfxconv | |
231 ------- | |
491 | 232 |
233 Image input to C64 char font conversion: | |
234 | |
235 $ gfxconv font16x16.pcx -f chr -o font16x16.chr | |
236 | |
237 - Input file "font16x16.pcx" is a paletted PCX image (preferably 2-colors), | |
238 containing a 16x16 pixel font. | |
239 - "-f chr" specifies conversion to c64 char memory format, gfxconv | |
240 splits the input image to 8x8 blocks, outputting them in sequence. | |
241 | |
242 | |
243 Convert input image to IFFMaster ARAW + assembler include file, | |
244 while remapping some palette entries: | |
245 | |
246 $ gfxconv -R "#000000:0" -f araw -i image -B 3 input.png -o output.raw | |
247 | |
248 - "-R #000000:0" remaps all input image palette colors matching RGB | |
249 hex triplet #000000 to palette index 0. | |
250 - "-f araw" specifies output format to be IFFMaster ARAW. | |
251 - "-B 3" _clamps_ output to be 3 bitplanes. Any bits above those are | |
252 simply discarded. | |
253 | |
254 | |
255 C64 char font to PNG imge conversion: | |
256 | |
425 | 257 $ gfxconv chars1.fnt -i char -s 2 -S 10 -c 255:1 -f png -o chars1.png |
258 | |
259 - Input file "chars1.fnt" is interpreted as character data (-i char) | |
260 - "-s 2" skips first two bytes of the input file (loading address) | |
261 - "-S 10" scales output image to be 10 times larger | |
262 - "-c 255:1" defines background color (bit value 0) to be transparent | |
263 (255, only works for PNG) and foreground to be C64 color 1 (white) | |
264 - "-f png" sets output format to PNG | |
265 | |
266 | |
491 | 267 Extract sprites from a C64 memory dump, convert to PNG: |
268 | |
425 | 269 $ gfxconv bub_dump.raw -i s -s 0x5800 -n 20 -f png -o bub \ |
270 -q -S 3 -m -c 255:2:5:1 | |
271 | |
272 - Input file "bub_dump.raw" is a raw memory dump of Bubble Bobble | |
273 extracted via VICE in game running mode. | |
274 - "-i s" sets input to be interpreted as sprite data | |
275 - "-s 0x5800" skips 0x5800 bytes, basically the memory address as the | |
276 input is a straight memory dump file. | |
277 - "-n 20" sets max item count to 20, so 20 sprites will be dumped. | |
278 - "-o bub" sets filename prefix to "bub" | |
279 - "-q" selects sequential output (separate files) | |
280 - "-m" selects multicolor input | |
281 - "-c 255:2:5:1" sets the multicolor color mappings | |
282 (255 is the transparency color again) | |
283 | |
491 | 284 |
425 | 285 $ gfxconv chars3.fnt -i c -s 2 -n 3 |
286 | |
287 Dump as character data into stdout, skipping 2 bytes at start, and | |
288 limit output to 3 items (characters). | |
289 | |
290 ---- : -------------- #0 | |
291 0002 : ........ | |
292 0003 : ..####.. | |
293 0004 : .#....#. | |
294 0005 : #..##..# | |
295 0006 : #.#....# | |
296 0007 : #..##..# | |
297 0008 : .#....#. | |
298 0009 : ..####.. | |
299 ---- : -------------- #1 | |
300 000a : ........ | |
301 000b : ...##... | |
302 000c : ..#..#.. | |
303 000d : ..####.. | |
304 000e : .##..#.. | |
305 000f : .##..#.. | |
306 0010 : .##..#.. | |
307 0011 : ........ | |
308 ---- : -------------- #2 | |
309 0012 : ........ | |
310 0013 : ..###... | |
311 0014 : ..#..#.. | |
312 0015 : ..###... | |
313 0016 : .##..#.. | |
314 0017 : .##..#.. | |
315 0018 : .####... | |
316 0019 : ........ | |
317 | |
318 ----------------------------------------------------------------------- |