V9990 XBASIC / PowerBasic

© Henrik Gilvad 1993/1994
OCR'ed and corrected by Dan Derpaux 2005
HTML and additional corrections by Patriek Lesparre 2005

Introduction

The "V9990 XBASIC" was based on the "MSX XBASIC" also called "BASIC KUN". The first version of the V9990 XBASIC was done from within a Disassembler / Monitor program called "MEMO". This gave a working, but not optimal version of XBASIC, therefore the complete Xbasic was disassembled and all graphical routines were rewritten. The original XBASIC version was the one which had a bug in the "ON INTERVAL" and which did not draw on screen 10/11 in the same way as basic. The "ON INTERVAL" has now been fixed. The "SET SCROLL" has been added, with the 3th and 4th parameters being the X and Y scroll of LAYER B in the DUALPLANE mode. (These 2 parameters are not MSX compatible !)
The PUT SPRITE command supports both the P1,P2 and Bn modes.
The SET PAGE now have a 3rd parameter which is the DISPLAY PAGE of LAYER B. This command has also been changed so it works like in uncompiled basic. This means that it will syncronise with the picture IF the 1st parameter is written. In the dualplane mode this is the LAYER A.

V9990 XBASIC instructionset

In this section you can read about all graphical commands. Some commands works just as normal, some have been extended, some only works limited and some does not work at all.

BASE(number)

This command have no function on the V9990.

BLOAD"file",S

BLOAD does not work from XBASIC, use it from BASIC only.

BSAVE"file"...

BSAVE does not work from XBASIC, use it from BASIC only.

CIRCLE

Only "CIRCLE(X,Y),RADIUS,COLOR" parameters can be used.
The CIRCLE routine in ROM is used to draw the circle.
Ex. "CIRCLE(128,106),100,15"

CLS

Screen 0 calls the ROM CLS, all others clears the graphic area.
In the Dualplane mode only the upper plane is cleared.
The Character Table is not cleared! (USE "SCREEN 2-4")

COLOR fo,ba,bo

Sets the Foreground,Background,Border colors.
Syntax: "COLOR foreground,background,border"
The border can be from 0-63 in all modes. (Palette 0-63)
The foreground and background limits depends on the mode:

Screen 0,1,2,3,4,5,70-15
Screen 60-3 and 16-31
screen 8-120-255

COLOR=(p,r,g,b)

Redefines one of the 64 colors.

p = 0-630-15 is palette 0, 16-31 is palette 1 etc.
r,g,b = 0-7MSX compatible values.
p = 64-12764-79 is palette 0, 80-95 is palette 1 etc.
r,g,b = 0-31V9990 palette values.

The first 16 color deflnitions are stored in VRAM: (32 bytes)

Screen 0,1,3,7,8,10,11,12&HFA80 + &H10000 * page #
Screen 2,4,5,6&H7680 + &H08000 * page #

COLOR SPRITE(nr)=value

This command has no meaning on the V9990

COLOR SPRITE$(nr)=str

This command has no meaning on the V9990

COPY

syntax "COPY (x,y)-(x,y),page To (x,y),page,logop"
This command coples an rectangular area from Vram-Vram.
EX: "COPY(0,0)-(255,255),0 TO (0,0),1 , TPSET

COPY SCREEN mode

No current function on V9990.

DRAW string

This is not supported in XBASIC.

INTERVAL ON/OFF/STOP

This did not work in MSX XBASIC, it does now.

LINE

Draws a line. "STEP" and LOGOPs can be used.
Ex. "LINE (xl,yl)-(x2,y2),15,,XOR"

LINE , B

Draws a BOX. "STEP" and LOGOPs can be used.
Ex. "LINE (xl,yl)-(x2,y2),15,B,PSET"

LINE , BF

Draws a filled BOX. "Step" and LOGOPs can be used.
Ex. "LINE (x1,y1)-(x2,y2),15,BF,PSET"

LOCATE x,y

This only works correctly in SCREEN 0.

