*********

Welcome to Project 64!

The goal of Project 64 is to preserve Commodore 64 related documents
in electronic text format that might otherwise cease to exist with the
rapid advancement of computer technology and declining interest in 8-
bit computers on the part of the general population. If you would like
to help by converting C64 related hardcopy documents to electronic
texts please contact the manager of Project 64, Cris Berneburg, at
pcgeek@compuserve.com.

Extensive efforts were made to preserve the contents of the original
document.  However, certain portions, such as diagrams, program
listings, and indexes may have been either altered or sacrificed due
to the limitations of plain vanilla text.  Diagrams may have been
eliminated where ASCII-art was not feasible.  Program listings may be
missing display codes where substitutions were not possible.  Tables
of contents and indexes may have been changed from page number
references to section number references. Please accept our apologies
for these limitations, alterations, and possible omissions.

Document names are limited to the 8.3 file convention of DOS. The
first characters of the file name are an abbreviation of the original
document name. The version number of the etext follows next. After
that a letter may appear to indicate the particular source of the
document. Finally, the document is given a .TXT extension.

The author(s) of the original document and members of Project 64 make
no representations about the accuracy or suitability of this material
for any purpose.  This etext is provided "as-is".  Please refer to the
warantee of the original document, if any, that may included in this
etext.  No other warantees, express or implied, are made to you as to
the etext or any medium it may be on.  Neither the author(s) nor the
members of Project 64 will assume liability for damages either from
the direct or indirect use of this etext or from the distribution of
or modification to this etext. Therefore if you read this document or
use the information herein you do so at your own risk.

*********

The Project 64 etext of the BLARG instructions, written and
copyrighted by Stephen Judd <judd@merle.acns.nwu.edu>, obtained from
usenet newsgroup comp.sys.cbm.

BLARG10.TXT, April 1997, etext #193.

*********

BLARG -- Basic Language Graphics extension

version 1.0 2/10/97

BLARG is a little BASIC extension which adds some graphics commands to
the normal C-64 BASIC.  In addition it supports the SuperCPU
optimization modes, as well as double buffering.  Finally, it is free
for use in your own programs, so feel free to do so!

My goal was to write a BASIC extension which was compact, fast, and
actually available for downloading :).  Also, something that wasn't
BASIC7.0.  It doesn't have tons of features but I deem it to be Nifty.

Anyways, these are adaptations of my algorithms from C=Hacking and
such.  They are not the most efficient implementations, but they are
fairly zippy, and fairly well beat the snot out of BASIC7.0 commands!
For instance, the times from moire3 (a line drawing test):

   Stock 64	1200 jiffies	(1X)
   SCPU Mode 17	137 jiffies	(9.1X)
   SCPU Mode 16	59 jiffies	(20.2X)
   BASIC7.0 (1MHz)	4559 jiffies	(1/3.5 X)

So lines are nearly 4x faster on a stock 64 than a 128 running
BASIC7.0.  Running in mode16 on a SuperCPU is 77 times faster than
BASIC7.0!!!

Let's not even talk about BASIC7.0 circles.  Well, what the heck,
let's talk about them :)

circletest1:
   Stock 64        360 jiffies     (1x)
   SCPU Mode 17    50 jiffies      (7x)
   SCPU Mode 16    22 jiffies      (15.4x)
   BASIC7.0        17394 j :)      1/49x

Bottom line: mode 16 circles are, if you can believe it, 790x faster
than BASIC7.0 circles (and much better looking, especially at large
radii -- BASIC7.0 circles are actually 128-sided polygons :-/  ).

The total size of the program right now is a bit over 2k, and sits at
$C000.  To install the program, just load and run.  To re-initialize
the system (after a warm reset for instance) just type SYS49152.  The
command list is located near $C000, immediately followed by the
routine addresses, in case you want to take a peek.

A second program, BLARG$8000, is included in the archive.  To use it,
load ,8,1 and type SYS32768 to initialize.  This program is included
so that it may be loaded from a BASIC program.

Several demo programs are included, and offer a good way of learning
the commands (for instance, try typing ORIGIN 10,10 before running
MOIRE3).

Words to the wise:

1 - If you use a DOS extension like JiffyDOS then be sure to enclose
filenames etc. in quotes (unless you want them to be tokenized, in
which case feel free to omit quotes).

