Software bitmap engine. More...

#include "maths.h"
#include "vdp.h"
#include "pal.h"

Classes
struct	Bitmap
	Genesis 4bpp Bitmap structure definition. Use the unpackBitmap() method to unpack if compression is enabled. More...
struct	Pixel
	Pixel definition. More...
struct	Line
	Line definition. More...
struct	Triangle
	Triangle definition. More...
Defines
#define	BMP_PLANWIDTH_SFT planeWidthSft
#define	BMP_PLANHEIGHT_SFT planeHeightSft
#define	BMP_PLANWIDTH 64
	Bitmap plane width (in tile)
#define	BMP_PLANHEIGHT 64
	Bitmap plane height (in tile)
#define	BMP_CELLWIDTH_SFT 5
#define	BMP_CELLWIDTH (1 << BMP_CELLWIDTH_SFT)
	Bitmap width (in tile): 32.
#define	BMP_CELLHEIGHT 20
	Bitmap height (in tile): 20.
#define	BMP_CELLWIDTHMASK (BMP_CELLWIDTH - 1)
#define	BMP_CELLXOFFSET (((screenWidth >> 3) - BMP_CELLWIDTH) / 2)
#define	BMP_CELLYOFFSET (((screenHeight >> 3) - BMP_CELLHEIGHT) / 2)
#define	BMP_XPIXPERTILE_SFT 3
#define	BMP_YPIXPERTILE_SFT 3
#define	BMP_XPIXPERTILE (1 << BMP_XPIXPERTILE_SFT)
	Number of X pixel per tile: 8 pixels per tile.
#define	BMP_YPIXPERTILE (1 << BMP_YPIXPERTILE_SFT)
	Number of y pixel per tile: 8 pixels per tile.
#define	BMP_XPIXPERTILEMASK (BMP_XPIXPERTILE - 1)
#define	BMP_YPIXPERTILEMASK (BMP_YPIXPERTILE - 1)
#define	BMP_WIDTH_SFT (BMP_CELLWIDTH_SFT + BMP_XPIXPERTILE_SFT)
#define	BMP_WIDTH (1 << BMP_WIDTH_SFT)
	Bitmap width (in pixel): 256.
#define	BMP_HEIGHT (BMP_CELLHEIGHT * BMP_YPIXPERTILE)
	Bitmap height (in pixel): 160.
#define	BMP_WIDTH_MASK (BMP_WIDTH - 1)
#define	BMP_PITCH_SFT (BMP_CELLWIDTH_SFT + 2)
#define	BMP_PITCH (1 << BMP_PITCH_SFT)
	Bitmap scanline pitch (number of byte per scanline): 128.
#define	BMP_PITCH_MASK (BMP_PITCH - 1)
#define	BMP_GENBMP16_WIDTH(genbmp16) ((genbmp16)[0])
	Get width of genesis bitmap 16 object.
#define	BMP_GENBMP16_HEIGHT(genbmp16) ((genbmp16)[1])
	Get height of genesis bitmap 16 object.
#define	BMP_GENBMP16_PALETTE(genbmp16) (&((genbmp16)[2]))
	Return pointer to palette of genesis bitmap 16 object.
#define	BMP_GENBMP16_IMAGE(genbmp16) (&((genbmp16)[18]))
	Return pointer to image data of genesis bitmap 16 object.
#define	BMP_GETPIXEL(x, y) BMP_getPixelFast(x, y)
#define	BMP_SETPIXEL(x, y, col) BMP_setPixelFast(x, y, col)
#define	BMP_BASETILEINDEX TILE_USERINDEX
#define	BMP_FB0TILEINDEX BMP_BASETILEINDEX
#define	BMP_FB1TILEINDEX (BMP_BASETILEINDEX + (BMP_CELLWIDTH * BMP_CELLHEIGHT))
#define	BMP_FB0ENDTILEINDEX (BMP_FB0TILEINDEX + (BMP_CELLWIDTH * BMP_CELLHEIGHT))
#define	BMP_FB1ENDTILEINDEX (BMP_FB1TILEINDEX + (BMP_CELLWIDTH * BMP_CELLHEIGHT))
#define	BMP_BASETILE (BMP_BASETILEINDEX * 32)
#define	BMP_FB0TILE (BMP_FB0TILEINDEX * 32)
#define	BMP_FB1TILE (BMP_FB1TILEINDEX * 32)
Functions
void	BMP_init (u16 double_buffer, VDPPlane plane, u16 palette, u16 priority)
	Initialize the software bitmap engine.
