mahnke.tech

3d Graphics on the Commodore 64, Part One

Fri, 12 Apr 2019 00:00:00

Published on 2019-04-12

This is something that came from an exercise I’ve given myself to improve my assembly language skills, which in turn is to improve improve the ISA design for my homebrew vale8 computer.

I’m interested in demoscene culture in general, and there’s a lot of demoscene-related documentation for the C64 machine. After doing a custom font and basic scroller effects on the C64, I thought a more challenging project in 6502 might be to animate wireframe geometry (the seminal “spinning cube” effect).

Here’s the result, a spinning pyramid.

In this multi-part post series, we’ll make this effect using C and 6502 assembly. The line drawing routines are in 6502 assembly, whereas the model’s vertices are pre-calculated using a C program.

Prerequisites

Understanding of C.
Understanding of 6502 assembly language.
Ability to assemble programs and run them in an emulator, or on a C64.

Further References

Disclaimer

I’m a novice 6502 programmer. Demoscene veterans do this sort of thing with much better performance. I’m just showing the way that I worked out for myself. I know there are opportunities for optimization, and I’m looking forward to learning more of them.

Procedure

We can divide the procedure of animating 3d geometry into a few steps. The program must follow each step for each frame of animation.

Draw the Model’s Faces

For each face, draw a line from one vertex of the face to the next, in a counterclockwise direction.

Transform the 3d Model in the World

In our case, change its rotation about the y axis each frame.

Transform Model Vertices to Display Coordinates

Convert each vertex from its 3d coordinate space to a 2d pixel coordinate on the C64’s 320x200 bitmap display.

Prerequisites to Drawing Lines

Modern video cards support graphics APIs that are high enough in level as to provide either immediate- or retained-mode functions to draw primitives like lines and polygons. The C64 provides no such interface for drawing primitives in its bitmap modes. Instead, we set the color of each pixel individually. Since we’ll implement line drawing routines that will tell us which pixels to set, we need to also make some routines to actually set those pixels.

We’ll understand how to use the C64’s standard high-resolution bitmap mode and then create some subroutines to make it convenient to use with cartesian coordinates.

Standard High-resolution Bitmap Mode

The C64 provides two bitmap modes. The one we will use is the standard high-resolution bitmap mode. This mode gives us 320x200 pixels, where each pixel may be one of 2 colors chosen from the 16-color palette. I’ll refer to it as “bitmap mode” going forward.

Enabling Bitmap Mode

To enter bitmap mode, set bit 5 of register $d011 to 1, as follows:

    lda $d011
    ora #$20
    sta $d011

Setting Bitmap Memory Location

The location of the start of bitmap memory can be either $0000 or $2000 (8192). This number is in bytes relative to the start of the current VIC bank. The default VIC bank starts at memory location $0000. If we leave it there, we must set the start of bitmap memory to $2000 since there are some lower memory values we cannot modify.

To set the start of bitmap memory to $2000, set bit 3 of register $d018 to 1:

    lda $d018
    ora #$08
    sta $d018

Bitmap Memory Arrangement

The bitmap memory is an 8192-byte array of memory. Each bit of each memory address is used to set the color of a corresponding pixel on the display.

From the perspective of a human accustomed to using the cartesian coordinate system, the VIC uses bitmap memory in an inconvenient way. We might have expected the memory to be mapped to the display something like this.

Instead, we have this.

One way to think of the bitmap memory is a 40x25 grid of cells, each of which is 8 pixels wide and 8 pixels high. This gives us 320 columns and 200 rows of pixels.

The grid of cells starts in the top left corner of the display. The bitmap memory address corresponds to a row of 8 pixels in a cell. When we increment the bitmap memory address, we move down to the next row of pixels in the current cell. When we move past the bottom row of pixels in the cell, we move to the top row of pixels in the next cell to the right. When we move past the rightmost cell in the row of cells, we move down to the leftmost cell in the next row of cells.

Once again, the value of each bitmap memory address controls the colors of one row of 8 pixels in a cell. Bit 7 (the highest bit) of the value controls the leftmost pixel, and bit 0 (the lowest bit) controls the rightmost pixel. Since each bit can be set to either 0 or 1, there are two possible colors for each pixel in any given cell.

Bitmap Colors

