DUDS
Distributed Update of Data from Something
duds::ui::graphics::BppImage Class Reference

An image that uses a single bit to represent the state of each pixel; a black or white picture. More...

#include <BppImage.hpp>

Collaboration diagram for duds::ui::graphics::BppImage:

Classes

class  ConstPixel
 A forward iterator like class that visits each location of the image or a subset of the image. More...
 
struct  EndPixel
 Can be used as an end iterator to avoid making a whole iterator. More...
 
class  Pixel
 A forward and output iterator that visits each location of the image. More...
 

Public Types

enum  Direction {
  HorizInc, VertInc, HorizDec, VertDec,
  Rotate0DCCW = HorizInc, Rotate90DCCW = VertInc, Rotate180DCCW = HorizDec, Rotate270DCCW = VertDec
}
 Controls the direction ConstPixel and Pixel objects will move across the image when the object is incremented. More...
 
enum  Operation {
  OpSet, OpNot, OpAnd, OpOr,
  OpXor, OpTotal
}
 Tells how to modify the destination pixel with the source pixel data. More...
 
typedef std::uintptr_t PixelBlock
 The type used to hold pixel values, one bit per pixel. More...
 

Public Member Functions

 BppImage ()
 Make an empty image with zero size. More...
 
 BppImage (const ImageDimensions &id)
 Makes an image of the requested size with uninitialized image data. More...
 
 BppImage (int width, int height)
 Makes an image of the requested size with uninitialized image data. More...
 
 BppImage (BppImage &&mv)
 Move constructor. More...
 
 BppImage (const BppImage &src)
 Copy constructor. More...
 
 BppImage (const char *data)
 Copies constant image data into a new image. More...
 
 BppImage (const std::vector< char > &data)
 Copies constant image data into a new image with run-time bounds checks on accesses to data. More...
 
Pixel begin ()
 Returns a Pixel (iterator) to the upper left of the image. More...
 
Pixel begin (Direction dir)
 Returns a Pixel (iterator) to the start of the image for the given direction. More...
 
Pixel begin (const ImageLocation &origin, const ImageDimensions &size, Direction dir=HorizInc)
 Returns a Pixel (iterator) to the start of a subset the image for the given direction. More...
 
ConstPixel begin () const
 Returns a ConstPixel (iterator) to the upper left of the image. More...
 
void blankImage (bool state)
 Changes the state of every pixel in the image to the given state. More...
 
int blocksPerLine () const
 Returns the number of PixelBlock objects per row in the image data. More...
 
const PixelBlockbuffer () const
 Retuns a pointer to the start of image data. More...
 
PixelBlockbuffer ()
 Retuns a pointer to the start of image data. More...
 
const PixelBlockbufferLine (int py) const
 Returns a pointer to the start of the given line. More...
 
PixelBlockbufferLine (int py)
 Returns a pointer to the start of the given line. More...
 
std::size_t bufferSize () const
 Returns the number of PixelBlocks, not bytes, that make up the image buffer. More...
 
void bufferSpot (PixelBlock *(&addr), PixelBlock &mask, const ImageLocation &il)
 Provides the location of the specified pixel inside the image data. More...
 
void bufferSpot (PixelBlock *(&addr), PixelBlock &mask, int x, int y)
 Provides the location of the specified pixel inside the image data. More...
 
void bufferSpot (const PixelBlock *(&addr), PixelBlock &mask, const ImageLocation &il) const
 Provides the location of the specified pixel inside the image data. More...
 
ConstPixel cbegin () const
 Returns a ConstPixel (iterator) to the upper left of the image. More...
 
ConstPixel cbegin (Direction dir) const
 Returns a ConstPixel (iterator) to the start of the image for the given direction. More...
 
ConstPixel cbegin (const ImageLocation &origin, const ImageDimensions &size, Direction dir=HorizInc) const
 Returns a ConstPixel (iterator) to the start of a subset the image for the given direction. More...
 
void clear ()
 Removes all image data. More...
 
void clearImage ()
 Clears every pixel (change to false) in the image. More...
 
void clearLines (int start, int height)
 Clears all the pixles of the given contiguous horizontal lines. More...
 
void clearPixel (const ImageLocation &il)
 Changes the state of a pixel to clear (false). More...
 
void clearPixel (int x, int y)
 Changes the state of a pixel to clear (false). More...
 
ConstPixel cpixel (const ImageLocation &il, Direction dir=HorizInc) const
 Returns a ConstPixel (iterator) to iterate across the image starting from the given location. More...
 
ConstPixel cpixel (int x, int y, Direction dir=HorizInc) const
 Returns a ConstPixel (iterator) to iterate across the image starting from the given location. More...
 
const std::vector< PixelBlock > & data () const
 Provides access to the internal vector storing the image data. More...
 
const ImageDimensionsdimensions () const
 Returns the dimensions of the image. More...
 
void drawBox (ImageLocation ul, ImageDimensions id, Operation op=OpSet)
 Draws a box into this image. More...
 
void drawBox (ImageLocation ul, ImageDimensions id, bool state)
 Draws a box into this image. More...
 
void drawBox (int x, int y, int w, int h=1, Operation op=OpSet)
 Draws a box into this image. More...
 
void drawBox (int x, int y, int w, int h, bool state)
 Draws a box into this image. More...
 
bool empty () const
 Returns true if there is no image data. More...
 
Pixel end ()
 Returns a Pixel end iterator. More...
 
ConstPixel end () const
 Returns a ConstPixel end iterator. More...
 
std::int16_t height () const
 Returns the height of the image. More...
 
void invert ()
 Toggles the state of all pixels. More...
 
void invertLines (int start, int height)
 Toggles the state of all pixels of the given contiguous horizontal lines. More...
 
bool invertPixel (const ImageLocation &il)
 Toggles the state of a pixel. More...
 
bool invertPixel (int x, int y)
 Toggles the state of a pixel. More...
 
ConstPixel operator() (int x, int y) const
 Returns a ConstPixel (iterator) to inspect the given pixel and to iterate across the image starting from the given location. More...
 
BppImageoperator= (BppImage &&mv)
 Move assignment. More...
 
BppImageoperator= (const BppImage &src)
 Copy assignment. More...
 
