Skip to content

Documentation

Jump to bottom
TheLX5 edited this page Feb 9, 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.

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-20 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

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).

Code examples {#examples}

This section includes several ways that you have to work with this system. More will be added later.

Using !dss_tile_buffer

This is basically what I like to call the "standard" way of interacting with a recently found ExGFX via find_and_queue_gfx. This is only valid for 16x16 tiles.

If you want to use a single tile, you can use the following approach:

   lda !dss_tile_buffer+$00    ; this will draw the first tile from the ExGFX file
   sta $6302,y
   lda !dss_tile_buffer+$06    ; this will draw the seventh tile from the ExGFX file
   sta $6306,y
   lda !dss_tile_buffer+$0F    ; this will draw the fifteenth tile from the ExGFX file
   sta $630A,y

If you're drawing tiles with a loop you could opt for this other approach:

   phx                      ; remember to preserve X if you're using it for other things!
   lda tile_indices,x       ; use a table which holds the index for each tile you want from the buffer
   tax                      ; transfer it to X, X is preferred because it supports long addressing
   lda !dss_tile_buffer,x   ; load the tile data from !dss_tile_buffer
   plx                      ; get back your previous X

Handling 8x8 tiles

WIP

Loading multiple ExGFX

WIP

Limit amount of tiles modified by DSS

WIP

Clone this wiki locally