void	BMP_end ()
	End the software bitmap engine.
void	BMP_reset ()
	Reset the software bitmap engine.
void	BMP_setBufferCopy (u16 value)
	Enable back buffer preservation.
u16	BMP_flip (u16 async)
	Flip bitmap buffer to screen.
void	BMP_clear ()
	Clear bitmap buffer.
u8 *	BMP_getWritePointer (u16 x, u16 y)
	Get write pointer for specified pixel.
u8 *	BMP_getReadPointer (u16 x, u16 y)
	Get read pointer for specified pixel.
u16	BMP_hasFlipRequestPending ()
	Return true (!= 0) if a flip request is pending.
void	BMP_waitWhileFlipRequestPending ()
	Wait until no more flip request is pending.
u16	BMP_hasFlipInProgess ()
	Return true (!= 0) if a flip operation is in progress.
void	BMP_waitFlipComplete ()
	Wait until the asynchronous flip operation is completed. Blit operation is the bitmap buffer transfer to VRAM.
void	BMP_drawText (const char *str, u16 x, u16 y)
	Draw text in bitmap mode.
void	BMP_clearText (u16 x, u16 y, u16 w)
	Clear text in bitmap mode.
void	BMP_clearTextLine (u16 y)
	Clear a line of text in bitmap mode.
void	BMP_showFPS (u16 float_display)
	Show the frame rate in bitmap mode.
u8	BMP_getPixel (u16 x, u16 y)
	Get pixel at specified position (safe version with bounds verification)
u8	BMP_getPixelFast (u16 x, u16 y)
	Get pixel at specified position (fast version without bounds verification)
void	BMP_setPixel (u16 x, u16 y, u8 col)
	Set pixel at specified position (safe version with bounds verification)
void	BMP_setPixelFast (u16 x, u16 y, u8 col)
	Set pixel at specified position (fast version without bounds verification)
void	BMP_setPixels_V2D (const Vect2D_u16 *crd, u8 col, u16 num)
	Set pixels from Vect2D array (safe version with bounds verification)
void	BMP_setPixelsFast_V2D (const Vect2D_u16 *crd, u8 col, u16 num)
	Set pixels from Vect2D array (fast version without bounds verification)
void	BMP_setPixels (const Pixel *pixels, u16 num)
	Set pixels from Pixel array (safe version with bounds verification)
void	BMP_setPixelsFast (const Pixel *pixels, u16 num)
	Set pixels from Pixel array (fast version without bounds verification)
u16	BMP_clipLine (Line *l)
	Clip the specified line so it fit in bitmap screen (0, 0, BMP_WIDTH, BMP_HEIGHT)
void	BMP_drawLine (Line *l)
	Draw a line (no bounds verification). You can use BMP_clipLine(..) first to clip the line to view range if needed.
u16	BMP_isPolygonCulled (const Vect2D_s16 *pts, u16 num)
	Determine if the specified polygon is culled. The polygon points should be defined in clockwise order. The method returns 1 if the polygon is back faced and should be eliminated for 3D rendering.
u16	BMP_drawPolygon (const Vect2D_s16 *pts, u16 num, u8 col)
	Draw a polygon. The polygon points should be defined in clockwise order. Use the BMP_isPolygonCulled(..) method to test if polygon should be draw or not.
void	BMP_drawBitmapData (const u8 *data, u16 x, u16 y, u16 w, u16 h, u32 pitch)
	Draw the specified 4BPP bitmap data.
u16	BMP_drawBitmap (const Bitmap *bitmap, u16 x, u16 y, u16 loadpal)
	Draw a Genesis Bitmap.
u16	BMP_drawBitmapScaled (const Bitmap *bitmap, u16 x, u16 y, u16 w, u16 h, u16 loadpal)
	Load and draw a Genesis Bitmap with specified dimension.
void	BMP_loadBitmapData (const u8 *data, u16 x, u16 y, u16 w, u16 h, u32 pitch)
void	BMP_loadBitmap (const Bitmap *bitmap, u16 x, u16 y, u16 loadpal)
void	BMP_loadAndScaleBitmap (const Bitmap *bitmap, u16 x, u16 y, u16 w, u16 h, u16 loadpal)
void	BMP_getBitmapPalette (const Bitmap bitmap, u16 pal)
void	BMP_scale (const u8 src_buf, u16 src_wb, u16 src_h, u16 src_pitch, u8 dst_buf, u16 dst_wb, u16 dst_h, u16 dst_pitch)
	Scale the specified source bitmap image to specified dimension.
