nv_sprite_extra_code.asm

//////////////////////////////////////////////////////////////////////////////
// nv_sprite_extra_code.asm
// Copyright(c) 2021 Neal Smith.
// License: MIT. See LICENSE file in root directory.
//////////////////////////////////////////////////////////////////////////////
// this file contains subroutines that operate on sprites.  Usually the 
// address of the extra data for a sprite is required to perform some
// operation.  For these type of subroutines the address is usually 
// passed to the subroutine with MSB in Accumulator and LSB in X Register.
// there are macros in this file, but code will also be generated by
// instanciating the macros at a specific label.
//////////////////////////////////////////////////////////////////////////////

#importonce

#if !NV_C64_UTIL_DATA
.error "Error - nv_sprite_extra_code.asm: NV_C64_UTIL_DATA not defined.  Import nv_c64_util_data.asm"
#endif

// the #if above doesn't seem to always work so..
// if data hasn't been imported yet, import it into default location
#importif !NV_C64_UTIL_DATA "nv_c64_util_default_data.asm"

#import "nv_sprite_macs.asm"
#import "nv_sprite_extra_macs.asm"
#import "nv_sprite_raw_macs.asm"
#import "nv_math16_macs.asm"
#import "nv_screen_macs.asm"

.macro nv_sprite_load_extra_ptr()
{
    // load the address of the caller's param block to a pointer in 
    // zero page (first 256 bytes of memory.)  we need a zero page 
    // location to store the address of the caller's nv_sprite_extra_data
    // so that we can later use indirect index addressing into the 
    // extra data for the individual fields (sprit num, x loc, y loc, etc)
    stx ZERO_PAGE_LO   // store lo byte of addr of caller's param block
    sta ZERO_PAGE_HI   // store hi byte of addr of caller's param block 
}


//////////////////////////////////////////////////////////////////////////////
// Sets a sprites color from the last byte in the sprite data
// the sprite data is found by getting the address of the first byte
// of it from the sprite's extra data.
// To call subroutine setup the following then JSR
// Accum: MSB of address of nv_sprite_extra_data
// X Reg: LSB of address of the nv_sprite_extra_data
.macro nv_sprite_set_color_from_extra_sr()
{
    nv_sprite_standard_save(SaveBlock)

    // load ZERO_PAGE_LO and ZERO_PAGE_HI with addr of sprite extra data
    nv_sprite_load_extra_ptr()

    // get the sprite number in X reg
    nv_sprite_extra_byte_to_x(NV_SPRITE_NUM_OFFSET)
    //ldy #NV_SPRITE_NUM_OFFSET       // load Y reg with offset to sprite number
    //lda (ZERO_PAGE_LO),y            // indirect indexed load sprite num to accum
    //tax                             // keep sprite number in X reg
    
    nv_sprite_extra_word_to_mem(NV_SPRITE_DATA_PTR_OFFSET, scratch_word)
    
    //scratch_word now has the data ptr in it

    // store sprite data pointer in scratch word
    lda scratch_word
    sta ZERO_PAGE_LO

    lda scratch_word+1
    sta ZERO_PAGE_HI

    // our zero page pointer now points to the sprite data
    // the 63rd byte of which contains the color data
    ldy #63
    lda (ZERO_PAGE_LO), y

    // now accum has the color data in the low nibble
    // and X has the sprite number
    // write the color data to the color data register for this
    // sprite number.  write the whole byte because only the 
    // low nibble is writable
    sta NV_SPRITE_0_COLOR_REG_ADDR,x   // store in color reg for this sprite  

    nv_sprite_standard_restore(SaveBlock)
    rts

SaveBlock:
    nv_sprite_standard_alloc()
}


//////////////////////////////////////////////////////////////////////////////
// To call this subroutine setup the following then JSR
// Accum: MSB of address of nv_sprite_extra_data
// X Reg: LSB of address of the nv_sprite_extra_data
.macro nv_sprite_set_mode_from_extra_sr()
{
    nv_sprite_standard_save(SaveBlock)

    // load ZERO_PAGE_LO and ZERO_PAGE_HI with addr of sprite extra data
    nv_sprite_load_extra_ptr()

    // get the sprite number in X reg then mask for it in Accum
    nv_sprite_extra_byte_to_x(NV_SPRITE_NUM_OFFSET)
    nv_sprite_get_mask_in_a()
    pha                             // push mask on to stack

    // replace zero page pointer that was pointing to extra block to 
    // instead point to the 64 bytes of sprite data
    nv_sprite_data_ptr_to_zero_page()

    // our zero page pointer now points to the sprite data
    // the 64th byte of which contains the color data
    ldy #63
    lda (ZERO_PAGE_LO), y

    // accum now has the 64th byte of the sprite data
    // if any of the four bits in the high nibble are set then 
    // the sprite is multi color (low res).  If
    // no bits in the high nibble are set then
    // its hi res (single color)
    ldx #$F0
    stx scratch_byte
    bit scratch_byte
    beq SingleColor     // if none of the high 4 bits set then single color

MultiColor:
    // if fell through here then multi color mode
    // for multi color mode we need to set the bit for this sprite
    // in the sprite mode register
    pla                           // pop the sprite mask to the accumulator
    ora NV_SPRITE_MODE_REG_ADDR   // or the mask in accum with sprite register 
    sta NV_SPRITE_MODE_REG_ADDR   // store the updated value in sprite reg
    nv_sprite_standard_restore(SaveBlock)
    rts
    
SingleColor:
    // for single color mode we need to clear the bit in the 
    // sprite mode register that corresponds to our sprite
    pla                           // pop the sprite mask to the accum
    eor #$ff                      // negate the mask
    and NV_SPRITE_MODE_REG_ADDR   // clear bit for this sprite 
    sta NV_SPRITE_MODE_REG_ADDR   // store updated sprite reg back
    nv_sprite_standard_restore(SaveBlock)
    rts

SaveBlock:
    nv_sprite_standard_alloc()
}


