@database CadOS macros
@node main "CadOS macros"
CadOS provides many useful macros for your usage.

Each macro has these entries:

Name:	The @{" name " link name} of the macro.
Args:	The @{" arguments " link args} of the macro.
Does:	What the macro @{" does " link does}.
Needs:	What the macro @{" needs " link needs} to function.
Relocs:	The amount of @{" relocs " link relocs} a macro will generate.
Type:	What @{" type " link type} of macro it is.
Exmpls:	A few @{" examples " link exmpls} of usage.

To see the macro list, it is available listed either @{" alphabetically " link macro_alpha} or
listed by @{" concept " link macro_concept}.
@endnode

@node name "The name of the macro"
This is the name of the macro, the name you use it by, in exactly the
right "case" (eg capital and small letters).
@endnode

@node args "The arguments of the macro"
These are the arguments the macro takes.

[arg1|arg2|arg3] means all, some or none of arg1, arg2 and arg3.

[arg]	means arg is optional.

(0-50)	means the argument is numerical, and must be between the range
	shown, inclusive.

"strng"	is a string argument, and you must use your assembler's method of
	passing strings as macro arguments, usually the string on its own,
	or in <angle brackets> if it has a space or comma.

If the args are "none" then there are NO ARGS, there is NOT one arg called
"none"!!!
@endnode

@node does "What the macro does"
This describes exactly what the macro actually does.
@endnode

@node needs "What the macro needs to function"
Some macros have special requirements, eg none of the timing macros will
work if you deliberately disable the int-server.
@endnode

@node relocs "The amount of relocs a macro will generate"
While CadOS is entirely pc-relative, ie it contains no absolute	addresses
that have to be filled in by the AmigaDOS loader, some of the macros DO use
absolute addresses, because not all instructions can be made pc-relative
without using a temporary register, which is usually a waste of time. So
for the macros that do generate relocs, the number of them they generate is
listed.
@endnode

@node type "What kind of macro it is"
Some macros (colour4, colour8, costab, etc) generate data. That means they
become the equivalent of "dc" commands in your source. You should use them
at a label after your code, and use them by pointing at the label in your
code, eg

GetCosine
; input: d0=angle (0-359), output: d0=cosine*4096
	move.w	cosines(pc,d0.w*2),d0
	rts
cosines	costab.w 4096,0,360

The other macros generate code. They should be used in your code.
@endnode

@node exmpls "A few examples of usage"
A few actual examples of how the macro would be used.
@endnode

@node macro_concept "The list of macros by concept"
@{b}@{u}Colour generating:@{ub}@{uu}
 @{"  " link colfade} colfade
 @{"  " link colour4} colour4
 @{"  " link colour8} colour8

@{b}@{u}DMA:@{ub}@{uu}
 @{"  " link dmaoff} dmaoff
 @{"  " link dmaon} dmaon

@{b}@{u}Loading:@{ub}@{uu}
 @{"  " link load_ch} load_ch
 @{"  " link load_fa} load_fa

@{b}@{u}Misc:@{ub}@{uu}
 @{"  " link get} get
 @{"  " link getbase} getbase
 @{"  " link lofsync} lofsync
 @{"  " link QUITDEMO} QUITDEMO
 @{"  " link QUITDEMO_FROMINT} QUITDEMO_FROMINT
 @{"  " link setcop} setcop
 @{"  " link tstlmb} tstlmb
 @{"  " link tstrmb} tstrmb
 @{"  " link vsync} vsync
 @{"  " link waitblit} waitblit

@{b}@{u}Timing:@{ub}@{uu}
 @{"  " link bumptime} bumptime
 @{"  " link ifnottime} ifnottime
 @{"  " link iftime} iftime
 @{"  " link resettime} resettime
 @{"  " link settime} settime
 @{"  " link waituntil} waituntil

@{b}@{u}Trigonometric:@{ub}@{uu}
 @{"  " link costab} costab
 @{"  " link sintab} sintab
 @{"  " link sincostab} sincostab
@endnode

