Skip to content

Documentation

Jump to bottom
TheLX5 edited this page Mar 2, 2021 · 20 revisions

Contents

Routines

find_and_queue_gfx

This routine handles finding the tile number data of a given ExGFX ID OR queueing a ExGFX file to be uploaded to VRAM during the next frames. Also, the routine can predict whether the sprite ExGFX will be loaded during the next V-Blank period or not. If it predicts that the GFX will be ready, the graphics become instantly available to use and will be marked as ready.

For usage in custom sprites, use %FindAndQueueGFX() instead of find_and_queue_gfx.

Input

Item Size Description
A 8-bit ExGFX ID in the range you want to use. By default it's D00-DFF.
If it's $FF it will be considered as NULL and the routine will end prematurely.

Output

Item Size Description
Carry 1 bit Flag to determine if the sprite has its graphics on VRAM. Useful to know if the sprite ready to be drawn on screen.
  • Set: Sprite is ready.
  • Clear: Sprite is not ready. It just put its graphics into queue or something failed (not enough unused tiles, invalid tile length, null ID).
!dss_tile_buffer 1-32 bytes  This table will hold the tile numbers of the loaded ExGFX and is filled from first to last index (0-19).
Do note that this table is never cleared between calls, as this allows the user rearrange the data to fit several ExGFXs tile data (see how Chucks were handled).
$0D-$0F 24 bit Pointer to the tile number data in the !dss_tile_buffer_complete table.

Other info

Item Description
A Will contain garbage.
X/Y They will retain their original values and sizes.
DB Preserved.
DP Unchanged.
$00-$0F Will contain garbage.
$313A-$313F Will contain garbage.

Example of usage

When using this routine you'd most likely want to call it at the very start of your graphics routine, as it corrupts everything GetDrawInfo sets for you in $00 and $01, or you could preserve the data, your choice.

graphics_routine:
   lda.b #<exgfx_id>       ; here goes the ExGFX ID you want to find
   %FindAndQueueGFX()
   bcs .graphics_loaded
.graphics_not_loaded
   ; do whatever if the graphics haven't been loaded
   ; usually you want to abort drawing the graphics
   rts

.graphics_loaded
   ; continue your graphics routine here
   ; !dss_tile_buffer will contain the tile numbers for the loaded ExGFX
   rts

dynamic_spriteset_queue

This routine handles uploading graphics to VRAM in small chunks to avoid overextending the V-Blank period. You can only call this routine within UberASM and should only be called under a nmi label.

When a 16x16 tile gets uploaded, its corresponding VRAM value is set to zero, this is how the VRAM queue routine detects if there are any GFX pending to be uploaded. Also the queue index is increased by 4 for each uploaded tile.

Input

N/A

Output

N/A

Other info

Item Description
A Should be 8-bit.
X/Y Should be 8-bit.
DB Not modified.
DP Modified with $4300, restored with $3000.
$00-$0F Not used.

Example of usage

As it was explained at the intro, this routine is meant to be used with UberASM under a nmi label. The included files already take care of this, so you really don't have to call this at any other point.

nmi:
    jml dynamic_spriteset_queue    ; change it to JSL if you have more routines here

dynamic_spriteset_init

This routine takes care of initializing RAM used by the system to its required values.

Input

N/A

Output

N/A

Other info

Item Description
A Returned as 8-bit.
X/Y Returned as 8-bit.
DB Modified with $40. Returns with $00.
DP Not modified.
$00-$0F Not used.

Example of usage

As it was explained at the intro, this routine is meant to be used with UberASM under a init label. The included files already take care of this, so you really don't have to call this at any other point.

init:
    jml dynamic_spriteset_init    ; change it to JSL if you have more routines here

RAM

Name Size Description
!dss_map 64 bytes Map of used 16x16 tiles in SP3-SP4.
Each entry has an 8-bit ID, useful to quickly compare data.
!dss_list 32 bytes List of IDs of the currently loaded GFX files. Each entry is 8-bits.
ID $FF is treated as an invalid GFX
!dss_list_timer 32 bytes Timer to mark as unused each GFX file.
Each GFX is marked as unused after 16 frames of being unused. This is customizable in a global basis.
!dss_gfx_size 32 bytes Amount of tiles used by each loaded GFX.
!dss_list_usage 32 bytes GFX usage map.
How many times each GFX was searched within a frame, if zero, the timer will start to tick down.
!dss_list_queue_index 64 bytes 16-bit table which contains the last queue index written to for the current GFX.
!dss_list_gfx_loaded 32 bytes List of flags for each item in the GFX list to determine wheter the GFX has been loaded or not
!dss_tile_buffer 32 bytes Array containing tile number for the latest loaded/searched ExGFX file.
!dss_tile_buffer_complete 1024 bytes Array of arrays containing tile numbers for each GFX loaded.
!dss_ram_buffer_index 1 byte Index used to determine which RAM buffer will be used to decompress GFX. Only the lower 3 bits are used.
!dss_maximum_tiles 1 byte Maximum amount of tiles that can be loaded via DSS in SP3/SP4. Only set during level load.
!dss_loaded_tiles 1 byte Current amount of tiles that were loaded via DSS in SP3/SP4. It can't exceed !dss_maximum_tiles.
!dss_gfx_queue 256 bytes Queue of pending graphics to be uploaded to VRAM.
The values need to be VRAM locations for each 16x16 tile needed to be uploaded to VRAM.
Up to 64 tiles can be put in queue, but only a certain amount will be uploaded each frame which is determined by !dss_queue_tiles.
Format:
  • Byte 1-2: VRAM destination
  • Byte 3-4: RAM GFX buffer location
This system can be used for other purposes if desired.
!dss_gfx_queue_index_nmi 2 bytes Index for !dss_gfx_queue during V-Blank.
!dss_gfx_queue_index_game 2 bytes Index for !dss_gfx_queue outside V-Blank.
!dss_vram_dest 64 bytes Map of possible VRAM destinations for sprite tiles.
$FF is treated as invalid.
Only updated during level load.
!dss_regular_sprite_copy 22 bytes Copy of the regular sprite number table ($9E).
!dss_custom_sprite_copy 22 bytes Copy of the custom sprite number table ($7FAB10).
!dss_extended_sprite_copy 10 bytes Copy of the extended sprite number table ($170B).
!dss_cluster_sprite_copy 20 bytes Copy of the cluster sprite table ($1892).
!dss_bounce_sprite_copy 20 bytes Copy of the bounce sprite table ($1699).

Patch signature

This patch leaves a small signature of data at $01DF78. The first three bytes spell "DSS" and the last two bytes are used for the version number in XX.YY format.

Clone this wiki locally