bool operator== (const BppImage &other) const
 Returns true if the contents of the two images are identical. More...
 
void patternLines (int start, int height, PixelBlock val)
 Writes a pattern of pixles to a set of contiguous horizontal lines. More...
 
Pixel pixel (const ImageLocation &il, Direction dir=HorizInc)
 Returns a Pixel (iterator) to iterate across the image starting from the given location. More...
 
Pixel pixel (int x, int y, Direction dir=HorizInc)
 Returns a Pixel (iterator) to iterate across the image starting from the given location. More...
 
void resize (const duds::ui::graphics::ImageDimensions &newdim)
 Changes the size of the image. More...
 
void resize (int width, int height)
 Changes the size of the image. More...
 
void setImage ()
 Sets every pixel (set to true) in the image. More...
 
void setLines (int start, int height)
 Sets all the pixles of the given contiguous horizontal lines. More...
 
void setPixel (const ImageLocation &il)
 Changes the state of a pixel to set (true). More...
 
void setPixel (int x, int y)
 Changes the state of a pixel to set (true). More...
 
int size () const
 Returns the number of pixels that make up the image. More...
 
ImageLocation startPosition (Direction dir=HorizInc) const
 Returns the starting location needed to iterate over the entire image in the given direction. More...
 
bool state (const ImageLocation &il) const
 Returns the state of the image pixel of the requested location. More...
 
bool state (int x, int y) const
 Returns the state of the image pixel of the requested location. More...
 
void state (const ImageLocation &il, bool s)
 Changes the state of a pixel. More...
 
void state (int x, int y, bool s)
 Changes the state of a pixel. More...
 
void swap (BppImage &other)
 Swap two images. More...
 
std::int16_t width () const
 Returns the width of the image. More...
 
void write (const BppImage *const src, const ImageLocation &destLoc, const ImageLocation &srcLoc, const ImageDimensions &srcSize, Direction srcDir=HorizInc, Operation op=OpSet)
 Writes the specified portion of the source into this image. More...
 
void write (const BppImage *const src, const ImageLocation &destLoc, const ImageDimensions &srcSize, Direction srcDir=HorizInc, Operation op=OpSet)
 Writes a portion of the source image, starting from (0, 0), into this image. More...
 
void write (const std::shared_ptr< const BppImage > &src, const ImageLocation &destLoc, const ImageLocation &srcLoc, const ImageDimensions &srcSize, Direction srcDir=HorizInc, Operation op=OpSet)
 Writes the specified portion of the source into this image. More...
 
void write (const std::shared_ptr< const BppImage > src, const ImageLocation &destLoc, const ImageDimensions &srcSize, Direction srcDir=HorizInc, Operation op=OpSet)
 Writes a portion of the source image, starting from (0, 0), into this image. More...
 
void write (const BppImage *const src, const ImageLocation &dest, Direction srcDir=HorizInc, Operation op=OpSet)
 Writes as much of the given source image as will fit into this image. More...
 
void write (const std::shared_ptr< const BppImage > &src, const ImageLocation &dest, Direction srcDir=HorizInc, Operation op=OpSet)
 Writes as much of the given source image as will fit into this image. More...
 

Static Public Member Functions

static constexpr std::size_t bufferBlockSize (int w, int h)
 Returns the size of an image buffer as the number of PixelBlock PixelBlocks needed to store an image of the specified size. More...
 
static constexpr int bufferBlocksPerLine (int width)
 Returns the number of PixelBlock objects that will be used for each horizontal line of an image of the indicated width. More...
 
static constexpr int bufferBlocksPerLine (ImageDimensions dim)
 Returns the number of PixelBlock objects that will be used for each horizontal line of an image of the indicated width. More...
 
static constexpr std::size_t bufferByteSize (int w, int h)
 Returns the size of an image buffer in bytes needed for the specified image size. More...
 
static constexpr ConstPixel cend ()
 Returns a ConstPixel end iterator. More...
 
static EndPixel endPixel ()
 Convenience function that returns EndPixel, which can be used as an end iterator with any ConstPixel or Pixel object, regardless what BppImage object they are working upon. More...
 
static std::shared_ptr< BppImagemake (const ImageDimensions &id)
 Convenience function to make a shared pointer to an image using the BppImage(const ImageDimensions &) constructor. More...
 
static std::shared_ptr< BppImagemake (int width, int height)
 Convenience function to make a shared pointer to an image using the BppImage(int, int) constructor. More...
 
static std::shared_ptr< BppImagemake (const char *data)
 Convenience function to make a shared pointer to an image using the BppImage(const char *) constructor. More...
 
static std::shared_ptr< BppImagemake (const std::vector< char > &data)
 Convenience function to make a shared pointer to an image using the BppImage(const std::vector<char> &) constructor. More...
 
static ImageLocation startPosition (const ImageLocation &origin, const ImageDimensions &size, Direction dir=HorizInc)
 Returns the starting location needed to iterate over the specified subeset of an image in the given direction. More...
 

Private Types

typedef bool(* OpBitFunction) (bool dest, bool src)
 
typedef void(* OpFunction) (PixelBlock *dest, const PixelBlock &src, const PixelBlock &mask)
 

Private Attributes

int blkPerLine
 Number of PixelBlocks used for each horizontal line. More...
 
ImageDimensions dim
 The dimensions of the image. More...
 
std::vector< PixelBlockimg
 The image data. More...
 

Static Private Attributes

static const OpBitFunction OpBitFunctions [OpTotal]
 Functions implementing the operations listed in Operation one bit at a time. More...
 
static const OpFunction OpFunctions [OpTotal]
 Functions implementing the operations listed in Operation one PixelBlock at a time. More...
 

Detailed Description

An image that uses a single bit to represent the state of each pixel; a black or white picture.

The image data is stored as a vector of PixelBlock objects. These are pointer-sized integers. The LSb of the first PixelBlock represents the left-most pixel of the top-most row. Each succesive bit and PixelBlock moves to the right. PixelBlocks do not span rows, so unused space will fill the higher value bits of the right-most PixelBlock at the end of each row.

