Sprite and Sound APIs

rje · Post by **rje** » Fri Jul 23, 2021 5:34 pm

I complain about being a bad assembly programmer, and perhaps most of that is just because I don't practice writing it.

So ok.

I also complain about the USABILITY of the sprite and sound registers on VERA.

OK, it sounds like I have an intersection of interests here.

Does it makes sense to write a sound-and-sprite API? I mean, is it a good place to dig into learning how to be a better assembly language programmer? Maybe I can write something that hooks into cc65?

Looking for ideas and encouragement here.

x16tial · Post by **x16tial** » Fri Jul 23, 2021 7:24 pm

Sounds like to me, if you did that, you'd be halfway to a complete game engine... ? Well, maybe 25%, but still.

rje · Post by **rje** » Fri Jul 23, 2021 7:55 pm

Hey, I hadn't thought of it that way. And I'm not sure that's true... but that's an angle I hadn't considered.

I guess the sound does require management... but Dusan has already written the guts of that; I can steal his code and adapt it.

I think of the assembly that must underpin Martin Kees' SuperBASIC. SuperBASIC Documentation.pdf

Maybe you're right, maybe the line is blurry.

But I'm lazy, so I just think of an API.

rje · Post by **rje** » Fri Jul 23, 2021 8:22 pm

SPRITE_API: a jump table in available RAM. In the $400s or $8000s or whatever.

SPRITE_API+$00: define sprite. R0a = sprite number. R0b = sprite resolution. R1 = VERA RAM address or offset. R2a = width. R2b = height.

SPRITE_API+$03: move sprite. R0a = number, R1 = x location, R2 = y location.

SPRITE_API+$06: kill sprite. R0a = number.

SPRITE_API+$09: enable sprite. R0a = number.

This is JUST an API -- and a relatively simple one. It wraps the POKEs to VERA, and that's about it. Yet the usability gain in my mind is enormous.

rje · Post by **rje** » Fri Jul 23, 2021 8:23 pm

SOUND_API: a jump table somewhere in available RAM.

More ambitious. At its core it's Dusan's interrupt code with storage for envelope configurations and voice state.

SOUND_API+$00: define sound. R0a = voice. R1a = Attack. R1b = Decay. R2a = Sustain. R2b = Release.

SOUND_API+$03: play sound. R0a = voice. R1 = wave. R2 = frequency. R3 = pulse width. R4 = volume.

VOICE ENVELOPES (16 bytes). Which envelope each voice is using, if any.

VOICE STATES(16 bytes). (Internal) state variable. Current state ('A','D','S','R', or 0 for 'done') of voice. Used by interrupt.

VOICE TARGETS(16 bytes). (Internal) state variable. Target value for voice. Used by interrupt.

ENVELOPE DATA(16 bytes). Envelope configurations. Four bytes per envelope: one each for Attack, Decay, Sustain, and Release, in jiffies or something.

Snickers11001001 · Post by **Snickers11001001** » Fri Jul 23, 2021 8:29 pm

I've always found that, more than necessity,  'simple annoyance' is actually the mother of invention. So I say go for it! There's no question that VERA and SOUND are tough (or at least tedious) nuts to crack right now. (I kinda feel nostalgic about that, since that was how the C64 was ... you had to really grind to learn the VICII and SID registers and stuff before you could make magic!)

Speaking of annoyance, I've been playing with doing a little port / adaptation of one of my favorite arcade games in X16 BASIC and PETSCII graphics just to prove the speed of the thing makes it possible. (If you do make a sound API I will happily try to adapt it for calling from BASIC which will save me a lot of brain damage when I get to the 'sound' part of my coding.) In any event, I've found the annoying and repeated need for a way to do a fast and compact "locate" for the text screen, preferably with a color specification. Sure, one can achieve the result by a combination of PRINT TAB(x) and a string array holding down arrows, i.e., Y$(y) -  (costly in memory and degraded performance as x and y coordinates get further to the right or bottom of the screen); or, more cheaply in terms of memory by doing a few pokes and using 'SYS' to call the kernal 'PLOT' routine (an official supported routine with a dedicated vector even on the x16 and everything!), but... like I said it reached the point of actual annoyance.

So, now I'm thinking I'll revive a dubious talent from my misspent youth and actually try to package the routine as a BASIC 'wedge' for the X16. This will require using some rom calls whose addresses might change between now and the official release, but it will at least be a fun exercise anyway in any event!

