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