In bitmap mode, each byte of display memory $0400-$07e7 controls the color of all pixels in a corresponding 8x8 cell of the bitmap. The upper 4 bits of the byte determine the color of a pixel whose bit is 1 in bitmap memory, and the lower 4 bits of the byte determine the color of a pixel whose bit is 0 in bitmap memory. The display memory maps to bitmap cells left to right, top to bottom. The following example sets the second cell in the first row of cells (pixel rows 0-7 and columns 8-15) to an alternating cyan-and-black pattern, as shown in the previous images.

lda #$aa
sta $2008
lda #$30
sta $0401

Here is a test program demonstrating how bitmap and color memory work.

This is everything we need to know about bitmap mode before we implement our drawing routines.

Pixel Placement Routines

Our line drawing algorithms will give us the results in cartesian coordinates. This is typical, so we want to address the bitmap in cartesian terms, if possible. So let’s define some drawing routines that take cartesian coordinates as input and modify the bitmap memory appropriately behind the scenes.

We’ll define several routines that allow us to control a “pen” on the display. With these routines, we can move the pen to (almost) any (x, y) coordinate on the display, move the pen relative distances in four directions, and set the color of the pixel where the pen is located. Here is the commented source code for all the functions.

;; pen_init: Initialize the pen. Call this routine before
;; each invocation of pen_move_to.
pen_init:
    ;; Set pen address to beginning of
    ;; bitmap memory.
    lda #$20
    sta pen_addr_hi
    lda #$00
    sta pen_addr_lo

    ;; First pixel row in the cell.
    lda #$07
    sta pen_row_loc

    ;; First pixel column in the cell.
    lda #$80
    sta pen_pixel_bit

    rts

;; pen_move_to: Move the drawing pen to an (x, y) pixel
;; coordinate position on the display.
;; args
;;   y: y coordinate of the position
;;   x: x coordinate of the position
pen_move_to:
    pha
    tsx

    ;; Divide y by 8 and look up the address of the cell in
    ;; bitmap memory. The result is within 7 bytes of the
    ;; right address for the y coordinate. Store the result
    ;; to pen position.
    lda arg0
    lsr
    lsr
    lsr
    tax
    lda .cell_addr_hi,x
    sta pen_addr_hi
    lda .cell_addr_lo,x
    sta pen_addr_lo

    ;; Take y % 8, which is the number of bytes to add to
    ;; get the pixel row. Add it to the current pen
    ;; position and store new pen position.
    ; y % 8 == a & (8 - 1)
    lda arg0
    and #$07
    sta $0101,x

    clc
    adc pen_addr_lo
    sta pen_addr_lo

    ;; pen_row_loc == 7 - pixel row
    lda #$07
    sec
    sbc $0101,x
    sta pen_row_loc
    pla

    ;; Begin with pen_pixel_bit == #$80, which
    ;; represents the leftmost pixel column of the current
    ;; cell. Shift right x number of times. If we shift all
    ;; the way to the right and out of the register, add 8
    ;; to disp_pen_addr, which moves to the next cell.
+++ ldx arg1
    beq ++
-   lda pen_pixel_bit
    lsr
    sta pen_pixel_bit
    bne +
    lda #$80
    sta pen_pixel_bit
    lda #$08
    clc
    adc pen_addr_lo
    sta pen_addr_lo
    bcc +
    inc pen_addr_hi
+   dex
    bne -
++  rts

;; pen_move_up: Move the pen one pixel row up on the
;; display.
pen_move_up:
    ;; Move one pixel row up in the current cell.
    inc pen_row_loc
    lda #$08
    sec
    sbc pen_row_loc
    bne ++
    ;; If we leave the current cell, move to the bottommost
    ;; pixel row one cell up; effectively subtract 313 from
    ;; the pen address.
    lda #$00
    sta pen_row_loc
    lda #$01
    clc
    adc pen_addr_lo
    sta pen_addr_lo
    bcs +
    dec pen_addr_hi
+   lda #$c6
    clc
    adc pen_addr_lo
    sta pen_addr_lo
    bcs +
    dec pen_addr_hi
+   rts

;; pen_move_down: Move the pen one pixel row down on the
;; display.
pen_move_down:
    ;; Move one pixel row down in the current cell.
    dec pen_row_loc
    bpl ++
    ;; If we leave the current cell, move to the topmost
    ;; pixel row one cell down; add 313 to the pen address.
    lda #$07
    sta pen_row_loc
    lda #$ff
    clc
    adc pen_addr_lo
    sta pen_addr_lo
    bcc +
    inc pen_addr_hi
+   lda #$3a
    clc
    adc pen_addr_lo
    sta pen_addr_lo
    bcc +
    inc pen_addr_hi
