65c02 Assembly programming for the Commander x16

*** Warning - The X16 is a prototype - it's hardware could change at any time*

*** Double Warning - V31 of the emulator changed many video register addresses...
sources.7z has been updated, but documentation on this site will not be updated until emulator reaches final state*

The Commander x16 is a FPGA enhanced recreation of the C64, adding high resolution graphics, Tilemap support and hardware sprites it gives the 6502 programmer the opportunity to develop for a more modern system with the familiarity of the C64. The commander X16 is still under construction - the developers have a facebook group here

Commodore 64 Commander x16 Cpu 1mhz 6510 (6502 base) 8mhz 65x02 Ram 64k 512k+ Sprites 8 per line (24x21 px) 128 sprites 8x8 to 64x64 Resolution 320x200 2 color 160x200 4 color Up to 640x480 256 color Sound chip SID 2x AY-3-8910 + Digital Sound

New Ports
The 'Vera' Graphics

VRAM

To access this data - write an address to $9F20-$9F22, then read or write with port $9F23

256 color Hello World on the Commander x16 with the x16emu Lets create a Hello World example, using a bitmap font in 256 color mode.

x16_HelloWorld.asm

Using 256 color BMP screens...

The x16 can run .PRG files in the same way as a C64... we're creating a generic header here for
We're going to need some bytes of the zero page, to make them easier, we'll give them pair names... We define them with EQU statements
We're going to need access to the new hardware using ports $9F20-$9F27 We need 3 'address' ports between $9F20-$9F22 ... these define the 20 bit VRAM address we want to write to. When we write to $9F23 the data we write will be written to VRAM... as long as increment is enabled (with the top nibble of $9F20) we can keep writing more bytes to the screen... We also need the control port to set up the Address port (we only use this once!)
First we need to set up our port... we're going to use port 1 at adress $9F23... We need to set up the Address ports at ($9F20-#9F22) to control port 1... we do this by setting Bit 0 to 0 and writing to 'Vera_Ctrl' at $9F25
We're going to need to set our VRAM address a lot! we'll use the AYX registers to set the VRAM HML writing address... Don't forget, we'll probably want to set the top nibble of A to $1- to ensure the address auto increments with each write!
OK, we're ready to start writing... first we need to set up our screen layout... we need to write to VRAM addresses $40040-$40042 $40040 will turn on the screen for us... We'll use $40041 & $40042 to set the screen size The result? a 320x240 screen of 256 colors!
We're going to set up our palette... we do this by writing to VRAM address $40200 onwards... The code here will copy 256 color entries to VRAM. Each palette entry takes 2 bytes... one nibble per byte. Because the 65c02 is little endian, the first byte is $GB, the second is $-R The sample palette shown will set up a CPC type color palette... with a blue background, and yellow text! (Note... the palette screenshot is abridged... there's more test colors in the sourcefile)
OK, we've got our palette set up, but now it's time to turn on our screen and set it up... We set up the screen as an 8 bit per pixel (256 color) bitmap screen by setting the top 3 bits of $040000 - we also set the bottom bit 0 to turn on the screen We also reset all the other parameters, we write zeros to $040001-$040009
Our screen is now set up, so lets test it! Each pixel of the screen is 1 byte, and the screen starts at vram address $0000... each line is 320 bytes wide and the screen is 240 lines tall, so the screen is 76,800 bytes in size To test the screen, and see our palette, we'll fill the entire screen with concecutive bytes
The results can be seen to the right!

Printing characters to the screen...