@node macro_alpha "The list of macros sorted alphabetically"
 @{"  " link bumptime} bumptime
 @{"  " link colfade} colfade
 @{"  " link colour4} colour4
 @{"  " link colour8} colour8
 @{"  " link costab} costab
 @{"  " link dmaoff} dmaoff
 @{"  " link dmaon} dmaon
 @{"  " link get} get
 @{"  " link getbase} getbase
 @{"  " link ifnottime} ifnottime
 @{"  " link iftime} iftime
 @{"  " link load_ch} load_ch
 @{"  " link load_fa} load_fa
 @{"  " link lofsync} lofsync
 @{"  " link QUITDEMO} QUITDEMO
 @{"  " link QUITDEMO_FROMINT} QUITDEMO_FROMINT
 @{"  " link resettime} resettime
 @{"  " link setcop} setcop
 @{"  " link settime} settime
 @{"  " link sintab} sintab
 @{"  " link sincostab} sincostab
 @{"  " link tstlmb} tstlmb
 @{"  " link tstrmb} tstrmb
 @{"  " link vsync} vsync
 @{"  " link waitblit} waitblit
 @{"  " link waituntil} waituntil

You can also browse forward through the macros, listed alphabetically,
using your "Browse @{u}>@{uu}" button.
@endnode

@node bumptime
Name:	bumptime
Args:	TIME
Does:	sets the internal timecounter to TIME, if TIME hasn't already
	passed.
Needs:	only available if the internal interrupt server is't left out.
Relocs:	3
Type:	code
Exmpls:	bumptime 199
	bumptime 1024
@endnode

@node colfade
Name:	colfade
Args:	red1 (0-255), green1 (0-255), blue1 (0-255), red2 (0-255),
	green2 (0-255), blue (0-255), steps, method
Does:	generates a colour fade from one AGA colour to another, taking the
	specified number of steps to complete it. The 'method' is what form
	the generated data will take. Here is a table of the methods

	Method	Output
	------	-----------------
	  1	dc.b	r,g,b		; SetColourRGB style
	  2	dc.l	$00RRGGBB	; SetColour style
	  3	dc.w	$0RGB		; the old 4096 colour style

Needs:	nothing
Relocs:	0
Type:	data
Exmpls:	colfade	255,255,255,0,0,0,256,1	; creates SetColoursRGB style 256-
					; step fade from white to black.
	colfade	0,0,255,255,255,0,32,3	; fade from blue to yellow in 32
					; colours in 32 'dc.w's
@endnode

@node colour4
Name:	colour4
Args:	red (0-15), green (0-15), blue (0-15), intensity (0-15)
Does:	does a dc.w $0RGB, but with a global colour intensity
Needs:	nothing
Relocs:	0
Type:	data
Exmpls:	colour4	15,15,15,10	; creates $AAA
	colour4	15,15,15,5	; creates $555
	colour4	15,15,15,1	; creates $111
	colour4	5,14,11,15	; creates $5EB
	colour4	3,9,12,15	; creates $39C
	colour4	5,4,5,15	; creates $545
@endnode

@node colour8
Name:	colour8
Args:	red (0-255), green (0-255), blue (0-255), intensity (0-255)
Does:	does a dc.l $00RRGGBB, but with a global colour intensity
Needs:	nothing
Relocs:	0
Type:	data
Exmpls:	colour8	255,255,255,255	; creates $FFFFFF
	colour8	255,255,255,127	; creates $7F7F7F
@endnode

