Isle 2D Drawing

How Earthrise Works

Earthrise steps through a list of instructions, writing the resulting pixels to vram to create a drawing. You can think of Earthrise as a simple processor designed for graphics; it fetches, decodes, and executes instructions in the familiar processor way. Isle uses a RISC-V CPU, but Earthrise has its own custom 16-bit instructions for drawing.

Earthrise instructions are of two main types: loading registers and drawing shapes. To understand why Earthrise has these two types of instructions, we need to consider the data needed to draw a shape.

To draw a triangle, we need coordinates, colour, and options (such as whether it's a filled or outline shape). Packing this information into a single Earthrise instruction would be unwieldy. We'd need variable-length instructions (triangles need more coordinates than lines), and there would be significant duplication, for example, when two triangles share coordinates. We can avoid these problems by introducing internal registers that hold coordinates and colours. Individual instructions can load values into registers. Once the required values are set, another instruction does the actual drawing.

In summary, all Earthrise instructions are 16 bits long and do one simple thing; for example, load a coordinate register, load a colour register, draw a line, or draw a triangle.

Earthrise module: hardware/gfx/earthrise.v (ref doc)

Earthrise Command List

Earthrise reads instructions from the Earthrise command list: hardware/mem/erlist.v (ref doc).

The command list is a dedicated, dual-port memory accessible to the CPU, but separate from the main system ram. There is no CPU memory contention when Earthrise fetches drawing instructions and no risk of Earthrise trying to execute RISC-V program code or data. The command list has a 32-bit data bus for simplicity when working with a 32-bit CPU; each command list location holds two instructions.

Drawing Shapes

Earthrise currently draws (outline and filled):

• Pixels
• Lines
• Triangles
• Rects
• Circles

Earthrise depends on two primitive shape drawing modules: Line and Circle. Line uses Bresenham's line algorithm to draw a line between two arbitrary points. Circle draws circles with the midpoint circle algorithm, a generalisation of Bresenham's algorithm. Using the line module, we can also draw triangles and rectangles.

• Line: hardware/gfx/line.v (ref doc)
• Circle: hardware/gfx/circle.v (ref doc)

A future post will discuss the algorithms behind these modules.

Coordinates & Colours

To draw a shape, we use the values from coordinates and colour registers:

• Four pairs of coordinate registers: (x0, y0) (x1, y1) (x2, y2) (x3, y3)
• Four colour registers (two line and two filled): lca, lcb, fca, fcb

When you issue a drawing instruction, such as draw triangle, the engine automatically selects the required coordinate registers, but you can choose whether you want an outline or filled shape and whether to use colour A or B. Having a choice of two colours in drawing instructions provides some flexibility without making the number of registers unmanageable.

Coordinates are signed 12-bit integers, so have a range of -2048 to +2047. Colours are unsigned 8-bit integers with a range of 0-255. Coordinates will likely switch to 16-bit fixed-point in future to support sub-pixel precision. Sub-pixel precision results in smoother animation, which is particularly noticeable at low resolutions.

I'm not going to discuss the internals of the Earthrise Verilog module for now; instead, I'm going to take a look at how graphics programming works and show you how to draw your own graphics.

Earthrise Demo

In this chapter, we'll use Earthrise without a CPU, relying on pre-written drawing instructions. I've configured Earthrise to execute a series of drawing instructions loaded into its command list with $readmemh.

Chapter 3 design: hardware/book/ch03/ch03.v

Build the included design, then I'll show you how to draw your own graphics. The build process is the same as the previous chapters.

Each board has its own top module:

• Lakritz: boards/lakritz/top_ch03.v (build instructions)
• Nexys Video: boards/nexys_video/ch03/top_ch03.v (build instructions)
• ULX3S: boards/ulx3s/top_ch03.v (build instructions)
• Verilator: boards/verilator/top_ch03.v (build instructions)

The all shapes test drawing (as seen in the photo above):

• Earthrise asm: res/drawing/all-shapes.eas
• compiled: res/drawing/all-shapes.mem

Graphics Programming

Earthrise instructions are simple, but writing binary or hex instructions by hand is tedious. The (forthcoming) CPU can generate them for us using functions in the Isle system library, but I've created a simple assembler format and assembler tool for programming Earthrise directly.

Drawing Lines

Earthrise assembler for drawing a couple of lines:

# set colours
lca 10  # load 10 into line colour A
lcb  8  # load 8 into line colour B

# set coordinates for 1st line
x0   8  # load 8 into coordinate x0
y0  16
x1  16
y1  24

draw line ca  # draw line (8, 16)->(16 ,24) in colour A

# set coordinates for 2nd line - use existing values of x0, x1, and y1
y0  32

draw line cb  # draw line (8, 32)->(16 ,24) in colour B

stop

You set the colours and coordinates, then issue a drawing instruction. The colour is a reference to a colour index in the colour lookup table discussed in the previous chapter on bitmap graphics.

I recommend adding a stop instruction at the end of your Earthrise commands. Otherwise, Earthrise keeps executing until it reaches the end of the command list, which wastes time and may contain old instructions.

The machine code for each instruction (in hex format) looks like this:

0xC00A  # lca 10
0xC108  # lcb  8
0x0008  # x0   8
0x1010  # y0  16
0x2010  # x1  16
0x3018  # y1  24
0xD100  # draw line ca
0x1020  # y0  32
0xD102  # draw line cb
0xCE00  # stop (CEase)

Notice how we reused coordinate registers when drawing the second line (we only updated y0).

The Earthrise programming reference describes the registers and instructions, so I won't go over them here.

Assembler Tool

The Earthrise assembler tool (erasm) converts mnemonics into hexadecimal text suitable for loading into the command list at build time using the Verilog $readmemh function.

You can find the assembler in the Isle tools directory. It's written in Python and accepts one argument, the path to a file containing Earthrise assembler instructions:

$ tools/erasm/erasm.py res/drawing/all-shapes.eas
C108C00A
10000020
30BF20DF
00DFD100
D1022020
10080014
30082014
...

Each 32-bit entry contains two Earthrise instructions in little-endian order to match the design of the Earthrise command list (discussed above).

Let's Draw

The hardware design in this chapter has a 336x192 bitmap in 16 colours using the Go-16 colour palette. The Go-16 palette is based on Gopuri16 by BBUNSIK.

With the help of the Earthrise programming reference and res/drawing/all-shapes.eas example, you can create your own drawing.

For example, draw filled squares in bright blue (colour 3) and yellow (colour 13):

# set colours
fca 3
fcb 13

# 1st square
x0 32
y0 32
x1 96
y1 96
draw rectf ca

# 2nd square
x0 128
y0  32
x1 192
y1  96
draw rectf cb

stop

Save your drawing instructions to a file, such as res/drawings/first-draw.eas

Assemble your drawing and check for any error messages:

tools/erasm/erasm.py res/drawing/first-draw.eas

Save the results into a .mem file:

tools/erasm/erasm.py res/drawing/first-draw.eas > res/drawing/first-draw.mem

Update FILE_ER_LIST in your board's top_ch03.v to point at your mem file. Then rebuild your hardware design using make or build_ch03.tcl (Nexys Video).

This chapter is a brief introduction to Earthrise; I'll have more to say about 2D graphics once we have our RISC-V CPU. For now, I want to focus on completing our graphics hardware, and our next component is a Unicode text mode.

Next step: Text Mode (under construction) or Isle Index

You can sponsor me to support Isle development and get early access to new chapters and designs.