B-ASIC

B-Asic is a set of RSX commands allowing to use the Amstrad CPC Plus features from BASIC. It was written by Longshot of Logon System.

B-ASIC is a set of RSX instructions to manage the extra features of the CPC PLUS Since release 3.0 B-ASIC runs only on CPC range with 128 Kb memory Main instructions can manage colour and sprites, providing an extra bank of 64 sprites for a total of 80 sprites

B-ASIC doesn't take any byte of the CPC Basic memory. The RSX definition and code for locomative basic are not declared in main memory By the way, the whole interruption system and RSX managment is modified when B-Asic start.

From a technical point of view, the code of the program BASIC using B-ASIC is copied in a bank, because one bank is always open for the system to store the BASIC code. By the way, there are two video page available for the user.

Some instructions are not explained because they will disappear from next version. (SPLIT, RETARDX, RETARDY, MASQUE) A set of new powerful instructions will come in future versions.

HISTORICS

• V3.1 xx/xx/1993 B-ASIC doesn't use any byte of BASIC main memory
• V3.2 25/02/2006 Bug fix on table calculation for path in interrupt

                 Correct a firmware bug (ei before real interrupt handler end)

• V3.3 27/02/2006 Forgotten to copy BASIC code from bank 2 to 5

                 New instruction : SPRWHERE	
                 

INSTRUCTIONS

COLOURS INSTRUCTIONS SET

INKF,pen,colour pen=[0..15] colour=[0..4095] Modify colour of a pen Example : INKF,0,2303

INKFRVB,pen,red,green,blue pen=[0..15] red=[0..15] green=[0..15] blue=[0..15] Modify colour for a pen using colour elementaries components Example : FOR I=0 TO 15:INKFRVB,0,I,0,0:NEXT I

BORDERP,colour colour=[0..4095] Modify border's colour. Example : BORDERP,543

BORDERRVB,red,green,blue red=[0..15] green=[0..15] blue=[0..15] Modify border colour using colour elementaries components Example : FOR I=0 TO 15:BORDERRVB,0,0,0,I:NEXT I

INKS,pen,colour pen=[1..15] colour=[0..4095] Modify colour of an hardware sprite pen Note : The pen 0 cannot be modified. It's the transparent colour. Example : INKS,1,3456

INKSRVB,pen,red,green,blue pen=[1..15] red=[0..15] green=[0..15] blue=[0..15] Modify colour for an hardware sprite pen using colour elementaries components Note : The pen 0 cannot be modified. It's the transparent colour. Example : FOR I=0 TO 15:INKFRVB,0,I,0,0:NEXT I

SPRITES INSTRUCTIONS SET SPROFF,SpriteNumber SpriteNumber=[0..15] Sprite display is disactivated for specified sprite. Example : SPROFF,3

SPRON,SpriteNumber SpriteNumber=[0..15] Sprite display is activated for specified sprite. Example : SPRON,3

SPRZOOM,SpriteNumber,XZoom,YZoom SpriteNumber=[0..15] XZoom=[0..3] YZoom=[0..3] Define sprite zoom for specified sprite. If XZoom or YZoom is zeroed, sprite is not displayed Zoom value of 1 is no magnify. Note : Sprite must be activated by SPRON instruction to be displayed on screen Example : SPRZOOM,2,2,1 define the sprite 2 magnification to 2x horiz. and 1x vertically

SPRXY,SpriteNumber,XPos,YPos SpriteNumber=[0..15] XPos=[-256..767] YZoom=[-256..255] Define sprite position on screen according a mode 2 definition Note : Sprite must be activated by SPRON instruction to be displayed on screen Example : SPRXY,2,100,80 define sprite 2 position at 100,80 coordinates

SPRTDEF,SpriteNumber,Address,DurationPer,WaitingPer SpriteNumber=[0..15] Address=[0..65535] DurationPer=[0..65535] WaitingPer=[0..65535] Periods are defined by period of 0,02 second (e.g. 50 = 1 second) Define a path for the specified sprite. The path is defined by screen positions, given by a set of x,y coordinates defined in memory. Each coordinate is defined on 2 bytes (4 bytes for a screen position) in the memory The coordinate must be stored on a little endian method, e.g. the less significant byte in first and the most significant byte in second position in memory. The last x coordinate must take the value F0F0 (hexa) to indicate the path end definition DurationPer indicates the time while the sprite will run on the path (at the last position the path start again at the fist position). If DurationPer is zeroed, so the duration is infinite. WaitingPer indicate the start period which occurs when the path will be activated (see SPRTON and SPRTOFF instructions) Note : A same path can be used by one or more sprites. Example : SPRTDEF,3,&3000,0,100 to define for sprite 3 a path defined in &3000 with an infinite loop of the path after 2 seconds of start delay after SPRTON,3 instruction.