@node costab
Name:	costab
Args:	.SIZE	amplitude, add, elements
Does:	generates a cosine array. same as this in basic:
	Dim _COS(ELEMENTS) : A=0
	For X#=0 To 2*Pi# Step (2*Pi#)/ELEMENTS
	   _COS(A)=ADD+AMPLITUDE*Cos(X#)
	   Inc A
	Next X#
Needs:	the assembler you use requires the COS, INT and REPT directives
Relocs:	0
Type:	data
Exmpls:	costab.w 159,160,512	; table is 1024 bytes long
	costab.l 32767,32768,1024	; table is 4096 bytes long
@endnode

@node dmaoff
Name:	dmaoff
Args:	[BLITTER|COPPER|RASTER|SPRITE|DISK|AUDIO]
Does:	turns any mentioned DMA sources above off. dmaoff with no args will
	turn the dma master off. doing this causes the screen display to
	glitch, so don't do it during the demo, maybe at the end.
Needs:	don't use this during an Enable period! Dangerous...
Relocs:	0
Type:	code
Exmpls:	dmaoff	BLITTER,SPRITE
	dmaoff	RASTER,COPPER,BLITTER
	dmaoff
@endnode

@node dmaon
Name:	dmaon
Args:	[BLITTER|COPPER|RASTER|SPRITE|DISK|AUDIO]
Does:	turns any mentioned DMA sources above on. dmaon with no args will
	turn the dma master on. this should be done at the beginning of a
	demo, because some music replays assume it IS switched on.
Needs:	don't use this during an Enable period! Dangerous...
Relocs:	0
Type:	code
Exmpls:	dmaon	BLITTER,SPRITE
	dmaon	RASTER,COPPER,BLITTER
	dmaon
@endnode

@node get
Name:	get
Args:	.SIZE label, addressreg
Does:	gets the variable AT label, into an addressregister eg a0. it works
	exactly like the instruction move, but it is pc-relative.
Needs:	nothing
Relocs:	0
Type:	code
Exmpls:	get.l	gfxbase,a6
	get.l	myscr,a1
@endnode

@node getbase
Name:	getbase
Args:	basename
Does:	gets a library base into a6. Any other library base you have stored
	at a label ending in "base" will work with this macro. You can also
	get the base "exec" which will become a move.l 4.w,a6 instruction.
Needs:	opened library pointer at the named label ending in "base"
Relocs:	1
Type:	code
Exmpls:	getbase	gfx
	getbase	int
	getbase	dos
	getbase	exec
@endnode

@node getbasepc
Name:	getbasepc
Args:	basename
Does:	gets a library base into a6, PC relative. See @{" getbase " link getbase}
Needs:	opened library pointer at the named label ending in "base", in the
	same hunk, and within 32k of the program counter.
Relocs:	0
Type:	code
Exmpls:	getbase	gfx
	getbase	int
	getbase	dos
	getbase	exec
@endnode

@node ifnottime
Name:	ifnottime
Args:	TIME, label
Does:	branches to label, if the timecounter is less than TIME.
Needs:	only available if the internal interrupt server isn't left out.
Relocs:	2
Type:	code
Exmpls:	ifnottime 100,_SkipPart2
	ifnottime 64*6*2,patternpassed
@endnode

@node iftime
Name:	iftime
Args:	TIME, label
Does:	branches to label if the timecounter is equal to or has passed
	TIME.
Needs:	only available if the internal interrupt server isn't left out.
Relocs:	2
Type:	code
Exmpls:	iftime	100,twosecs
	iftime	42*3,part
@endnode

@node load_ch
Name:	load_ch
Args:	"filename"
Does:	calls LoadFile for the filename given, into chip memory. Returns
	what LoadFile does, ie A0=pointer or 0 if failed, D0=length
Needs:	nothing
Relocs:	1
Exmpls:	load_ch	mod.maniac
	load_ch	<came through da window.8svx>
@endnode

@node load_fa
Name:	load_fa
Args:	"filename"
Does:	calls LoadFile for the filename given, into either chip or fast
	memory (fast preferably). Returns what LoadFile does, ie A0=pointer
	or 0 if failed, D0=length
Needs:	nothing
Relocs:	1
Exmpls:	load_fa	chunky
	load_fa	<ending scroll.txt>
@endnode

@node lofsync
Name:	lofsync
Args:	none
Does:	this waits until we are in the LOng Frame.
Needs:	nothing
Relocs:	0
Exmpls:	lofsync
@endnode

@node QUITDEMO
Name:	QUITDEMO
Args:	none
Does:	quits the demo instantly, but not from an interrupt.
Needs:	Doesn't work from an interrupt
Relocs:	1
Exmpls:	QUITDEMO	; bye ;-)
@endnode