Note
Operations that modify images are not thread-safe.
Author
Jeff Jackowski
Todo:
Complete documentation.
Examples:
bppmenu.cpp, rendertext.cpp, and st7920.cpp.

Definition at line 321 of file BppImage.hpp.

Member Typedef Documentation

◆ OpBitFunction

typedef bool(* duds::ui::graphics::BppImage::OpBitFunction) (bool dest, bool src)
private

Definition at line 1553 of file BppImage.hpp.

◆ OpFunction

typedef void(* duds::ui::graphics::BppImage::OpFunction) (PixelBlock *dest, const PixelBlock &src, const PixelBlock &mask)
private

Definition at line 1560 of file BppImage.hpp.

◆ PixelBlock

The type used to hold pixel values, one bit per pixel.

Definition at line 326 of file BppImage.hpp.

Member Enumeration Documentation

◆ Direction

Controls the direction ConstPixel and Pixel objects will move across the image when the object is incremented.

The direction will be the reverse when decremented. All options are HorizInc rotated by a multiple of 90 degrees. They are given in clockwise order by where the iterator starts to iterate over the whole image. However, the order is conuter-colockwise for the results of the write() functions.

Note
If the listing is in alphabetical order, it is not in clockwise/counter-clockwise order.
Enumerator
HorizInc 

The X coordinate will be incremented until reaching the width limit.

When the limit is reached, X will be changed to zero and Y will be incremented. If Y passes the height limit, the position will be changed to (-1,-1), the end condition.

VertInc 

The Y coordinate will be incremented.

When the maximum height is reached, Y will be set to zero and X decremented. If X would go negative, the position will instead be changed to (-1,-1).

HorizDec 

The X coordinate will be decremented until reaching zero.

When zero is reached, X will be changed to the maximum width and Y will be decremented. If Y would go negative, the position will instead be changed to (-1,-1).

VertDec 

The Y coordinate will be decremented.

When zero is reached, Y will be set to the maximum height and X incremented. If X passes the width limit, the position will instead be changed to (-1,-1).

Rotate0DCCW 

The X coordinate will be incremented until reaching the width limit.

When the limit is reached, X will be changed to zero and Y will be incremented. If Y passes the height limit, the position will be changed to (-1,-1), the end condition.

Rotate90DCCW 

The Y coordinate will be incremented.

When the maximum height is reached, Y will be set to zero and X decremented. If X would go negative, the position will instead be changed to (-1,-1).

Rotate180DCCW 

The X coordinate will be decremented until reaching zero.

When zero is reached, X will be changed to the maximum width and Y will be decremented. If Y would go negative, the position will instead be changed to (-1,-1).

Rotate270DCCW 

The Y coordinate will be decremented.

When zero is reached, Y will be set to the maximum height and X incremented. If X passes the width limit, the position will instead be changed to (-1,-1).

Definition at line 386 of file BppImage.hpp.

◆ Operation

Tells how to modify the destination pixel with the source pixel data.

Enumerator
OpSet 

Assigns the pixels in the destination the same value as the pixels in the source.

OpNot 

Assigns the pixels in the destination the opposing value of the pixels in the source.

OpAnd 

Performs a bitwise and operation with the destination and source data, and places the result in the destination.

OpOr 

Performs a bitwise or operation with the destination and source data, and places the result in the destination.

OpXor 

Performs a bitwise exclusive-or operation with the destination and source data, and places the result in the destination.

OpTotal 

The total number of supported operations.

Definition at line 1521 of file BppImage.hpp.

Constructor & Destructor Documentation

◆ BppImage() [1/7]

duds::ui::graphics::BppImage::BppImage ( )
inline

Make an empty image with zero size.

Definition at line 965 of file BppImage.hpp.

◆ BppImage() [2/7]

duds::ui::graphics::BppImage::BppImage ( const ImageDimensions id)

Makes an image of the requested size with uninitialized image data.

Definition at line 28 of file BppImage.cpp.

◆ BppImage() [3/7]

duds::ui::graphics::BppImage::BppImage ( int  width,
int  height 
)
inline

Makes an image of the requested size with uninitialized image data.

Definition at line 973 of file BppImage.hpp.

◆ BppImage() [4/7]

duds::ui::graphics::BppImage::BppImage ( BppImage &&  mv)

Move constructor.

Definition at line 33 of file BppImage.cpp.

◆ BppImage() [5/7]

duds::ui::graphics::BppImage::BppImage ( const BppImage src)

Copy constructor.

Definition at line 39 of file BppImage.cpp.

◆ BppImage() [6/7]

duds::ui::graphics::BppImage::BppImage ( const char *  data)

Copies constant image data into a new image.

This is intended for use with the output of the Bit-Per-Pixel Image Compiler (bppic). The BppImageArchive uses this constructor with data from an archive made by bppic, and it can be used directly with the const char arrays from the C++ output of bppic.

Parameters
dataThe source data. It starts with the width and height, in that order. Both are two bytes in little endian form. Following that is the image data. The LSb of each byte is for the pixel furthest left in the byte. If the width is not evenly divisible by 8, the last byte of each line will contain unused bits. Each line of the image will start on a new byte.

Definition at line 42 of file BppImage.cpp.

◆ BppImage() [7/7]

duds::ui::graphics::BppImage::BppImage ( const std::vector< char > &  data)

Copies constant image data into a new image with run-time bounds checks on accesses to data.

Parameters
dataThe source data. It starts with the width and height, in that order. Both are two bytes in little endian form. Following that is the image data. The LSb of each byte is for the pixel furthest left in the byte. If the width is not evenly divisible by 8, the last byte of each line will contain unused bits. Each line of the image will start on a new byte.
Exceptions
ImageTruncatedErrorThe provided data was too short. Either there isn't enough data for the smallest possible image, or the indicated dimensions require more data.

Definition at line 63 of file BppImage.cpp.

Member Function Documentation

◆ begin() [1/4]

BppImage::Pixel duds::ui::graphics::BppImage::begin ( )

Returns a Pixel (iterator) to the upper left of the image.

Definition at line 249 of file BppImage.cpp.

Referenced by write().

◆ begin() [2/4]

BppImage::Pixel duds::ui::graphics::BppImage::begin ( Direction  dir)

Returns a Pixel (iterator) to the start of the image for the given direction.

