Documentation

Contents

• Routines
  • find_and_queue_gfx
    • Input
    • Output
    • Other info
    • Example of usage
  • dynamic_spriteset_queue
    • Input
    • Output
    • Other info
    • Example of usage
  • dynamic_spriteset_init
    • Input
    • Output
    • Other info
    • Example of usage
• RAM
  • !dss_map
  • !dss_list
  • !dss_list_timer
  • !dss_gfx_size
  • !dss_list_usage
  • !dss_list_queue_index
  • !dss_list_gfx_loaded
  • !dss_tile_buffer
  • !dss_tile_buffer_complete
  • !dss_ram_buffer_index
  • !dss_maximum_tiles
  • !dss_loaded_tiles
  • !dss_gfx_queue
  • !dss_gfx_queue_index_nmi
  • !dss_gfx_queue_index_game
  • !dss_vram_dest
  • !dss_regular_sprite_copy
  • !dss_custom_sprite_copy
  • !dss_extended_sprite_copy
  • !dss_cluster_sprite_copy
  • !dss_bounce_sprite_copy
• Patch signature

---

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.