Amiga ISO Collection/AmigaUtilCD2.iso/Programming/Basic/wst!blz1.dms/in.adf/docs/version19.doc

Text File | 1994-09-05 | 19.9 KB | 565 lines

BUM7 MAIN DOC

Updates and Fixes to Blitz2 v1.9
--------------------------------


Stability

Several improvements have been made to the stability of Blitz2 programs.
First up all string commands have been fixed to both work properly with
the null-termination system introduced in v.18 (our apologies here) and
error checking has been added. No longer will system crashes be caused
with illegal size parameters in mid$() etc.

Also, the ASMEND command has been added. Using assembler in statements
and functions use to require the use of UNLK A4 and RTS. This system
did not work properly when runtime errors were enabled. A fullproof
method is now available, simply use the ASMEND command in place of any
RTS commands. Blitz2 will look after the unlinking of A4, allow for
runtime errors and then do an RTS. Finally my darts demo runs with
runtime errors enabels (yipeeee!).

And finally, runtime error checking has been added for square bracket
arrays. Yup, out of range checking has been incorporated for those of
us whose first guess at why our programs were crashing was to go through
and check such usage manually. This with the new string checking and the
sexy new debugger should return a few people to using Blitz2's runtime
debugging features. Thanks to all those and their abuse for helping us
get these problems resolved.


Debugging

The debugger is now a separate program that is launched by Blitz2 when a
prgram is run (runtime errors enabled of course).

The gadgets in the window allow the programmer access to the standard
debugging features. CtrlAltC can still be used to halt programs, especially
those using Slices and Displays in Blitz mode.

By increasing the size of the window the program listing can be viewed.

A PANIC! button has also been introduced once a program is launched from
the editor. Yup, programs are now launched not run so those into weird
system crashes may be able to return to Ted leaving their programs disabled
in memory. A REBOOT button may have been more useful...

The source code for the default debugger is included in the acidlibsrc
directory of the libsdev archive. It is extremely well documented by
Mark so those wanting to extend the functionality of the system are
most welcome. Serial port support for using a remote terminal would
be very nice.


Interupts and BlitzKeys

BlitzKeys, BlitzKeys, BlitzKeys. A common profanity used by those of us
use to keyboard lock ups in keyboard based Blitz games (especially
SkidMarks). Well no more!

Blitz now leaves Amiga interupts enabled in Blitz mode. This means that
not only is the system keyboard interupt still running (thank the lord)
but any SetInts initiated in Amiga mode will continue.

Other advantages are that Blitz mode is now more acceptable to the CD32
environment and RawStatus can be used in Amiga mode for keyboard games
not wanting to run in Windows (yuck).

Blitzkeys On now does a bit of a "BlitzkeysInput" for one character inputs
only, any other inputs use the previously defined Input channel.

Blitzkeys Off no longer exists. BlitzRepeat has gone (no repeating keys).


Serial Stuff

Peter Tavinor has upgraded the Serial Library. ReadSerial now return a
word (read unsigned byte) so chr$(255) is acceptable. WriteSerialString
includes flags for DoIO and True String (not null terminated). ReadSerial
has a new flag "WaitForChar"


GadTools

The GTPalette has had several default tags removed as they crashed under
2.0 (yeh, great, just what tags are suppose to avoid). AttachGTList had
a minor problem in some situations (now fixed).

Another bug that has been found in GadTools under 2.0 is that GTLists
actually allocate gadget id's for internal use. Besides being completely
unethical (and fixed in 3.0) it means that programmers should use id
values of greater than 50 to avoid this system bug. Adding GTLists last
in your list should also work although their id's should be more than the
number of lines of text they should display (no I am not going to explain
further).


ScreensLib

The Screen command now rounds the width up to the nearest multiple of 16
rather than causing the error "Screen Width Must be a multiple of 16".
Common sense I think.


ValLib

