Capabilities

A capability is an abstract feature or set of features that is implemented in different ways by different hardware devices. Capabilities allow application code to be cleanly separated from the specific hardware device drivers to allow easier mocking, testing in a development environment, and porting to new hardware.

2D Graphics

The 2D Graphics capability represents 2D display devices of various kinds that provide a rectangular matrix of pixels. The most abstract capability interface can represent devices of all color types: single-color, bi-color, RGB and anything in between.

This capability is split into two parts: the 2D graphics surface interface, IBuffered2dGraphicsSurface provides a low-level double-buffered device interface supporting only single-pixel operations, while the graphics utility class, Graphics2d, wraps the surface interface to provide higher-level shape drawing such as line segments and circles.

template < typename COORD_TYPE, typename COLOR_TYPE >

class IBuffered2dGraphicsSurface

Interface for a 2D bitmap supporting pixel set operations and buffer flips.

This is an interface intended to be implemented for a 2D display device that can then be used with the Graphics2d template class to perform higher-level graphics operations.

The coordinate system for all implementations is two-dimensional with each dimension proceeding from zero at the top left. However actual hardware may be mounted at a different orientation than its driver expects, causing the coordinate system to appear rotated.

The behavior when specifying pixels outside the bounds of the bitmap is undefined, but it should be avoided since it’s likely to cause data corruption and possibly crashes on at least some implementations.

Public Type

typedef COORD_TYPE coord_type

Typedef for the type used for coordinates.

Exposed here for the benefit of wrapping classes, like Graphics.

typedef COLOR_TYPE color_type

Typedef for the type used for coordinates.

Exposed here for the benefit of wrapping classes, like Graphics.

Public Functions

void set_pixel(COORD_TYPE x, COORD_TYPE y, COLOR_TYPE color)

Set a particular pixel in the back-buffer to the given color.

COLOR_TYPE get_pixel(COORD_TYPE x, COORD_TYPE y)

Get the color of the given pixel in the back-buffer.

void flip(COORD_TYPE x1, COORD_TYPE x2, COORD_TYPE y1, COORD_TYPE y2)

Flip the back-buffer to the front-buffer for the given rectangular region.

Implementations will update the given region as efficiently as possible. For example, an implementation for display hardware that only supports updating entire lines might ignore the x coordinates but update the range of rows given.

COLOR_TYPE get_closest_color(unsigned char r, unsigned char g, unsigned char b)

Get the closest color supported by this surface for the 8-bit-per-channel RGB color given.

This function only really makes sense for true color displays, and is likely to be unimplemented or implemented in a strange way for implementations that target low-color displays or displays whose colors are intrinsic rather than user-programmable.

COORD_TYPE get_width()

Get the width of the buffer in pixels.

COORD_TYPE get_height()

Get the width of the buffer in pixels.

template < typename SURFACE_TYPE >

class Graphics2d

Higher-level graphics utility class.

Wraps a 2D graphics surface to provide higher-level drawing primitives like line segments and circles.

Public Type

typedef SURFACE_TYPE::coord_type coord_type

The coordinate type of the underlying graphics surface.

typedef SURFACE_TYPE::color_type color_type

The color type of the underlying graphics surface.

Public Functions

Graphics2d(SURFACE_TYPE * surface)

void set_pixel(COORD_TYPE x, COORD_TYPE y, COLOR_TYPE color)

Set the given pixel in the back buffer to the given color.

COLOR_TYPE get_pixel(COORD_TYPE x, COORD_TYPE y)

Get the color of the given pixel from the back buffer.

COORD_TYPE get_width()

Set the width of the underlying surface.

COORD_TYPE get_height()

Set the height of the underlying surface.

void flip()

Copy to the front-buffer any changes made since the last call to flip.

template < unsigned int WIDTH, unsigned int HEIGHT, typename COLOR_TYPE >

class AbstractBuffered2dGraphicsSurface

Abstract class providing a common-case implementation of I2DBufferedGraphicsSurface with an in-memory backbuffer whose maximum size depends on the size of the int type on the target.

The back-buffer is implemented as a two-dimentional array of the given COLOR_TYPE. This can be appropriate for RGB or other multi-color displays, but may not be best for displays with color formats that require less than one byte per pixel.

Subclasses of this must implement the flip method taking an explicit rectangle.

Public Functions

AbstractBuffered2dGraphicsSurface()

void set_pixel(unsigned int intx x, unsigned int inty y, COLOR_TYPE color)

Set a particular pixel in the back-buffer to the given color.

void get_pixel(unsigned int intx x, unsigned int inty y)

Get the color of the given pixel in the back-buffer.

unsigned int get_width()

Get the width of the buffer in pixels.

unsigned int get_height()

Get the width of the buffer in pixels.

void flip(unsigned int intx1 x1, unsigned int intx2 x2, unsigned int inty1 y1, unsigned int inty2 y2)

Flip the back-buffer to the front-buffer for the given rectangular region.

Implementations will update the given region as efficiently as possible. For example, an implementation for display hardware that only supports updating entire lines might ignore the x coordinates but update the range of rows given.