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</tt> is a read-twice register. You should always read from CGDATAREAD</tt> an even number of times.
 * You should always set the CGRAM word address with CGADD</tt> 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</tt>. Then preform two 8-bit writes to CGDATA</tt>. After the second write to CGDATA</tt> 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</tt>.

.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 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</tt> 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

OAM: Object Attribute Memory
The PPU contains two internal RAM blocks (a 512 byte low-table and a 32 byte hi-table) that form the OAM.

The S-CPU can access the OAM using the OAMADD</tt>, OAMDATA</tt> and OAMDATAREAD</tt> PPU registers.


 * The S-CPU can only access the OAM during Vertical Blank or Force Blank.
 * Writing to OAMADD</tt> sets an internal 9 bit OAM word address.
 * The 8th bit of the internal OAM word address (bit 0 of OAMADDH</tt>) determines which OAM table accessed.
 * The internal OAM address is reset whenever OAMADDL</tt> or OAMADDH</tt> is written to.
 * You should always set both OAMADDL</tt> and <tt>OAMADDH</tt> (eg, with a 16 bit write to <tt>OAMADD</tt>) when setting the OAM word address.
 * You should always write to <tt>OAMADD</tt> before transferring data to the OAM.
 * <tt>OAMDATA</tt> is a write-twice register when writing to the OAM low-table.
 * When writing to the low-table, the data is only written to the OAM on the second <tt>OAMDATA</tt> write.
 * When writing to the hi-table, the data is written to the OAM on every <tt>OAMDATA</tt> write.
 * Despite this, you should always treat <tt>OAMDATA</tt> as a write-twice register.
 * The internal OAM addresses is reset to the last value written to <tt>OAMADD</tt> when VBlank starts and the screen is enabled (not in force-blank).
 * <tt>OAMADD</tt> can also enable OAM priority rotation.
 * When using OAM priority rotation, the first-sprite is updated and may be incremented on every <tt>OAMDATA</tt> write or <tt>OAMDATAREAD</tt> read.
 * If you are using OAM priority rotation, you will need to write to <tt>OAMADD</tt> any after a OAM transfer to reset the first-sprite.

Reading and writing to OAM is the same as writing to CGRAM, except the OAM address register (<tt>OAMADD</tt>) is 16 bits wide.

It is highly recommended that you create a 544 byte OAM buffer in Work-RAM and only transfer data to the OAM via this buffer during the Vertical Blanking Period. (See VBlank routine for an example of a DMA transfer from an OAM buffer to OAM.)