z88dk SP1 software sprite library

The place for codemasters or beginners to talk about programming any language for the Spectrum.
Post Reply
User avatar
PeterJ
Site Admin
Posts: 6858
Joined: Thu Nov 09, 2017 7:19 pm
Location: Surrey, UK

z88dk SP1 software sprite library

Post by PeterJ »

Over the years I have had a go with z88dk. I have a basic grasp of C and have been able to write simple text based routines.

I thought I would have a go with graphics and found the sprite library, but can't find any tutorials or documentation (apart from information as to what it is) online:

https://www.z88dk.org/wiki/doku.php?id= ... prites:sp1

I also found the Spectrum specific functions here:

https://www.z88dk.org/wiki/doku.php?id= ... zxspectrum

Would anybody be willing to share some simple examples? (Especially of the uint zx_attr(uchar row, uchar col) and uint zx_screenstr(uchar row, uchar col) functions)

Thanks in advance.
User avatar
bob_fossil
Manic Miner
Posts: 654
Joined: Mon Nov 13, 2017 6:09 pm

Re: z88dk SP1 software sprite library

Post by bob_fossil »

Hi Peter,

I haven't used the SP1 library so far but it is used here, I think:

https://github.com/z88dk/z88dk/tree/mas ... /BlackStar

Can't vouch for the game itself but the source was useful in getting my head around some of the compiler quirks that can arise when using z88dk and assembly code with the sdcc compiler instead of sccz80.

Bob Fossil
dfzx
Manic Miner
Posts: 673
Joined: Mon Nov 13, 2017 6:55 pm
Location: New Forest, UK
Contact:

Re: z88dk SP1 software sprite library

Post by dfzx »

I wrote a series of getting started articles for Z88DK earlier this year, but stopped before doing SP1. It's a rather intimidating library which is poorly documented. The docs which are there appear to be a bit out of date.

The examples and Blackstar source are probably your best bet, but learning a library by reading source code isn't easy.
Derek Fountain, author of the ZX Spectrum C Programmer's Getting Started Guide and various open source games, hardware and other projects, including an IF1 and ZX Microdrive emulator.
User avatar
PeterJ
Site Admin
Posts: 6858
Joined: Thu Nov 09, 2017 7:19 pm
Location: Surrey, UK

Re: z88dk SP1 software sprite library

Post by PeterJ »

Would you be able to post a link to your tutorials? Thanks
dfzx
Manic Miner
Posts: 673
Joined: Mon Nov 13, 2017 6:55 pm
Location: New Forest, UK
Contact:

Re: z88dk SP1 software sprite library

Post by dfzx »

PeterJ wrote: Tue Nov 21, 2017 8:42 am Would you be able to.post a link to your tutorials? Thanks
This is the first one:

https://github.com/z88dk/z88dk/blob/mas ... Started.md

Currently 7 in the series.
Derek Fountain, author of the ZX Spectrum C Programmer's Getting Started Guide and various open source games, hardware and other projects, including an IF1 and ZX Microdrive emulator.
User avatar
PeterJ
Site Admin
Posts: 6858
Joined: Thu Nov 09, 2017 7:19 pm
Location: Surrey, UK

Re: z88dk SP1 software sprite library

Post by PeterJ »

This really is a fantastic piece of work. Thank you.
dfzx
Manic Miner
Posts: 673
Joined: Mon Nov 13, 2017 6:55 pm
Location: New Forest, UK
Contact:

Re: z88dk SP1 software sprite library

Post by dfzx »

PeterJ wrote: Fri Nov 24, 2017 7:16 am This really is a fantastic piece of work. Thank you.
Thank you! It's my only contribution to the Speccy scene so I'm grateful for the appreciation. :)
Derek Fountain, author of the ZX Spectrum C Programmer's Getting Started Guide and various open source games, hardware and other projects, including an IF1 and ZX Microdrive emulator.
hikoki
Manic Miner
Posts: 576
Joined: Thu Nov 16, 2017 10:54 am

Re: z88dk SP1 software sprite library

Post by hikoki »

Do you know FASE ?
It allows coding in z88dk's C and Boriel Basic. It's said to manage many sprites at 50Hz.
Andy Dansby is writing a game making-of on his blog : http://andyspeccysite.simplesite.com
andydansby
Microbot
Posts: 147
Joined: Fri Nov 24, 2017 5:09 pm
Location: Syracuse, NY, USA
Contact:

Re: z88dk SP1 software sprite library

Post by andydansby »

I do have a link for SPLib2 which is older than SP1, but the concepts I believe are the same.

Check out http://www.mojontwins.com/warehouse/splib2-tutorial.pdf

You should be able to carry the concepts of splib to SP1, written by the same person.

I am starting to mess around with FASE, but it always seems to be 1 step forward and 2 steps back. Trying to clear my brain before I start attacking FASE again.

Andy Dansby
dfzx
Manic Miner
Posts: 673
Joined: Mon Nov 13, 2017 6:55 pm
Location: New Forest, UK
Contact:

Re: z88dk SP1 software sprite library

Post by dfzx »

[mention]PeterJ[/mention], did you get any further with SP1? I've been looking at it for a few hours now and all I'm getting is bl**dy frustrated!

I was trying to write a simple program which would print a single sprite on the screen. Working forwards (i.e. starting with a blank editor) I just hit crashes, smudges and squiggles. :? So I started again with one of the demos and started taking stuff out which didn't seem relevant. I achieved my aim, but have no idea how it works!