We're going to define another function to set the VRAM write address... AddVHML_AYX will add AXY (or just XY) to the address we're writing to... We'll use this during calculations of addresses, and to move down a line after drawing parts of our characters
OK, lets start printing our character! We're using a 1bpp font (as seen in the regular tutorials)... but our font has no characters below 32... so first we subtract 32 from our character number/ Each 1bpp character is made up of 8 bytes, so we multiply the number of the character we want to show by 8, and add the base address of the BitmapFont... we store the result in zero page z_hl ... this is our Source bitmap font data.
We've calculated our source address, now it's time to calculate the destination. We're using two bytes in RAM defined as CursorX and CursorY... these are the X,Y position of our 'Cursor' in characters... We need to calculate the address of the character position... to do this we need to use the following formula Address = VRAM Base + CursorY * FontHeight * ScreenWidth + CursorX * FontWidth So Address = 0 + CursorY * 8 * 320 + CursorX * 8 We achieve these multiplication by a series of bitshifts and additions... using z_de as a temporary holder during the calculations... once we've calculated the Y part, we do the same for the X part, and add the two together... we have to ensure we pass any carry to the higher byte... Once we're done, we use SetVeraHML to set the address from AYX
OK, we're going to need to copy the data from z_HL, and write it to V_D1.... The source data is 1bpp... the destination data is 8bpp So, we read in one byte from z_HL - store it into z_As, then we pop each of the bits off the left of the byte... writing each to the screen data... We use X as a pixel counter for the line, so we repeat this pixel shifting 8 times
Ok, we've done one line of our font... so we need to move down a line Each line is 320 bytes, BUT our character is 8 - so we add 320-8 to the memory address to calculate the next line. We use Y as a counter for the line (and an offset for the font source address) we INC Y until it reaches 8 Once we've finished drawing our character, we increase our CursorX... we check if we've gone over the 40 character wide screen, if it has we use our NextLine function to move down a line
We need some functions to complete the code - these are almost the same as the c64 originals (we now use 65c02 command STZ)
The results can be seen here.. In this example, we've use the PrintChar function to run a monitor tool to show the registers and memory... this will help with future development on the x16!

X16:2 - 2x 16 color Layers on the Commander x16 When we looked at the last episode, the Command x16 emulator 4bpp support did not work... however now it's been fixed... Lets use it to create two 320x240 sixteen color (4bpp) layers and see what they can do!... we'll even 'upgrade' our hello world code to work in 4bpp!

x16_Multilayer.asm

4bpp Bitmap font

We're going to convert our old code, and make it 4bpp... because we've halved the number of bytes, our screen is now 160 bytes wide. We need to alter the calculation code of our screen calculation code. If we remove two of the rotate commands, we'll effectively halve the calculations from 320 bytes per X line to 160
We need to change the byte copying code... the 4bpp mode has 2 pixels per byte (with each pixel color defined by a nibble in the byte)... we need to shift 2 bits from the source font into our byte before storing it to the screen... We also need to alter our 'newline' code, as the screen is 160 bytes wide, and our font is 4 bytes wide... so the calculation now adds 160-4 to move down a line.

2x 4bpp Layers

Just like last time we need to set the registers for Layer 1 with the registers at VRAM $040000 Last time we set the top 3 bits to 7 (BMP 8bpp)... this time we want to use mode 6 (BMP 4bpp)... we're going to set the screen up as 320x240 again, as there are now two pixels per byte, this time the screen will be 320x200/2=$9600 bytes in size. We need to define an offset for the layer in VRAM with Registers $40004/5.... the first layer is at $00000 (like before)

Ok, on to the second layer... it's register format is identical... but the registers at $040010 Again we set up a layer in Mode 6... so this layer will also be 4bpp We need to define an offset for the second layer in VRAM with Registers $40014/5.... we don't want it to overlap the last screen, so we'll put the second layer is at $0A000 (like before)

Due to the size of the screens, there isn't enough memory for two 320x240 bitmap screens with 256 colors, but 16 color layers are likely to be enough for any realistic needs! Most systems from the 90's only had 16 colors or less anyway, so it's what a classic system had to work with.

Putting a bitmap on the screen

We're going to show a bitmap to the screen! The 4bpp format is simple... 2 pixels per screen byte... the top nibble (%XXXX----) is the left pixel... the bottom nibble (%----XXXX) is the right pixel Essentially, the x16 4bpp mode is the same format as most other 16 color systems like the MSX (but not the CPC Mode 0!)
We're going to load our address bitmap (in program code) into zero page entry z_hl... the 4bpp bitmap is 48x48 The VRAM destination will be the top left of screen Layer 2... as the screen starts at $0A000, this is the address we write to for the top left.
We need to copy all the data from our bitmap to the screen... Because our screen is 4bpp (2 pixels per byte)... we only need to write 24 bytes per line... We use a function IncHL to update the zero page z_hl pair... When we get to the end of a line (when the X register reaches zero)... we do the next line... we need to add 160 to the VRAM position, but we need to subtract the 24 byte width
The Chibiko bitmap on Layer 2 has been drawn over the background text on Layer 1 ! We'll notice the background color 0 of the bitmap in layer 2 is transparent... we'll also notice the colors are wrong!

