Saturn Game Tutorial

with complete SEGA Saturn demo
version 05/07/01

Enter the C4 - 2005 Saturn Coding Contest:
http://www.rockin-b.de/c4/2005/C4_2005.htm

COPY C:\Saturn~1\SET_COF.BAT .\TMP.BAT
CALL TMP.BAT
DEL TMP.BAT

COPY C:\Saturn~1\SET_ELF.BAT .\TMP.BAT
CALL TMP.BAT
DEL TMP.BAT

slInitSystem(TV_320x240, tex_SpriteTable, 1);

// init CD block and CD file system
init_CD();

// init sound and CD audio
init_Sound();

// init sprite GPU, upload textures
init_VDP1();

// init background GPU, upload images
init_VDP2();
   
while(1) {
}

// return to demo demo loader
// or activate multiplayer
SYS_Exit(0);


<Toolbox>/Xtns/Script-Fu/SegaSaturn/setTransColor
<Image>/Script-Fu/SegaSaturn/setTransColor

Puts a new layer of the specified color behind all other layers of the image, such that all transparent pixels will have this color.

<Toolbox>/Xtns/Script-Fu/SegaSaturn/maxContrastAlpha
<Image>/Script-Fu/SegaSaturn/maxContrastAlpha

Saturn cannot display sprites with an alpha channel, so this prepares images with alpha channel to get a transparent color. Basically switches the transparent pixel scheme from alpha channel to colorkey.
After running the script, the alpha channel does only contain two values: 0 or 255 (full opaque or full transparent).

<Toolbox>/Xtns/Script-Fu/SegaSaturn/sprs2lyr

Reads multiple image files specified by file name pattern and creates one new image containing each of the images in a seperate layer.
Animations and movies are represented that way in The GIMP. You can playback the animation by right-clicking on the generated image and selecting Filter/Animation/play.

<Toolbox>/Xtns/Script-Fu/SegaSaturn/lyrs2img
<Image>/Script-Fu/SegaSaturn/lyrs2img

Starting from an animation (e.g. an image with multiple layers, like generated with sprs2lyr) a new image is created which contains only one layer onto which all previous layers (frames of an animation) are pasted, started from top to bottom. This image can then be converted to raw Saturn format with BGCON.

RB_SaturnPCM.EXE shot.wav c

RB_SaturnPCM.EXE shot.wav

BGCON.EXE TGA2DHUF.TXT

CD 15
IF TGA
IM BITMAP
CMP DHUFF
RGBHI ON
TRANS -1
L lava.tga
OF BIN
S lava.bin
OF C
S lava.c lava

RGBHI ON
TRANS -1

sprani01.bmp
sprani02.bmp
.....