+   rts

;; pen_move_left: Move the pen one pixel row left on the
;; display.
pen_move_left:
    ;; Shift the pixel column bit left and store.
    lda pen_pixel_bit
    clc
    asl
    sta pen_pixel_bit
    bcc +
    ;; If we shifted out of the left, put the bit back into
    ;; the right side of the value, and move to the same
    ;; pixel row in the previous cell; effectively subtract
    ;; 8 from the pen address.
    lda #$01
    sta pen_pixel_bit
    lda #$f8
    clc
    adc pen_addr_lo
    sta pen_addr_lo
    bcs +
    dec pen_addr_hi
+   rts

;; pen_move_right: Move the pen one pixel row right on the
;; display.
pen_move_right:
    ;; Shift the pixel column bit right and store.
    lda pen_pixel_bit
    lsr
    sta pen_pixel_bit
    bne +
    ;; If we shifted out of the right, put the bit back into
    ;; the left side of the value, and move to the same
    ;; pixel row in the next cell; add 8 to the pen address.
    lda #$80
    sta pen_pixel_bit
    lda #$08
    clc
    adc pen_addr_lo
    sta pen_addr_lo
    bcc +
    inc pen_addr_hi
+   rts

;; pen_px_set: Set the bitmap memory bit representing the
;; current pixel position to 1.
pen_px_set:
    lda pen_pixel_bit
    ldx #$00
    ora (pen_addr_lo,x)
    sta (pen_addr_lo,x)
    rts

Here is the complete pen source file.

We can draw any shape we want from our assembly language programs using these pen routines.

Here is a test program that uses the pen to draw straight lines from the right side of the display to the left, then left to right, then top to bottom, then bottom to top.

You might have noticed the line from right to left does not originate from the far right side of the display. Examining our subroutine declaration again:

;; pen_move_to: Move the drawing pen to an (x, y) pixel
;; coordinate position on the display.
;; args
;;   y: y coordinate of the position
;;   x: x coordinate of the position

We take two arguments, y and x. Because x is supplied in an 8-bit memory location, the maximum value of x is 255. However, the rightmost pixel column on the display is 319. Because the size of the memory location that stores x is smaller than 319, pen_move_to can’t reach the right side of the display. Since our geometry will not be drawn onto the far right of the display, this is not a problem for our use case. If we want pen_move_to to reach past column 255, we can do that by taking a third argument holding one extra bit for x. When the bit is set, the column counter first counts to 255, then resets to zero, then counts again until reaching the value of the “x” argument.

Wrapping Up

Here is a zip file containing the test_bitmap and test_pen programs, as well as all the files needed to build and run them.

In the next part of this series, we implement routines to draw lines directly from any pixel on the display to another, automatically calculating all the pixels in between. Please contact me on the fediverse or Twitter with any questions or comments.

The vale8 Instruction Set

Fri, 12 Apr 2019 00:00:00

Published on 2019-04-12

One of the earliest challenges I faced when I decided to design a custom CPU for the vale8 was that, because I had almost no practical experience with assembly language(s), I also had little intuition for knowing what instructions to include in the CPU’s instruction set. My experience creating GB and 8085 CPU emulators was helpful in that I at least understood how to implement many common CPU instructions. Regardless, it was clear I needed a wider perspective.

There are other ways to approach designing a CPU’s ISA than from the viewpoint of the assembly language programmer. For example, if the CPU is mainly intended to be used with one or more higher-level languages, it can implement the minimum subset of instructions required by those languages. However, designing around support for higher level languages with no attention to the assembly language could result in a product that’s unpleasant to program using assembly language.

While I am interested in implementing either Forth or BASIC on vale8 eventually, I’m going to keep them out of scope for now. That means assembly is the single supported programming language for the first version of vale8. With that in mind, my goal for the instruction set is for it to be as simple as it can be while still being fun to program directly in assembly.

To get a better sense of how “good” assembly languages feel, I’ve decided to do some small projects in assembly language for one or more popular 8-bit processors. I’ll take that practical experience back to the vale8 ISA design.

Introducing the vale8x64 Computer

Tue, 09 Apr 2019 00:00:00

Published on 2019-04-09

History

I missed the majority of the home computer revolution of the 1970s and ’80s. If I’d been born a few years earlier, I might have used an Apple IIe or Commodore 64 at home. But Nintendo’s marketing game was strong and reached my brother and me at young ages. The NES became the first “computer” in our household. I was fascinated by it, but the NES wasn’t presented as a personal computer. It didn’t welcome exploration. I don’t recall ever feeling encouraged to take it apart to get to know what was inside.

