snes sprites functionality. More...

#include <snes/snestypes.h>

Data Structures
struct	t_metasprites
	Dynamic metasprite definition (16 bytes) More...

struct	t_sprites
	Dynamic sprite definition (16 bytes) More...

Macros
#define	OAM_ATTR(priority, hflip, vflip, gfxoffset, paletteoffset) ((vflip << 7) \| (hflip << 6) \| (priority << 4) \| (paletteoffset << 1) \| ((gfxoffset >> 8) & 1))
	defined attribute of a sprite More...

#define	oamGetX(id) (oamMemory[id + 0])
	get the x oam coordinate to the supplied values More...

#define	oamGetY(id) (oamMemory[id + 1])
	get the y oam coordinate to the supplied values More...

#define	OBJ_SIZE16_L32 (3 << 5)
	default OAM size 16x16 (SM) and 32x32 (LG) pix for OBJSEL register

#define	OBJ_SIZE16_L64 (4 << 5)
	default OAM size 16x16 (SM) and 64x64 (LG) pix for OBJSEL register

#define	OBJ_SIZE32_L64 (5 << 5)
	default OAM size 32x32 (SM) and 64x64 (LG) pix for OBJSEL register

#define	OBJ_SIZE8_L16 (0 << 5)
	default OAM size 8x8 (SM) and 16x16 (LG) pix for OBJSEL register

#define	OBJ_SIZE8_L32 (1 << 5)
	default OAM size 8x8 (SM) and 32x32 (LG) pix for OBJSEL register

#define	OBJ_SIZE8_L64 (2 << 5)
	default OAM size 8x8 (SM) and 64x64 (LG) pix for OBJSEL register

#define	OBJ_SPRITE16 2
	sprite with 16x16 identifier

#define	OBJ_SPRITE32 1
	sprite with 32x32 identifier

#define	OBJ_SPRITE8 4
	sprite with 8x8 identifier

#define	REG_OAMADDH ((vuint8 )0x2103)
	OAM Address and Priority Rotation (W) 15 OAM Priority Rotation (0=OBJ num 0, 1=OBJ num N) (OBJ with highest priority) 9-14 Not used 7-1 OBJ Number num N (for OBJ Priority) ;bit7-1 are used for two purposes 8-0 OAM Address (for OAM read/write) ;. More...

#define	REG_OAMDATA ((vuint8 )0x2104)
	OAM Data Write (W)

#define	REG_OBSEL ((vuint8 )0x2101)
	Object Size and Object Base (W) 7-5 OBJ Size Selection (0-5, see below) (6-7=Reserved) Val Small Large 0 = 8x8 16x16 ;Caution: 1 = 8x8 32x32 ;In 224-lines mode, OBJs with 64-pixel height 2 = 8x8 64x64 ;may wrap from lower to upper screen border. 3 = 16x16 32x32 ;In 239-lines mode, the same problem applies 4 = 16x16 64x64 ;also for OBJs with 32-pixel height. 5 = 32x32 64x64 6 = 16x32 32x64 (undocumented) 7 = 16x32 32x32 (undocumented) (Ie. a setting of 0 means Small OBJs=8x8, Large OBJs=16x16 pixels) (Whether an OBJ is "small" or "large" is selected by a bit in OAM) 4-3 Gap between OBJ 0FFh and 100h (0=None) (4K-word steps) (8K-byte steps) 2-0 Base Address for OBJ Tiles 000h..0FFh (8K-word steps) (16K-byte steps)

#define	REG_RDOAM ((vuint8 )0x2138)
	OAM Data Read (R)

Functions
void	oamClear (u16 first, u8 numEntries)
	Hides the sprites in the supplied range: if count is zero all 128 sprites will be hidden. More...

void	oamDynamic16Draw (u16 id)
	Add a 16x16 sprite on screen. oambuffer[id] needs to be populate before. More...

void	oamDynamic32Draw (u16 id)
	Add a 32x32 sprite on screen. oambuffer[id] needs to be populate before. More...

void	oamDynamic8Draw (u16 id)
	Add a 8x8 sprite on screen. oambuffer[id] needs to be populate before. More...