ON SPRITE GOSUB

This does not work on the V9990. (It does not have it)

PAINT

Fills an area on the screen.

Ex. "PAINT (128,128),15,8" fills with color 15 until color 8 is met. In screen 2 and 4 it will try to go beyond the screen because of the dualplane mode. Plane B is located at coordinates 512-767 and therefore the X,Y clipper routine can not stop the PAINT at X location 255.

This can be fixed with a "VDP(6)=VDP(6)AND&B11110011" just before the PAINT. The VDP(6) register must be set back to its original value after the paint, or else the clipper routine can not allow drawing on plane B.

POINT

Ex: "A=POINT(x,y)" gives the color of a DOT on the screen.
In XBASIC it also works in the 16 bit mode.

PRESET

(x,y),color,logop

'Clears' a pixel to the COLOR.

PRINT #1,...

This only works from BASIC. With a short machine code included it is possible to print on the graphical screen from xbasic.

PRINT

Prints strings and numbers on the P2 screen. (0,1,3) (At the moment it does not work in screen 2 and 4).

PSET

(x,y),color,logop

'Sets' the pixel to the COLOR.
PSET and PRESET is the same on MSX 2 and 2+ screens, but it was needed in MSX 1 screen modes.

PUT SPRITE

PUTSPRITE nr,(x,y),c,pat

nr can be from 0-255, but only 0-124 are real sprites.
x can be from 0-1023 (Also negative values)
y can be from 0-255
pat can be from 0-255
c is not used because V9990 uses multicolor sprites.

PUT SPRITE works in all modes!
Screen 0,1,2,3,4 have multicolor sprites. 0-124
Screen 5-12 have 'cursor' sprites 0-1 (32x32 dots, 1 color)

SCREEN

0-12. Calls the rom.

SET PAGE

SYNTAX: "SET PAGE display1,activepage,display2"

Display1 is the page shown on the upper layer. Activepage is the page that will be worked on. Display2 is the page shown on the lower layer. (Plane B)

The page numbers can be from 0-15 in screen 2,4,5,6. It can be from 0-7 in screen 3,7,8,10,11,12

The Display2 page only have 2 pages but bit 6 and 7 can be used to disable Layer A og B. (Read about this later.)

The SETPAGE command will wait for the Picture Sync only if there is a number in the "DISPLAY1" page location.
(USE VDP(18)=x if you want to change it without the WAIT)
Warning: The old XBASIC does not wait!

If you want to switch the ACTIVE page fast then do not write the 'Display1' number

SPRITE$

NOT SUPPORTED ! (Will access the VRAM though.)

VDP

Writes values to the V9990 registers. Be carefull not to use V9990 XBASIC VDP programs on MSX2 and visa versa.

NOTE: The VDP command will wait for the Command Executing flag to be inactive before it writes values to any registers. This is needed because the V9990 XBASIC use a better method than the old Xbasic when giving Hardware drawing commands. The old Xbasic waited for the Command Executing flag to go inactive before it returned to basic, but in the V9990 xbasic all commands will only wait in the beginning of each command. This gives better use of the CPU power. If the VDP did not wait, then it would be possible that commands would not be executed correctly.

var=VDP(nr)

Reads a register in the V9990.

var=VDP(-xx)

Reads the STATUS register of the VDP. This register is the same as the MSX VDP(-2), but has got one bit more.
All negative values will just give the VDP(-2) value.

VPOKE

0-64k relative to the beginning of the active page.
Ex. "VPOKE bH3456,44"

In screen 2,4,5 and 6, the VPOKE adress is converted like this:

Page 0VPOKE 0,0writes to #00000
Page 1VPOKE 0,0writes to #08000
Page 2VPOKE 0,0writes to #10000
Page 3VPOKE 0,0writes to #18000
etc.
Page 0VPOKE &H8000,0writes to #08000
Page 1VPOKE &H8000,0writes to #00000
Page 2VPOKE &H8000,0writes to #18000
Page 3VPOKE &H8000,0writes to #10000
etc.