SPRTON,SprNb1,SprNb2,...,SprNbx SprNbx=[O..15] Start the path simultanously for the specified sprites. Note : An undefined path for the sprite may occur an erratic behaviour of the sprite started. Example : SPRTON,1,5,7 start the path for sprites 1, 5 and 7 simultaneously

SPRTOFF,SprNb1,SprNb2,...,SprNbx SprNbx=[0..15] Stop the path simultaneously for the specified sprites Example : SPRTOFF,1,7 stop the path for sprites 1 and 7 simultanously

SPRSWAP,SpriteNumber1,SpriteNumber2 SpriteNumberx=[0..15] Exchange the sprite content of two sprites. Note : If SpriteNumber1=SpriteNumber2 it results just a waste of time. Example : SPRSWAP,1,5 exchange the graphics data of sprites 1 and 5

SPRPLOT,SpriteNumber,XPos,YPos,SpritePen SpriteNumber=[0..15] XPos=[0..15] YPos=[0..15] SpritePen=[0..15] Plot a pixel in the specified sprite at specified coordinates Note : SpritePen=0 means the transparent pen for sprite Example : SPRPLOT,3,10,9,4 plot a pixel pen 4 at coordinates 10,9 of sprite 3

SPRCOPY,SpriteOrg,SpriteDst SpriteOrg=[0..15], SpriteDst=[0..15] Copy the content of SpriteOrg to SpriteDst. Example : SPRCOPY,1,2 copy the content of sprite 1 to sprite 2

SPRTURNX,SpriteNumber SpriteNumber=[0..15] Flip the sprite specified on horizontal axis Example : SPRTURNX,1

SPRTURNY,SpriteNumber SpriteNumber=[0..15] Flip the sprite specified on vertical axis Example : SPRTURNY,1

SPRFILL,SpriteNumber,SpritePen SpriteNumber=[0..15] SpritePen=[0..15] Fill the specified sprite with the specified pen Note : SpritePen=0 means the transparent pen for sprite Example : SPRFILL,1,12 fill the sprite 1 with pen 12

SPRSAVE,[SpriteNumber,] BlocNumber, Filename SpriteNumber=[0..15] BlocNumber=[0..4] Filename=Name of file in Amsdos standard Save a sprite or a set of 16 sprites (defined as one Block) to disk B-Asic can store 64 sprites definitions more than the usal sprite contained in asic ram. These 64 sprites are organised as 4 sets of 16 sprites named "Block". Bloc 1 : sprites 0 to 15, Bloc 2 : sprites 16 to 31, Bloc 3 : sprites 32 to 47 and Bloc 4 : sprites 48 to 63 Bloc 0 is used for the 16 "real" asic sprites. If SpriteNumber is not precised in the instruction, so a complete block is saved If SpriteNumber is precised, only the specified sprite of the block is saved Note : Sprites are not optimised (e.g. 1 pixel=1 byte) Example : SPRSAVE,3,2,"SPR3BLK1.BIN" save the sprite 3 of the Bloc 2 (e.g. sprite 18/63) in the file named "SPR3BLK1.BIN" Example : SPRSAVE,0,"SPRASIC.BIN" save the content of block 0 (e.g. 16 asic sprites)

SPRLOAD,[SpriteNumber,] BlocNumber, Filename SpriteNumber=[0..15] BlocNumber=[0..4] Filename=Name of file in Amsdos standard Load a sprite or a set of 16 sprites (defined as one Block) from disk B-Asic can store 64 sprites definitions more than the usal sprite contained in asic ram. These 64 sprites are organised as 4 sets of 16 sprites named "Block". Bloc 1 : sprites 0 to 15, Bloc 2 : sprites 16 to 31, Bloc 3 : sprites 32 to 47 and Bloc 4 : sprites 48 to 63 Bloc 0 is used for the 16 "real" asic sprites. If SpriteNumber is not precised in the instruction, so a complete block is loaded If SpriteNumber is precised, only the specified sprite of the block is loaded Note : Sprites are not optimised (e.g. 1 pixel=1 byte) Note : If the file specified has an invalid size, an error is displayed Example : SPRLOAD,3,2,"SPR3BLK1.BIN" load the sprite 3 of the Bloc 2 (e.g. sprite 18/63) from the file "SPR3BLK1.BIN" Example : SPRLOAD,3,"RAAHHHHH.SPR" load the block 3 (e.g. sprites 32 to 47) from file "RAAHHHHH.SPR"

SPRTORAM,SpriteAsic,SpriteRam SpriteAsic=[0..15] SpriteRam=[0..63] Copy the content of the current asic sprite in the sprite ram specified See SPRLOAD/SPRSAVE instruction for block oragnisation. Example : SPRTORAM,1,17 copy sprite asic 1 to sprite 17 of ram (e.g.in Block 2)