You have 10 work RAM animations in total. They got 5 different pixel sizes. For 2 sizes it can happen that multiple (let's say a maximum is 3 and 2) animations are displayed at once, which are supposed to be out of synch. Some other sizes are displayed at once, too, but they are in synch, e.g. always show equal frames.
->
You will need to have 5 dummy frames, one for each size. Plus additional (2 and 1) dummy frames for each out of synch animation instance that can be displayed at once.

Pitfall:
3Dto3D.EXE doesn't preserve quads, it converts all to triangles. Although DXF2SG3.EXE can convert triangles to quads it can fail resulting in a corrupted 3D model.
(example: SaturnPlanet in the demo, see SaturnPlanet2.sg3 resulting from SaturnPlanet2.DXF)
Command line:

This tool got a lot of options and preserves quads. Besides to extract just the geometry (-x), it got an experimental mode to preserve all other info in the file (like hierarchy) which just modifies the geometry. It is experimental because it's not known exactly what DXF features are supported by DXF2SG3.EXE and 3DEditor. You only need to experiment with this if the standard option (-x) don't fit your needs.
Command line:

It allowes to invert normals (-back), convert triangles to quads (-quad), create dual plane polygons (-dual) and apply object transformations like scale (-scl x y z), rotation (-rot x y z) and translation (-pos x y z)
Command line:

DXF2SG3.EXE SaturnPlanet3.DXF -back -scl 10 10 10 -rot 90 0 0
DXF2SG3.EXE SaturnRings3.DXF -back -dual -scl 10 10 10

content: raw pixel data
used for: transfer to VDP1 VRAM
availability: not used after transfer
code:

Uint16    texture_SpriteTable000[] = {
};

content: width, height, VDP1 VRAM destination
used for: slInitSystem()
availability: has to be always present for drawing
code:

TEXTURE    tex_SpriteTable[] = {
};

content: texture id, color mode, bitmap source
used for: transfer to VDP1 VRAM
availability: not used after transfer
code:

PICTURE    pic_SpriteTable[] = {
};

content: sprite drawing attributes
used for: drawing
availability: needed for drawing only
code:

SPR_ATTR attr_SpriteTable[] = {
};

CD 15
IF TGA
IM BITMAP
CMP NONE
RGBHI ON
TRANS -1
OF BIN
L spr000.tga
S SprTbl.bin
L spr001.tga
S SprTbl.bin
L spr002.tga
S SprTbl.bin
...
L spr309.tga
S SprTbl.bin

BGCON.EXE TGA2BIN.TXT

CMP_DecRunlen(in, &out, maxoutsize);

"Transpalent" - orthogonal, just like you see it
"Repeat Edge" - repeat where texture is too small
"Rap Arround" - wrap texture around (for spheres, ...)

// check if pad is connected
// and return first pad with input
// multi tap compatible, up to 12 pads
//
// return:    -1      - no pad connected
//            -2      - no input
//            else    - pad index
Sint8 demo_getFirstPadIndex()
{
}

if( (Smpc_Peripheral[index].data & PER_DGT_ST) == 0)

if( (Smpc_Peripheral[index].push & PER_DGT_ST) == 0)

Uint16 data = Smpc_Peripheral[index].data;

if(((data & PER_DGT_TA) == 0) && ((data & PER_DGT_TB) == 0) && ((data & PER_DGT_TC) == 0) && ((data & PER_DGT_ST) == 0))

#include <sddrvs.dat>

void init_SFX()
{
}

#include "soundFX/electronicdoor.c"

char *shot = NULL;
Uint32 shot_size = 382464;
PCM shot_dat = {(_Stereo | _PCM16Bit) , 0 , 127 , 0 , 0x0 , 0 , 0 , 0 , 0};

void load_PCM()
{
}

#include <sddrvs.dat>

void init_SFX()
{
}

// most basic CD block initialization
CDC_CdInit();
// GFS CD file system init
GFS_Init();
// SGL CD file system init
slCdInit();

slCDDAOn(127, 127, 0, 0);

Uint32 toc[102];
Uint8 cdtrack;

void getFirstAudioTrack()
{
}


void CDDA_pause();
void CDDA_play(Uint8 track);

// stop CD, seek home position
void CDDA_stop();

// start CD scan / fast forward
// or continue playing
void CDDA_fwd();

// start CD scan / fast rewind/reverse
// or continue playing
void CDDA_rvs();

// returning one of the strings below
char *CDDA_getStatusName();
char *CD_status[] = {
    "BUSY",
    "PAUSE",
    "STANDBY",
    "PLAY",
    "SEEK",
    "SCAN",
    "OPEN",
    "NODISC",
    "RETRY",
    "ERROR",
    "FATAL",
    "UNKNOWN"
};

slTVOff();

// the address for background color in VRAM is taken from various examples,
// don't know why
// !!! beware, 1st try the bgcol was the only thing to see on real Saturn
// what exactly is the back_col_adr? maybe the color at this adress is
// interpreted as background color and wheereever such color occurs,
// it's replaced by the given one
// !! all i see is the background color....
slBack1ColSet((void *)BACK_CRAM, CD_Black);
   
   
// the debug text lib take the NBG0 scroll <- the only one with 24bits color depth
// priority = 0 -> scroll not displayed
// take farest away   
slPriorityNbg0(7);
slPriorityNbg1(6);
//    slPrioritySpr0-7(0);   

// we want bitmap scrolls
// only NBG0 and NBG1 can handle bitmap mode
// color modes:
//      palettet:           COL_TYPE_16, COL_TYPE_256, COL_TYPE_2048
//      rgb:                COL_TYPE_32768, COL_TYPE_1M
// bitmap sizes(BM_HxV):    BM_512x256, BM_512x512, BM_1024x256, BM_1024x512
slBitMapNbg1(COL_TYPE_32768, BM_512x256, (void *)VDP2_VRAM_A0);
// might want to clear it or load an image later
// memset((void *)VDP2_VRAM_A0, CD_Black, 256*512*2);

// monitor position in scroll coordinate space
// sets the position of monitors topleft corner(fixed format)
slScrPosNbg1(toFIXED(0.0), toFIXED(0.0));

// reduction setting: only NGB0 and NBG1 are able to RBG, too)
// modes:   ZOOM_1, ZOOM_HALF, ZOOM_QUATER      each untill x256
slZoomModeNbg1(ZOOM_1);
   
// zoom
// fixed point reziprocal of scale ratio in x and y direction
slZoomNbg1(toFIXED(1.0), toFIXED(1.0));           

// registeres scrolls
// call only after all scroll function settings
// returns 0 or -1(ERROR)
slScrAutoDisp(NBG0ON | NBG1ON);

slTVOn();


void loadBG()
{

// load from CD into an allocated buffer, decompress and display the
// background image
Sint32 load = GFS_Load(GFS_NameToId("LAVA.BIN"), 0, (Uint32 *)buffer, 120260);
if(load <= 0)
if(DeHuff(buffer, (void *)adr) != 0)
   
img2VRAM((Uint16 *)VDP2_VRAM_A0, 512, (Uint16 *)(0x200000), 240, 320);

}

// line-by-line transfer to vram
void img2VRAM(Uint16 *vram, Uint16 vram_width, Uint16 *img, Uint16 img_height, Uint16 img_width)
{

int i;
Uint32 oVRAM = 0;
Uint32 oIMG = 0;
   
for(i = 0; i < img_height; i++) {
}   

}

slInitSystem(TV_320x240, tex_SpriteTable, 1);

set_sprite(pic_SpriteTable, 310, tex_SpriteTable);

// load from CD, decompress and set transparent color of the
// work RAM sprite animation
Sint32 load = GFS_Load(GFS_NameToId("SPRTBL.BIN"), 0, (Uint32 *)buffer, 120260);
if(load <= 0)
// I know it's word unit
void *out = (void *)0x200000;
if(CMP_DecRunlenWord(buffer, &out, 0x100000) != CMP_DEC_OK)
set_colorkey((Uint16 *)adr, 244768/2, CD_Blue, 0);
// this assumes consecutive character pattern order in VRAM
// like 3DEditor usually generates it by default
slDMACopy((void *)0x200000, (void *)(SpriteVRAM + CGADDRESS), (Uint32)244768);

// display attributes of all used sprites in VDP1 VRAM
// have this global in your program
// see How to create a sprite/texture table
SPR_ATTR attr_SpriteTable[] = {
    SPR_ATTRIBUTE(0,No_Palet,No_Gouraud,CL32KRGB|SPenb|ECdis,sprNoflip),   
    ....
}

void drawSprite()
{
}


You have 10 work RAM animations in total. They got 5 different pixel sizes. For 2 sizes it can happen that multiple (let's say a maximum is 3 and 2) animations are displayed at once, which are supposed to be out of synch. Some other sizes are displayed at once, too, but they are in synch, e.g. always show equal frames.
->
You will need to have 5 dummy frames, one for each size. Plus additional (2 and 1) dummy frames for each out of synch animation duplicate that can be displayed at once.

Uint8 *adr = (Uint8 *)0x200000;
Sint32 load;

// load from CD, decompress and set transparent color of the
// work RAM sprite animation
load = GFS_Load(GFS_NameToId("NEWBIE.BIN"), 0, (Uint32 *)buffer, 120260);
if(load <= 0)
if(DeHuff(buffer, (void *)adr) != 0)
set_colorkey((Uint16 *)adr, 570960/2, CD_Blue, 0);

SPR_TYPE_SINGLE,
SPR_TYPE_ANI_WRAM,
SPR_TYPE_ANI_VRAM

SpriteType type;
char *name;
FIXED pos[XYZS];
ANGLE ang;
Uint32 spriteID;
// for animations
Uint32 frame, nFrames;
Uint8 *source, *target;
Uint32 size;
struct {
} frameskip;

{SPR_TYPE_SINGLE, "cool", {toFIXED(0.0), toFIXED(-60.0), toFIXED(169), toFIXED(1.0)}, DEGtoANG(0.0), 0, 0, 0, NULL, NULL, 0, {0, 0}},
{SPR_TYPE_ANI_WRAM, "newbie 1 work RAM", {toFIXED(-80.0), toFIXED(60.0), toFIXED(169), toFIXED(1.0)}, DEGtoANG(0.0), 1, 0, 183, (Uint8 *)0x200000, (Uint8 *)(SpriteVRAM + CGADDRESS+864), 104*15*sizeof(Uint16), {0, 10}},
{SPR_TYPE_ANI_WRAM, "newbie 2 work RAM", {toFIXED(80.0), toFIXED(60.0), toFIXED(169), toFIXED(1.0)}, DEGtoANG(0.0), 2, 6, 183, (Uint8 *)0x200000, (Uint8 *)(SpriteVRAM + CGADDRESS+3984), 104*15*sizeof(Uint16), {0, 10}},
{SPR_TYPE_ANI_VRAM, "driving 1 video RAM", {toFIXED(-80.0), toFIXED(-60.0), toFIXED(169), toFIXED(1.0)}, DEGtoANG(0.0), 3, 0, 17, NULL, NULL, 0, {0, 20}},
{SPR_TYPE_ANI_VRAM, "driving 2 video RAM", {toFIXED(80.0), toFIXED(-60.0), toFIXED(169), toFIXED(1.0)}, DEGtoANG(0.0), 3, 3, 17, NULL, NULL, 0, {0, 20}},

// animate
if(sprite->type != SPR_TYPE_SINGLE) {
}

if(sprite->type == SPR_TYPE_ANI_VRAM)
else

int i;

for(i = 0;i < 5; i++)

slSynch();

#include "polygons/SaturnRings3_textured.mdl"

POINT    point_0[] = {
};

POLYGON    polygon_0[] = {
};

ATTR    attribute_0[] = {
};

XPDATA    xpdata_0[] = {
};

(you need a texture table, see How to create a sprite/texture table)

// init SGL with specifying the TEXTURE table
slInitSystem(TV_320x240, tex_SpriteTable, 1);

// and transfer sprite/texture bitmap data to VDP1 VRAM
// specify TEXTURE and PICTURE table and length of PICTURE table
set_sprite(pic_SpriteTable, 310, tex_SpriteTable);


// you need to specify NULL as TEXTURE table.
slInitSystem(TV_320x240, NULL, 1);

// init current matrix
slUnitMatrix(CURRENT);
   
// object transformation
slTranslate(pos[X], pos[Y], pos[Z]);
slScale(sca[X], sca[Y], sca[Z]);
slRotX(ang[X]);                                             
slRotY(ang[Y]);              
slRotZ(ang[Z]);

// display Saturn rings
slPutPolygon((PDATA *)&xpdata_SaturnRings);

// change frame
// essencial for all in SGL
slSynch();


// init current matrix
slPushUnitMatrix();
{  
}
slPopMatrix();

// change frame
// essencial for all in SGL
slSynch();

slPutPolygonS((PDATA *)&xpdata_SaturnRings);

// change frame
// essencial for all in SGL
slSynch();

ATTR    attribute_0[] = {

ATTRIBUTE(Single_Plane, SORT_CEN, 54, C_RGB(20,20,20), GRreal(0), CL32KRGB|MESHoff|CL_Gouraud,sprNoflip, UseGouraud),
...

};

// !!!!! VERY IMPORTANT
// don't take different gouraud table addresses
// in the .mdl files and here
#define    GRaddr    0x1c38 //0xe000

// SGL300PV.TXT: suppose it's maximum sized gouraud table in use
// but in the end, there seems to be only one gouraud table for all objects
#define GOUR_REAL_MAX   256    

// work area for realtime gouraud table computation
GOURAUDTBL       gourRealMax[GOUR_REAL_MAX];
Uint8            vwork[GOUR_REAL_MAX];

// the real time gouraud function is
// only documented in japanese language(only little in english)...
// instead of copying the global gouraud table to VRAM
// only once at startup
// slPutPolygonX() computes a new one
// for every XPDATA object every frame
// and copies the table to VRAM with slGouraudTblCopy()
// For this, a local temporary gouraud table is needed
// which is big enough to hold the biggest gouraud table in use
slInitGouraud(gourRealMax, GOUR_REAL_MAX, GRaddr, vwork);
slIntFunction(slGouraudTblCopy);

// light source variables
FIXED light[XYZ];
ANGLE light_ang[XYZ] = { DEGtoANG(0), DEGtoANG(0), DEGtoANG(0)};
ANGLE light_angAdd[XYZ] = { DEGtoANG(1.0), DEGtoANG(0.5), DEGtoANG(0)};

void draw()
{
}

// compute moving light direction vector
void computeLight()
{
}


mkisofs.exe -quiet -sysid "SEGA SATURN" -volid "SaturnApp" -volset "SaturnApp" -publisher "SEGA ENTERPRISES, LTD." -preparer "SEGA ENTERPRISES, LTD." -appid "SaturnApp" - abstract "ABS.TXT" -copyright "CPY.TXT" -biblio "BIB.TXT" -generic-boot IP.BIN -full-iso9660-filenames -o sl.iso cd

FILE "sl_coff.iso" BINARY
  TRACK 01 MODE1/2048
      INDEX 01 00:00:00
      POSTGAP 00:02:00
FILE "denied.mp3" MP3
  TRACK 02 AUDIO
    PREGAP 00:02:00
    INDEX 01 00:00:00
FILE "freeze.mp3" MP3
  TRACK 03 AUDIO
    INDEX 01 00:00:00
FILE "outback.mp3" MP3
  TRACK 04 AUDIO
    INDEX 01 00:00:00
FILE "scream.mp3" MP3
  TRACK 05 AUDIO
    INDEX 01 00:00:00

/* for initializing the CD-ROM when testing with PAR */
// taken from somewhere ???
#define SYS_CDINIT1(i) \

#define SYS_CDINIT2() \

int CdUnlock (void)
{
}