Different directions start in a different location, but will iterate over the whole image.

Definition at line 256 of file BppImage.cpp.

◆ begin() [3/4]

BppImage::Pixel duds::ui::graphics::BppImage::begin ( const ImageLocation origin,
const ImageDimensions size,
Direction  dir = HorizInc 
)

Returns a Pixel (iterator) to the start of a subset the image for the given direction.

Different directions and subsets start in different locations, but will iterate over the entire subset of the image.

Parameters
originThe origin (top left); used to limit the iteration to a subset of the image data. The top left location is not modified by the iteration direction dir. The area to iterate over must exist within the source image.
sizeThe size of the image to iterate over. This is used to limit the iteration to a subset of the image data. The axes for width and height are not modified by the iteration direction dir. The area to iterate over must exist within the source image.
dirThe direction of the iteration as defined in the enum Direction.

Definition at line 263 of file BppImage.cpp.

◆ begin() [4/4]

ConstPixel duds::ui::graphics::BppImage::begin ( ) const
inline

Returns a ConstPixel (iterator) to the upper left of the image.

Definition at line 1360 of file BppImage.hpp.

◆ blankImage()

void duds::ui::graphics::BppImage::blankImage ( bool  state)

Changes the state of every pixel in the image to the given state.

Postcondition
All pixels will be set to state.
See also
clearImage()
setImage()

Definition at line 340 of file BppImage.cpp.

◆ blocksPerLine()

int duds::ui::graphics::BppImage::blocksPerLine ( ) const
inline

Returns the number of PixelBlock objects per row in the image data.

Definition at line 1167 of file BppImage.hpp.

Referenced by drawBox(), and operator==().

◆ buffer() [1/2]

const BppImage::PixelBlock * duds::ui::graphics::BppImage::buffer ( ) const

Retuns a pointer to the start of image data.

Exceptions
ImageZeroSizeError

Definition at line 138 of file BppImage.cpp.

◆ buffer() [2/2]

PixelBlock* duds::ui::graphics::BppImage::buffer ( )
inline

Retuns a pointer to the start of image data.

Exceptions
ImageZeroSizeError

Definition at line 1124 of file BppImage.hpp.

◆ bufferBlockSize()

static constexpr std::size_t duds::ui::graphics::BppImage::bufferBlockSize ( int  w,
int  h 
)
inlinestatic

Returns the size of an image buffer as the number of PixelBlock PixelBlocks needed to store an image of the specified size.

Definition at line 347 of file BppImage.hpp.

Referenced by BppImage(), and resize().

◆ bufferBlocksPerLine() [1/2]

static constexpr int duds::ui::graphics::BppImage::bufferBlocksPerLine ( int  width)
inlinestatic

Returns the number of PixelBlock objects that will be used for each horizontal line of an image of the indicated width.

There may be unused space in the more significant bits of the last PixelBlock in the line.

Definition at line 363 of file BppImage.hpp.

Referenced by BppImage(), and resize().

◆ bufferBlocksPerLine() [2/2]

static constexpr int duds::ui::graphics::BppImage::bufferBlocksPerLine ( ImageDimensions  dim)
inlinestatic

Returns the number of PixelBlock objects that will be used for each horizontal line of an image of the indicated width.

There may be unused space in the more significant bits of the last PixelBlock in the line.

Definition at line 372 of file BppImage.hpp.

◆ bufferByteSize()

static constexpr std::size_t duds::ui::graphics::BppImage::bufferByteSize ( int  w,
int  h 
)
inlinestatic

Returns the size of an image buffer in bytes needed for the specified image size.

Definition at line 355 of file BppImage.hpp.

◆ bufferLine() [1/2]

const BppImage::PixelBlock * duds::ui::graphics::BppImage::bufferLine ( int  py) const

Returns a pointer to the start of the given line.

Parameters
pyThe Y-coordinate of the line.
Returns
The address of the start of line py.
Exceptions
ImageBoundsErrorThe given location is out of bounds. To satisfy C++ iterator requirements, one past the end will not throw, but should not be dereferenced.

Definition at line 175 of file BppImage.cpp.

Referenced by BppImage(), invertLines(), duds::hardware::devices::displays::SimulatedBppDisplay::outputFrame(), duds::hardware::devices::displays::ST7920::outputFrame(), and patternLines().

◆ bufferLine() [2/2]

PixelBlock* duds::ui::graphics::BppImage::bufferLine ( int  py)
inline

Returns a pointer to the start of the given line.

Parameters
pyThe Y-coordinate of the line.
Returns
The address of the start of line py.
Exceptions
ImageBoundsErrorThe given location is out of bounds. To satisfy C++ iterator requirements, one past the end will not throw, but should not be dereferenced.

Definition at line 1159 of file BppImage.hpp.

◆ bufferSize()

std::size_t duds::ui::graphics::BppImage::bufferSize ( ) const
inline

Returns the number of PixelBlocks, not bytes, that make up the image buffer.

This result includes space allocated but not used for the image data.

Definition at line 1088 of file BppImage.hpp.

◆ bufferSpot() [1/3]

void duds::ui::graphics::BppImage::bufferSpot ( PixelBlock *&  addr,
PixelBlock mask,
const ImageLocation il 
)

Provides the location of the specified pixel inside the image data.

A class for the result of bufferSpot() is not provided because it is more useful when combined with a coordinate, and the ConstPixel and Pixel classes do that.

Parameters
addrThe address of the PixelBlock that contains the requested pixel.
maskA bitmask that will be set to identify the pixel inside the PixelBlock.
ilThe location to find within the image data.
Exceptions
ImageBoundsErrorThe given location is out of bounds.

Definition at line 185 of file BppImage.cpp.

Referenced by duds::ui::graphics::BppImage::ConstPixel::ConstPixel(), invertPixel(), duds::ui::graphics::BppImage::ConstPixel::location(), duds::ui::graphics::BppImage::ConstPixel::operator++(), duds::ui::graphics::BppImage::ConstPixel::origdimloc(), duds::ui::graphics::BppImage::ConstPixel::origin(), and state().

◆ bufferSpot() [2/3]

