Changes
'''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]].
=== INTRODUCTION ==B-ASIC is a set of RSX instructions to manage the extra features of the CPC PLUSSince release 3.0 B-ASIC runs only on CPC range with 128 Kb memoryMain 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 memoryBy 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, becauseone bank is always open for the system to store the BASIC code. By the way, there are two video page availablefor 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 penExample : 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 componentsExample : 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 componentsExample : 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 penNote : 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 componentsNote : 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 displayedZoom value of 1 is no magnify.Note : Sprite must be activated by SPRON instruction to be displayed on screenExample : 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 definitionNote : Sprite must be activated by SPRON instruction to be displayed on screenExample : 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 memoryThe coordinate must be stored on a little endian method, e.g. the less significant bytein 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 definitionDurationPer indicates the time while the sprite will run on the path (at the last positionthe 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 infiniteloop 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 coordinatesNote : SpritePen=0 means the transparent pen for spriteExample : SPRPLOT,3,10,9,4 plot a pixel pen 4 at coordinates 10,9 of sprite 3 '''SPRCOPY,SpriteOrg,SpriteDstSpriteOrg=[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 axisExample : SPRTURNX,1 '''SPRTURNY,SpriteNumber'''SpriteNumber=[0..15]Flip the sprite specified on vertical axisExample : SPRTURNY,1 '''SPRFILL,SpriteNumber,SpritePen'''SpriteNumber=[0..15] SpritePen=[0..15]Fill the specified sprite with the specified penNote : SpritePen=0 means the transparent pen for spriteExample : 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 standardSave a sprite or a set of 16 sprites (defined as one Block) to diskB-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 andBloc 4 : sprites 48 to 63Bloc 0 is used for the 16 "real" asic sprites.If SpriteNumber is not precised in the instruction, so a complete block is savedIf SpriteNumber is precised, only the specified sprite of the block is savedNote : 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 standardLoad a sprite or a set of 16 sprites (defined as one Block) from diskB-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 andBloc 4 : sprites 48 to 63Bloc 0 is used for the 16 "real" asic sprites.If SpriteNumber is not precised in the instruction, so a complete block is loadedIf SpriteNumber is precised, only the specified sprite of the block is loadedNote : Sprites are not optimised (e.g. 1 pixel=1 byte)Note : If the file specified has an invalid size, an error is displayedExample : 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,SpriteRamSpriteAsic=[0..15] SpriteRam=[0..63]Copy the content of the current asic sprite in the sprite ram specifiedSee 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,SpriteAsicSpriteRam=[0..63] SpriteAsic=[0..15]Copy the content of the sprite in ram in the current asic sprite specifiedSee 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 0Example : 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+YrelIt'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 pixelsExample : 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 spriteThat means that real sprite position take care of this defined coordinates.Example : DEFORGXY,1,10,20:SPRXY,1,5,3 display sprite at 15,23Note : 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, thenthe 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 variableGet the x,y coordinates of the specified spriteImportant note : varx and vary must be defined first like integer (declaration in basic with '%') andthey must be given to the instruction "by address" ('@' before the variable name). The declaration mustbe 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 pageInstruction reserved to experimented users. '''POKEVR,Address,val1,...,valn'''Adress=[&4000..&7FFF] Valx=[&00..&FF]Poke one or more bytes in second video pageInstruction reserved to experimented users. == ERROR MESSAGES =='''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. [[Category:StubProgramming]]
