Initialising the Copper

Initialising the copper is fairly straight forward, more simple than the documentation would make it seem.

Include the header file to get access to some very useful macros

#include <arch/zxn.h>
#include <arch/zxn/copper.h>

Then create your copper list

uint16_t gradientBars[] = {
    CU_WAIT(16,0),CU_MOVE(REG_PALETTE_INDEX, 0x10),CU_MOVE(REG_PALETTE_VALUE_8, 252),
    CU_WAIT(18,0),CU_MOVE(REG_PALETTE_INDEX, 0x10),CU_MOVE(REG_PALETTE_VALUE_8, 244),
    CU_WAIT(20,0),CU_MOVE(REG_PALETTE_INDEX, 0x10),CU_MOVE(REG_PALETTE_VALUE_8, 236),
    CU_WAIT(22,0),CU_MOVE(REG_PALETTE_INDEX, 0x10),CU_MOVE(REG_PALETTE_VALUE_8, 228),
    CU_WAIT(24,0),CU_MOVE(REG_PALETTE_INDEX, 0x10),CU_MOVE(REG_PALETTE_VALUE_8, 228),
    CU_WAIT(26,0),CU_MOVE(REG_PALETTE_INDEX, 0x10),CU_MOVE(REG_PALETTE_VALUE_8, 236),
    CU_WAIT(28,0),CU_MOVE(REG_PALETTE_INDEX, 0x10),CU_MOVE(REG_PALETTE_VALUE_8, 244),
    CU_WAIT(30,0),CU_MOVE(REG_PALETTE_INDEX, 0x10),CU_MOVE(REG_PALETTE_VALUE_8, 252),

    // Set border back to black
    CU_WAIT(192,48),
    CU_MOVE(REG_PALETTE_INDEX, 0x10),
    CU_MOVE(REG_PALETTE_VALUE_8, 0),

    // Wait for a nonexistent line to halt the copper at the end of the screen
    CU_WAIT(400,0)
};

Then upload the copper list to the copper’s RAM which is separate to the system RAM. I use this little C function

static uint16_t copperProgLen;

void InitCopper(uint8_t copperProg[])
{
    uint8_t *copperPtr = copperProg;
    copperProgLen = sizeof copperProg / sizeof *copperProg;
    for (int i = 0; i < copperProgLen*2; i++) {
        IO_NEXTREG_REG = REG_COPPER_DATA;
        IO_NEXTREG_DAT = copperPtr[i];
    }

    IO_NEXTREG_REG = REG_COPPER_CONTROL_H;
    IO_NEXTREG_DAT = 0xC0;
    IO_NEXTREG_REG = REG_COPPER_CONTROL_L;
    IO_NEXTREG_DAT = 0;
}

That’s it, the “code” is now running. Read on to find out how to use this to make some interesting effects.

It’s important to have a distinction between the list of copper commands in your C code and the list of instructions the copper is running. They are different. Changing the list of instructions in your code’s copper list does nothing until that code is uploaded to the copper itself.