void duds::ui::graphics::BppImage::bufferSpot ( PixelBlock *&  addr,
PixelBlock mask,
int  x,
int  y 
)
inline

Provides the location of the specified pixel inside the image data.

A class for the result of bufferSpot() is not provided because it is more useful when combined with a coordinate, and the ConstPixel and Pixel classes do that.

Parameters
addrThe address of the PixelBlock that contains the requested pixel.
maskA bitmask that will be set to identify the pixel inside the PixelBlock.
xThe X coordinate.
yThe Y coordinate.
Exceptions
ImageBoundsErrorThe given location is out of bounds.

Definition at line 1200 of file BppImage.hpp.

◆ bufferSpot() [3/3]

void duds::ui::graphics::BppImage::bufferSpot ( const PixelBlock *&  addr,
PixelBlock mask,
const ImageLocation il 
) const
inline

Provides the location of the specified pixel inside the image data.

A class for the result of bufferSpot() is not provided because it is more useful when combined with a coordinate, and the ConstPixel and Pixel classes do that.

Parameters
addrThe address of the PixelBlock that contains the requested pixel.
maskA bitmask that will be set to identify the pixel inside the PixelBlock.
ilThe location to find within the image data.
Exceptions
ImageBoundsErrorThe given location is out of bounds.

Definition at line 1215 of file BppImage.hpp.

◆ cbegin() [1/3]

BppImage::ConstPixel duds::ui::graphics::BppImage::cbegin ( ) const

Returns a ConstPixel (iterator) to the upper left of the image.

Definition at line 274 of file BppImage.cpp.

Referenced by write().

◆ cbegin() [2/3]

BppImage::ConstPixel duds::ui::graphics::BppImage::cbegin ( Direction  dir) const

Returns a ConstPixel (iterator) to the start of the image for the given direction.

Different directions start in a different location, but will iterate over the whole image.

Definition at line 281 of file BppImage.cpp.

◆ cbegin() [3/3]

BppImage::ConstPixel duds::ui::graphics::BppImage::cbegin ( const ImageLocation origin,
const ImageDimensions size,
Direction  dir = HorizInc 
) const

Returns a ConstPixel (iterator) to the start of a subset the image for the given direction.

Different directions and subsets start in different locations, but will iterate over the entire subset of the image.

Parameters
originThe origin (top left); used to limit the iteration to a subset of the image data. The top left location is not modified by the iteration direction dir. The area to iterate over must exist within the source image.
sizeThe size of the image to iterate over. This is used to limit the iteration to a subset of the image data. The axes for width and height are not modified by the iteration direction dir. The area to iterate over must exist within the source image.
dirThe direction of the iteration as defined in the enum Direction.

Definition at line 288 of file BppImage.cpp.

◆ cend()

static constexpr ConstPixel duds::ui::graphics::BppImage::cend ( )
inlinestatic

Returns a ConstPixel end iterator.

It can be used as an end iterator with any ConstPixel, regardless of the source BppImage object in use. It is less efficient than using an EndPixel object, but its constexpr status should mitigate this compared to using the non-const end().

Definition at line 1382 of file BppImage.hpp.

◆ clear()

void duds::ui::graphics::BppImage::clear ( )

Removes all image data.

Postcondition
The image has zero size. All ConstPixel and Pixel objects using this object are invalid.

Definition at line 117 of file BppImage.cpp.

Referenced by resize().

◆ clearImage()

void duds::ui::graphics::BppImage::clearImage ( )
inline

Clears every pixel (change to false) in the image.

Examples:
bppmenu.cpp, and rendertext.cpp.

Definition at line 1509 of file BppImage.hpp.

Referenced by duds::hardware::devices::displays::ST7920::initialize().

◆ clearLines()

void duds::ui::graphics::BppImage::clearLines ( int  start,
int  height 
)
inline

Clears all the pixles of the given contiguous horizontal lines.

Parameters
startThe first horizontal line (y-coordinate) to write.
heightThe number of lines to write.

Definition at line 1496 of file BppImage.hpp.

◆ clearPixel() [1/2]

void duds::ui::graphics::BppImage::clearPixel ( const ImageLocation il)
inline

Changes the state of a pixel to clear (false).

Parameters
ilThe location to change.

Definition at line 1426 of file BppImage.hpp.

◆ clearPixel() [2/2]

void duds::ui::graphics::BppImage::clearPixel ( int  x,
int  y 
)
inline

Changes the state of a pixel to clear (false).

Parameters
xHorizontal coordinate to change.
yVertical coordinate to change.

Definition at line 1434 of file BppImage.hpp.

◆ cpixel() [1/2]

BppImage::ConstPixel duds::ui::graphics::BppImage::cpixel ( const ImageLocation il,
Direction  dir = HorizInc 
) const

Returns a ConstPixel (iterator) to iterate across the image starting from the given location.

The whole image will be traversed, save for what came before the given location.

Parameters
ilThe starting location.
dirThe direction of iteration.

Definition at line 235 of file BppImage.cpp.

◆ cpixel() [2/2]

ConstPixel duds::ui::graphics::BppImage::cpixel ( int  x,
int  y,
Direction  dir = HorizInc 
) const
inline

Returns a ConstPixel (iterator) to iterate across the image starting from the given location.

The whole image will be traversed, save for what came before the given location.

Parameters
xThe horizontal starting location.
yThe vertical starting location.
dirThe direction of iteration.

Definition at line 1282 of file BppImage.hpp.

◆ data()

const std::vector<PixelBlock>& duds::ui::graphics::BppImage::data ( ) const
inline

Provides access to the internal vector storing the image data.

Definition at line 1133 of file BppImage.hpp.

Referenced by BppImage().

◆ dimensions()

◆ drawBox() [1/4]

void duds::ui::graphics::BppImage::drawBox ( ImageLocation  ul,
ImageDimensions  id,
Operation  op = OpSet 
)

Draws a box into this image.

Note
This function exists partly as a test of how to write data into an image one PixelBlock at a time. The overhead may not make this function worthwhile unless a PixelBlock is large enough, and 32-bits might not be large enough. The algorithm could be adapted for use in the write() functions.
Parameters
ulThe upper-left location of the box.
idThe dimensions of the box.
opThe bit-wise operation to perform to draw the box. One operand will be the image data, and the other will always be set bit(s). This means that OpSet will change pixels to true (set), OpNot will change pixels to false (clear), and OpXor will toggle (invert) pixels.
Exceptions
ImageBoundsErrorThe box extends beyond the bounds of the image.