void	oamDynamicMetaDraw (u16 id, s16 x, s16 y, u8 *sprmeta)
	Add a Meta sprite on screen (can be composed of 8x8,16x16 or 32x32 sprites). oambuffer[id] needs to be populate before. More...

void	oamFix16Draw (u16 id)
	Add a 16x16 sprite on screen. oambuffer[id] needs to be populate before. ! More...

void	oamFix32Draw (u16 id)
	Add a 32x32 sprite on screen. oambuffer[id] needs to be populate before. ! More...

void	oamFix8Draw (u16 id)
	Add a 8x8 sprite on screen. oambuffer[id] needs to be populate before. ! More...

void	oamFlip (u16 id, u8 xf, u8 yf)
	sets an oam entry to the supplied values More...

void	oamInit (void)
	Initializes the 2D sprite engine.

void	oamInitDynamicSprite (u16 gfxsp0adr, u16 gfxsp1adr, u16 oamsp0init, u16 oamsp1init, u8 oamsize)
	initialize the dynamic sprite engine with each sprite size entries More...

void	oamInitDynamicSpriteEndFrame (void)
	Must be call at the end of the frame, initialize the dynamic sprite engine for the next frame.

void	oamInitDynamicSpriteScreen (void)
	Init Dynamic sprite engine on a screen (can be useful if you do not want to refresh sprite each frame).

void	oamInitGfxAttr (u16 address, u8 oamsize)
	Initializes the default sprite size and address in VRAM. More...

void	oamInitGfxSet (u8 tileSource, u16 tileSize, u8 tilePalette, u16 paletteSize, u8 tilePaletteNumber, u16 address, u8 oamsize)
	Initializes a sprites Gfx and Loads the GFX into VRAM. More...

void	oamSet (u16 id, u16 xspr, u16 yspr, u8 priority, u8 hflip, u8 vflip, u16 gfxoffset, u8 paletteoffset)
	sets an oam entry to the supplied values More...

void	oamSetAttr (u16 id, u16 xspr, u16 yspr, u16 gfxoffset, u8 attr)
	sets an oam entry to the supplied values More...

void	oamSetEx (u16 id, u8 size, u8 hide)
	Put the correct size and hide or show a sprite. More...

void	oamSetGfxOffset (u16 id, u16 gfxoffset)
	sets an oam graphic offset to the supplied values More...

void	oamSetVisible (u16 id, u8 hide)
	Hide or show a sprite. More...

void	oamSetXY (u16 id, u16 xspr, u16 yspr)
	sets an oam coordinate to the supplied values More...

void	oamUpdate (void)
	Write all OBJ descriptors to OAM.

void	oamVramQueueUpdate (void)
	Update VRAM graphics for sprites 32x32, 16x16 and 8x8 (can but call in Vblank if needed).

Variables
t_sprites	oambuffer [128]
	Sprite Table (from no$sns help file) Contains data for 128 OBJs. OAM Size is 512+32 Bytes. The first part (512 bytes) contains 128 4-byte entries for each OBJ: Byte 0 - X-Coordinate (lower 8bit) (upper 1bit at end of OAM) Byte 1 - Y-Coordinate (all 8bits) Byte 2 - Tile Number (lower 8bit) (upper 1bit within Attributes) Byte 3 - Attributes Attributes: Bit7 Y-Flip (0=Normal, 1=Mirror Vertically) Bit6 X-Flip (0=Normal, 1=Mirror Horizontally) Bit5-4 Priority relative to BG (0=Low..3=High) Bit3-1 Palette Number (0-7) (OBJ Palette 4-7 can use Color Math via CGADSUB) Bit0 Tile Number (upper 1bit) After above 512 bytes, additional 32 bytes follow, containing 2-bits per OBJ: Bit7 OBJ 3 OBJ Size (0=Small, 1=Large) Bit6 OBJ 3 X-Coordinate (upper 1bit) Bit5 OBJ 2 OBJ Size (0=Small, 1=Large) Bit4 OBJ 2 X-Coordinate (upper 1bit) Bit3 OBJ 1 OBJ Size (0=Small, 1=Large) Bit2 OBJ 1 X-Coordinate (upper 1bit) Bit1 OBJ 0 OBJ Size (0=Small, 1=Large) Bit0 OBJ 0 X-Coordinate (upper 1bit) And so on, next 31 bytes with bits for OBJ4..127. Note: The meaning of the OBJ Size bit (Small/Large) can be defined in OBSEL Register (Port 2101h). More...