//////////////////////////////////////////////////////////////////////////////
// Set the sprite hardware register for the sprite data "pointer" 
// for a specific sprite (0-7)
// To call subroutine setup the following then JSR
//   Accum: MSB of address of nv_sprite_extra_data
//   X Reg: LSB of address of the nv_sprite_extra_data
.macro nv_sprite_set_data_ptr_from_extra_sr()
{   
    nv_sprite_standard_save(SaveBlock)

    // load ZERO_PAGE_LO and ZERO_PAGE_HI with addr of sprite extra data
    nv_sprite_load_extra_ptr()

    // copy sprite data pointer to scratch_word
    nv_sprite_extra_word_to_mem(NV_SPRITE_DATA_PTR_OFFSET, scratch_word)
    
    //scratch_word now has the data ptr in it
    nv_lsr16u_mem16u_immed8u(scratch_word, 6)       // dividing by 64 (more or less)
                                    // the low byte of scratch_word now has
                                    // the sprite data block number
                                    // the posible remaining 2 high bits
                                    // are ignored.
 
     // get the sprite number in X reg
     nv_sprite_extra_byte_to_x(NV_SPRITE_NUM_OFFSET)

    lda scratch_word                  // implied this is multiplied by 64 by system
    sta NV_SPRITE_0_DATA_PTR_REG_ADDR,x   // store in ptr for this sprite

    nv_sprite_standard_restore(SaveBlock)
    rts

SaveBlock:
    nv_sprite_standard_alloc()
}


.macro nv_sprite_push_extra_ptr()
{
    // save A and X on stack
    pha  // push A (hi byte)
    tay  // save A (hi byte)
    txa  // lo byte
    pha  // save lo byte
    tax  // lo byte back to X
    tya  // hi byte back to A
}

.macro nv_sprite_pop_extra_ptr()
{
    // restore A and X
    pla  // pop low byte to A
    tax  // move lo byte to X
    pla  // pop hi byte to A
}

///////////////////////////////////////////////////////////////////////////////
// macro to save the Accum, the X and the values in the zero page
// locations that we use for indirection in most routines that need to 
// indirectly access the sprite's extra data block
// Subroutines that take the extra data address in Accum, and X 
// and then reference the fields with ZERO_PAGE_HI and ZERO_PAGE_LO
// can use this macro to save the state and then use 
// nv_sprite_standard_restore() macro to restore them befor returning.
// note that if used then the following labels need one byte each
// allocated 
//   save_a, save_x, save_zero_lo, save_zero_hi
// space can be allocated via including the nv_sprite_standard_alloc() macro
.macro nv_sprite_standard_save(save_block)
{
    sta save_block
    stx save_block+1
    ldy ZERO_PAGE_LO
    sty save_block+2
    ldy ZERO_PAGE_HI
    sty save_block+3 
}


//////////////////////////////////////////////////////////////////////////////
// inline macro to allocate enough memory to save commonly used registers
// and memory contents such as:
//   Accumulator
//   X register
//   ZERO_PAGE_HI
//   ZERO_PAGE_LO
// use this macro to allocate the memory block passed to the 
// nv_sprite_standard_save() and nv_sprite_standard_restore() macros
.macro nv_sprite_standard_alloc()
{
    save_a: .byte 0
    save_x: .byte 0 
    save_zero_lo: .byte 0
    save_zero_hi: .byte 0
}

//////////////////////////////////////////////////////////////////////////////
// inline macro to restore commonly used registers
// and memory contents such as:
//   Accumulator
//   X register
//   ZERO_PAGE_HI
//   ZERO_PAGE_LO
// use this macro to restore the registers and memory locations to the values
// that were saved from the nv_sprite_standard_save() macro to the same 
// block of memory.
.macro nv_sprite_standard_restore(save_block)
{
    lda save_block
    ldx save_block+1
    ldy save_block+2
    sty ZERO_PAGE_LO
    ldy save_block+3
    sty ZERO_PAGE_HI
}

//////////////////////////////////////////////////////////////////////////////
// setup a sprite based on its extra data
// To call subroutine setup the following then JSR
// Accum: MSB of address of nv_sprite_extra_data
// X Reg: LSB of address of the nv_sprite_extra_data
.macro nv_sprite_setup_from_extra_sr()
{
    sta save_hi
    stx save_lo
    jsr NvSpriteSetModeFromExtra

    lda save_hi
    ldx save_lo
    jsr NvSpriteSetDataPtrFromExtra
    
    lda save_hi
    ldx save_lo
    jsr NvSpriteSetColorFromExtra

    rts

save_hi: .byte 0
save_lo: .byte 0 
}

//////////////////////////////////////////////////////////////////////////////
// inline macro to create an 8 bit mask for the sprite number that is in
// the x register.  
//   X Reg: must contain sprite number (from 0 to 7)
//   Accum: will contain a mask for the sprite number if sprite number in X 
//          is 0 the mask will have the  0 bit set, ie: $01.  if the sprite
//          num in X is 1 then the 1 bit in mask will be set, ie: $02, etc. 
.macro nv_sprite_get_mask_in_a()
{
    // sprite number assumed to be in X register already

    lda #0      // load Accum with 0
    sec         // set carry flag so first rol will rotate in a 1
 Loop:
    rol         // rotate the 1 until we get to our sprite's bit
    dex         // dec X reg until beyond 0  when we can stop rotating
    bpl Loop    // when dex cause us to roll from 0 to FF then exit loop

    // now the accumulator has the sprite mask for sprite num
}