Val() now accepts hex and binary strings (preceeded by "$" and "%" of course.)
Because Val() returns a float it should not be used to evaluate 32 bit integers
(longs).


Display Library

A quick version of the InitCoplist command has been included which calculates
the number of colours, sprites and size depending on just the type parameter.

As promised the Display library now sports new commands for palette effects
and so forth. There are two varieties of copper based commands, the first
allows the user to insert a new palette or copperstring at a certain line
of the display, the other allows control of each and every line of the
display.

For line based effects a negative value should be used in combination
with the numcustoms parameter of the InitCopList command. Color splits,
bitmap scrolling, scan doubling/trebling/quadrupling and custom copper
strings can now be acheived on a line by line basis.


Palette Library.

A number of commands have been added to the Palette library for use mainly
with the display library. Fades and Colour cycling can now be performed on
palette objects themselves (rather than on screens and slices) and hence
can be used in conjunction with the DisplayPalette command.


Banks and Decoding.

Decode commands have been added to allow programmers to both include shapes,
sounds, palettes, music and ILBM's (IFF bitmaps) in their programs or from
preloaded files (mainly using the LoadBank command or unpacking type commands).

To include such files in the program the incbin command is used. Typically
a list of included files will be situated at the bottom of the listing (with
and End statement just above to be safe). Each IncBin will be preceeded by
a label and the ?label syntax would be used to pass the location of each
included file to the appropriate Decode command at the top of the program.

Those unhappy with the slow but memory unhungry LoadBitMap command can take
advantage of the fast but memory hungry method of loading iff/ilbm files
with the code listed in the DecodeILBM command description.