2 - If it looks like your machine has completely frozen try typing
RUN-STOP, shift-clear, MODE 17 (Sometimes you can break the program
before it can tell VIC where the screen is located).  MODE16 and
MODE17 will always fix stuff up, whereas run/stop-restore doesn't
always do the trick.

3 - Always keep in mind that MODE 16,17, and 18 may hose string
variables.

4 - IF/THEN bypasses the IGONE vector, so a statement like IF A=0 THEN
GRON will fail.  The statement IF A=0 THEN:GRON will work fine.

Without further ado:

GRON [COLOR] -- Turns graphics on.  If the optional parameter COLOR is
        specified the bitmap is cleared and the colormap is
        initialized to that value, specifically,

        COLOR = 16*foreground color + background color

	Examples:
		GRON  -- Turn on bitmap without clearing it.
		GRON20 -- Turn on bitmap, clear, purple bg, white fg

GROFF -- Turns graphics off (sticks you back into text mode, or
	whatever mode you were in when you last called GRON)

CLEAR [color] -- Clear current graphics buffer.  CLEAR is part of
	the GRON routine, but will not set VIC or CIA#2.

COLOR n -- COLOR 1 sets the drawing color to the foreground color;
	COLOR 0 sets it to background.

ORIGIN CX, CY -- Sets the upper-left corner of the screen to have
	coordinates CX,CY.  More precisely, commands will subtract
	CX,CY from coordinates passed into it.  Among other things,
	this provides a mechanism for negative numbers to be
	handled -- LINE -10,0,40,99 will not work, but ORIGIN 10,0:
        LINE 0,0,50,99 will.  This value is initialized to (0,0)
        whenever SYS49152 is called.

PLOT X,Y -- Sticks a point at coordinates X,Y.  (Actually at
	coordinates X-XC, Y-YC).  X may be in the range 0..319
	and Y may be 0..199; points outside this range will not be
	plotted.

LINE X1,Y1,X2,Y2 -- Draws a line from X1,Y1 to X2,Y2 (subtracting
	XC,YC as necessary).  X1 may be any 16-bit value and Y2
	may be any 8-bit value.  Coordinates off of the screen will
	simply not be plotted!

CIRCLE XC,YC,R -- Draws a circle of radius R centered at XC,YC
	(translating as necessary).  The algorithm is smart and can
	handle R=0..255 correctly (as far as I know!).  I used a
	modified version of my algorithm, which makes very nice
	circles in my quite biased opinion, except for a few radii
	which come out a little ovalish.  Oh well.

MODE n -- New graphics MODE.
	MODE 16 -- SuperCPU mode.  This moves the bitmap screen to
		$A000, the colormap to $8C00, the text screen to $8800,
		and sets the SuperCPU bank 2 optimization mode.
		$9000-$9FFF is totally unused :(.
	MODE 17 -- Normal mode.  Bitmap->$E000, Colormap ->$CC00,
		text screen -> $0400.
	MODE 18 -- Double buffer mode.  MODE16 memory configuration,
		no SCPU optimization.
	MODE16, MODE17, and MODE18 reset the BASIC memtop and stringtop
	pointers, so any defined strings may get hosed.
	(They also execute GROFF, and hence turn on the text screen).
	Any other MODE parameter will be set to the BITMASK parameter.
	What is BITMASK?  Anything drawn to the screen is first ANDed
	with BITMASK.  (Try MODE 85 sometime).
	(Although these numbers are reserved for future expansion).

BUFFER n -- Set drawing buffer.
	When double-buffer mode is activated (MODE 18), both buffers
	are available for drawing and displaying.  It is then
	possible to draw in one buffer while displaying the other.
	BUFFER n selects which buffer the PLOT,LINE,CIRCLE, and CLEAR
	commands will affect.  If n=0 then it swaps the target
	buffer.  Otherwise, n=odd references the buffer at $A000
	and n=even selects the buffer at $E000.

SWAP -- Swap displayed buffer.
	Assuming MODE18 is selected, SWAP simply selects which buffer
	is displayed on the screen; specifically, it flips between
	the two.  SWAP only affects what is displayed on the
	screen; BUFFER only affects the target of the drawing commands.

*********

End of the Project 64 etext of the BLARG instructions.

*********
