Apple-2-SW
/
fdraw
mirror of https://github.com/fadden/fdraw.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
fdraw/docs/demos.md

7.0 KiB
Raw Permalink Blame History

fdraw Demo README

The fdraw distribution comes with a handful of demonstration programs. Most of them are written in Applesoft BASIC, and use the amperfdraw interface. This is a somewhat poor way to demonstrate animation performance, as Applesoft adds a tremendous amount of overhead, but it is the only way to show what you can do with Applesoft.

The easiest way to run them is with the "DEMO" program, which scans the DEMOS directory for BASIC programs and presents a list. You can also just run them directly.

  • INTRO : Sort of a "hello, world" for fdraw. Mix of single- and double-buffered animation.

  • CIRCULAR : Draws lots of circles.

  • RECTSPLAT : Draws lots of rectangles.

  • CUBIC : Draws a spinning wireframe 3D cube. (The 3D coordinates are pre-computed -- fdraw doesn't do matrix transforms.)

  • TUNNEL : Animates circles to simulate driving through a tunnel.

  • LINEAR : Draws lots of lines. The wipes show speed differences for horizontal and vertical special cases, while the circular spinner shows HPLOT is not as fast as &HPLOT which is not as fast as &PLOT for a set of lines at a variety of angles.

  • LINE.DIFF : Draws several lines with the ROM routines and fdraw side-by-side to illustrate the difference in line style.

  • CLEARLY : Clears the screen 32 times, 4 sets in each of the 8 colors. The first round is done with the Applesoft ROM routine ("CALL 62454"), the second round uses the fdraw &CLEAR function.

  • HRFAN : A simple line-art demo, using "xdraw" DrawLine with lines in different colors. Not a great demo, as the Applesoft code driving it is rather slow, but it looks pretty good if you bump up the emulation speed or switch to IIgs "fast" mode. (This deserves a conversion to assembly language.)

  • BRIAN.THEME.ORI : The Brian's Theme demo from the DOS 3.3 System Master. Unmodified except for integration with the demo menu system, and with the bug on line 31112 fixed.

  • BRIAN.THEME.NEW : The Brian's Theme demo with '&' placed in front of the various draw calls. There isn't a huge difference in speed, as there's a lot of overhead from Applesoft, but its interesting to note the change in the appearance of the lines.

  • WIGGLE : Sample program that shows direct use of rasterization tables.

When the demos are launched from the menu, they will assume that fdraw is already loaded and won't try to load it again. If you run the demo program directly, it will try to load FDRAW.FAST and AMPERFDRAW from the parent directory before doing any drawing.

Extras

The EXTRAS directory has some additional software that isn't "officially" part of fdraw, but may be of use.

NOTE: some of these assume fdraw and amperfdraw are already loaded, and will hang if not. Run DEMO and hit <esc> before running these.

  • ARRAY.EXAMPLE : The &PLOT example from the documentation.

  • XDRAW.ANIM : A demonstration of line animation using "xdraw" mode and a simple shape that is drawn twice by a single &PLOT call. One copy is offset by 2 pixels, so each &PLOT call erases the previous copy and draws a new copy 2 pixels to the right. The animation is shown twice, once with "erase all, draw all", and once with the erase and draw calls interleaved for every line.

  • LINEFONT : Program for creating draw-array tables for text phrases. Used to create data files for the "intro" demo. See the "LINEFONT Details" section for more information.

  • DAVIEWER: Views the contents of .DA files created by LINEFONT.

  • BENCHCLEAR : Calls the "clear" function 256 times from a small assembly-language program. Handy for benchmarks, but slightly silly since it's relatively easy to calculate the exact cycle cost.

LINEFONT Details

NOTE: this program is an unfinished rough cut ("pre alpha"), used for preparing data for demos.

The program includes a font definition, routines for displaying characters, and code for generating and exporting pre-rendered strings.

Character vertices are expressed as floating-point values. The baseline is at zero, the peak ascent is at 1.0, the lowest descent is -1.0. The leftmost pixel is at zero, the maximum value for the rightmost pixel is 1.0. Characters don't have to fill out the entire cell -- proportionally-spaced fonts are supported -- but they are expected to start at the left edge.

So a capital 'M' might look like this:

0.0,0.0 -> 0.0,1.0 -> 0.5,0.7 -> 1.0,1.0 -> 1.0,0.0

There is currently no "user interface", unless the "user" can program in Applesoft BASIC. To generate strings, add a series of statements that set variables and call 20000 to add rendered strings to the set. The relevant variables are:

  • S$ - string to add
  • DW - desired width, in pixels, of a cell 1.0 units wide
  • DH - desired height, in pixels of a cell 2.0 units high (ascent + descent)
  • IS% - inter-character spacing, in pixels
  • SW% - width of the space character (usually same as DW)
  • MO% - monospace flag; if nonzero, all chars are treated as 1.0 units wide

Remove the REM from the start of line 1010 to enable the character viewer. At present only a couple of lower-case letters are defined.

LINEFONT Output

The LINEFONT program outputs a binary blob that can be passed to the &PLOT array-draw function. The file structure is:

+0  byte - number of array sets in the list.
+1  2 bytes * N - table of offsets to individual array sets.  One of
    these per array set.  The value is the offset from the start of the
    file.

(2N+1) array set #1:
+0  byte - number of vertices (0-127)
+1  byte - number of index pairs (0-127)
+2  2 bytes * V - vertices (values are signed X/Y)
+X  2 bytes * I - index pairs (values are 0-127)

To display phrase #3, you would get the 16-bit value from the offset table with PEEK(start + 1 + 3 * 2) + PEEK(start + 2 + 3 * 2) * 256. You get the number of vertices from PEEK(start + offset), and the number of index pairs from PEEK(start + offset + 1). Finally, call the array-draw function with:

VA = start + offset + 2
IA = VA + num_vertices * 2
&PLOT va, ia, num_index_pairs

The 0,0 point in the blob is in the center of the phrase horizontally (which allows a maximum width of 255 pixels), and at the font baseline vertically (so most of the font will appear above the zero point, but descenders will extend below).

Future Enhancements

Right now the font definition is embedded in the program. This takes up a lot of space -- before too long the BASIC program is going to intrude on the hi-res page -- and is unnecessarily restrictive. The font should be defined by a separate program, and BSAVEd into a line-font file that LINEFONT can load.

Generating strings should be menu-driven and interactive, rather than requiring manual changes to the code to fiddle with sizes and spacing. DAVIEWER should be folded into the generation program (though it's kind of handy as a simple example of how to unpack and access content).