My code:

Code: Select all

/*
 * zcc +zx -vn -m -startup=31 -clib=sdcc_iy -O3 --max-allocs-per-node200000 one.c graphics.asm -o one -create-app
 */

#pragma output STACKPTR=53248                    // place stack at $d000 at startup

#include <arch/zx.h>
#include <arch/zx/sp1.h>

struct sp1_Rect cr = {0, 0, 32, 24};            // rectangle covering the full screen

extern unsigned char ball[];

int main()
{
  static struct sp1_ss *s;

  zx_border(INK_BLACK);
 
  sp1_Initialize( SP1_IFLAG_MAKE_ROTTBL | SP1_IFLAG_OVERWRITE_TILES | SP1_IFLAG_OVERWRITE_DFILE, INK_BLACK | PAPER_WHITE, ' ' );
  sp1_Invalidate(&cr);
 
  s = sp1_CreateSpr(SP1_DRAW_LOAD1LB, SP1_TYPE_1BYTE,  2,  0,  0);
  sp1_AddColSpr(s, SP1_DRAW_LOAD1, 0, 8, 0);
  sp1_AddColSpr(s, SP1_DRAW_LOAD1RB, 0, 0, 0);

  sp1_MoveSprAbs(s, &cr, ball, 10, 14, 0, 4);

  sp1_UpdateNow();
 
  return 0;
}
and the graphics.asm file for those following along:

Code: Select all

SECTION rodata_user

PUBLIC _ball

._ball
	defb @00111100
	defb @01000010
	defb @10000001
	defb @10000001
	defb @10000001
	defb @10000001
	defb @01000010
	defb @00111100

	defb 0,   0,   0,   0
	defb 0,   0,   0,   0
My original code didn't have the pragma to move the stack pointer. Why is that necessary I wonder? The program just locks up without it.

I tried taking out those flags to the SP1 init routine:

Code: Select all

SP1_IFLAG_MAKE_ROTTBL | SP1_IFLAG_OVERWRITE_TILES | SP1_IFLAG_OVERWRITE_DFILE
and replacing them with a zero. I don't know what any of those do, and there's no documentation for them, so what use could they possibly be? :) Turns out that without them the program prints a squiggle on the left side of the screen, but I've no idea why.

The 2 in the call to create the sprite:

Code: Select all

s = sp1_CreateSpr(SP1_DRAW_LOAD1LB, SP1_TYPE_1BYTE,  2,  0,  0);
looks like it should be a 1. I think it means 1 character cell high, which is what my little ball graphic is. Only if I make it a 1 nothing gets shown. So I made it a 2 but I don't understand why.

What do these calls do, I wonder:

Code: Select all

sp1_AddColSpr(s, SP1_DRAW_LOAD1, 0, 8, 0);
sp1_AddColSpr(s, SP1_DRAW_LOAD1RB, 0, 0, 0);
I think this is building the sprite in memory, column by column. But what's the LOAD1 and LOAD1RB mean? And why the 8? Weird things happen if I take these lines out of change them.

In the graphics file the 8 zero bytes after the sprite data are required. A smudge appears next to the graphic if I leave them out. The old spritepack doc suggests they're required for mask data, or maybe rotation data. It's not really clear.

Anyway, enough of my honking. It's just frustration really. Has anyone learnt how to use SP1? If so, how did you go about it?
Derek Fountain, author of the ZX Spectrum C Programmer's Getting Started Guide and various open source games, hardware and other projects, including an IF1 and ZX Microdrive emulator.
User avatar
bob_fossil
Manic Miner
Posts: 654
Joined: Mon Nov 13, 2017 6:09 pm

Re: z88dk SP1 software sprite library

Post by bob_fossil »

I think the stack pointer is important as SP1 uses dynamic memory. The source for the Blackstar example has the following comment in it's zpragma.inc:

Code: Select all

#pragma output REGISTER_SP = 0xd000 // typical stack location when using sp1
Digging into the include file sp1.h, SP1_DRAW_LOAD and so on appear to be function pointers:

Code: Select all

extern void    SP1_DRAW_LOAD1(void);        // load sprite 1-byte definition graph only no mask; sw rotation will use LOAD1_NR if no rotation necessary
extern void    SP1_DRAW_LOAD1NR(void);      // load sprite 1-byte definition graph only no mask; no rotation applied, always drawn at exact tile boundary
extern void    SP1_DRAW_LOAD1LB(void);      // load sprite 1-byte definition graph only no mask; sw rotation as LOAD1 but for left boundary of sprite only
extern void    SP1_DRAW_LOAD1RB(void);      // load sprite 1-byte definition graph only no mask; sw rotation as LOAD1 but for right boundary of sprite only
So it looks like when you call sp1_AddColSpr you specify a drawing method in the parameters. Don't know if this makes it any clearer? :) I've found that poorly updated documentation is the curse of the z88dk. Your best bet would be to get into contact with Alvin as he is the font of all z88dk knowledge - or even better, somehow get him to register on this forum. I think he's busy with development on the ZX Spectrum Next these days but I've learnt more about using the z88dk in forum posts with him than I have from anywhere else.

I'm using R-Tape's posted beginners sprite code to write myself a basic sprite handling routine from C that I can understand.
Post Reply