Definition at line 485 of file BppImage.cpp.

Referenced by duds::ui::graphics::BppPositionIndicator::render().

◆ drawBox() [2/4]

void duds::ui::graphics::BppImage::drawBox ( ImageLocation  ul,
ImageDimensions  id,
bool  state 
)
inline

Draws a box into this image.

Parameters
ulThe upper-left location of the box.
idThe dimensions of the box.
stateThe pixel state to write.
Exceptions
ImageBoundsErrorThe box extends beyond the bounds of the image.

Definition at line 1718 of file BppImage.hpp.

◆ drawBox() [3/4]

void duds::ui::graphics::BppImage::drawBox ( int  x,
int  y,
int  w,
int  h = 1,
Operation  op = OpSet 
)
inline

Draws a box into this image.

Parameters
xThe upper-left horizontal coordinate of the box.
yThe upper-left vertical coordinate of the box.
wThe width of the box.
hThe height of the box.
opThe bit-wise operation to perform to draw the box. One operand will be the image data, and the other will always be set bit(s). This means that OpSet will change pixels to true (set), OpNot will change pixels to false (clear), and OpXor will toggle (invert) pixels.
Exceptions
ImageBoundsErrorThe box extends beyond the bounds of the image.

Definition at line 1739 of file BppImage.hpp.

◆ drawBox() [4/4]

void duds::ui::graphics::BppImage::drawBox ( int  x,
int  y,
int  w,
int  h,
bool  state 
)
inline

Draws a box into this image.

Parameters
xThe upper-left horizontal coordinate of the box.
yThe upper-left vertical coordinate of the box.
wThe width of the box.
hThe height of the box.
stateThe pixel state to write.
Exceptions
ImageBoundsErrorThe box extends beyond the bounds of the image.

Definition at line 1758 of file BppImage.hpp.

◆ empty()

bool duds::ui::graphics::BppImage::empty ( ) const
inline

Returns true if there is no image data.

Definition at line 1080 of file BppImage.hpp.

Referenced by drawBox(), and empty().

◆ end() [1/2]

Pixel duds::ui::graphics::BppImage::end ( )

Returns a Pixel end iterator.

This is less efficient than using an EndPixel object, but is more consistent with how iterators are used.

Referenced by invertLines(), and patternLines().

◆ end() [2/2]

ConstPixel duds::ui::graphics::BppImage::end ( ) const
inline

Returns a ConstPixel end iterator.

It can be used as an end iterator with any ConstPixel, regardless of the source BppImage object in use. It is less efficient than using an EndPixel object, but its constexpr status should mitigate this compared to using the non-const end().

Definition at line 1391 of file BppImage.hpp.

◆ endPixel()

static EndPixel duds::ui::graphics::BppImage::endPixel ( )
inlinestatic

Convenience function that returns EndPixel, which can be used as an end iterator with any ConstPixel or Pixel object, regardless what BppImage object they are working upon.

Definition at line 1368 of file BppImage.hpp.

◆ height()

std::int16_t duds::ui::graphics::BppImage::height ( ) const
inline

Returns the height of the image.

Definition at line 1106 of file BppImage.hpp.

Referenced by duds::hardware::display::BppGraphicDisplay::height().

◆ invert()

void duds::ui::graphics::BppImage::invert ( )

Toggles the state of all pixels.

Definition at line 320 of file BppImage.cpp.

◆ invertLines()

void duds::ui::graphics::BppImage::invertLines ( int  start,
int  height 
)

Toggles the state of all pixels of the given contiguous horizontal lines.

Parameters
startThe first horizontal line (y-coordinate) to invert.
heightThe number of lines to invert.

Definition at line 326 of file BppImage.cpp.

◆ invertPixel() [1/2]

bool duds::ui::graphics::BppImage::invertPixel ( const ImageLocation il)

Toggles the state of a pixel.

Parameters
ilThe location to toggle.

Definition at line 313 of file BppImage.cpp.

◆ invertPixel() [2/2]

bool duds::ui::graphics::BppImage::invertPixel ( int  x,
int  y 
)
inline

Toggles the state of a pixel.

Parameters
xHorizontal coordinate to toggle.
yVertical coordinate to toggle.

Definition at line 1462 of file BppImage.hpp.

◆ make() [1/4]

static std::shared_ptr<BppImage> duds::ui::graphics::BppImage::make ( const ImageDimensions id)
inlinestatic

Convenience function to make a shared pointer to an image using the BppImage(const ImageDimensions &) constructor.

Examples:
bppmenu.cpp.

Definition at line 1018 of file BppImage.hpp.

Referenced by duds::ui::graphics::BppFont::render(), and duds::ui::menu::renderers::BppMenuRenderer::render().

◆ make() [2/4]

static std::shared_ptr<BppImage> duds::ui::graphics::BppImage::make ( int  width,
int  height 
)
inlinestatic

Convenience function to make a shared pointer to an image using the BppImage(int, int) constructor.

Definition at line 1025 of file BppImage.hpp.

◆ make() [3/4]

static std::shared_ptr<BppImage> duds::ui::graphics::BppImage::make ( const char *  data)
inlinestatic

Convenience function to make a shared pointer to an image using the BppImage(const char *) constructor.

Definition at line 1032 of file BppImage.hpp.

◆ make() [4/4]

static std::shared_ptr<BppImage> duds::ui::graphics::BppImage::make ( const std::vector< char > &  data)
inlinestatic

Convenience function to make a shared pointer to an image using the BppImage(const std::vector<char> &) constructor.

Definition at line 1039 of file BppImage.hpp.

◆ operator()()

ConstPixel duds::ui::graphics::BppImage::operator() ( int  x,
int  y 
) const
inline

Returns a ConstPixel (iterator) to inspect the given pixel and to iterate across the image starting from the given location.

The whole image will be traversed, save for what came before the given location.

Parameters
xThe horizontal starting location.
yThe vertical starting location.