RAMTOSPR,SpriteRam,SpriteAsic SpriteRam=[0..63] SpriteAsic=[0..15] Copy the content of the sprite in ram in the current asic sprite specified See SPRLOAD/SPRSAVE instruction for block oragnisation. Example : RAMTOSPR,17,1 copy sprite sprite 17 of ram (2nd of bloc 2) in sprite asic 1

CATCH,SpriteNumber,XPos,YPos SpriteNumber=[0..15] XPos=[0..143] YPos=[0..183] Get a sprite from mode 0 screen at specified coordinates (coordinates top/left). Note : This instruction runs only in graphic mode 0 Example : CATCH,3,120,100 catch the pixels from 120,100 to 135,115 in sprite 3

INKCOPY Copy the whole colour screen palette to sprite palette.

SPRLINK,SpriteNumber1,SpriteNumber2,Xrel,Yrel SpriteNumberx=[0..15] XRel=[-256..767] YRel=[-256..255] Link a sprite (2) to another sprite (1) with a relative position. That means if sprite (1) is moved, then sprite (2) is moved too. So if sprite 1 is moved in X1,Y1 then the sprite 2 will be moved automatically in X1+Xrel,Y1+Yrel It's possible to link all the sprites in all combinations to create one or more "super sprites" Note : A sprite cannot be linked to itself. Example : SPRLINK,1,2,16,0 link sprite 2 to sprite 1 with a relative x position of 16 pixels Example : SPRLINK,2,5,0,16 link sprite 5 to sprite 2 with a relative y position of 16 pixels [ so move the sprite 1 signify to move sprite 2 and 5 ]

SPRUNLINK,SpriteNumber1,SpriteNumber2 SpriteNumberx=[0..15] Unlink a sprite from anoter sprite. Example : SPRUNLINK,2,5 erase the link between sprite 2 and 5

ERALINK Erase all link

DEFORGXY,SpriteNumber,XPos,YPos SpriteNumber=[0..15] XPos=[-256..767] YPos=[-256..255] Define absolute origin position of the specified sprite That means that real sprite position take care of this defined coordinates. Example : DEFORGXY,1,10,20:SPRXY,1,5,3 display sprite at 15,23 Note : It's possible to define an origin position for a sprite following a path (see SPRTDEF) The default of origin at B-Asic reset is 0,0

DEFORGSPR,SpriteSlave,SpriteMaster SpriteSlave=[0..15] SpriteMaster=[0..15] Define the origin position of SpriteSlave with the position of SpriteMaster. Note : It's possible to define a sprite relative position for a sprite following a path (see SPRTDEF) It's possible to generate complex definitions of sprites movments. If a sprite 1 use a path 1 and a sprite 2 use a path 2, if the sprite 2 is the slave of sprite 1, then the path 2 will be relative to path 1. To erase the slavery of a sprite, use DEFORGXY instruction

SPRWHERE,SpriteNumber,@varx%,@vary% SpriteNumber=[0..15] varx=Name of x variable vary=Name of y variable Get the x,y coordinates of the specified sprite Important note : varx and vary must be defined first like integer (declaration in basic with '%') and they must be given to the instruction "by address" ('@' before the variable name). The declaration must be respected to avoid unpredictibles results. Example : 10 VARX%=0: VARY%=0 : SPRWHERE,1,@VARX%,@VARY%: PRINT VARX%,VARY%

OTHERS INSTRUCTIONS SET POKEASIC,Address,val1,...,valx Adress=[&4000..&7FFF] Valx=[&00..&FF] Poke one or more bytes in Asic I/O page Instruction reserved to experimented users.

POKEVR,Address,val1,...,valn Adress=[&4000..&7FFF] Valx=[&00..&FF] Poke one or more bytes in second video page Instruction reserved to experimented users.

Bad arguments number Bad number of arguments used in the instruction

Invalid Argument An invalid value is used in one or more arguments of the instruction

Invalid Filename A bad filename was used in a SPRSAVE or SPRLOAD instruction

Disc Error An I/O error has occured in a SPRSAVE or SPRLOAD instruction. Disc is missing, or the disk has a wrong or damaged format.

Not a Sprite file The size of the file specified in SPRLOAD is not correct. See if you do no use the SPRLOAD with a block instead of a single sprite (or the opposite)

Same Sprites Numbers An instruction SPRLINK or SPRUNLINK is attempted with 2 identical sprite numbers.

Bad Graphic Mode Instruction CATCH is not used in MODE 0

Invalid Moving List An invalid table is created for SPRTDEF (e.g. the first coordinate is the path end)

Link Table Full The link table is full. Normally this error cannot occur in a well built program.

Sprites not Linked Instruction SPRUNLINK is used with sprites not linked.