I don’t even remember having a concept of a home computer when we got our first one. It had an 80286 CPU with MS-DOS 3.3, 1 MiB RAM, 5.25” floppy disk drive, 20 MB hard drive, CGA-compatible graphics and a monochrome monitor, custom built at a local computer store.

I was immediately interested in the machine. Information wasn’t as plentiful as it is today, but was available in the computer’s manuals and from the owner of the computer store. I remember going to the library, finding the computer section, and checking out my first programming book. I think this was it.

My first programming book.

That book introduced me to the BASIC programming language. Fortunately, DOS provided a BASIC interpreter. I was able to start writing my first programs using the examples in the book, which were simple number guessing games and word games with shallow branching logic.

“Gee-Whiz” BASIC, the programming language bundled with MS-DOS.

Not long after, we got Microsoft QuickBASIC. The manual had example programs. I was able to make most of the example programs work, but not all of them. I didn’t comprehend what I was reading in the manual the way I would have needed to use the language in a truly general purpose way. The results I created were the best I could do at the time, but incomplete. But that was fine; I was programming and I was happy.

The iconic QuickBASIC launch screen.

I learned BASIC and QuickBASIC’s program structure well. Variables, for loops and other control structures, and subroutines made sense. But I didn’t understand the memory model. I didn’t know how to talk to the computer’s hardware. I didn’t know what assembly language was. I was vaguely aware that there were ways to program the computer other than BASIC and QuickBASIC. I knew there were things called binary and hexadecimal, and I thought you could write programs with them. Although I studied geometry, algebra, and calculus in high school and university, I didn’t develop a joy or intuition for how math and programming intertwine during that time. With regard to deeply understanding computers, I kind of got myself stuck. I resigned myself to being an expert computer operator, but only a casual computer programmer, for many years.

Over time, and with much help, I eventually improved at programming to the point that I can now demonstrably be paid to it. I have better intellect and focus to understand the things I couldn’t before. But commercial software development practices and modern consumer hardware favor using libraries, frameworks, and other layers of abstraction over really knowing what happens inside the machine and programming directly against its hardware. And the layers of abstraction increase with each new generation of consumer computers and OS software.

I think there was a time when it was more natural to learn the fundamentals of computing as part of being either a computer enthusiast or professional. In this sense, my comprehension came too late; I had missed out on the first era of low level computing in popular culture.

In the present moment, near future, and near past, I only consider a small slice of all the possible choices and outcomes. Planning into the future is done using a small known set of alternatives, compared to what we learn was possible in retrospect. Perspective widens as history moves further away; looking at time passed, I can see everything I did, but also everything I couldn’t or chose not to do at any time. It’s sometimes natural to see things not done as missed opportunities. But this is only true if the window of opportunity has actually passed. Otherwise, the feeling of having missed out is erroneous; realizing there’s something valuable left undone isn’t identifying a missed opportunity, it’s identifying a new one.

Beginnings (from Breadboard to FPGA)

After I started studying electronics and computer architecture last year, I started designing my own computer. I committed to creating most major components (RAM is an exception) from first principles, down to and including its processor. This has become a major project that I’ve named vale8x64 (vale8 for short). I see vale8 as one opportunity to fill gaps in my understanding of technology and gain the experience I previously missed. The exercise of creating vale8 is my means of learning computing down to the metal, silicon, and logic. It’s free, with all HDL and software licensed under GPLv3 from the beginning, in case what I learn during this project will eventually be helpful to someone else as well.

Although I can trace its roots back to my growing interest in emulation, vale8 really began when I started working with TTL logic. Throwing logic chips on breadboards was a fun and tangible way to start building a computer, with the wiring helping me visualize how data flows on the bus. But I quickly grew frustrated with the high cost of parts and long iteration times. Routing and wiring on a breadboard takes careful planning, especially if wiring is to stay neat, so the breadboard method didn’t lend itself to long-term experimentation. I started to look for alternatives.

I knew FPGAs existed and understood them as a way to implement reconfigurable hardware using a programming language, but didn’t understand at all how they worked. I began researching and learning VHDL and Verilog. I reproduced what I had done on the breadboards in VHDL and simulated the results using GHDL. After I’d reached parity between the breadboard design and the VHDL version and felt like I conceptually understood how an HDL describes hardware, I started to look into FPGA boards.