Variables
u8 *	bmp_buffer_read
u8 *	bmp_buffer_write

Detailed Description

Software bitmap engine.

Author:: Stephane Dallongeville

Date:: 08/2011

This unit provides methods to simulate bitmap mode on SEGA genesis.

The software bitmap engine permit to simulate a 256x160 pixels bitmap screen.
Bitmap engine requires a large amount of memory (~41KB) which is dynamically allocated at BMP_init(..) time and released when BMP_end() is called.
Bitmap engine uses a double buffer so you can draw to the write buffer while the read buffer is being sent to video memory.
These buffers are transferred to VRAM during blank area, by default on NTSC system the blanking period is really short so it takes approximately 10 frames to blit an entire buffer.
To improve transfer performance the blank area is extended to fit bitmap resolution:
scanline 0-31 = blank
scanline 32-191 = active
scanline 192-262/312 = blank

With extended blank bitmap buffer can be transferred to VRAM 20 times per second in NTSC
and 25 time per second in PAL.

Define Documentation

#define BMP_GETPIXEL	(	x,
		y
	)	BMP_getPixelFast(x, y)

Deprecated:: Use BMP_getPixelFast(..) instead (inlining make macro useless)

#define BMP_SETPIXEL	(	x,
		y,
		col
	)	BMP_setPixelFast(x, y, col)

Deprecated:: Use BMP_setPixelFast(..) instead (inlining make macro useless)

Function Documentation

void BMP_clearText	(	u16	x,
		u16	y,
		u16	w
	)

Clear text in bitmap mode.

Parameters:

x	X coordinate (in tile).
y	y coordinate (in tile).
w	Number of characters to clear.

void BMP_clearTextLine ( u16 y )

Clear a line of text in bitmap mode.

Parameters:

y	y coordinate (in tile).

u16 BMP_clipLine ( Line * l )

Clip the specified line so it fit in bitmap screen (0, 0, BMP_WIDTH, BMP_HEIGHT)

Parameters:

l	Line to clip.

Returns:: FALSE (0) is the line is entirely outside bitmap screen (no clip is done).
TRUE if at least one pixel is on screen (line is clipped if needed).

u16 BMP_drawBitmap	(	const Bitmap *	bitmap,
		u16	x,
		u16	y,
		u16	loadpal
	)

Draw a Genesis Bitmap.

A Genesis bitmap is automatically created from .bmp or .png file via the rescomp tool.
The resulting file contains bitmap size info and 16 colors palette.

Parameters:

bitmap	Genesis Bitmap. The Bitmap is unpacked "on the fly" if needed (require some memory).
x	X coordinate (should be an even value).
y	y coordinate.
loadpal	Load the bitmap palette information when non zero.

Returns:: FALSE if there is not enough memory to unpack the specified Bitmap (only if compression was enabled).

X coordinate is aligned to even value for performance reason.
So BMP_drawBitmap(bitmap,0,0,TRUE) will produce same result as BMP_drawBitmap(bitmap,1,0,TRUE)

void BMP_drawBitmapData	(	const u8 *	data,
		u16	x,
		u16	y,
		u16	w,
		u16	h,
		u32	pitch
	)

Draw the specified 4BPP bitmap data.

Parameters:

data	4BPP image data buffer.
x	X coordinate (should be an even value for byte alignment).
y	y coordinate.
w	width (should be an even value for byte alignment).
h	height.
pitch	bitmap pitch (number of bytes per bitmap scanline).

X coordinate as Width are aligned to even value for performance reason.
So BMP_drawBitmapData(data,0,0,w,h,w) will produce same result as BMP_drawBitmapData(data,1,0,w,h,w)

u16 BMP_drawBitmapScaled	(	const Bitmap *	bitmap,
		u16	x,
		u16	y,
		u16	w,
		u16	h,
		u16	loadpal
	)

Load and draw a Genesis Bitmap with specified dimension.

A Genesis bitmap is automatically created from .bmp or .png file via the rescomp tool.
The resulting file contains bitmap size info and 16 colors palette.
This method will scale and draw the bitmap with the specified dimension.

Parameters:

bitmap	Genesis bitmap. The Bitmap is unpacked "on the fly" if needed (require some memory).
x	X coordinate (should be an even value).
y	y coordinate.
w	final width.
h	final height.
loadpal	Load the bitmap palette information when non zero.

Returns:: FALSE if there is not enough memory to unpack the specified Bitmap (only if compression was enabled).