rje · Post by **rje** » Fri Jul 23, 2021 8:41 pm

13 minutes ago, Snickers11001001 said:

I've always found that, more than necessity, 'simple annoyance' is actually the mother of invention. So I say go for it! There's no question that VERA and SOUND are tough (or at least tedious) nuts to crack right now. (I kinda feel nostalgic about that, since that was how the C64 was ... you had to really grind to learn the VICII and SID registers and stuff before you could make magic!)

Thank you!

See Martin Kees' document, which I attached above. It REALLY opened up access to Sprites and Sound on the 64, and made me a more productive BASIC coder ... without consuming any of the precious RAM I needed for sprites and code.

Quote

In any event, I've found the annoying and repeated need for a way to do a fast and compact "locate" for the text screen, preferably with a color specification. ...

So, now I'm thinking I'll revive a dubious talent from my misspent youth and actually try to package the routine as a BASIC 'wedge' for the X16. This will require using some rom calls whose addresses might change between now and the official release, but it will at least be a fun exercise anyway in any event!

Something in my mind is telling me that Michael's KERNAL mods includes this, but I'm not sure.

ZeroByte · Post by **ZeroByte** » Fri Jul 23, 2021 8:44 pm

I've been working towards a sound API - I'm still going round and round as to certain format issues / performance issues / etc.

There's a very nascent version of it in my Flappy Bird game. The idea is to use a simple data stream format for the various chips, and some basic function calls to start/stop them. My biggest issue right now is getting a little bit more experienced in dealing with banked memory, as there's just no way around using HiRAM for music and PCM data. SFX streams are very short and fit just fine in LoRAM, so it's easy enough to define those in-line in C as #include'd const byte arrays... but songs tend to push the 20KB barrier (VGM-exported songs I'm messing with) on YM, and even more for PSG.

Plus, there's already a simple sound engine for BASIC posted in the downloads area. Have you checked that out yet?

Snickers11001001 · Post by **Snickers11001001** » Fri Jul 23, 2021 9:16 pm

3 minutes ago, rje said:

Something in my mind is telling me that Michael's KERNAL mods includes this, but I'm not sure.

I'll double check. My original take on looking at the reference guide was that the cursor-locate was referring to a pixel cursor and the new API for putting a character was in reference to the graphical (GEOS style) characters that go to the bitmap instead of the regular BASIC text screen. Part of me still wants to mess with a wedge as a way to parse expressions or command parameters inline in basic instead of 'poke,poke,poke,poke,sys" combos. At the moment, I'm working with a stub routine that you call with 'SYS' and it grabs its parameters from the first three integer variables. We'll see how it goes.

rje · Post by **rje** » Fri Jul 23, 2021 9:24 pm

Of course, I'm an idiot for not checking the DOCUMENTATION.

https://github.com/commanderx16/x16-docs/blob/master/Commander X16 Programmer's Reference Guide.md#sprites

Sprites

$FEF0: sprite_set_image - set the image of a sprite

$FEF3: sprite_set_position - set the position of a sprite

Function Name: sprite_set_image

Purpose: Set the image of a sprite

Call address: $FEF0

Signature: bool sprite_set_image(byte number: .a, width: .x, height: .y, apply_mask: .c, word pixels: r0, word mask: r1, byte bpp: r2L);

Error returns: .C = 1 in case of error

Description: This function sets the image of a sprite. The number of the sprite is given in .A, The bits per pixel (bpp) in r2L, and the width and height in .X and .Y. The pixel data at r0 is interpreted accordingly and converted into the graphics hardware's native format. If the .C flag is set, the transparency mask pointed to by r1 is applied during the conversion. The function returns .C = 0 if converting the data was successful, and .C = 1 otherwise. Note that this does not change the visibility of the sprite.

Note: There are certain limitations on the possible values of width, height, bpp and apply_mask:

Width and height may not exceed the hardware's capabilities.

Legal values for bpp are 1, 4 and 8. If the hardware only supports lower depths, the image data is converted down.

apply_mask is only valid for 1 bpp data.

Function Name: sprite_set_position

Purpose: Set the position of a sprite or hide it.

Call address: $FEF3

Signature: void sprite_set_position(byte number: .a, word x: r0, word y: r1);

Error returns: None

Description: This function shows a given sprite (.A) at a certain position or hides it. The position is passed in r0 and r1. If the x position is negative (>$8000), the sprite will be hidden.