I use free software as exclusively as possible, so the first criterion I chose for my search was a free software toolchain. I was surprised to find only one: Project Icestorm. Apparently the development tooling for FPGAs in general is in a pretty backwards state, with most vendors supplying bloated, node-locked proprietary software packages and keeping the FPGA bitstream details locked away, slowing development of free software alternatives. I was grateful to find IceStorm and familiarized myself with the specs for the Lattice iCE40 line of FPGAs, which is what IceStorm currently supports. I found the iCEstick, a starter board in a USB stick form factor, and ordered it.

I knew I would hit the iCEstick’s limitations pretty quickly. In particular, there wouldn’t be enough GPIO pins to do both VGA and serial I/O at the same time. But since I’d yet to synthesize my first bitstream and program it to an FPGA, it seemed like a good place to start.

I converted all my VHDL to Verilog, since IceStorm doesn’t currently support VHDL. I reached and surpassed my breadboard design, creating a turing complete CPU with a minimal instruction set on the iCEstick board.

It’s been a pleasure so far to use the IceStorm toolchain in my Make-driven workflow and to read its documentation. IceStorm makes me feel like I’ve gotten into FPGA development at a great time.

I filled the iCEstick’s PLBs to capacity, and then ordered the UP5K breakout board to give myself more PLB and I/O capacity. The UP5K is what I’m currently using to develop vale8.

Specs

Here are the currently planned specs for the first version of the vale8 product and some notes on each.

16-bit address/8-bit data CPU

I’m developing a custom processor to act as vale8’s CPU. It is influenced by RISC-V, ZipCPU, and others.

I’ve created several iterations of the CPU’s instruction set so far, learning from mistakes each time. I expect several further iterations before the ISA is final.

The CPU clock speed is to be determined, because it depends on the final configuration of the peripherals and external memory, which is also to be determined.

A 16-bit address width allows the processor to address up to 64 KiB of memory.

8-bit data seems to be a good balance between minimalism and ability for creative expression. The demoscene started on machines with 8-bit processors.

8 bits is also a good size for a programmer to practice use of full adder logic, since add with carry is frequently used to operate with numbers larger than 8 bits.

16-bit address/8-bit data width is a common configuration for 8-bit processors of the day, notably the 6502, 8085, and Z80.

6502 Pinout, with 16 address lines and 8 data lines.

Memory-mapped I/O

With memory-mapped I/O, both the computer’s memory and its I/O devices use the same address space. In other words, communicating with an I/O device is done simply by reading from or writing to a location in memory.

This is a very simple way to do I/O, and since vale8 has a small number of I/O peripherals, the impact on available system memory should be acceptable.

RS-232 Serial Port I/O

The serial port can be used to exchange data between the vale8 computer and a different computer over a serial cable. In this way, you can use another computer to reprogram the vale8’s memory. You can also type commands to it interactively with the other computer’s keyboard.

Supporting serial communication delays the need for both persistent program storage and a keyboard controller.

Character Cell VGA Graphics

Character cell graphics is a system in which the display is arranged in rows and columns of characters of equal dimensions. For example, the display may be 320x240 pixels and 40x30 characters. In this case, each character is 8x8 pixels.

The running program selects the character to be used in each row and column of the display from the set of available characters in the computer’s memory. In this way, the program chooses what combination of letters, numbers, or graphical characters appear on the screen to make text or graphics.

The computer usually provides a standard set of characters for convenience, but characters may also be reprogrammable.

Now that we’ve discussed character cell graphics in general, here’s a test image from an early version of the vale8 VGA controller.

vale8’s display resolution, character dimensions and number of available colors are to be determined, although the first version is likely to support one color (monochrome).

I plan for the VGA controller to support programmable characters. In lieu of full bitmap graphics support, this provides some ability to customize graphics.

Sound Generator

I’m inspired by subtractive synthesizers like the NES APU and the SID (used in the Commodore 64). The target for the Vale Audio Unit (VAU) is a 4-oscillator sound generator, with each voice independently supporting triangle, variable-duty pulse wave, sawtooth, and noise waveforms. I’m working on the VAU presently, and specs may change depending on what fits on the final FPGA’s resources.

See the vtracker repository if interested in following the progress of the VAU. I’m developing a tracker (music sequencer) along with the VAU itself.

Hosted Machine Code Monitor

The machine code monitor is among the most fundamental user programs, so vale8’s ROM will include one. The CPU instruction set has a BRK (“break”) instruction that saves the CPU state and then then jumps into the machine code monitor for interactive debugging.