u8	oamMemory [128 4+8 4]
	to address oam table low and high

Detailed Description

snes sprites functionality.

Macro Definition Documentation

◆ OAM_ATTR

#define OAM_ATTR	(	priority,
		hflip,
		vflip,
		gfxoffset,
		paletteoffset
	)	((vflip << 7) \| (hflip << 6) \| (priority << 4) \| (paletteoffset << 1) \| ((gfxoffset >> 8) & 1))

defined attribute of a sprite

Parameters

priority	The sprite priority (0 to 3)
vflip	flip the sprite vertically
hflip	flip the sprite horizontally
gfxoffset	tilenumber graphic offset
paletteoffset	palette default offset for sprite

◆ oamGetX

#define oamGetX ( id ) (oamMemory[id + 0])

get the x oam coordinate to the supplied values

Parameters

id	the oam number to be set [0 - 127] * 4 because of oam structure

Examples: input/superscope/superscope.c.

◆ oamGetY

#define oamGetY ( id ) (oamMemory[id + 1])

get the y oam coordinate to the supplied values

Parameters

id	the oam number to be set [0 - 127] * 4 because of oam structure

Examples: input/superscope/superscope.c.

◆ REG_OAMADDH

#define REG_OAMADDH (*(vuint8 *)0x2103)

OAM Address and Priority Rotation (W) 15 OAM Priority Rotation (0=OBJ num 0, 1=OBJ num N) (OBJ with highest priority) 9-14 Not used 7-1 OBJ Number num N (for OBJ Priority) ;bit7-1 are used for two purposes 8-0 OAM Address (for OAM read/write) ;.

This register contains of a 9bit Reload value and a 10bit Address register (plus the priority flag). Writing to 2102h or 2103h does change the lower 8bit or upper 1bit of the Reload value, and does additionally copy the (whole) 9bit Reload value to the 10bit Address register (with address Bit0=0 so next access will be an even address). Caution: During rendering, the PPU is destroying the Address register (using it internally for whatever purposes), after rendering (at begin of Vblank, ie. at begin of line 225/240, but only if not in Forced Blank mode) it reinitializes the Address from the Reload value; the same reload occurs also when deactivating forced blank anytime during the first scanline of vblank (ie. during line 225/240).

Function Documentation

◆ oamClear()

void oamClear	(	u16	first,
		u8	numEntries
	)

Hides the sprites in the supplied range: if count is zero all 128 sprites will be hidden.

Parameters

first	number of 1st sprite to write * 4 because of oam structure
numEntries	total number of sprites to write

◆ oamDynamic16Draw()

void oamDynamic16Draw ( u16 id )

Add a 16x16 sprite on screen.
oambuffer[id] needs to be populate before.

Parameters

id	the oam number to be used [0 - 127]

Examples: games/likemario/LikeMario.c, and graphics/Sprites/DynamicEngineSprite/DynamicEngineSprite.c.

◆ oamDynamic32Draw()

void oamDynamic32Draw ( u16 id )

Add a 32x32 sprite on screen.
oambuffer[id] needs to be populate before.

Parameters

id	the oam number to be used [0 - 127]

Examples: graphics/Sprites/DynamicEngineSprite/DynamicEngineSprite.c.

◆ oamDynamic8Draw()

void oamDynamic8Draw ( u16 id )

Add a 8x8 sprite on screen.
oambuffer[id] needs to be populate before.

Parameters

id	the oam number to be used [0 - 127]

◆ oamDynamicMetaDraw()

void oamDynamicMetaDraw	(	u16	id,
		s16	x,
		s16	y,
		u8 *	sprmeta
	)

Add a Meta sprite on screen (can be composed of 8x8,16x16 or 32x32 sprites).
oambuffer[id] needs to be populate before.

Parameters

id	the oam number to be used [0 - 127].
x	x coordinate of the metasprite
y	y coordinate of the metasprite
sprmeta	pointer to metasprite structure (must finish with 0xFFFF, see t_metasprites)

