sgdk: bmp.h File Reference

sgdk

- Main Page
- Related Pages
- Classes
- Files

- File List
- File Members

Classes | Defines | Functions | Variables
bmp.h File Reference

Software bitmap engine. More...

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

Go to the source code of this file.

## 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_H_
#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.

All Classes Files Functions Variables Typedefs Enumerations Enumerator Defines