Changing the layer

Lets fix those colors... The layer uses only 16 colors of our 256 color palette... but we can alter WHICH 16 colors... Rather than using colors 0-15 (&00-&0F) we can set it to use colors 16-31 (&10-&1F)
We do this with VRAM register $40017 - L2_BM_PAL_OFFS... In tile modes this is a scroll option (L2_HSCROLL_H) but in bitmap modes the register has the alternate purpose... Effectively the bottom nibble of $40017 sets the top nibble of the color for Layer 2... (suffice to say there is a similar register for Layer 1 at $40007)
If we want, we can hide the layer, we just turn it off with the bottom bit of $40010

The 'Hscroll' option works as a Palette offset for bitmap modes... unfortunately it seems there's no hardware scroll option for the bitmap modes... If we want to do scrolling, we're probably going to be best to use tilemap modes (we'll look at them soon)... otherwise we'd have to use software scroll.

X16:3 - Hardware Sprites on the Commander x16 The X16 is capable of good hardware sprites... with sizes from 8x8-64x64 - in 16 or 256 colors,with 128 sprites onscreen We've got a lot of capability! Lets learn how to get some sprites onscreen!

x16_SpriteTest.asm

Setting Hardware sprites

Each of the 128 sprites are controlled by settings held in VRAM between $40800-$40FFF... each has 8 bytes...
The actual bitmap data of the sprites is held in normal VRAM - so we want to store it outside the visible screen...

Before we can actually use sprites, however, we need to turn them on, we do this with Bit 0 of $40020

Bitmap Data format

The Sprites can be in two formats: in 8bpp (256 color ) mode, each byte is the color number in 4bpp (16 color ) mode ,a byte covers two pixels... the High Nibble (%XXXX----) is the left pixel, the Low Nibble (%----XXXX) is the right pixel Data in these formats can be exported from my AkuSprite Editor

Some useful new functions for VRAM

We're going to define a new macro called 'SetVeraAddr'... It will set the 3 bytes of the 20 bit address (and the autoinc parameter)... this will be a bit easier than our previous SetVeraHML command
We're going to define a new function 'VLDIR'... it uses z_BC and z_HL zeropage pairs and mimics the Z80 LDIR command. this will load z_BC bytes from z_hl and write them all to VERA port v_d1 ($9f23) We can use this to copy bitmaps  to VRAM

Coding Sprites

We're going to copy data from the label 'Sprite' to the VRAM... We need to copy our sprite bitmap to an area outside of visible VRAM... I copied the sprite to $10000 - which is outside of the visible screen for a single 4bpp layer
Now we need to turn sprites on, we do this by writing a #1 to $40020
We're going to create a simple function to set a hardware sprite! We'll use A to define the hardware sprite number, zeropage z_IX for the Xpos, z_IY for the Ypos, and z_HL defines the source Vram address (bitshifted 5 times to the right) Each sprite has 8 bytes of data, so we multiply A by 8 (via bitshifting) and add $40800 (as this is the base of the sprite data) We use SetVeraHML to set the VRAM address to AYX We're ready to send the sprite settings!
Ok... we're ready to start sending the sprite settings... First we send the address of the sprite in VRAM (RORed 5 times)... the top bit of the address has a different purpose, it defines if the sprite is 256 color or 16 color - 0=4bpp,1=8bpp Next we send the Xpos and Ypos
We're going to set up some more settings, the Z Layer position of the sprite (3=Top) We'll set the size of the sprite to 16x16.

Here we've shown a single sprite frame, but if we have multiple versions of the sprite at different addresses, we just need to alter the address to update the animation of the sprite... Take a look at the example in the sources file to see more!

Using our Sprite routine

We can use this function to draw a sprite to the screen, the example shown will show a 256 color sprite (due to the $8--- at the top of z_hl) from memory position $10100 (10100 shifted right 5 times= $808) Hardware sprite 0 will be shown at (10,10)
The sprite will be shown to screen.

The example in this episode works fine for hardware sprites 0-15, but not 16+... it's not clear why! Unfortunately, with the documentation limited, and the emulator in an early state, When something doesn't work it's not clear if it's an Emulator but, Unclear documentation, or a mistake by the author of these tutorials... If a solution becomes clear later, the code sample will be updated.