the meta structure is composed of:
x offset,y offset,gfx offset, attribute, size (8,16,32),gfxfile
the function will reserve the number of sprites in oambuffer, beginning with id.

Examples: graphics/Sprites/DynamicEngineMetaSprite/DynamicEngineMetaSprite.c.

◆ oamFix16Draw()

void oamFix16Draw ( u16 id )

Add a 16x16 sprite on screen.
oambuffer[id] needs to be populate before. !

Sprite is never refresh (VRAM must be update before) ! oamframeid is the VRAM entry number for sprite (eg.4 for VRAM offset 0x0040, 15 for 0x0CC...) ! WARNING: as the sprite engine begin at VRAM address 0x0000, you need to take care of High bit ! if you want to use a VRAM entry number more than 0x00FF

Parameters

id	the oam number to be used [0 - 127]

◆ oamFix32Draw()

void oamFix32Draw ( u16 id )

Add a 32x32 sprite on screen.
oambuffer[id] needs to be populate before. !

Sprite is never refresh (VRAM must be update before) ! oamframeid is the VRAM entry number for sprite (eg.4 for VRAM offset 0x0040, 15 for 0x0CC...) ! WARNING: as the sprite engine begin at VRAM address 0x0000, you need to take care of High bit ! if you want to use a VRAM entry number more than 0x00FF

Parameters

id	the oam number to be used [0 - 127]

◆ oamFix8Draw()

void oamFix8Draw ( u16 id )

Add a 8x8 sprite on screen.
oambuffer[id] needs to be populate before. !

Sprite is never refresh (VRAM must be update before) ! oamframeid is the VRAM entry number for sprite (eg.4 for VRAM offset 0x0040, 15 for 0x0CC...) ! WARNING: as the sprite engine begin at VRAM address 0x0000, you need to take care of High bit ! if you want to use a VRAM entry number more than 0x00FF

Parameters

id	the oam number to be used [0 - 127]

◆ oamFlip()

void oamFlip	(	u16	id,
		u8	xf,
		u8	yf
	)

sets an oam entry to the supplied values

Parameters

id	the oam number to be set [0 - 127] * 4 because of oam structure
xf	x flipping [0 - 1]
yf	y flipping [0 - 1]

◆ oamInitDynamicSprite()

void oamInitDynamicSprite	(	u16	gfxsp0adr,
		u16	gfxsp1adr,
		u16	oamsp0init,
		u16	oamsp1init,
		u8	oamsize
	)

initialize the dynamic sprite engine with each sprite size entries

Parameters

gfxsp0adr	address of large sprite graphics entry
gfxsp1adr	address of small sprite graphics entry
oamsp0init	address of large sprite number (useful when we have some hud sprites which are not update each frame)
oamsp1init	address of small sprite number (useful when we have some hud sprites which are not update each frame)
oamsize	default OAM size : OBJ_SIZE8_L16, OBJ_SIZE8_L32, OBJ_SIZE16_L32 (64pix size is not supported)

Examples: games/likemario/LikeMario.c, graphics/Sprites/DynamicEngineMetaSprite/DynamicEngineMetaSprite.c, graphics/Sprites/DynamicEngineSprite/DynamicEngineSprite.c, objects/mapandobjects/mapandobjects.c, and objects/nogravityobject/nogravityobjects.c.

◆ oamInitGfxAttr()

void oamInitGfxAttr	(	u16	address,
		u8	oamsize
	)

Initializes the default sprite size and address in VRAM.

Parameters

address	address of sprite graphics (8K-word steps)
oamsize	default OAM size (OBJ_SIZE8_L16, OBJ_SIZE8_L32, OBJ_SIZE8_L64, OBJ_SIZE16_L32, OBJ_SIZE16_L64 and OBJ_SIZE32_L64)

Examples: input/superscope/superscope.c.

◆ oamInitGfxSet()

void oamInitGfxSet	(	u8 *	tileSource,
		u16	tileSize,
		u8 *	tilePalette,
		u16	paletteSize,
		u8	tilePaletteNumber,
		u16	address,
		u8	oamsize
	)

