Reading and writing PPU memory

CGRAM

The PPU contains an internal 256 x 15bit memory called CGRAM that holds the palette data.

The S-CPU can access the CGRAM using the CGADD, CGDATA and CGDATAREAD registers.

• The S-CPU can only access the CGRAM during Vertical Blank, Horizontal Blank or Force Blank.
  • If the CGDATA or CGDATAREAD registers are accessed during active-display the data will be read from or written to the wrong CGRAM address.
• CGDATA is a write-twice register. You must always write to CGDATA an even number of times.
  • The color data is only written to the CGRAM on the second CGDATA write.
• CGDATAREAD is a read-twice register. You should always read from CGDATAREAD an even number of times.
• You should always set the CGRAM word address with CGADD before reading or writing to CGRAM.
  • This will also reset an internal odd/even counter.
  • Mixing CGRAM reads and writes is not recommended.
• Each CGRAM color is 15 bits in size.
  • When writing to CGRAM, bit 15 is ignored
  • When reading CGRAM, bit 15 will be PPU2 open bus and should be masked.

To write to CGRAM, first set the CGRAM word address (ie, palette color index) with an 8-bit write to CGADD. Then preform two 8-bit writes to CGDATA. After the second write to CGDATA the color data will be written to CGRAM and the internal CGRAM word address will be incremented by one. Subsequent colors can be written to CGRAM with two more 8-bit writes to CGDATA.

.a8
.i16
// DB access registers
// REQUIRES: h-blank, v-blank or force-blank

    // Set a single CGRAM color at `COLOR_INDEX` to `COLOR_VALUE`

    // Set CGRAM word address (color index)
    lda     #COLOR_INDEX
    sta     CGADD

    // Write low byte
    lda     #.lobyte(COLOR_VALUE)
    sta     CGDATA

    // Write high byte
    lda     #.hibyte(COLOR_VALUE)
    sta     CGDATA

Variables:
    zpFarPtr - a 3 byte pointer in zero-page.


// Write a block of colors to CGRAM.
//
// INPUT: A = starting color index
// INPUT: X = number of colors to write (MUST BE > 0)
// INPUT: zpFarPtr = palette data
// REQUIRES: Vertical-Blank or Force-Blank.
//           (There is not enough Horizontal-Blank time to run this code)
.a8
.i16
// DB access registers
.proc WriteCgramBlock
    // Set CGRAM word address (color index)
    sta     CGADD

    ldy     #0
    Loop:
        // Write low byte
        lda     [zpFarPtr],y
        sta     CGDATA
        iny

        // Write high byte
        lda     [zpFarPtr],y
        sta     CGDATA
        iny

        dex
        bne     Loop
    rts
.endproc

Writing to CGRAM using DMA or HDMA is preformed using the One register, write twice transfer pattern (DMAP pattern 2). (See HDMA examples#HDMA to CGRAM for a HDMA example.)

Variables:
    cgramBuffer : uint16[256] = a buffer of 256 colors in RAM


// Transfer a 256 color buffer (`cgramBuffer`) to CGRAM using DMA channel 0
//
// REQUIRES: Vertical-Blank or Force-Blank
// DB access registers
// Uses DMA channel 0
subroutine TransferBufferToCgram:
    // reset CGRAM address
    CGADD = 0


    // DMA parameters: one write-twice register, to PPU
    DMAP0 = 2

    // B-Bus address
    BBAD0 = .lobyte(CGDATA)

    // A-Bus address
    A1T0  = .loword(cgramBuffer)
    A1B0  = .bankbyte(cgramBuffer)

    // Transfer size (SHOULD BE EVEN)
    DAS0  = .sizeof(cgramBuffer)

    // Start DMA transfer on channel 0
    MDMAEN = 1 << 0

Reading from CGRAM is preformed with the CGDATAREAD register in a similar manner as CGRAM writes. Bit 15 of the color data is open-bus and should be masked to 0.

VARIABLES: zpTmpWord - a temporary uint16 variable in zero-page.

// INPUT: A = color index to read
// OUTPUT: zpTmpWord = color value
// REQUIRES: v-blank or force-blank
.a8
.i16
// DB access registers
.proc ReadCgramColor
    sta     CGADD

    // Read low-byte
    lda     CGDATAREAD
    sta     zpTmpWord

    // Read high-byte
    lda     CGDATAREAD
    // (The MSB is open-bus and should be masked)
    and     #0x7f
    sta     zpTmpWord + 1

    rts
.endproc