In screen 0,1,3,7,8,10,11,12 the ACTIVE page is used as the 64k block adressing.

VPEEK

Returns the contents of a VRAM byte. See VPOKE.
Ex. "A=VPEEK(&H3456)"

Some tips

SET SCROLL (Layer A)

You can now use the "SET SCROLL x1,y1,x2,y2" commands from XBASIC. But you can also use VDP registers in this way:

X
FOR X=0 TO 511 : VDP(19)=X AND 7 : VDP(20)=X \ 8 : NEXT X

Y
FOR Y = 0 TO 255 : VDP(17) = Y : NEXT Y

SET SCROLL (Layer B)

The VDP registers for PLANE B are:

X
FOR X=0 TO 511 : VDP(23)=X AND 7 : VDP(24)=X\8 : NEXT X

Y
FOR Y=0 TO 255 : VDP(21)=Y : NEXT Y

SYNCHRONISE WITH PICTURE. (Y-BORDER)

WAIT &H65, 64, 0 ; Wait for Picture
WAIT &H65, 64, 64 ; Wait for Sync

(Use both!)

You can also use the "SET PAGE display1" or "SET SCROLL" to syncronise. The commands will return just below the graphic area of the screen. If you use COLOR (p,r,g,b) then there will be some noise in the border, but if you wait some time then the noise can be moved outside of the visable border.

The recommended sync method is to use "SET SCROLL" or the two WAIT commands.

SET PAGE (Layer B)

The SET PAGE's 3rd parameter is the Plane B page number 0 or 1. You can also use a VDP reglster to change it.

VDP(22) = page (0-1)

SCROLL Y-WRAPPING

When a program uses Y-scroll then it might be good to have only 256 or 512 y-lines in the SCROLL picture. Normally the V9990 is set up to just show all the lines available after each other. Therefore Page1 (line 0) will be displayed after Page0 (line 255) in the normal mode. If you want Page0 (line 0) to follow Page0 (line 255) then set bit 6 in VDP(18) like this

Set 256 Y-lines.
VDP(18) = (VDP(18) AND &B00111111) OR 64

If you want 2 pages after each other in the Y-direction then set bit 7 in VDP(18). (Then bit 6 must not be set!)

Set 512 Y-lines.
VDP(18) = (VDP(18) AND &B00111111) OR 128

The default mode is selected by clearing bit 6-7 in VDP(18)

Set 'all' Y-lines. (As many as the VRAM can store)
VDP(18) = (VDP(18) AND &B00111111)

If the 512 Y-line wrapping is selected the pages will be hooked together in pairs like this: 0-1, 2-3, 4-5, 6-7, 8-9
(Screen 2-4 (game modes) uses Character Tables so they can only show 2 'pages')

SET PAGE and SET SCROLL commands does both preserve bit 6-7 of VDP(18)!

COLOR REDEFINITION in 0-31 R,G,B values

In BASIC and XBASIC the colors can only be defined in 0-7 RGB steps because this is the standard MSX color resolution. However the v9990 can define its palettes with RGB values frorn 0-31. This is how to do it:

;
;   COLOR = (C,R,G,B)   C = 0-63, R,G,B = 0-31
;
VDP(14) = C * 4
OUT (&h61), R
OUT (&h61), G
OUT (&h61), B

You can also READ the palette:

;
;   Read the RGB values of a color.
;
VDP(14) = C * 4
R = INP(&h61)
G = INP(&h61)
B = INP(&h61)

Note that when you access the palette register (&H61) then the V9990 cannot read it itself, and therefore some dots might get 'snowy' on the screen. It is therefore best to access the palettes when no graphics is shown. This is called the BORDER area. See the "SYNCRONISE WITH PICTURE" routine.

SPRITE PATTERNS

Sprite patterns are stored as normal 16 color graphics. Each sprite is 16x16 dots and you can store 256 active patterns at one time. This fills 256x256 dots in any page of the VRAM. The default SPRITE PATTERN page is page 0 but you can change this with VDP(25). See page 85 in the V9990 application manual to see more.