Initializes a sprites Gfx and Loads the GFX into VRAM.

Parameters

tileSource	address of sprites graphics entry
tileSize	size of sprites graphics
tilePalette	address of sprites palette entry
paletteSize	size of palette
tilePaletteNumber	palette number (0..8)
address	address of sprite graphics (8K-word steps)
oamsize	default OAM size (OBJ_SIZE8_L16, OBJ_SIZE8_L32, OBJ_SIZE8_L64, OBJ_SIZE16_L32, OBJ_SIZE16_L64 and OBJ_SIZE32_L64)

Examples: graphics/Backgrounds/Mode1ContinuosScroll/Mode1ContinuosScroll.c, graphics/Sprites/AnimatedSprite/AnimatedSprite.c, graphics/Sprites/DynamicSprite/DynamicSprite.c, graphics/Sprites/ObjectSize/ObjectSize.c, graphics/Sprites/SimpleSprite/SimpleSprite.c, input/mouse/mouse.c, input/superscope/superscope.c, maps/mapscroll/mapscroll.c, and objects/moveobjects/moveobjects.c.

◆ oamSet()

void oamSet	(	u16	id,
		u16	xspr,
		u16	yspr,
		u8	priority,
		u8	hflip,
		u8	vflip,
		u16	gfxoffset,
		u8	paletteoffset
	)

sets an oam entry to the supplied values

Parameters

id	the oam number to be set [0 - 127] * 4 because of oam structure
xspr	the x location of the sprite in pixels
yspr	the y location of the sprite in pixels
priority	The sprite priority (0 to 3)
vflip	flip the sprite vertically
hflip	flip the sprite horizontally
gfxoffset	tilenumber graphic offset
paletteoffset	palette default offset for sprite

Examples: games/breakout/breakout.c, graphics/Backgrounds/Mode1ContinuosScroll/Mode1ContinuosScroll.c, graphics/Sprites/AnimatedSprite/AnimatedSprite.c, graphics/Sprites/DynamicSprite/DynamicSprite.c, graphics/Sprites/ObjectSize/ObjectSize.c, graphics/Sprites/SimpleSprite/SimpleSprite.c, input/mouse/mouse.c, input/superscope/superscope.c, maps/mapscroll/mapscroll.c, and objects/moveobjects/moveobjects.c.

◆ oamSetAttr()

void oamSetAttr	(	u16	id,
		u16	xspr,
		u16	yspr,
		u16	gfxoffset,
		u8	attr
	)

sets an oam entry to the supplied values

Parameters

id	the oam number to be set [0 - 127] * 4 because of oam structure
xspr	the x location of the sprite in pixels
yspr	the y location of the sprite in pixels
gfxoffset	tilenumber graphic offset
attr	(attributes with priority, flipping, palette)

◆ oamSetEx()

void oamSetEx	(	u16	id,
		u8	size,
		u8	hide
	)

Put the correct size and hide or show a sprite.

Parameters

id	the oam number to be set [0 - 127] * 4 because of oam structure
size	normal or large (OBJ_SMALL or OBJ_LARGE)
hide	1 (OBJ_HIDE) to to hide the sprite, 0 (OBJ_SHOW) to see it

Examples: games/breakout/breakout.c, graphics/Backgrounds/Mode1ContinuosScroll/Mode1ContinuosScroll.c, graphics/Sprites/AnimatedSprite/AnimatedSprite.c, graphics/Sprites/DynamicSprite/DynamicSprite.c, graphics/Sprites/ObjectSize/ObjectSize.c, graphics/Sprites/SimpleSprite/SimpleSprite.c, input/superscope/superscope.c, maps/mapscroll/mapscroll.c, and objects/moveobjects/moveobjects.c.

◆ oamSetGfxOffset()

void oamSetGfxOffset	(	u16	id,
		u16	gfxoffset
	)

sets an oam graphic offset to the supplied values

Parameters

id	the oam number to be set [0 - 127] * 4 because of oam structure
gfxoffset	tilenumber graphic offset

Examples: input/superscope/superscope.c.

◆ oamSetVisible()

void oamSetVisible	(	u16	id,
		u8	hide
	)

