<commit_before>freemlib for Neo-Geo - Sprite functionality
===========================================
In order to use Sprites, you need to know how the data is laid out.
In the VRAM, there are four sections called SCB (Sprite Control Blocks).
Each SCB section controls a different part of the sprite.

{SCB1}
SCB1 holds the tilemaps, palette, auto-animation, and flip bits.

Tile number				0000|00000000
Palette					00000000
Auto-anim modes			2-bit/3-bit, one bit for each
HFlip, VFlip			one bit each

{SCB2}
SCB2 holds the shrinking coefficients.
Horiz. Size				0000
Vert.  Size				00000000

{SCB3}
SCB3 holds the vertical positions, sticky bit, and sprite tile size.
Y Position				000000000
Sticky Bit				one bit
Sprite Size				000000

{SCB4}
SCB4 has the horizontal position only.
X position				000000000

After the SCB sections is the Sprite List. I'm not 100% sure how it operates.

{Sprite List (Even Scanlines)}	$8600-$867F
{Sprite List (Odd Scanlines)}	$8680-$86FF
I think the system throws the sprite numbers into here, but I'm not sure how
they map to the scanlines or whatever.

================================================================================
<Function Sketchpad>

(Overall)
Active Sprites (for keeping track)
VRAM Buffers
 * background layers
 * etc.

(Metasprite)
Functions for dealing with a metasprite
* Add metasprite to active pool
* Remove metasprite from active pool
* Change metasprite X position
* Change metasprite Y position
* Change metasprite Horiz flip
* Change metasprite Vert flip
* Change metasprite Animation

(Sprite)
Functions for dealing with a single sprite
* Change sprite X position
* Change sprite Y position
* Change sprite palette
* Change sprite Horiz. flip
* Change sprite Vert. flip
* Change sprite tilemap

================================================================================
[Metasprite Data]
Metasprites are a collection of Sprites. On the Neo-Geo, it's a bit easier to
make metasprites, compared to other consoles. SCB3's Sprite height and Sticky
bit go a long way in making metasprites easier to deal with.

Commands have "mspr" prefix.

<Metasprite Data Block>
$00			Number of Sprites in Metasprite		(word)
$02...end	Pointers to Sprite data				(long)

================================================================================<commit_msg>sprite brainstorming<commit_after>freemlib for Neo-Geo - Sprite functionality
===========================================
In order to use Sprites, you need to know how the data is laid out.
In the VRAM, there are four sections called SCB (Sprite Control Blocks).
Each SCB section controls a different part of the sprite.

{SCB1}
SCB1 holds the tilemaps, palette, auto-animation, and flip bits.

Tile number				0000|00000000
Palette					00000000
Auto-anim modes			2-bit/3-bit, one bit for each
HFlip, VFlip			one bit each

{SCB2}
SCB2 holds the shrinking coefficients.
Horiz. Size				0000
Vert.  Size				00000000

{SCB3}
SCB3 holds the vertical positions, sticky bit, and sprite tile size.
Y Position				000000000
Sticky Bit				one bit
Sprite Size				000000

{SCB4}
SCB4 has the horizontal position only.
X position				000000000

After the SCB sections is the Sprite List. I'm not 100% sure how it operates.

{Sprite List (Even Scanlines)}	$8600-$867F
{Sprite List (Odd Scanlines)}	$8680-$86FF
I think the system throws the sprite numbers into here, but I'm not sure how
they map to the scanlines or whatever.

================================================================================
<Brainstorming>
Sprites are usually transferred to the VRAM in VBlank...

* DATlib does this
* AOF does this
* smkdan's two scrolling demos do this (scroll1.asm being easier to understand)
* furrtek's nyancat demo does this
* Frog Feast, the list goes on...

[Frog Feast]
* "SpritesChanged" can skip the logic in RenderSprites if needed.

[smkdan scroll2.asm]
(scroll1 is easier, but scroll2 is more flexible)
* "vramlist": 512 words (list of addresses, increments, and data to upload to VRAM)
* "vramptr":  1 dword (current pointer into vramlist, reset every frame)

vramlist entries:
0		Number of words in this entry ("n")
1		VRAM address
2		VRAM increment
3..n	data words

Main loop:
* update previous scroll values
* ControllerScroll
* ClampScroll
* CheckUpdate		; see if sprite VRAM needs to be updated
* BufferSCB3		; yscroll, ysize, chain
* BufferSCB4		; xscroll

VBlank:
* UpdateVRAM		; make VRAM changes based on commands in list

--------------------------------------------------------------------------------
[Questions and Thoughts]
* How many sprites can I update/how much data can I push in one VBlank?
* Will likely need to provide some conversion routines for vram data
* Current metasprite system does not account for all possibilities; chain bit forced
* Is it possible to use the lower bits of SCB4 for custom purposes?

--------------------------------------------------------------------------------
[Data Formats]
The best formats are those that map to the LSPC...like smkdan's.

$00		(w) data length
$02		(w) vram address
$04		(w) vram increment
$06...	(w) vram data in words

================================================================================
<Function Sketchpad>

(Overall)
Active Sprites (for keeping track)
VRAM Buffers
 * background layers
 * etc.

(Metasprite)
Functions for dealing with a metasprite
* Add metasprite to active pool
* Remove metasprite from active pool
* Change metasprite X position
* Change metasprite Y position
* Change metasprite Horiz flip
* Change metasprite Vert flip
* Change metasprite Animation

(Sprite)
Functions for dealing with a single sprite
* Change sprite X position
* Change sprite Y position
* Change sprite palette
* Change sprite Horiz. flip
* Change sprite Vert. flip
* Change sprite tilemap

================================================================================
[Metasprite Data]
Metasprites are a collection of Sprites. On the Neo-Geo, it's a bit easier to
make metasprites, compared to other consoles. SCB3's Sprite height and Sticky
bit go a long way in making metasprites easier to deal with.

todo:
* allow for multiple "groups" of sprites in a single metasprite
* add x and y offsets to each sprite block

Commands have "mspr" prefix.

<Metasprite Data Block>
$00			Number of Sprites in Metasprite		(word)
$02...end	Pointers to Sprite data				(long)


<WIP new metasprite data block>
$00			Number of Metasprite components		(word)
------------
$02			Number of sprites in Component 1	(word)
$04			Component 1 overall X offset		(word)
$06			Component 1 overall Y offset		(word)
$08			Pointers to Component 1 Sprite data	(long)
............
etc.

================================================================================
{'fraction_non_alphanumeric': 0.1746549933224514, 'fraction_numerical': 0.031310283424840483, 'mean_word_length': 3.9668386145910097, 'pattern_counts': {'":': 2, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 10, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3917417', 'n_tokens_mistral': 2143, 'n_tokens_neox': 1896, 'n_words': 877}