X coordinate as width are aligned to even values for performance reason.
So BMP_drawBitmapScaled(bitmap,0,0,w,h,pal) will produce same result as BMP_drawBitmapScaled(bitmap,1,0,w,h,pal)

void BMP_drawLine ( Line * l )

Draw a line (no bounds verification). You can use BMP_clipLine(..) first to clip the line to view range if needed.

Parameters:

l	Line to draw.

u16 BMP_drawPolygon	(	const Vect2D_s16 *	pts,
		u16	num,
		u8	col
	)

Draw a polygon.
The polygon points should be defined in clockwise order.
Use the BMP_isPolygonCulled(..) method to test if polygon should be draw or not.

Parameters:

pts	Polygon points buffer.
num	number of point (length of points buffer).
col	fill color.

Returns:: 0 if polygon was not drawn (outside screen or whatever).

void BMP_drawText	(	const char *	str,
		u16	x,
		u16	y
	)

Draw text in bitmap mode.

Parameters:

str	String to display.
x	X coordinate (in tile).
y	y coordinate (in tile).

void BMP_end ( )

End the software bitmap engine.

Release memory used by software bitmap engine (~41 KB).

u16 BMP_flip ( u16 async )

Flip bitmap buffer to screen.

Blit the current bitmap back buffer to the screen then flip buffers so back buffer becomes front buffer and vice versa.
If you use async flag the Bitmap buffer will be sent to video memory asynchronously during blank period and the function return immediatly.
If a flip is already in process then flip request is marked as pending and will be processed as soon the current one complete.
You can use BMP_waitWhileFlipRequestPending() method to ensure no more flip request are pending before writing to bitmap buffer.
If a flip request is already pending the function wait until no more request are pending.

Parameters:

async Asynchronous flip operation flag.

Returns:: Only meaningful for async operation:
0 if the flip request has be marked as pending as another flip is already in process.
1 if the flip request has be initiated.

See also:: BMP_hasFlipRequestPending(); BMP_waitWhileFlipRequestPending()

void BMP_getBitmapPalette	(	const Bitmap *	bitmap,
		u16 *	pal
	)

Deprecated:: Uses bitmap->palette instead.

u8 BMP_getPixel	(	u16	x,
		u16	y
	)		`[inline]`

Get pixel at specified position (safe version with bounds verification)

Parameters:

x	X coordinate.
y	Y coordinate.

See also:: BMP_getPixelFast; BMP_setPixel

u8 BMP_getPixelFast	(	u16	x,
		u16	y
	)		`[inline]`

Get pixel at specified position (fast version without bounds verification)

Parameters:

x	X coordinate.
y	Y coordinate.

See also:: BMP_getPixel; BMP_setPixelFast

u8* BMP_getReadPointer	(	u16	x,
		u16	y
	)

Get read pointer for specified pixel.

Parameters:

x	X pixel coordinate.
y	Y pixel coordinate.

As coordinates are expressed for 4bpp pixel BMP_getReadPointer(0,0) and BMP_getReadPointer(1,0) actually returns the same address.

u8* BMP_getWritePointer	(	u16	x,
		u16	y
	)

Get write pointer for specified pixel.

Parameters:

x	X pixel coordinate.
y	Y pixel coordinate.

As coordinates are expressed for 4bpp pixel BMP_getWritePointer(0,0) and BMP_getWritePointer(1,0) actually returns the same address.

void BMP_init	(	u16	double_buffer,
		VDPPlane	plane,
		u16	palette,
		u16	priority
	)

Initialize the software bitmap engine.

Parameters:

double_buffer	Enabled VRAM double buffer. VRAM Double buffer permit to avoid image tearing because of partial screen refresh. It requires almost all VRAM tiles space (~41 KB) so enable it only if you don't need other plane or sprites.
plane	Plane to use to display the bitmap. Accepted values are: BG_A BG_B
palette	Palette index to use to render the bitmap plane. Set it to 0 if unsure.
priority	Set the priority of bitmap plane. 0 = low priority (default). 1 = high priority.

Requires ~41 KB of memory which is dynamically allocated.

u16 BMP_isPolygonCulled	(	const Vect2D_s16 *	pts,
		u16	num
	)

Determine if the specified polygon is culled.
The polygon points should be defined in clockwise order.
The method returns 1 if the polygon is back faced and should be eliminated for 3D rendering.

Parameters:

pts	Polygon points buffer.
num	number of point (length of points buffer).

Returns:: 1 if polygon is culled (should not be draw) and 0 otherwise.