//////////////////////////////////////////////////////////////////////////////
// subroutine macro to set sprite's location in the sprite registers based on
// the appropriate values in the sprite extra data block  
// To call subroutine setup the following then JSR
// Accum: MSB of address of nv_sprite_extra_data
// X Reg: LSB of address of the nv_sprite_extra_data
.macro nv_sprite_set_location_from_extra_sr()
{
    nv_sprite_standard_save(SaveBlock)

    nv_sprite_load_extra_ptr()

    // get sprite number in accum
    nv_sprite_extra_byte_to_a(NV_SPRITE_NUM_OFFSET)
    pha     // push accum (sprite number 0-7)
    
    // multiply by 2 and put in x reg.  Need to multiply by 2 because
    // there x and y location together for each sprite.
    asl 
    tax
    
    // get sprite x location from extra data block to accum
    nv_sprite_extra_byte_to_a(NV_SPRITE_X_OFFSET)

    // store the x location to the correct sprite register
    sta NV_SPRITE_0_X_REG_ADDR,x    // store in right sprite's x loc


    // get sprite y location from extra data block to accum
    nv_sprite_extra_byte_to_a(NV_SPRITE_Y_OFFSET)

    // store y position to correct sprite register
    sta NV_SPRITE_0_Y_REG_ADDR,x    // store in right sprites y loc

    // load MSB of sprite X position to A 
    nv_sprite_extra_byte_to_a(NV_SPRITE_X_OFFSET + 1)
    bne SetBit                            // high byte was non zero, so set bit
    // clear bit

    // create a sprite mask for our sprite number in accumulator and negate it
    pla         // pop sprite number off stack to accum
    tax         // move sprite number to X reg
    nv_sprite_get_mask_in_a()
    eor #$ff    // negate mask so our bit is 0, other bits 1s

    // and with reg that holds all the sprite x hi bits
    // then store it back to the same register so our sprite's bit is clear
    and NV_SPRITE_ALL_X_HIGH_BIT_REG_ADDR
    sta NV_SPRITE_ALL_X_HIGH_BIT_REG_ADDR 
    
    nv_sprite_standard_restore(SaveBlock)
    rts
    
 SetBit: 
    // setting bit for the sprite
    pla                                 // pop sprite num to accum
    tax                                 // sprite num to x for get mask macro
    nv_sprite_get_mask_in_a()           // get a mask for our sprite num
    ora NV_SPRITE_ALL_X_HIGH_BIT_REG_ADDR   // or with the reg of all hi X bits
    sta NV_SPRITE_ALL_X_HIGH_BIT_REG_ADDR   // store back with our bit set

    nv_sprite_standard_restore(SaveBlock)
    rts

SaveBlock:
    nv_sprite_standard_alloc()
}


//////////////////////////////////////////////////////////////////////////////
// subroutine to move a sprite based on information in the sprite extra 
// struct (info) that is passed into the macro.  The sprite x and y location
// in memory will be updated according to the x and y velocity.
// Note if the sprite goes off the edge it will be reset to the opposite side
// of the screen or bounce based on sprite extra data
// Note that this only updates the location in memory, it doesn't update the
// sprite location in sprite registers.  To update sprite location in registers
// and on the screen, call nv_sprite_set_location_from_memory_sr after this.
.macro nv_sprite_move_in_extra_sr()
{
    // save standard regs and memory values
    nv_sprite_standard_save(SaveBlock)
    
    // load the extra pointer from accum/X reg to zero page location
    nv_sprite_load_extra_ptr()

    // get sprite Y velocity in accum and branch for pos or negative
    nv_sprite_extra_byte_to_a(NV_SPRITE_VEL_Y_OFFSET)
    bpl PosVelY
NegVelY:
    jsr NvSpriteMoveInExtraNegY
    jmp DoneY
PosVelY:
    jsr NvSpriteMoveInExtraPosY
    jmp DoneY

DoneY:
    // Y location done, now on to X

    // get sprite x velocity in accum and branch for pos or negative
    nv_sprite_extra_byte_to_a(NV_SPRITE_VEL_X_OFFSET)
    bpl PosVelX

NegVelX:
    jsr NvSpriteMoveInExtraNegX
    jmp DoneX

PosVelX:
    jsr NvSpriteMoveInExtraPosX
    //jmp DoneX

DoneX:


FinishedUpdate:
    nv_sprite_standard_restore(SaveBlock)
    rts                // already popped the return address, jump back now

SaveBlock:
    nv_sprite_standard_alloc()
}


//////////////////////////////////////////////////////////////////////////////
// move sprite in positive X direction and bounce or wrap around
// Before calling the following must be set
//   ZERO_PAGE_LO: must have the LSB of the address of the sprite extra data
//   ZERO_PAGE_HI: must have the MSB of the address of the sprite extra data
//   Accumulator: must have the sprites X velocity which must be positive
.macro nv_sprite_move_in_extra_pos_x_sr()
{
    sta velocity            // move x vel to memory
    
    nv_sprite_extra_word_to_mem(NV_SPRITE_RIGHT_MAX_OFFSET, max_x)

    nv_sprite_extra_byte_to_a(NV_SPRITE_VEL_X_OFFSET)
    sta velocity

    nv_sprite_extra_word_to_mem(NV_SPRITE_X_OFFSET, cur_x)

    nv_adc16x_mem16x_mem8s(cur_x, velocity, potential_new_x)

    // potential_new_x has the new x if not bouncing or wrapping
    nv_ble16(potential_new_x, max_x, UsePotentialX)

TooFar:
    // if didn't branch above then trying to move too far.  Need
    // to bounce or wrap to the other side
    nv_sprite_extra_byte_to_a(NV_SPRITE_ACTION_RIGHT_OFFSET)
    beq WrapX                               // action 0=wrap, 1=bounce

BounceX:
    // didn't branch so bounce by setting X vel to twos compliement
    lda #$ff
    eor velocity 
    sec
    adc #$00
    nv_sprite_a_to_extra(NV_SPRITE_VEL_X_OFFSET)
    jmp DoneX

WrapX:
    // wrap by setting x to min position
    nv_sprite_extra_word_to_mem(NV_SPRITE_LEFT_MIN_OFFSET, potential_new_x)
    // fall through to UsePotentialX

UsePotentialX:
    nv_sprite_mem_word_to_extra(potential_new_x, NV_SPRITE_X_OFFSET)

DoneX:
    rts

// subroutine variables
velocity: .byte 0
potential_new_x: .word 0
cur_x: .word 0
max_x: .word 0
}