P1 mode (Screen 2 or 4)

VDP(25)=0Default, page 0
VDP(25)=2Sprite patterns are stored in page 1 - Layer A
VDP(25)=4Sprite patterns are stored in page 2 - Layer A
....
VDP(25)=14Sprite patterns are stored in page 7 - Layer A

P2 mode (Screen 3)

VDP(25)=blockAny 32kbyte block in VRAM. (From 0-15)

64 PALETTE COLOR MODE

If you want to use all 64 redefinable colors at the same time then do like this:

10 SCREEN 8 : VDP(13) = 0

Use "COLOR = (C,R,G,B)" to define the 64 colors.

The graphics are stored with 8 bits per pixel (like screen 8)

Change the X-resolution of a mode

The V9990 can show the following resolutions on a normal monitor:

256 x 212all colormodes
384 x 240all colormodes
512 x 212all colormodes
768 x 24016 colors max
1024 x 21216 colors max

(All modes can also be shown in Interlaced with the double # of Y-lines)

VDP(6) bit 4-5 selects which dot-resolution is displayed an the screen. If you want to experiment with it then use this routine:

VDP(6) = (VDP(6) AND &B11001111) + x*16 'X = 0-3 only I!!

You can also change the number of pixels per line in the 'image room'. This can be used to draw pictures which are up to 2048 dots wide, then you must use the SET SCROLL (or VDP) to see the rest of the picture.

VDP(6) = (VDP(6) AND &B11110011) + x*4 'X = 0-3 only !!!
' 0 =  256
' 1 =  512
' 2 = 1024
' 3 = 2048

Most routines in the BASIC and in the XBASIC should use these 2 bits to do the edge clipping of all drawing commands.

Using the 16 bit colormode

The V9990 can show up to 32768 different colors at the same time. This is not supported by the BASIC or XBASIC though, but you can enter the mode by setting bit 0-1 high in VDP(6). The problem is that the MSX basic is only designed to handle 8 bit color values.

Dual-Plane Priority

See page 85 in the application manual.

VDP(27) bit 0-1 sets the X-coordinate (in 64 dot steps) on which Layer B will begin to overlap Layer A.
VDP(27) bit 2-3 sets the Y-coordinate (in 64 dot steps) on which Layer B will begin to overlap Layer A.

There is also an undocumented feature to DISABLE any of the 2 layers. This is bit 6 and 7 of VDP(22). This can be used from Basic with the SET PAGE commands 3rd parameter because this is the same as the Layer B page register.

Note from Dan: It seems disabling any of the layers also disables the sprites.

EX 1
SET PAGE ,,128
Disables Layer A, Color 0 will be displayed from the palette.

EX 2
SET PAGE ,,64
Disables Layer B, Color 0 will be displayed from the palette.

This does not give faster graphics.

Faster graphic command interpretion

All coordinates in graphical commands are CLIPPED like this:

If coordinate < 0 then coordinate = 0
If coordinate > max then coordinate = max

This takes time and is only neccesary if the programmer doesn't know what (s)he is doing. If you want to get faster commands then do this POKE after the CALL TURBOON:
POKE &HF7C0,0 'Disables CLIPPER routine.
Or you can write this line in XBASIC to do the same: #C-

This gives up to 25 times faster commands depending on how big areas on the screen is involved in the command.

A "LINE(0,0)-(255,255),0,BF" will not get faster. If a lot of "COPY (X,Y)-STEP(15,15) TO (X2,Y2)" are used then they will be faster because the XBASIC will send send the commands faster to the VDP.

Use POKE &HF7C0,1 to enable the clipper again. (OR #C+)

When the clipper is disabled you can also use commands like this: LINE(0,0)-(255,2047),0,BF

Henrik Gilvad, 27 June 1994.


Last updated: . © by Patriek Lesparre. Hosted by The New Image.