void BMP_loadAndScaleBitmap	(	const Bitmap *	bitmap,
		u16	x,
		u16	y,
		u16	w,
		u16	h,
		u16	loadpal
	)

Deprecated:: Use BMP_drawBitmapEx(..) instead.

void BMP_loadBitmap	(	const Bitmap *	bitmap,
		u16	x,
		u16	y,
		u16	loadpal
	)

Deprecated:: Use BMP_drawBitmap(..) instead.

void BMP_loadBitmapData	(	const u8 *	data,
		u16	x,
		u16	y,
		u16	w,
		u16	h,
		u32	pitch
	)

Deprecated:: Use BMP_drawBitmapData(..) instead.

void BMP_reset ( )

Reset the software bitmap engine.

Rebuild tilemap for bitmap engine and clear buffers.

void BMP_scale	(	const u8 *	src_buf,
		u16	src_wb,
		u16	src_h,
		u16	src_pitch,
		u8 *	dst_buf,
		u16	dst_wb,
		u16	dst_h,
		u16	dst_pitch
	)

Scale the specified source bitmap image to specified dimension.

Take a source bitmap with its specified dimension and scale it in the
destination buffer with specified dimension.

Parameters:

src_buf	source bitmap buffer.
src_wb	source width in byte.
src_h	source height.
src_pitch	source pitch (number of bytes per scanline).
dst_buf	destination bitmap buffer.
dst_wb	destination width in byte.
dst_h	destination height.
dst_pitch	destination pitch (number of bytes per scanline).

void BMP_setBufferCopy ( u16 value )

Enable back buffer preservation.

The bitmap engine is always using double buffering in maim memory so you can continue to write your bitmap while the previous bitmap is being transferred to video memory.
The problem with double buffer is that your content is not preserved on a frame basis as you have 2 differents buffers, by enabling "buffer copy" you can preserve your bitmap but this has an important CPU cost as we need to copy bitmap buffer at each flip operation.
By default buffer copy is disabled for obvious performance reason.

void BMP_setPixel	(	u16	x,
		u16	y,
		u8	col
	)		`[inline]`

Set pixel at specified position (safe version with bounds verification)

Parameters:

x	X pixel coordinate.
y	Y pixel coordinate.
col	pixel color (should be 8 bits filled: 0x00, 0x11, .. for plain color)

See also:: BMP_setPixelFast; BMP_getPixel

void BMP_setPixelFast	(	u16	x,
		u16	y,
		u8	col
	)		`[inline]`

Set pixel at specified position (fast version without bounds verification)

Parameters:

x	X pixel coordinate.
y	Y pixel coordinate.
col	pixel color (should be 8 bits filled: 0x00, 0x11, .. for plain color)

See also:: BMP_setPixel; BMP_getPixelFast

void BMP_setPixels	(	const Pixel *	pixels,
		u16	num
	)

Set pixels from Pixel array (safe version with bounds verification)

Parameters:

pixels	Pixels buffer.
num	number of pixel to draw (length of pixels buffer).

void BMP_setPixels_V2D	(	const Vect2D_u16 *	crd,
		u8	col,
		u16	num
	)

Set pixels from Vect2D array (safe version with bounds verification)

Parameters:

crd	Vect2D_u16 Coordinates buffer.
col	pixels color (should be 8 bits filled: 0x00, 0x11, .. for plain color)
num	number of pixel to draw (length of coordinates buffer).

void BMP_setPixelsFast	(	const Pixel *	pixels,
		u16	num
	)

Set pixels from Pixel array (fast version without bounds verification)

Parameters:

pixels	Pixels buffer.
num	number of pixel to draw (length of pixels buffer).

void BMP_setPixelsFast_V2D	(	const Vect2D_u16 *	crd,
		u8	col,
		u16	num
	)

Set pixels from Vect2D array (fast version without bounds verification)

Parameters:

crd	Vect2D_u16 Coordinates buffer.
col	pixels color (should be 8 bits filled: 0x00, 0x11, .. for plain color)
num	number of pixel to draw (length of coordinates buffer).

void BMP_showFPS ( u16 float_display )

Show the frame rate in bitmap mode.

Parameters:

float_display If this value is true (!= 0) the frame rate is displayed as float (else it's integer).

Variable Documentation

u8* bmp_buffer_read

Current bitmap read buffer.

u8* bmp_buffer_write

Current bitmap write buffer.

Classes

Defines

Functions

Variables

Detailed Description

Define Documentation

Function Documentation

Variable Documentation