Hide or show a sprite.

Parameters

id	the oam number to be set [0 - 127] * 4 because of oam structure
hide	1 (OBJ_HIDE) to to hide the sprite, 0 (OBJ_SHOW) to see it

Warning: When OBJ_HIDE is used, the sprite is set at these coordinates: x = 255, y 240. Therefore when a sprite is hidden and it is needed to show it again (use OBJ_SHOW), it is necessary to reset the sprite coordinates with oamSetXY(). If the sprite needs to be hidden and keep its coordinates, please use oamSetGfxOffset instead by passing a transparent tile.

Examples: graphics/Backgrounds/Mode1ContinuosScroll/Mode1ContinuosScroll.c, graphics/Sprites/AnimatedSprite/AnimatedSprite.c, input/mouse/mouse.c, input/superscope/superscope.c, and maps/mapscroll/mapscroll.c.

◆ oamSetXY()

void oamSetXY	(	u16	id,
		u16	xspr,
		u16	yspr
	)

sets an oam coordinate to the supplied values

Parameters

id	the oam number to be set [0 - 127] * 4 because of oam structure
xspr	the x location of the sprite in pixels
yspr	the y location of the sprite in pixels

Examples: graphics/Backgrounds/Mode1ContinuosScroll/Mode1ContinuosScroll.c, and input/superscope/superscope.c.

Variable Documentation

◆ oambuffer

t_sprites oambuffer[128]

extern

Sprite Table (from no$sns help file)
Contains data for 128 OBJs. OAM Size is 512+32 Bytes. The first part (512
bytes) contains 128 4-byte entries for each OBJ:
Byte 0 - X-Coordinate (lower 8bit) (upper 1bit at end of OAM)
Byte 1 - Y-Coordinate (all 8bits)
Byte 2 - Tile Number (lower 8bit) (upper 1bit within Attributes)
Byte 3 - Attributes
Attributes:
Bit7 Y-Flip (0=Normal, 1=Mirror Vertically)
Bit6 X-Flip (0=Normal, 1=Mirror Horizontally)
Bit5-4 Priority relative to BG (0=Low..3=High)
Bit3-1 Palette Number (0-7) (OBJ Palette 4-7 can use Color Math via CGADSUB)
Bit0 Tile Number (upper 1bit)
After above 512 bytes, additional 32 bytes follow, containing 2-bits per OBJ:
Bit7 OBJ 3 OBJ Size (0=Small, 1=Large)
Bit6 OBJ 3 X-Coordinate (upper 1bit)
Bit5 OBJ 2 OBJ Size (0=Small, 1=Large)
Bit4 OBJ 2 X-Coordinate (upper 1bit)
Bit3 OBJ 1 OBJ Size (0=Small, 1=Large)
Bit2 OBJ 1 X-Coordinate (upper 1bit)
Bit1 OBJ 0 OBJ Size (0=Small, 1=Large)
Bit0 OBJ 0 X-Coordinate (upper 1bit)
And so on, next 31 bytes with bits for OBJ4..127. Note: The meaning of the OBJ
Size bit (Small/Large) can be defined in OBSEL Register (Port 2101h).

current sprite buffer for dynamic engine

Examples: games/likemario/LikeMario.c, graphics/Sprites/DynamicEngineMetaSprite/DynamicEngineMetaSprite.c, and graphics/Sprites/DynamicEngineSprite/DynamicEngineSprite.c.

Data Structures

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ OAM_ATTR

◆ oamGetX

◆ oamGetY

◆ REG_OAMADDH

Function Documentation

◆ oamClear()

◆ oamDynamic16Draw()

◆ oamDynamic32Draw()

◆ oamDynamic8Draw()

◆ oamDynamicMetaDraw()

◆ oamFix16Draw()

◆ oamFix32Draw()

◆ oamFix8Draw()

◆ oamFlip()

◆ oamInitDynamicSprite()

◆ oamInitGfxAttr()

◆ oamInitGfxSet()

◆ oamSet()

◆ oamSetAttr()

◆ oamSetEx()

◆ oamSetGfxOffset()

◆ oamSetVisible()

◆ oamSetXY()

Variable Documentation

◆ oambuffer