New Commands
------------

   GTStatus(GTList#,Id) ;bbgtlib
   GTArrowSize size       ;bbgtlib
   DecodeILBM BitMap#,MemoryLocation ;ilbmifflib
   DecodeSound Sound#,MemoryLocation ;audiolib
   DecodePalette Palette#,MemoryLocation[,Palette Offset] ;palettelib
   DecodeMedModule MedModule#,MemoryLocation ;medlib
   DecodeShapes Shape#[,Shape#],MemoryLocation ;shapeslib
   InitShape Shape#,Width,Height,Depth ;shapeslib
   SetPeriod Sound#,Period ;audiolib ;audiolib
   Bank(Bank#)
   LoadBank Bank#,FileName$[,MemType]
   AllocMem (size,type) ;banklib
   FreeMem location,size ;banklib
   BlockScroll X1,Y1,Width,Height,X2,Y2[,BitMap#] ;scrolllib
   ClipBlitMode BPLCON0  ;2dlib
   CyclePalette Palette# ;palettelib
   FadePalette SrcPalette#,DestPalette#,Brightness.q ;palettelib
   InitPalette Palette#,NumColors ;palettelib
   PaletteRange Palette#,StartCol,EndCol,r0,g0,b0,r1,g1,b1 ;palettelib
   DuplicatePalette SrcPalette#,DestPalette# ;palettelib
   SavePalette Palette#,FileName$ ;iffmakelib
   CustomColors CopList#,CCOffset,YPos,Palette,startcol,numcols ;displaylib
   CustomString CopList#,CCOffset,YPos,Copper$ ;displaylib
   DisplayDblScan CopList#,Mode[,copoffset] ;displaylib
   DisplayRainbow CopList#,Register,Palette[,copoffset] ;displaylib
   DisplayRGB CopList#,Register,line,r,g,b[,copoffset] ;displaylib
   DisplayUser CopList#,Line,String[,Offset] ;displaylib
   DisplayScroll CopList#,&xpos.q(n),&xpos.q(n)[,Offset] ;displaylib
   ReadSerialMem Unit#,Address,Length ;seriallib
   WriteSerialMem Unit#,Address,Length ;seriallib
   PopInput & PopOutput ;inputoutputlib
   GameB(por#) ;gameiolib
   NumPars ;cliargslib
   Par$(parameter#) ;cliargslib
   FromCLI ;cliargslib
   ParPath$ (parameter,type) ;cliargslib

Function: GTStatus(GTList#,Id) ;bbgtlib

GTStatus returns the status of and gadtools toggle gadgets, a value
of 1 means the the gadget is selected, 0 deselected.


Statement: GTArrowSize size       ;bbgtlib

Allows the size of GTScroller arrows to be preset. Default size is 16.


Statement: DecodeILBM BitMap#,MemoryLocation ;ilbmifflib

A very fast method of unpacking standard iffilbm data to a bitmap. Not
only does this command allow a faster method of loading standard IFF
files but allows the programmer to "incbin" iff pictures in their programs.
See the discussion above for using DecodeILBM on both files and included
memory.


Statement: DecodeSound Sound#,MemoryLocation ;audiolib

DecodeSound similar to the other new Decode commands allows the programmer
to include sound files within their program's object code.


Statement: DecodePalette Palette#,MemoryLocation[,Palette Offset] ;palettelib

DecodePalette allows the programmer to unpack included iff palette information
to Blitz2 palette objects.


Statement: DecodeMedModule MedModule#,MemoryLocation ;medlib

DecodeMedModule replaces the cludgemedmodule, as med modules are not packed
but used raw, DecodeMedModule simply checks to see the memorylocation passed
is in ChipMem (if not it copies the data to chip) and points the Blitz2
MedModule object to that memory.


Statament: DecodeShapes Shape#[,Shape#],MemoryLocation ;shapeslib

DecodeShapes, similar to DecodeMedModule ensures the data is in chip and
then configures the Shape object(s) to point to the data.


Statement: InitShape Shape#,Width,Height,Depth ;shapeslib

InitShape has been added to simple create blank shape objects. Programmers
who make a habit of using ShapesBitMap to render graphics to a shape object
will appreciate this one for sure.


Statement: SetPeriod Sound#,Period ;audiolib ;audiolib

Hmmm, not sure why we never included this command in the original audiolib,


Function: Bank(Bank#)

Returns the memory location of the given memory Bank, replaces the older
and more stupidly named BankLoc command.


Statement: LoadBank Bank#,FileName$[,MemType]

The LoadBank command has been modified, instead of having to initialise
the bank before loading a file, LoadBank will now initialise the bank
to the size of the file if it is not already large enough or has not been
initialised at all.


Function: Bank(Bank#)

Returns the memory location of the given memory Bank, replaces the older
and more stupidly named BankLoc command.


Statement: LoadBank Bank#,FileName$[,MemType]

The LoadBank command has been modified, instead of having to initialise
the bank before loading a file, LoadBank will now initialise the bank
to the size of the file if it is not already large enough or has not been
initialised at all.
SetPeriod simply allows the user to override the frequence information (period)
of the sound object after it has been loaded. To alter a sound's pitch while
playing programmers should hit the audio hardware direct (hardware locations
are listed at the back of the reference manual).


Function: Bank(Bank#)

Returns the memory location of the given memory Bank, replaces the older
and more stupidly named BankLoc command.


Statement: LoadBank Bank#,FileName$[,MemType]

The LoadBank command has been modified, instead of having to initialise
the bank before loading a file, LoadBank will now initialise the bank
to the size of the file if it is not already large enough or has not been
initialised at all.


Function: AllocMem (size,type) ;banklib

Unlike calling Exec's AllocMem_ command directly Blitz2 will automatically
free any allocated memory when the program ends. Programmers are advised
to use the InitBank command.

Flags that can be used with the memory type parameter are:

1=public    ;fast is present
2=chipmem
65536=clear ;clears all memory allocated with 0's


Statement: FreeMem location,size ;banklib

Used to free any memory allocated with the AllocMem command.


Statement: BlockScroll X1,Y1,Width,Height,X2,Y2[,BitMap#] ;scrolllib

Same as the Scroll command except that BlockScroll is much faster but
only works with 16 bit aligned areas. This means that X1, X2 and Width
must all be multiples of 16. Useful for block scrolling routines that
render the same blocks to both sides of the display, the programmer
can now choose to render just one set and then copy the result to the
other side with the BlockScroll command.


Statement: ClipBlitMode BPLCON0  ;2dlib

Same as BlitMode except applies to the ClipBlit command. Another oversight
now fixed.


Statement: CyclePalette Palette# ;palettelib

CyclePalette uses the standard color cycling parameters in the palette
object to cycle the colors. Unlike the Cycle command which copied the
resulting palette to the current screen the CyclePalette command just
modifies the palette object and can hence be used with the DisplayBitmap
command in the new Display library.


Statement: FadePalette SrcPalette#,DestPalette#,Brightness.q ;palettelib

FadePalette multiplies all colours in a Palette by the Brightness argument
and places the result in the DestPalette.


Statement: InitPalette Palette#,NumColors ;palettelib

InitPalette simply initialises a palette object to hold NumColors. All colors
will be set to black.


Statement: PaletteRange Palette#,StartCol,EndCol,r0,g0,b0,r1,g1,b1 ;palettelib

PaletteRange creates a spread of colors within a palette. Similar to DPaint's
spread function PaletteRange takes a start and end colour and creates the
color tweens between them.


Statement: DuplicatePalette SrcPalette#,DestPalette# ;palettelib

DuplicatePalette simply creates a new Palette which exactly matches the
SrcPalette.


Statement: SavePalette Palette#,FileName$ ;iffmakelib

Creates a standard IFF "CMAP" file using the given Palette's colors.


Statement: CustomColors CopList#,CCOffset,YPos,Palette,startcol,numcols ;displaylib

Using the custom copper space in a display, CustomColors will alter the displays
palette at the given YPos. The number of customcops required is either 2+numcols
for ecs displays and 2+n+n+n/16 for aga displays. In aga, numcols must be a multiple
of 32.

Note that large AGA palette changes may take several lines of the display to be
complete.


Statement: CustomString CopList#,CCOffset,YPos,Copper$ ;displaylib

CustomString allows the user to insert their own copper commands (contained
in a string) into the display's copper list at a given vertical position.
The amount of space required is equal to the number of copper instructions
in the Copper$ (length of string divide by 4) plus 2 which of course have
to be allocated with InitCopList before CustomString is used.


Statement: DisplayDblScan CopList#,Mode[,copoffset] ;displaylib

DisplayDblScan is used to divide the vertical resolution of the display by
2,4,8 or 16 using Modes 1,2,3 and 4. This is most useful for fast bitmap
based zooms. A Mode of 0 will return the display to 100% magnification.

As with the DisplayRainbow, DisplayRGB, DisplayUser and DisplayScroll
commands DisplayDblScan uses the new line by line copper control of the
display library. To initialise this mode a negative parameter is used
in the CustomCops parameter of the InitCopList command. DisplayDblScan
requires 2 copper instructions per line (make CustomCops=-2).


Statement: DisplayRainbow CopList#,Register,Palette[,copoffset] ;displaylib

DisplayRainbow is used to alter a certain colour register vertically down
a display. It simple maps each colour in a palette to the coresponding
vertical position of the display. ECS displays require one copper instruction
per line while AGA displays require 4.


Statement: DisplayRGB CopList#,Register,line,r,g,b[,copoffset] ;displaylib

DisplayRGB is a single line version of DisplayRainbow allowing the programmer
to alter any register of any particular line. As with DisplayRainbow ECS
displays require 1 copper instruction while AGA requires 4.


Statement: DisplayUser CopList#,Line,String[,Offset] ;displaylib

DisplayUser allows the programmer to use their own Copper$ at any line of
the display. Of course copper instructions have to be allocated with the
number of copper instructions in the InitCoplist multiplied by -1.


Statement: DisplayScroll CopList#,&xpos.q(n),&xpos.q(n)[,Offset] ;displaylib

DisplayScroll allows the program to dynamically display any part of a bitmap
on any line of the display. DisplayScroll should always follow the DisplayBitMap
command. The parameters are two arrays holding a list of xoffsets that represent
the difference in horizontal position from the line above. AGA machines are able
to use the fractional part of each entry for super hiresolution positioning
of the bitmap. Three instructions per line are required for the DisplayScroll
command.


Statement: ReadSerialMem Unit#,Address,Length ;seriallib

ReadSerialMem will fill the given memory space with data from the
given serial port.


Statement: WriteSerialMem Unit#,Address,Length ;seriallib

WriteSerialMem send the given memory space out the given serial port.


Statement: PopInput & PopOutput ;inputoutputlib

After input or output has been re-directed (eg using windowoutput/fileoutput),
these two commands may be used to return the channel to it's previous condition.

Function: GameB(por#) ;gameiolib

Returns button state of cd32 style game controllers - values returned are:

1  = play/pause
2  = reverse
4  = forward
8  = green
16 = yellow
32 = red
64 = blue

If more than one button is held down, values are added together. For example,
a value of 6 means both the forward (4) and reverse (2) buttons are held down.
Use an 'and' to isolate the status of a single button, like this -

;check RED button on port 1...
;
if gameb(1) & 32
  ;
  ;RED button is down...
  ;
else
  ;
  ;RED button is NOT down...
  ;
endif


argslib fixes
-------------

This library processes arguments passed to it.  A few fixes have mainly
been made over the old one.

1)  Quoted arguments count as one argument.  EG "One arg"  will give your
  program both words as one argument, not 2.

2)  Mulitple workbench arguments are allowed now.


If you are to use workbench arg handling, you MUST have WBSTARTUP at the top of
your program!!


Function: NumPars ;cliargslib

Returns the number of parameters passed to your program.


Function: Par$(parameter#) ;cliargslib

Returns the string value of a parameter.

NOTE: If the parameter asked for is a directory/device/volume etc
(IE NOT A FILE) then Par$(#) will return an empty string.  This is a one
way you can check to see if a file was passed or not.


Function: FromCLI ;cliargslib

Returns TRUE (-1) if your program was run from the CLI, or FALSE (0) if run
from the WorkBench.


Function: ParPath$ (parameter,type) ;cliargslib

This returns the path that this parameter resides in.
'type' specifies how you want the path returned.

0 You want only the directory of the parameter returned.
1 You want the directory along with the parameter name returned.

EG:

If you passed the parameter "FRED" to your program from WorkBench, and FRED
resides in the directory "work:mystuff/myprograms" then ParPath$(0,0) will
return "work:mystuff/myprograms", but ParPath$(0,1) will return
"work:mystuff/myprograms/FRED".

CAVEAT
The way WB handles argument passing of directories is different to that of
files.  When a directory is passed as an argument, ArgsLib gets an empty
string for the name, and the directory string holds the path to the passed
directory AND the directory name itself.  EG

Passing the blitz2 directory to a program will result in:

Par$(x)     Being an empty string.
ParPath$(x,0)   Being something like work:Basic/blitz2.
ParPath$(x,1) Being work:Basic/blitz2/

YES!  The / is appended!  This is because to keep things simpler, and more
uniform ParPath$(x,1) Is the concatenation of

1)  The directory string passed by Workbench

AND

2)  A / followed by the name given by WorkBench.

So you can see why the / followed by the empty string occurs.

The easy way around this is simply to check Par$(x), if it is empty, then
use ParPath$(x,0), if it isn't (IE a file was passed) use ParPath$(x,1) and
you will have the entire pathname of the file OR directory.

See the demo program, which handles both cases.

NOTE 2: Is only useable from WorkBench, you will get an error if your program
was run from the CLI and you try to call ParPath$.