//////////////////////////////////////////////////////////////////////////////
// move sprite in negative X direction and bounce or wrap around
// Before calling the following must be set
//   ZERO_PAGE_LO: must have the LSB of the address of the sprite extra data
//   ZERO_PAGE_HI: must have the MSB of the address of the sprite extra data
//   Accumulator: must have the sprites X velocity which must be positive
.macro nv_sprite_move_in_extra_neg_x_sr()
{
    sta velocity            // move x vel to memory
    
    nv_sprite_extra_word_to_mem(NV_SPRITE_LEFT_MIN_OFFSET, min_x)
    nv_sprite_extra_word_to_mem(NV_SPRITE_RIGHT_MAX_OFFSET, max_x)

    nv_sprite_extra_byte_to_a(NV_SPRITE_VEL_X_OFFSET)
    sta velocity

    nv_sprite_extra_word_to_mem(NV_SPRITE_X_OFFSET, cur_x)

    nv_adc16x_mem16x_mem8s(cur_x, velocity, potential_new_x)

    // potential_new_x has the new x if not off left edge

    nv_bgt16(potential_new_x, max_x, TooFar)
    nv_bgt16(potential_new_x, min_x, UsePotentialX)

TooFar:
    // if didn't branch above then trying to move too far.  Need
    // to bounce or wrap to the other side
    nv_sprite_extra_byte_to_a(NV_SPRITE_ACTION_LEFT_OFFSET)
    beq WrapX                               // action 0=wrap, 1=bounce

BounceX:
    // didn't branch above, so bounce by setting X vel to twos compliement
    lda #$ff
    eor velocity 
    sec
    adc #$00
    nv_sprite_a_to_extra(NV_SPRITE_VEL_X_OFFSET)
    jmp DoneX

WrapX:
    // wrap by setting x to max position
    nv_sprite_extra_word_to_mem(NV_SPRITE_RIGHT_MAX_OFFSET, potential_new_x)
    // fall through to UsePotentialX

UsePotentialX:
    nv_sprite_mem_word_to_extra(potential_new_x, NV_SPRITE_X_OFFSET)

DoneX:
    rts

// subroutine variables
velocity: .byte 0
potential_new_x: .word 0
cur_x: .word 0
min_x: .word 0
max_x: .word 0
}

//////////////////////////////////////////////////////////////////////////////
// move sprite in negative Y direction and bounce or wrap around
// Before calling the following must be set
//   ZERO_PAGE_LO: must have the LSB of the address of the sprite extra data
//   ZERO_PAGE_HI: must have the MSB of the address of the sprite extra data
//   Accumulator: must have the sprites Y velocity which must be negative
.macro nv_sprite_move_in_extra_neg_y_sr()
{
    sta velocity            // move y vel to memory
    
    nv_sprite_extra_byte_to_a(NV_SPRITE_TOP_MIN_OFFSET)
    sta min_position

    // get sprite Y position in accum 
    nv_sprite_extra_byte_to_a(NV_SPRITE_Y_OFFSET)
    clc
    adc velocity            // add the velocity to the position
                            // accum has potential next position
    cmp min_position        // compare with max y position
    bcs AccumHasNewY        // if not past max y then we are done
    
TooFar:
    // new position is too far, either bounce or wrap
    nv_sprite_extra_byte_to_a(NV_SPRITE_ACTION_TOP_OFFSET)
    beq WrapY               // action 0 = Wrap, 1 = bounce

BounceY:
    // bounce by setting y velocity to its twos compliment
    lda #$ff
    eor velocity 
    sec
    adc #$00
    nv_sprite_a_to_extra(NV_SPRITE_VEL_Y_OFFSET)
    jmp DoneY

WrapY:
    // wrap by setting y to min position
    // bounce by negating y velocity
    nv_sprite_extra_byte_to_a(NV_SPRITE_BOTTOM_MAX_OFFSET)
    nv_sprite_a_to_extra(NV_SPRITE_Y_OFFSET)
    // fall through to AccumHasNewY

AccumHasNewY:
    nv_sprite_a_to_extra(NV_SPRITE_Y_OFFSET)

DoneY:
    rts

// subroutine variables
velocity: .byte 0
min_position: .byte 0
}


//////////////////////////////////////////////////////////////////////////////
// move sprite in positive Y direction and bounce or wrap around
// Before calling the following must be set
//   ZERO_PAGE_LO: must have the LSB of the address of the sprite extra data
//   ZERO_PAGE_HI: must have the MSB of the address of the sprite extra data
//   Accumulator: must have the sprites Y velocity which must be positive
.macro nv_sprite_move_in_extra_pos_y_sr()
{
    sta velocity            // move y vel to memory
    
    nv_sprite_extra_byte_to_a(NV_SPRITE_BOTTOM_MAX_OFFSET)
    sta max_position

    // get sprite Y position in accum 
    nv_sprite_extra_byte_to_a(NV_SPRITE_Y_OFFSET)
    clc
    adc velocity            // add the velocity to the position
                            // accum has potential next position
    cmp max_position        // compare with max y position
    bcc AccumHasNewY        // if not past max y then we are done

TooFar:
    // new position is too far, either bounce or wrap
    nv_sprite_extra_byte_to_a(NV_SPRITE_ACTION_BOTTOM_OFFSET)
    beq WrapY               // action 0 = wrap, 1 = bounce

BounceY:
    // bounce by setting y velocity to its twos compliment
    lda #$ff
    eor velocity 
    sec
    adc #$00
    nv_sprite_a_to_extra(NV_SPRITE_VEL_Y_OFFSET)
    jmp DoneY

WrapY:
    // wrap by setting y to min position
    // bounce by negating y velocity
    nv_sprite_extra_byte_to_a(NV_SPRITE_TOP_MIN_OFFSET)
    nv_sprite_a_to_extra(NV_SPRITE_Y_OFFSET)
    // fall through to AccumHasNewY

AccumHasNewY:
    nv_sprite_a_to_extra(NV_SPRITE_Y_OFFSET)

DoneY:
    rts

// subroutine variables
velocity: .byte 0
max_position: .byte 0
}


