OAM [Code documentation]

oam.asm

oam.asm contains all codes, variables and logic related to transferring data to the OAM (sprite attribute table).

Sections in oam.asm:

• Shadow OAM Vars, WRAM0
• OAM DMA Routine, ROM0
• Clear OAM, ROM0
• OAM DMA, HRAM

References:

• https://gbdev.gg8.se/wiki/articles/OAM_DMA_tutorial

SECTION "Shadow OAM Vars", WRAM0

• Contains the declaration of the shadow OAM.
• "Shadow X" means "a copy of X in RAM that has to be copied to the real thing"
• Located at WRAM (work RAM), as we want to be able to read and write to this location.
• We need to make a shadow OAM as we can only update the actual OAM data during VBlank. Thus, during the normal runtime of our program in RAM, we will update the sprite attribute variables through the shadow OAM instead. It is only during VBlank, will we copy over the data from shadow OAM to the actual OAM through the DMA process.
• Thus, at this location, we will reserve 160 bytes for the shadow OAM data.
• Also note, we need to ensure the starting memory address of the shadow OAM is 256 aligned. Thus, it needs to be located at $c100, $C200 or $C000 eg. This is to make the DMA transfer of data much easier.
• Variables:
  • wShadowOAM (reserve 160 bytes at this location)

wShadowOAM::
    ds 4 * 40 ; This is the buffer we'll write sprite data to, reserve 160 bytes for it
.end

SECTION "OAM DMA Routine", ROM0

• Here, we have the function for the DMA transfer process (move data from RAM to OAM during VBlank), along with the function to copy the function for the DMA transfer process to HRAM. As during the DMA transfer process, only the HRAM can be accessed.
• Located in ROM0.
• Functions:
  • DMARoutine
  • CopyDMARoutine

DMARoutine Function

• The function to transfer wShadowOAM data in RAM to OAM.

; ---DMARouting Logic---
DMARoutine:
    ld  a, HIGH(wShadowOAM) ; load in the first half of the wShadowOAM address
    ldh [$FF46], a ; start DMA transfer and start copying from wShadowOAM
        ; stall for 160 microseconds as we need to wait for DMA transfer to finish
    ret ; return back to codes
DMARoutineEnd: ; keep track of the end address of this function

CopyDMARoutine Function

• Move the function DMARoutine codes from RAM to HRAM
• We want to copy our DMARoutine function from ROM to HRAM, since during the DMA process only HRAM is accessible.

; ---CopyDMARoutine Logic---
DMARoutine:
    ld  hl, DMARoutine ; load in the starting address of the DMARoutine function
    ld  b, DMARoutineEnd - DMARoutine ; Number of bytes to copy
        ; start copying each byte of the DMARoutine function to the location in HRAM.
    ret ; return back to codes

SECTION "Clear OAM", ROM0

• Functions to help clean the OAM and shadowOAM data.
• Located at ROM0
• Functions:
  • ResetOAM
  • ResetShawdowOAM

ResetOAM Function

• Just cleans up OAM by resetting all the data in OAM to 0.
• This ensures that if there are any sprites that are not suppose to be there anymore (eg. it died), it'll be cleaned up and won't be shown on screen.
• Should also be run once at initialisation as sometimes the OAM at the start have some trash values placed inside.
• WARNING: Call during VBlank, since OAM can only be updated during VBlank.

ResetShawdowOAM Function

• Just cleans up the data in wShadowOAM by resetting all the data in it to be 0.
• Can be used anytime since wShadowOAM is in WRAM. Best to use when we are about to update wShadowOAM data for the sprites.

SECTION "OAM DMA", HRAM

• Located in HRAM
• Contained a function, which is just the DMARoutine copied into it.
• Can be run during the DMA transfer process since it is in HRAM. Helps transfer data from wShadowOAM to the actual OAM.
• Function:
  • hOAMDMA

hOAMDMA Function

• Call this function to update OAM.
• Call during VBLank.

hOAMDMA::
    ds DMARoutineEnd - DMARoutine ; Reserve space to copy the DMARoutineFunc to HRAM