@node QUITDEMO_FROMINT
Name:	QUITDEMO_FROMINT
Args:	none
Does:	quits the demo instantly, but only from an interrupt
Needs:	Only works in interrupt.
Relocs:	1
Exmpls:	QUITDEMO_FROMINT	; au revoir ;-)
@endnode

@node resettime
Name:	resettime
Args:	none
Does:	resets the internal timecounter to 0. The timer is also reset when
	the demo passes from an Enable period to Disable again.
Needs:	only available if the internal interrupt server isn't left out.
Relocs:	2
Exmpls:	resettime
@endnode

@node setcop
Name:	setcop
Args:	COPPER
Does:	sets the copperlist to the one referred to by COPPER. It also sets
	it as the default copper, to restart from if TakeoverScreen has to
	be called again (eg, a requester appears while loading)
Needs:	nothing
Relocs:	1, or 3 if COPPER is a label
Exmpls:	setcop	d0
	setcop	(a0)
	setcop	#$123456
	setcop	mycop
@endnode

@node settime
Name:	settime
Args:	TIME
Does:	sets the timecounter to TIME.
Needs:	only available if the internal interrupt server isn't left out.
Relocs:	2
Exmpls:	settime	100
	settime	150
@endnode

@node sintab
Name:	sintab
Args:	.SIZE	amplitude, add, elements
Does:	generates a sine array. same as this in basic:
	Dim _SIN(ELEMENTS) : A=0
	For X#=0 To 2*Pi# Step (2*Pi#)/ELEMENTS
	   _SIN(A)=ADD+AMPLITUDE*Sin(X#)
	   Inc A
	Next X#
Needs:	the assembler you use requires the SIN, INT and REPT directives
Relocs:	0
Type:	data
Exmpls:	sintab.w 159,160,512	; table is 1024 bytes long
	sintab.l 32767,32768,1024	; table is 4096 bytes long
@endnode

@node sincostab
Name:	sincostab
Args:	.SIZE	amplitude, add, elements
Does:	generates a sine array. that extends past 360°, so an entire cosine
	array is also present. you know that if you draw sin(x+90) and
	cos(x) they are the same, so the cosines are available at 90° into
	the sine array, eg 1/4 of the number of elements. same as this in
	basic:
	Dim _SIN(ELEMENTS+ELEMENTS/4) : A=0
	For X#=0 To 2*Pi#+Pi#/4 Step (2*Pi#)/ELEMENTS
	   _SIN(A)=ADD+AMPLITUDE*Sin(X#)
	   Inc A
	Next X#
Needs:	the assembler you use requires the SIN, INT and REPT directives
Relocs:	0
Type:	data
Exmpls:	sincostab.w	159,160,512	; cosptr=sinptr+(512/4)*2
	sincostab.l	159,160,512	; cosptr=sinptr+(512/4)*4
	sincostab.b	127,128,256	; cosptr=sinptr+(256/4)
@endnode

@node tstlmb
Name:	tstlmb
Args:	label
Does:	branches to label if left mouse button is pressed.
Needs:	nothing
Relocs:	0
Exmpls:	tstlmb	skip
@endnode

@node tstrmb
Name:	tstrmb
Args:	label
Does:	branches to label if right mouse button is pressed.
Needs:	nothing
Relocs:	0
Exmpls:	tstrmb	skip
@endnode

@node vsync
Name:	vsync
Args:	none
Does:	this waits for the vertical blank.
Needs:	If you disable the internal VBL server, then install your own VBL
	server, don't use this. OK to use if a) you are using the internal
	VBL server, or b) if you don't use any VBL server at all.
Relocs:	1
Exmpls:	vsync
@endnode

@node waitblit
Name:	waitblit
Args:	none
Does:	this waits for the blitter to finish. uses Commodore's method.
Needs:	nothing
Relocs:	0
Exmpls:	waitblit
@endnode

@node waituntil
Name:	waituntil
Args:	TIME
Does:	waits until the timecounter has reached TIME vertical blanks. If
	TIME has already passed, we just continue.
Needs:	only available if the internal interrupt server isn't left out.
Relocs:	2
Exmpls:	waituntil 100
	waituntil 64*6*8
@endnode