Definition at line 1292 of file BppImage.hpp.

◆ operator=() [1/2]

BppImage & duds::ui::graphics::BppImage::operator= ( BppImage &&  mv)

Move assignment.

Definition at line 95 of file BppImage.cpp.

◆ operator=() [2/2]

BppImage & duds::ui::graphics::BppImage::operator= ( const BppImage src)

Copy assignment.

Definition at line 104 of file BppImage.cpp.

◆ operator==()

bool duds::ui::graphics::BppImage::operator== ( const BppImage other) const

Returns true if the contents of the two images are identical.

Definition at line 145 of file BppImage.cpp.

◆ patternLines()

void duds::ui::graphics::BppImage::patternLines ( int  start,
int  height,
PixelBlock  val 
)

Writes a pattern of pixles to a set of contiguous horizontal lines.

Parameters
startThe first horizontal line (y-coordinate) to write.
heightThe number of lines to write.
valThe value, or pattern, of pixels to write. The pattern may extend past the right side boundry of the image.

Definition at line 333 of file BppImage.cpp.

◆ pixel() [1/2]

BppImage::Pixel duds::ui::graphics::BppImage::pixel ( const ImageLocation il,
Direction  dir = HorizInc 
)

Returns a Pixel (iterator) to iterate across the image starting from the given location.

The whole image will be traversed, save for what came before the given location.

Parameters
ilThe starting location.
dirThe direction of iteration.

Definition at line 224 of file BppImage.cpp.

◆ pixel() [2/2]

Pixel duds::ui::graphics::BppImage::pixel ( int  x,
int  y,
Direction  dir = HorizInc 
)
inline

Returns a Pixel (iterator) to iterate across the image starting from the given location.

The whole image will be traversed, save for what came before the given location.

Parameters
xThe horizontal starting location.
yThe vertical starting location.
dirThe direction of iteration.

Definition at line 1263 of file BppImage.hpp.

◆ resize() [1/2]

void duds::ui::graphics::BppImage::resize ( const duds::ui::graphics::ImageDimensions newdim)

Changes the size of the image.

Parameters
newdimThe new image dimensions.
Postcondition
The image data is undefined.
Exceptions
ImageBoundsErrorA negative dimension was provided.

Definition at line 123 of file BppImage.cpp.

Referenced by duds::hardware::devices::displays::SimulatedBppDisplay::configure(), and duds::hardware::devices::displays::ST7920::configure().

◆ resize() [2/2]

void duds::ui::graphics::BppImage::resize ( int  width,
int  height 
)
inline

Changes the size of the image.

Parameters
widthThe new width of the image.
heightThe new height of the image.
Postcondition
The image data is undefined.
Exceptions
ImageBoundsErrorA negative dimension was provided.

Definition at line 1074 of file BppImage.hpp.

◆ setImage()

void duds::ui::graphics::BppImage::setImage ( )
inline

Sets every pixel (set to true) in the image.

Definition at line 1515 of file BppImage.hpp.

Referenced by duds::hardware::devices::displays::ST7920::initialize().

◆ setLines()

void duds::ui::graphics::BppImage::setLines ( int  start,
int  height 
)
inline

Sets all the pixles of the given contiguous horizontal lines.

Parameters
startThe first horizontal line (y-coordinate) to write.
heightThe number of lines to write.

Definition at line 1488 of file BppImage.hpp.

◆ setPixel() [1/2]

void duds::ui::graphics::BppImage::setPixel ( const ImageLocation il)
inline

Changes the state of a pixel to set (true).

Parameters
ilThe location to change.

Definition at line 1441 of file BppImage.hpp.

◆ setPixel() [2/2]

void duds::ui::graphics::BppImage::setPixel ( int  x,
int  y 
)
inline

Changes the state of a pixel to set (true).

Parameters
xHorizontal coordinate to change.
yVertical coordinate to change.

Definition at line 1449 of file BppImage.hpp.

◆ size()

int duds::ui::graphics::BppImage::size ( ) const
inline

Returns the number of pixels that make up the image.

Definition at line 1094 of file BppImage.hpp.

Referenced by bufferSize().

◆ startPosition() [1/2]

ImageLocation duds::ui::graphics::BppImage::startPosition ( Direction  dir = HorizInc) const

Returns the starting location needed to iterate over the entire image in the given direction.

Parameters
dirThe iteration direction. Each direction starts at a different corner of the image.

Definition at line 201 of file BppImage.cpp.

Referenced by begin(), and cbegin().

◆ startPosition() [2/2]

ImageLocation duds::ui::graphics::BppImage::startPosition ( const ImageLocation origin,
const ImageDimensions size,
Direction  dir = HorizInc 
)
static

Returns the starting location needed to iterate over the specified subeset of an image in the given direction.

Parameters
originThe origin; the top left of the image subset.
sizeThe size of the image subset extending from the origin.
dirThe iteration direction. Each direction starts at a different corner of the image.

Definition at line 205 of file BppImage.cpp.

◆ state() [1/4]

bool duds::ui::graphics::BppImage::state ( const ImageLocation il) const

Returns the state of the image pixel of the requested location.

Parameters
ilThe location to query.

Definition at line 299 of file BppImage.cpp.

◆ state() [2/4]

bool duds::ui::graphics::BppImage::state ( int  x,
int  y 
) const
inline

Returns the state of the image pixel of the requested location.

Parameters
xHorizontal coordinate to query.
yVertical coordinate to query.

Definition at line 1404 of file BppImage.hpp.

◆ state() [3/4]

void duds::ui::graphics::BppImage::state ( const ImageLocation il,
bool  s 
)

Changes the state of a pixel.

Parameters
ilThe location to change.
sThe new state of the pixel.

Definition at line 306 of file BppImage.cpp.

◆ state() [4/4]

void duds::ui::graphics::BppImage::state ( int  x,
int  y,
bool  s 
)
inline

Changes the state of a pixel.

Parameters
xHorizontal coordinate to change.
yVertical coordinate to change.
sThe new state of the pixel.

Definition at line 1419 of file BppImage.hpp.

◆ swap()

void duds::ui::graphics::BppImage::swap ( BppImage other)

Swap two images.