//////////////////////////////////////////////////////////////////////////////
// enable a sprite and update its sprite_enabled flag in its extra data
// To call subroutine setup the following then JSR
// Accum: MSB of address of nv_sprite_extra_data
// X Reg: LSB of address of the nv_sprite_extra_data
.macro nv_sprite_extra_enable_sr()
{
    nv_sprite_standard_save(SaveBlock)

    nv_sprite_load_extra_ptr()

    // set enabled flag in extra
    lda #$01
    nv_sprite_a_to_extra(NV_SPRITE_ENABLED_OFFSET)

    // get sprite number in accum
    nv_sprite_extra_byte_to_a(NV_SPRITE_NUM_OFFSET)

    // now enable the sprite 
    nv_sprite_raw_enable_from_reg()

    nv_sprite_standard_restore(SaveBlock)
    rts
    
SaveBlock:
    nv_sprite_standard_alloc()
}

//////////////////////////////////////////////////////////////////////////////
// disable a sprite and update its sprite_enabled flag in its extra data
// To call subroutine setup the following then JSR
// Accum: MSB of address of nv_sprite_extra_data
// X Reg: LSB of address of the nv_sprite_extra_data
.macro nv_sprite_extra_disable_sr()
{
    nv_sprite_standard_save(SaveBlock)

    nv_sprite_load_extra_ptr()

    // clear enabled flag in extra
    lda #$00
    nv_sprite_a_to_extra(NV_SPRITE_ENABLED_OFFSET)

    // get sprite number in accum
    nv_sprite_extra_byte_to_a(NV_SPRITE_NUM_OFFSET)

    // now enable the sprite 
    nv_sprite_raw_disable_from_reg()

    nv_sprite_standard_restore(SaveBlock)
    rts
    
SaveBlock:
    nv_sprite_standard_alloc()
}


//////////////////////////////////////////////////////////////////////////////
// reverse the x velocity of sprite
// Accum: MSB of address of nv_sprite_extra_data
// X Reg: LSB of address of the nv_sprite_extra_data
.macro nv_sprite_extra_reverse_vel_x_sr()
{
    nv_sprite_standard_save(SaveBlock)

    nv_sprite_load_extra_ptr()

    // load accum with x velocity
    nv_sprite_extra_byte_to_a(NV_SPRITE_VEL_X_OFFSET)
    
    nv_twos_comp8x_a()

    nv_sprite_a_to_extra(NV_SPRITE_VEL_X_OFFSET)

    nv_sprite_standard_restore(SaveBlock)
    rts
    
SaveBlock:
    nv_sprite_standard_alloc()
}

//////////////////////////////////////////////////////////////////////////////
// reverse the y velocity of sprite
// Accum: MSB of address of nv_sprite_extra_data
// X Reg: LSB of address of the nv_sprite_extra_data
.macro nv_sprite_extra_reverse_vel_y_sr()
{
    nv_sprite_standard_save(SaveBlock)

    nv_sprite_load_extra_ptr()

    // load accum with x velocity
    nv_sprite_extra_byte_to_a(NV_SPRITE_VEL_Y_OFFSET)
    
    nv_twos_comp8x_a()

    nv_sprite_a_to_extra(NV_SPRITE_VEL_Y_OFFSET)

    nv_sprite_standard_restore(SaveBlock)
    rts
    
SaveBlock:
    nv_sprite_standard_alloc()
}


//////////////////////////////////////////////////////////////////////////////
// make sure the sprite's x velocity is positive, if its negative, then 
// then reverse it, if its alsready positive then do nothing.
// Accum: MSB of address of nv_sprite_extra_data
// X Reg: LSB of address of the nv_sprite_extra_data
.macro nv_sprite_extra_assure_vel_pos_x_sr()
{
    nv_sprite_standard_save(SaveBlock)

    nv_sprite_load_extra_ptr()

    // load accum with x velocity
    nv_sprite_extra_byte_to_a(NV_SPRITE_VEL_X_OFFSET)
    
    bpl NothingToDo         // x velocity already positive, just return

    nv_twos_comp8x_a()   // reverse the x velocity

    nv_sprite_a_to_extra(NV_SPRITE_VEL_X_OFFSET)  // save back to extra data

NothingToDo:
    nv_sprite_standard_restore(SaveBlock)
    rts
    
SaveBlock:
    nv_sprite_standard_alloc()
}

//////////////////////////////////////////////////////////////////////////////
// make sure the sprite's x velocity is negative, if its positive, then 
// then reverse it, if its alsready negative then do nothing.
// Accum: MSB of address of nv_sprite_extra_data
// X Reg: LSB of address of the nv_sprite_extra_data
.macro nv_sprite_extra_assure_vel_neg_x_sr()
{
    nv_sprite_standard_save(SaveBlock)

    nv_sprite_load_extra_ptr()

    // load accum with x velocity
    nv_sprite_extra_byte_to_a(NV_SPRITE_VEL_X_OFFSET)
    
    bmi NothingToDo         // x velocity already positive, just return

    nv_twos_comp8x_a()   // reverse the x velocity

    nv_sprite_a_to_extra(NV_SPRITE_VEL_X_OFFSET)  // save back to extra data

NothingToDo:
    nv_sprite_standard_restore(SaveBlock)
    rts
    
SaveBlock:
    nv_sprite_standard_alloc()
}

//////////////////////////////////////////////////////////////////////////////
// assure the y velocity of sprite is positive.  If its negative then
// reverse it.  If its alredy positive then do nothing.
// Accum: MSB of address of nv_sprite_extra_data
// X Reg: LSB of address of the nv_sprite_extra_data
.macro nv_sprite_extra_assure_vel_pos_y_sr()
{
    nv_sprite_standard_save(SaveBlock)

    nv_sprite_load_extra_ptr()

    // load accum with x velocity
    nv_sprite_extra_byte_to_a(NV_SPRITE_VEL_Y_OFFSET)
    
    bpl NothingToDo             // if already positive, then done

    nv_twos_comp8x_a()       // reverse velocity

    nv_sprite_a_to_extra(NV_SPRITE_VEL_Y_OFFSET)  // save vel back to extra

NothingToDo:
    nv_sprite_standard_restore(SaveBlock)
    rts
    
SaveBlock:
    nv_sprite_standard_alloc()
}

//////////////////////////////////////////////////////////////////////////////
// assure the y velocity of sprite is negative. If its positive then 
// reverse it.  If its already negative then do nothing.
// Accum: MSB of address of nv_sprite_extra_data
// X Reg: LSB of address of the nv_sprite_extra_data
.macro nv_sprite_extra_assure_vel_neg_y_sr()
{
    nv_sprite_standard_save(SaveBlock)

    nv_sprite_load_extra_ptr()

    // load accum with x velocity
    nv_sprite_extra_byte_to_a(NV_SPRITE_VEL_Y_OFFSET)
    
    bmi NothingToDo             // if already negative, then done

    nv_twos_comp8x_a()       // reverse velocity

    nv_sprite_a_to_extra(NV_SPRITE_VEL_Y_OFFSET)  // save vel back to extra

NothingToDo:
    nv_sprite_standard_restore(SaveBlock)
    rts
    
SaveBlock:
    nv_sprite_standard_alloc()
}




//////////////////////////////////////////////////////////////////////////////
// macro subroutine to get the center X and Y screen position of a sprite's 
// hitbox
// Macro params:
//   center_x_addr: the memory address pointing to a 16 bit word that will 
//                  get the center X location
//   center_y_addr: the memory address pointing to a 16 bit word that will 
//                  get the center Y location
// subroutine params 
//   Accum: MSB of address of nv_sprite_extra_data
//   X Reg: LSB of address of the nv_sprite_extra_data
.macro nv_sprite_extra_get_hitbox_center_sr(center_x_addr, center_y_addr)
{
    nv_sprite_standard_save(SaveBlock)

    nv_sprite_load_extra_ptr()

    // get the sprite x center location
    nv_sprite_extra_word_to_mem(NV_SPRITE_X_OFFSET, center_x_addr)
    nv_sprite_extra_byte_to_mem(NV_SPRITE_HITBOX_LEFT_OFFSET, HitboxLeft)
    nv_sprite_extra_byte_to_mem(NV_SPRITE_HITBOX_RIGHT_OFFSET, HitboxRight)
    nv_sbc8x(HitboxRight, HitboxLeft, HitboxWidth)
    lsr HitboxWidth                 // hitbox width divided by 2
    nv_adc16x_mem16x_mem8u(center_x_addr, HitboxWidth, center_x_addr)

    // get the sprite y center location
    nv_sprite_extra_byte_to_a(NV_SPRITE_Y_OFFSET)
    sta center_y_addr
    lda #$00
    sta center_y_addr+1
    nv_sprite_extra_byte_to_mem(NV_SPRITE_HITBOX_TOP_OFFSET, HitboxTop)
    nv_sprite_extra_byte_to_mem(NV_SPRITE_HITBOX_BOTTOM_OFFSET, HitboxBottom)

    nv_sbc8x(HitboxBottom, HitboxTop, HitboxHeight)
    lsr HitboxHeight            // hitbox height divided by 2
    nv_adc16x_mem16x_mem8u(center_y_addr, HitboxHeight, center_y_addr)

    nv_sprite_standard_restore(SaveBlock)
    rts

// use same words for left/top, right/bottom, width/height
HitboxTop:
HitboxLeft: .byte $00
HitboxBottom:
HitboxRight: .byte $00
HitboxHeight:
HitboxWidth: .byte $00
SaveBlock:
    nv_sprite_standard_alloc()
}


//////////////////////////////////////////////////////////////////////////////
//
//////////////////////////////////////////////////////////////////////////////
// Inline macro to test if a sprite's hitbox overlaps with a prefilled
// rectangle
// 
// Params: 
//   Accum: MSB of address of nv_sprite_extra_data
//   X Reg: LSB of address of the nv_sprite_extra_data
// macro params:
//   rect_addr: is address of retangle whose contents will be tested for
//              overlap with the sprite's rectangle.. the contents must
//              be prefilled with coords
// Return: loads the accum with 0 for no overlap or nonzero if is overlap
// Note: the Zero page locations use will be restored.  The accumulator will not
//       be restored because the result will be in the accum (0 or 1)
.macro nv_sprite_check_overlap_rect_sr(rect_addr)
{
    nv_sprite_standard_save(SaveBlock)

    nv_sprite_load_extra_ptr()

    .label r2_left = rect_addr
    .label r2_top = rect_addr + 2
    .label r2_right = rect_addr + 4
    .label r2_bottom = rect_addr + 6

    .const SPRITE_WIDTH = 24
    .const SPRITE_HEIGHT = 21
    .const LEFT_OFFSET = 26
    .const TOP_OFFSET = 53
    .const CHAR_PIXEL_WIDTH = $0008
    .const CHAR_PIXEL_HEIGHT = $0008

    /////////// put sprite's rectangle to rect1, use the hitbox not full sprite
    
    // get the sprite left and right hitbox coords as screen pixel coords
    // and put in r1_left, r1_right
    nv_sprite_extra_word_to_mem(NV_SPRITE_X_OFFSET, r1_left)
    nv_sprite_extra_byte_to_mem(NV_SPRITE_HITBOX_RIGHT_OFFSET, hitbox_right)
    nv_adc16x_mem16x_mem8u(r1_left, hitbox_right, r1_right)
    nv_sprite_extra_byte_to_mem(NV_SPRITE_HITBOX_LEFT_OFFSET, hitbox_left)
    nv_adc16x_mem16x_mem8u(r1_left, hitbox_left, r1_left)

    // get the sprite top and bottom hitbox coords as screen pixel coords
    // and put in r1_top, r1_bottom
    nv_sprite_extra_byte_to_a(NV_SPRITE_Y_OFFSET)
    sta r1_top
    lda #$00
    sta r1_top+1
    nv_sprite_extra_byte_to_mem(NV_SPRITE_HITBOX_TOP_OFFSET, hitbox_top)
    nv_sprite_extra_byte_to_mem(NV_SPRITE_HITBOX_BOTTOM_OFFSET, hitbox_bottom)
    nv_adc16x_mem16x_mem8u(r1_top, hitbox_bottom, r1_bottom)
    nv_adc16x_mem16x_mem8u(r1_top, hitbox_top, r1_top)

    // now check for overlap with sprite_rect and the rect for this macro
    nv_check_rect_overlap16(sprite_rect, rect_addr)
    
    // use hitbox_left as a temp, finished with it above
    // the standard restore will mess up our accumulator so save it here
    sta hitbox_left 

    nv_sprite_standard_restore(SaveBlock)

    // restore the accumulator from our temp
    lda hitbox_left
    rts
    
SaveBlock:
    nv_sprite_standard_alloc()
    sprite_rect:
    r1_left: .word 0
    r1_top: .word 0
    r1_right: .word 0
    r1_bottom: .word 0
    hitbox_left: .byte 0
    hitbox_top: .byte 0
    hitbox_right: .byte 0
    hitbox_bottom: .byte 0
}




//////////////////////////////////////////////////////////////////////////////
// Instantiate macros that need to be instantiated below here
//////////////////////////////////////////////////////////////////////////////

//////////////////////////////////////////////////////////////////////////////
// Params: 
//   Accum: MSB of address of nv_sprite_extra_data
//   X Reg: LSB of address of the nv_sprite_extra_data
NvSpriteSetColorFromExtra:
    nv_sprite_set_color_from_extra_sr()

//////////////////////////////////////////////////////////////////////////////
// Params: 
//   Accum: MSB of address of nv_sprite_extra_data
//   X Reg: LSB of address of the nv_sprite_extra_data
NvSpriteSetupFromExtra:
    nv_sprite_setup_from_extra_sr()

//////////////////////////////////////////////////////////////////////////////
// Params: 
//   Accum: MSB of address of nv_sprite_extra_data
//   X Reg: LSB of address of the nv_sprite_extra_data
NvSpriteSetModeFromExtra:
    nv_sprite_set_mode_from_extra_sr()

//////////////////////////////////////////////////////////////////////////////
// Params: 
//   Accum: MSB of address of nv_sprite_extra_data
//   X Reg: LSB of address of the nv_sprite_extra_data
NvSpriteSetDataPtrFromExtra:
    nv_sprite_set_data_ptr_from_extra_sr()

//////////////////////////////////////////////////////////////////////////////
// Params: 
//   Accum: MSB of address of nv_sprite_extra_data
//   X Reg: LSB of address of the nv_sprite_extra_data
NvSpriteSetLocationFromExtra:
    nv_sprite_set_location_from_extra_sr()

//////////////////////////////////////////////////////////////////////////////
// Params: 
//   Accum: MSB of address of nv_sprite_extra_data
//   X Reg: LSB of address of the nv_sprite_extra_data
NvSpriteMoveInExtra:
    nv_sprite_move_in_extra_sr()

//////////////////////////////////////////////////////////////////////////////
// Params: 
//   Accum: MSB of address of nv_sprite_extra_data
//   X Reg: LSB of address of the nv_sprite_extra_data
NvSpriteMoveInExtraNegY:
    nv_sprite_move_in_extra_neg_y_sr()

//////////////////////////////////////////////////////////////////////////////
// Params: 
//   Accum: MSB of address of nv_sprite_extra_data
//   X Reg: LSB of address of the nv_sprite_extra_data
NvSpriteMoveInExtraPosY:
    nv_sprite_move_in_extra_pos_y_sr()

//////////////////////////////////////////////////////////////////////////////
// Params: 
//   Accum: MSB of address of nv_sprite_extra_data
//   X Reg: LSB of address of the nv_sprite_extra_data
NvSpriteMoveInExtraNegX:
    nv_sprite_move_in_extra_neg_x_sr()

//////////////////////////////////////////////////////////////////////////////
// Params: 
//   Accum: MSB of address of nv_sprite_extra_data
//   X Reg: LSB of address of the nv_sprite_extra_data
NvSpriteMoveInExtraPosX:
    nv_sprite_move_in_extra_pos_x_sr()

//////////////////////////////////////////////////////////////////////////////
// Params: 
//   Accum: MSB of address of nv_sprite_extra_data
//   X Reg: LSB of address of the nv_sprite_extra_data
NvSpriteExtraEnable:
    nv_sprite_extra_enable_sr()


//////////////////////////////////////////////////////////////////////////////
// Params: 
//   Accum: MSB of address of nv_sprite_extra_data
//   X Reg: LSB of address of the nv_sprite_extra_data
NvSpriteExtraDisable:
    nv_sprite_extra_disable_sr()

//////////////////////////////////////////////////////////////////////////////
// Reverses X Vel 
//   Accum: MSB of address of nv_sprite_extra_data
//   X Reg: LSB of address of the nv_sprite_extra_data
NvSpriteReverseVelX:
    nv_sprite_extra_reverse_vel_x_sr()

//////////////////////////////////////////////////////////////////////////////
// Reverses X Vel 
//   Accum: MSB of address of nv_sprite_extra_data
//   X Reg: LSB of address of the nv_sprite_extra_data
NvSpriteReverseVelY:
    nv_sprite_extra_reverse_vel_y_sr()


//////////////////////////////////////////////////////////////////////////////
// fill nv_sprite_check_overlap_rect_addr with a rectangle to test for 
// overlap with the sprite extra data pointed to by Accum and X Reg
// Params: 
//   Accum: MSB of address of nv_sprite_extra_data
//   X Reg: LSB of address of the nv_sprite_extra_data
NvSpriteCheckOverlapRect:
    nv_sprite_check_overlap_rect_sr(nv_sprite_check_overlap_rect_addr)

nv_sprite_check_overlap_rect_addr: 
    nv_sprite_check_overlap_rect_left: .word 0
    nv_sprite_check_overlap_rect_top: .word 0
    nv_sprite_check_overlap_rect_right: .word 0
    nv_sprite_check_overlap_rect_bottom: .word 0


//////////////////////////////////////////////////////////////////////////////
// get the X and Y screen location of the center of the hitbox for the 
// sprite that has extra data pointed to by Accum and X Reg
// Params: 
//   Accum: MSB of address of nv_sprite_extra_data
//   X Reg: LSB of address of the nv_sprite_extra_data
// upon return nv_sprite_hitbox_center_x and nv_sprite_hitbox_center_y will have the 
// center x and y screen coord filled in.
NvSpriteGetHitboxCenter:
    nv_sprite_extra_get_hitbox_center_sr(nv_sprite_hitbox_center_x, nv_sprite_hitbox_center_y)

nv_sprite_hitbox_center_x: .word 0
nv_sprite_hitbox_center_y: .word 0



//////////////////////////////////////////////////////////////////////////////
// get the X and Y distances between two sprites.  
// subroutine Params: 
//   nv_sprite1_extra_ptr_for_hitbox_center_dist: the address of a word
//     that will contain the address of nv_sprite_extra_data for 
//     sprite1 in the distance calculation
//   nv_sprite2_extra_ptr_for_hitbox_center_dist: the address of a word
//     that will contain the address of nv_sprite_extra_data for 
//     sprite2 in the distance calculation
// upon return nv_sprite_hitbox_center_dist_x and 
//   nv_sprite_hitbox_center_dist_y will have the x and y distances betwen
//   the two sprites.  note that the distances will always be positive
//   regardless of sprite locations on the screen
NvSpriteGetHitboxCenterDist:
    lda nv_sprite1_extra_ptr_for_hitbox_center_dist+1
    ldx nv_sprite1_extra_ptr_for_hitbox_center_dist
    jsr NvSpriteGetHitboxCenter
    
    nv_xfer16_mem_mem(nv_sprite_hitbox_center_x, nv_sprite1_center_x)
    nv_xfer16_mem_mem(nv_sprite_hitbox_center_y, nv_sprite1_center_y)

    lda nv_sprite2_extra_ptr_for_hitbox_center_dist+1
    ldx nv_sprite2_extra_ptr_for_hitbox_center_dist
    jsr NvSpriteGetHitboxCenter
    nv_xfer16_mem_mem(nv_sprite_hitbox_center_x, nv_sprite2_center_x)
    nv_xfer16_mem_mem(nv_sprite_hitbox_center_y, nv_sprite2_center_y)

GetDistX:
    nv_bgt16(nv_sprite2_center_x, nv_sprite1_center_x, Sprite2GreaterX)

Sprite1GreaterX:
    nv_sbc16(nv_sprite1_center_x, nv_sprite2_center_x, nv_sprite_hitbox_center_dist_x)
    jmp GetDistY

Sprite2GreaterX:
    nv_sbc16(nv_sprite2_center_x, nv_sprite1_center_x, nv_sprite_hitbox_center_dist_x)

GetDistY:
    nv_bgt16(nv_sprite2_center_y, nv_sprite1_center_y, Sprite2GreaterY)

Sprite1GreaterY:
    nv_sbc16(nv_sprite1_center_y, nv_sprite2_center_y, nv_sprite_hitbox_center_dist_y)
    jmp HitboxCenterDistDone

Sprite2GreaterY:
    nv_sbc16(nv_sprite2_center_y, nv_sprite1_center_y, nv_sprite_hitbox_center_dist_y)

HitboxCenterDistDone:
    rts

// input, set before calling
nv_sprite1_extra_ptr_for_hitbox_center_dist: .word 0
nv_sprite2_extra_ptr_for_hitbox_center_dist: .word 0

// return vals
nv_sprite_hitbox_center_dist_x: .word 0
nv_sprite_hitbox_center_dist_y: .word 0

// internal temp variables
nv_sprite1_center_x: .word 0
nv_sprite1_center_y: .word 0
nv_sprite2_center_x: .word 0
nv_sprite2_center_y: .word 0
// end NvSpriteGetHitboxCenterDist 
//////////////////////////////////////////////////////////////////////////////

//////////////////////////////////////////////////////////////////////////////
// subroutine to make sure the X velocity of a sprite is positive.
// Params: 
//   Accum: MSB of address of nv_sprite_extra_data
//   X Reg: LSB of address of the nv_sprite_extra_data
NvSpriteAssureVelPosX:
    nv_sprite_extra_assure_vel_pos_x_sr()
// end NvSpriteAssureVelPosX
//////////////////////////////////////////////////////////////////////////////


//////////////////////////////////////////////////////////////////////////////
// subroutine to make sure the X velocity of a sprite is negative.
// Params: 
//   Accum: MSB of address of nv_sprite_extra_data
//   X Reg: LSB of address of the nv_sprite_extra_data
NvSpriteAssureVelNegX:
    nv_sprite_extra_assure_vel_neg_x_sr()
// end NvSpriteAssureVelNegX
//////////////////////////////////////////////////////////////////////////////

//////////////////////////////////////////////////////////////////////////////
// subroutine to make sure the Y velocity of a sprite is positive.
// Params: 
//   Accum: MSB of address of nv_sprite_extra_data
//   X Reg: LSB of address of the nv_sprite_extra_data
NvSpriteAssureVelPosY:
    nv_sprite_extra_assure_vel_pos_y_sr()
// end NvSpriteAssureVelPosY
//////////////////////////////////////////////////////////////////////////////


//////////////////////////////////////////////////////////////////////////////
// subroutine to make sure the Y velocity of a sprite is negative.
// Params: 
//   Accum: MSB of address of nv_sprite_extra_data
//   X Reg: LSB of address of the nv_sprite_extra_data
NvSpriteAssureVelNegY:
    nv_sprite_extra_assure_vel_neg_y_sr()
// end NvSpriteAssureVelNegY
//////////////////////////////////////////////////////////////////////////////