From 72e6cbfc6a4b4606f11a6d5285de65238dc0dbd4 Mon Sep 17 00:00:00 2001 From: "B. Watson" Date: Wed, 9 Nov 2022 17:12:04 -0500 Subject: Added dla2csv, dla2img. Split up docs. --- README.txt | 141 ++++++++++++++++++++++++++++++++----------------------------- 1 file changed, 74 insertions(+), 67 deletions(-) (limited to 'README.txt') diff --git a/README.txt b/README.txt index 0c64a2c..ea245a6 100644 --- a/README.txt +++ b/README.txt @@ -8,23 +8,29 @@ form aggregates of such particles. For a good description of DLA, see: https://en.wikipedia.org/wiki/Diffusion_limited_aggregation -This Atari 8-bit implementation is written in 6502 assembly, using the -ca65 assembler from the cc65 suite: https://cc65.github.io/ +The original version of this was in Atari BASIC, by ChrisTOS. It can +be found at https://github.com/ctzio/DLA/ + +This assembly version is by B. Watson (urchlay@slackware.com, Urchlay +on libera.chat IRC). The code is licensed under the WTFPL: do WTF you +want with it. It's written in 6502 assembly, using the ca65 assembler +from the cc65 suite: https://cc65.github.io/ + +Also included are support tools to convert the results to CSV or +image files. + +This file explains how to use the generator and tools. Other +documentation: -Building --------- +ALGORITHM.txt - English description of what the program does. -You need a Unix/GNU like system (which might even be modern -Windows), with GNU (or possibly BSD) make, Perl 5, and the CC65 tools -installed. Provided you have all that, simply type "make" to assemble -the source. +BUILD.txt - Instructions for building from source. Most users won't +want or need to do this, since Atari executables are provided. -If you have trouble building on Linux, ask me for help. If you have -trouble on other OSes, ask someone who actually knows about your OS -(not me, I don't do Windows or Mac). +NOTES.txt - Technical details about the implementation. -Running -------- +Using dla.xex +------------- The executable is called "dla.xex", and is a standard Atari binary load file. It can be run in the same way you run any other .xex files, @@ -45,14 +51,10 @@ center of the screen. Other seeds generate different types of image, and run faster than the dot; try them all. After you enter the seed type, the screen will clear and go solid -black, while the image is generated. The ANTIC chip's DMA is disabled, -to speed things up. However, you can "peek" at the progress of the -generator by holding down the Start key. This will show the work in -progress, but it will slow things down noticeably. +black, while the image is generated. Be patient... -After the image is finished generating, the screen DMA will be turned -back on, so you can see it. The bottom line shows a menu, from which -you can choose to: +After the image is finished generating, the image will be displayed. +The bottom line shows a menu, from which you can choose to: - Save: Save the image to disk. You'll be prompted for a filename, which must be a complete filespec (examples: D:TEST.DLA, @@ -69,64 +71,69 @@ you can choose to: The only way to exit the program (for now) is to press Reset or power cycle the Atari. -Algorithm ---------- +Using dla2csv.xex (or just dla2csv) +----------------------------------- -The algorithm works like this: +This program operates almost identically whether it's running on an +Atari or a modern machine. -1. The initial "seed" pixels are drawn. +First, you will be prompted for an input filename. On the Atari, you +must include the drive specifier (e.g. D:TEST.DLA or D2:FOO.DLA). This +must be a file created by the Save option in dla.xex. The file is read +into memory immediately. -2. Each particle starts on the edge of a circle whose center is the -center of the screen. The circle's radius depends on the number of -particles that have been rendered so far: radius is 15 for particles 1 -to 100, 30 for particles 101 to 300, 45 for particles 301 to 600, and -75 for particles 601 and up. +Next, choose the line-ending type. Choices are Atari, Unix, and MS +(aka MS-DOS or Windows). Choose the system under which you'll be +actually using the CSV file. -3. Walk the particle around randomly. For each step, pick a random one -of the 4 cardinal directions (no diagonals). +Next, you're asked for the output filename. On the Atari, this must +include the drive specifier (e.g. D:OUTPUT.CSV). This file will be +overwritten if it exists (unless of course it can't be overwritten due +to permissions or the Atari locked-file bit). -4. If the particle goes "out of bounds" (see below), respawn it and -try again (without incrementing the particle counter). +Next, the conversion process starts. This takes about one minute on +the Atari, and is instantaneous on a modern machine. Progress is shown +as a percentage. When it's finished, the output CSV file has been +written. -5. If the particle is ever adjacent to a set pixel, it gets stuck -there, the particle counter is incremented, and we go back to step 2. +Last, you're asked whether to convert another file. Answering N here +will exit the program. On the Atari, you should be returned to the DOS +menu or prompt, but your mileage may vary (it works on DOS 2.0S, at +least). Answering Y (or just pressing Return) starts the whole process +over at the input filename prompt. -When the particle counter reaches the max (the number the user -entered), the process is complete. +Using dla2img.sh +---------------- -Notes ------ +This is a shell script that calls ImageMagick's "magick" binary. For +it to work, you'll have to install your OS's image-magick package(s) +(or whatever it's actually called), or (I suppose) compile your own +ImageMagick from source (not recommended). -It should be possible to optimize this a bit further, maybe shave -another 5% to 10% off the run time. +Run dla2img.sh from a terminal (a shell). The script has built-in +help, which can be viewed by running it with no arguments. -There might be a quick way to limit the particles' movement outside -the initial circle's radius. Right now, it's limited to a square area; -width and height are the diameter of the circle plus 10 pixels. The -corners of this square waste a lot of time; it'd be better to come up -with a way to do an octagon (the square with the corners cut off), -which shouldn't slow down the inner loop too much... I actually did -implement this, but it was too slow (the time spent in calculations -was longer than the time saved by doing them). +Examples: -Tech stuff: rather than calculate points on a circle in asm code, -the tables of points for the 4 circle sizes are pre-calculated by a -perl script and included in the executable verbatim. The tables bloat -the code some (2KB), but the speed boost is well worth it. Also, the -graphics mode used is "graphics 8", but in ANTIC narrow playfield -mode, so the X resolution is 256... meaning I don't need two bytes -for the X cursor position (which saves a good bit of time). The code -that plots pixels doesn't use CIO to do so (it writes directly to the -screen memory), which also saves time. There's no floating point math -in the generation process: if there were, the asm version wouldn't be -all that much faster than the BASIC one... +# convert TEST.DLA to a 256x170 PNG image: +./dla2img.sh TEST.DLA test.png -Author ------- +# as above, but automatically crop the black borders: +./dla2img.sh TEST.DLA test.png -trim -The original version of this was in Atari BASIC, by ChrisTOS. It can -be found at https://github.com/ctzio/DLA/ +# other image types are supported ("magick -list format" to see them all): +./dla2img.sh TEST.DLA test.bmp +./dla2img.sh TEST.DLA test.jpg +./dla2img.sh TEST.DLA test.tiff -This assembly version is by B. Watson (urchlay@slackware.com, Urchlay -on libera.chat IRC). The code is licensed under the WTFPL: do WTF you -want with it. +If the conversion succeeds, there is no output in the terminal (no +news is good news). If you get a "magick: command not found" error, +you don't have ImageMagick installed correctly. + +If your magick binary is in a non-standard location (not in the +shell's $PATH), you can run it as e.g.: + +MAGICK=/path/to/magick ./dla2img.sh [arguments] + +dla2img.sh has been tested with various shells, including bash, zsh, ksh93, +mksh, and dash. -- cgit v1.2.3