Definition at line 111 of file BppImage.cpp.

Referenced by duds::ui::graphics::swap().

◆ width()

std::int16_t duds::ui::graphics::BppImage::width ( ) const
inline

Returns the width of the image.

Definition at line 1100 of file BppImage.hpp.

Referenced by duds::hardware::display::BppGraphicDisplay::width().

◆ write() [1/6]

void duds::ui::graphics::BppImage::write ( const BppImage *const  src,
const ImageLocation destLoc,
const ImageLocation srcLoc,
const ImageDimensions srcSize,
Direction  srcDir = HorizInc,
Operation  op = OpSet 
)

Writes the specified portion of the source into this image.

Parameters
srcThe source image.
destLocThe top-left location on this image where the source image will be placed.
srcLocThe top-left location in the source image, not modified by srcDir, that will be written into this image.
srcSizeThe width and height of the source image that will be used.
srcDirThe iteration direction on the source image. This allows the source to be rotated by 0, 90, 180, or 270 degrees.
opThe operation used to modify this image.
Todo:
Redo, at least for non-rotated images, using drawBox() implementation to operate on more than one pixel at a time.
Examples:
rendertext.cpp.

Definition at line 430 of file BppImage.cpp.

Referenced by duds::ui::graphics::PriorityGridLayout::render(), and write().

◆ write() [2/6]

void duds::ui::graphics::BppImage::write ( const BppImage *const  src,
const ImageLocation destLoc,
const ImageDimensions srcSize,
Direction  srcDir = HorizInc,
Operation  op = OpSet 
)
inline

Writes a portion of the source image, starting from (0, 0), into this image.

Parameters
srcThe source image.
destLocThe top-left location on this image where the source image will be placed.
srcSizeThe width and height of the source image that will be used.
srcDirThe iteration direction on the source image. This allows the source to be rotated by 0, 90, 180, or 270 degrees.
opThe operation used to modify this image.

Definition at line 1601 of file BppImage.hpp.

◆ write() [3/6]

void duds::ui::graphics::BppImage::write ( const std::shared_ptr< const BppImage > &  src,
const ImageLocation destLoc,
const ImageLocation srcLoc,
const ImageDimensions srcSize,
Direction  srcDir = HorizInc,
Operation  op = OpSet 
)
inline

Writes the specified portion of the source into this image.

Parameters
srcThe source image.
destLocThe top-left location on this image where the source image will be placed.
srcLocThe top-left location in the source image, not modified by srcDir, that will be written into this image.
srcSizeThe width and height of the source image that will be used.
srcDirThe iteration direction on the source image. This allows the source to be rotated by 0, 90, 180, or 270 degrees.
opThe operation used to modify this image.

Definition at line 1623 of file BppImage.hpp.

◆ write() [4/6]

void duds::ui::graphics::BppImage::write ( const std::shared_ptr< const BppImage src,
const ImageLocation destLoc,
const ImageDimensions srcSize,
Direction  srcDir = HorizInc,
Operation  op = OpSet 
)
inline

Writes a portion of the source image, starting from (0, 0), into this image.

Parameters
srcThe source image.
destLocThe top-left location on this image where the source image will be placed.
srcSizeThe width and height of the source image that will be used.
srcDirThe iteration direction on the source image. This allows the source to be rotated by 0, 90, 180, or 270 degrees.
opThe operation used to modify this image.

Definition at line 1645 of file BppImage.hpp.

◆ write() [5/6]

void duds::ui::graphics::BppImage::write ( const BppImage *const  src,
const ImageLocation dest,
Direction  srcDir = HorizInc,
Operation  op = OpSet 
)

Writes as much of the given source image as will fit into this image.

Parameters
srcThe source image.
destThe top-left location on this image where the source image will be placed. The source image will be clipped to fit.
srcDirThe iteration direction on the source image. This allows the source to be rotated by 0, 90, 180, or 270 degrees.
opThe operation used to modify this image.

Definition at line 462 of file BppImage.cpp.

◆ write() [6/6]

void duds::ui::graphics::BppImage::write ( const std::shared_ptr< const BppImage > &  src,
const ImageLocation dest,
Direction  srcDir = HorizInc,
Operation  op = OpSet 
)
inline

Writes as much of the given source image as will fit into this image.

Parameters
srcThe source image.
destThe top-left location on this image where the source image will be placed. The source image will be clipped to fit.
srcDirThe iteration direction on the source image. This allows the source to be rotated by 0, 90, 180, or 270 degrees.
opThe operation used to modify this image.

Definition at line 1680 of file BppImage.hpp.

Member Data Documentation

◆ blkPerLine

int duds::ui::graphics::BppImage::blkPerLine
private

Number of PixelBlocks used for each horizontal line.

A whole number is always used, save for the case of a zero size image.

Definition at line 340 of file BppImage.hpp.

Referenced by BppImage(), bufferLine(), bufferSpot(), clear(), drawBox(), operator=(), resize(), and swap().

◆ dim

ImageDimensions duds::ui::graphics::BppImage::dim
private

The dimensions of the image.

Definition at line 335 of file BppImage.hpp.

Referenced by BppImage(), bufferLine(), bufferSpot(), clear(), cpixel(), drawBox(), operator=(), operator==(), pixel(), resize(), startPosition(), swap(), and write().

◆ img

std::vector<PixelBlock> duds::ui::graphics::BppImage::img
private

◆ OpBitFunctions

const BppImage::OpBitFunction duds::ui::graphics::BppImage::OpBitFunctions
staticprivate
Initial value:

Functions implementing the operations listed in Operation one bit at a time.

These are intended to be used when there is no optimized implementation of an operation.

Definition at line 1559 of file BppImage.hpp.

Referenced by duds::ui::graphics::opxorbit(), and write().

◆ OpFunctions

const BppImage::OpFunction duds::ui::graphics::BppImage::OpFunctions
staticprivate
Initial value:

Functions implementing the operations listed in Operation one PixelBlock at a time.

These are intended to be used by more optimized implementations of an operation than OpBitFunctions.

Definition at line 1566 of file BppImage.hpp.

Referenced by drawBox(), and duds::ui::graphics::opxor().


The documentation for this class was generated from the following files: