Mercurial > hg > dmlib
annotate README.txt @ 1868:4bb3d10328a9
Update gfxconv usage examples.
author | Matti Hamalainen <ccr@tnsp.org> |
---|---|
date | Sun, 24 Jun 2018 17:35:32 +0300 |
parents | 9dced5352f70 |
children | cdf95a4d5282 |
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 ----------------------------------------------------------------------- | |
862 | 15 |
470 | 16 Programmed and designed by Matti Hämäläinen (ccr/TNSP) |
1599 | 17 (C) Copyright 2002-2018 Tecnic Software productions (TNSP) |
890
6a2a286f3d70
Remove license duplicate from README.
Matti Hamalainen <ccr@tnsp.org>
parents:
882
diff
changeset
|
18 Please see the file "COPYING" for license. |
425 | 19 |
20 Contact | |
21 ======= | |
22 IRC : ccr @ IRCNet, sometimes also Freenode | |
23 e-mail : ccr@tnsp.org | |
24 | |
862 | 25 |
425 | 26 ----------------------------------------------------------------------- |
27 | |
862 | 28 |
425 | 29 So, what is this? |
30 ================= | |
31 Basically .. a bunch of more and/or less random stuff. dmlib in | |
32 itself is a library with various things useful in demo programming. | |
33 There is a resource management subsystem, functions for loading | |
34 PNG and JPEG images. Software blitted and scaled sprites, etc. | |
35 Bitmap font routines. A XM module replayer. | |
36 | |
37 And a work-in-progress timeline-supporting demo framework, with | |
38 a Qt based GUI editor. | |
39 | |
40 And graphics converter and displayer for various restricted formats, | |
41 such as C64/VIC-20 characters, bitmaps, sprites, etc. | |
42 | |
43 .. So, yeah. There are many things in here. It's a junkyard of various | |
882 | 44 demo- or such development related pieces of code and utilities. Many |
45 parts can be disabled during compile-time from config.mak | |
425 | 46 |
47 Most modules can be enabled or disabled, per project basis via | |
48 compile-time configuration in config.mak. | |
49 | |
862 | 50 |
425 | 51 ----------------------------------------------------------------------- |
52 | |
862 | 53 |
425 | 54 Requirements |
55 ============ | |
56 The compilation and usage of these utilities requires following | |
57 software packages or functional equivalents installed: | |
58 | |
1354
a333081090ea
Documentation adjustments.
Matti Hamalainen <ccr@tnsp.org>
parents:
1277
diff
changeset
|
59 - GCC 4.6 or later |
425 | 60 - GNU binutils |
61 - GNU Make | |
62 - pkg-config | |
63 | |
862 | 64 You will also want these libraries: |
425 | 65 |
1557
5e5f75b45f8d
Initial port to SDL2. Many things will not work now.
Matti Hamalainen <ccr@tnsp.org>
parents:
1356
diff
changeset
|
66 - libSDL 2.0 |
882 | 67 - zlib |
425 | 68 - libPNG 1.2 and development headers (more optional, |
69 only required for PNG write and read support by some | |
70 utilities.) | |
1558 | 71 - SDL2_ttf for libSDL2 (optional, required for some things) |
425 | 72 - Tremor (integer-based Ogg Vorbis decoder) + libogg |
73 | |
862 | 74 And the demo editor framework requires (but it is not yet |
75 usable anyway, so you may as well skip these): | |
425 | 76 |
1558 | 77 - Qt 5.x framework libraries |
425 | 78 |
79 | |
80 For Linux -> Win32/64 cross-compilation I have used the standard | |
81 MinGW packages from Debian Testing (wheezy): | |
82 | |
83 gcc-mingw-w64 mingw-w64-i686-dev mingw-w64-x86-64-dev | |
84 | |
1558 | 85 with the additions of cross-compiled libSDL, zlib, Tremor, libogg |
86 and libPNG. The SDL-related stuff for MinGW can be found from | |
87 libSDL's website, though some things you may need to cross-compile | |
88 yourself. YMMV. | |
425 | 89 |
90 Please don't ask me for help to get cross-compilation working. | |
91 | |
862 | 92 |
425 | 93 ----------------------------------------------------------------------- |
94 | |
862 | 95 |
425 | 96 How to build |
97 ============ | |
98 1) $ cp config.mak.in config.mak | |
99 | |
100 2) Edit config.mak to enable/disable desired options. | |
101 Make sure you have the required depencies. | |
102 | |
103 3) $ gmake | |
104 or, if cross-compiling to Win32 via MinGW | |
105 $ gmake -f Makefile.w32 | |
106 | |
107 4) If it works -> Happy fun times \:D\ | |
108 | |
862 | 109 |
425 | 110 ----------------------------------------------------------------------- |
111 | |
882 | 112 |
425 | 113 Included utilities |
114 ================== | |
115 | |
116 xm2jss | |
117 ------ | |
118 Convert XM modules to internal JMOD format. You can optionally | |
1354
a333081090ea
Documentation adjustments.
Matti Hamalainen <ccr@tnsp.org>
parents:
1277
diff
changeset
|
119 optimize the module and even strip out various parts, such as |
a333081090ea
Documentation adjustments.
Matti Hamalainen <ccr@tnsp.org>
parents:
1277
diff
changeset
|
120 complete instruments (leaving only pattern data), sample data, |
a333081090ea
Documentation adjustments.
Matti Hamalainen <ccr@tnsp.org>
parents:
1277
diff
changeset
|
121 sample instruments, etc. |
425 | 122 |
123 | |
945
47f111643745
Viewmode utility was renamed to dumpmod, so reflect that change in the
Matti Hamalainen <ccr@tnsp.org>
parents:
890
diff
changeset
|
124 dumpmod |
425 | 125 ------- |
126 Simple XM/JMOD viewer. Dumps selected parts into stdout | |
127 as text format data. | |
128 | |
129 | |
130 ppl | |
131 --- | |
132 A simple XM/JMOD player with SDL-based UI. | |
133 | |
134 testpl | |
135 ------ | |
136 Even simpler player, with no UI at all. Uses SDL for audio. | |
137 | |
138 mod2wav | |
139 ------- | |
140 Render XM/JMOD modules into WAV files. | |
141 | |
142 | |
143 packed | |
144 ------ | |
145 Manipulate DMPACK files. Basically a bit like ZIP archive, | |
146 for glueing resource files into a zlib-compressed blob. | |
147 The dmlib resource subsystem can utilize these files. | |
148 | |
149 fontconv | |
150 -------- | |
151 Convert bitmap fonts. | |
152 | |
153 | |
154 objlink | |
155 ------- | |
156 Simple, but versatile commandline utility for combining binary | |
157 files into one file. Understands 2-byte loading address PRG | |
158 style files, and raw data. "Loading addresses" can be specified | |
159 and overridden. The utility also checks for overlaps, etc. | |
160 | |
161 data2inc | |
162 -------- | |
163 Simple data file to C/ASM source converter. | |
164 | |
165 gfxconv | |
166 ------- | |
450
acea24b77bdc
Update documentation a bit.
Matti Hamalainen <ccr@tnsp.org>
parents:
425
diff
changeset
|
167 Utility for "dumping" and converting various graphics in plain |
acea24b77bdc
Update documentation a bit.
Matti Hamalainen <ccr@tnsp.org>
parents:
425
diff
changeset
|
168 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
|
169 (including PNG, PCX, PPM, IFF ILBM and ARAW files). |
425 | 170 |
1794 | 171 Input can also be interpreted as bitmap, sprite or character data, |
425 | 172 in multicolor or single color. Colors can be mapped as desired. |
173 Image file output can be either single image (with chars/sprites | |
174 placed vertically if input is char/sprite data), or in separate | |
175 files. | |
176 | |
177 (Note: PNG support is a compile-time option) | |
178 | |
1794 | 179 64vw |
180 ---- | |
425 | 181 Compiled only if libSDL support is enabled. Can be used to |
1794 | 182 display various C64 image file formats. |
425 | 183 |
862 | 184 |
425 | 185 ----------------------------------------------------------------------- |
186 | |
862 | 187 |
425 | 188 Examples |
189 ======== | |
190 | |
191 data2inc | |
192 -------- | |
193 To convert a data file to a C structure using 'uint8_t' as type: | |
194 | |
195 $ data2inc -C -n variable_name -t uint8_t input.bin output.h | |
196 | |
197 | |
198 objlink | |
199 ------- | |
200 $ objlink -o intro.tmp -pppp intro.o gfx/dkdlogo2.drp:0x3800 \ | |
201 muzak.prg gfx/chars_4.fnt:0x6800 | |
202 | |
203 - "-o intro.tmp" sets output file | |
204 - As you can see, short options can be combined, like "-pppp". | |
205 However, the next parameters must be the corresponding option | |
206 arguments, in correct order, if any. | |
207 - It is possible to specify a overriding loading address via | |
208 ":<addr>" syntax. See the help for more information. | |
209 | |
210 | |
211 gfxconv | |
212 ------- | |
491 | 213 |
1868
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
214 Convert IFF ILBM format image to RGBA/32bit PNG: |
1356
e55426a0a010
Add another gfxconv example.
Matti Hamalainen <ccr@tnsp.org>
parents:
1354
diff
changeset
|
215 |
e55426a0a010
Add another gfxconv example.
Matti Hamalainen <ccr@tnsp.org>
parents:
1354
diff
changeset
|
216 $ gfxconv -f png -o output.png input.lbm |
e55426a0a010
Add another gfxconv example.
Matti Hamalainen <ccr@tnsp.org>
parents:
1354
diff
changeset
|
217 |
e55426a0a010
Add another gfxconv example.
Matti Hamalainen <ccr@tnsp.org>
parents:
1354
diff
changeset
|
218 |
1868
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
219 Convert IFF ILBM format image to indexed/paletted PNG: |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
220 |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
221 $ gfxconv -f png -o output.png input.lbm -P |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
222 |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
223 |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
224 Convert DrazPaint format C64 bitmap image to indexed/paletted PNG: |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
225 |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
226 $ gfxconv -f png -o output.png input.drp -P |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
227 |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
228 |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
229 Convert DrazPaint format C64 bitmap image to unpacked Koala Painter format: |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
230 |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
231 $ gfxconv -f kla -o output.png input.drp |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
232 |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
233 |
491 | 234 Image input to C64 char font conversion: |
235 | |
236 $ gfxconv font16x16.pcx -f chr -o font16x16.chr | |
237 | |
1868
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
238 - Input file "font16x16.pcx" is a paletted PCX image (preferably 2 colors), |
491 | 239 containing a 16x16 pixel font. |
240 - "-f chr" specifies conversion to c64 char memory format, gfxconv | |
241 splits the input image to 8x8 blocks, outputting them in sequence. | |
242 | |
243 | |
244 Convert input image to IFFMaster ARAW + assembler include file, | |
245 while remapping some palette entries: | |
246 | |
1868
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
247 $ gfxconv -R "#000000:0" -f araw -B 3 input.png -o output.raw |
491 | 248 |
249 - "-R #000000:0" remaps all input image palette colors matching RGB | |
250 hex triplet #000000 to palette index 0. | |
251 - "-f araw" specifies output format to be IFFMaster ARAW. | |
252 - "-B 3" _clamps_ output to be 3 bitplanes. Any bits above those are | |
253 simply discarded. | |
254 | |
255 | |
1868
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
256 Single color C64 char font to PNG imge conversion: |
491 | 257 |
1868
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
258 $ gfxconv chars1.fnt -i chr:sc -s 2 -S 10 -c 255:1 -f png -o chars1.png |
425 | 259 |
1868
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
260 - Input file is "chars1.fnt" |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
261 - "-i chr:mc" specifies that input is interpreted as single color chars. |
425 | 262 - "-s 2" skips first two bytes of the input file (loading address) |
263 - "-S 10" scales output image to be 10 times larger | |
264 - "-c 255:1" defines background color (bit value 0) to be transparent | |
265 (255, only works for PNG) and foreground to be C64 color 1 (white) | |
266 - "-f png" sets output format to PNG | |
267 | |
268 | |
491 | 269 Extract sprites from a C64 memory dump, convert to PNG: |
270 | |
1868
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
271 $ gfxconv bub_dump.raw -i spr:mc -s 0x5800 -n 20 -f png -o bub \ |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
272 -q -S 3 -c 255:2:5:1 |
425 | 273 |
1868
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
274 - Input file "bub_dump.raw" is a raw memory dump of Bubble Bobble |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
275 extracted via VICE in game running mode. |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
276 - "-i spr:mc" sets input to be interpreted as multicolor sprite data |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
277 - "-s 0x5800" skips 0x5800 bytes, basically the memory address as the |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
278 input is a straight memory dump file. |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
279 - "-n 20" sets max item count to 20, so 20 sprites will be dumped. |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
280 - "-o bub" sets filename prefix to "bub" |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
281 - "-q" selects sequential output (separate files) |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
282 - "-c 255:2:5:1" sets the multicolor color mappings |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
283 (255 is the transparency color again) |
425 | 284 |
491 | 285 |
1868
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
286 Dump ANSI colour ASCII output of the same dump file as above: |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
287 |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
288 $ gfxconv bub_dump.raw -i spr:mc -s 0x5800 -n 5 -f ansi |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
289 |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
290 - "-f ansi" sets output format to ANSI |
425 | 291 |
1868
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
292 |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
293 Dump as character data into stdout, skipping 2 bytes at start, and |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
294 limit output to 3 items (characters). |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
295 |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
296 $ gfxconv chars3.fnt -i chr:sc -s 2 -n 3 |
4bb3d10328a9
Update gfxconv usage examples.
Matti Hamalainen <ccr@tnsp.org>
parents:
1794
diff
changeset
|
297 |
425 | 298 |
299 ---- : -------------- #0 | |
300 0002 : ........ | |
301 0003 : ..####.. | |
302 0004 : .#....#. | |
303 0005 : #..##..# | |
304 0006 : #.#....# | |
305 0007 : #..##..# | |
306 0008 : .#....#. | |
307 0009 : ..####.. | |
308 ---- : -------------- #1 | |
309 000a : ........ | |
310 000b : ...##... | |
311 000c : ..#..#.. | |
312 000d : ..####.. | |
313 000e : .##..#.. | |
314 000f : .##..#.. | |
315 0010 : .##..#.. | |
316 0011 : ........ | |
317 ---- : -------------- #2 | |
318 0012 : ........ | |
319 0013 : ..###... | |
320 0014 : ..#..#.. | |
321 0015 : ..###... | |
322 0016 : .##..#.. | |
323 0017 : .##..#.. | |
324 0018 : .####... | |
325 0019 : ........ | |
326 | |
862 | 327 |
425 | 328 ----------------------------------------------------------------------- |