Bitmap Class Reference

#include <bitmap.h>

Public Member Functions
virtual	~Bitmap ()
virtual bool	init (utility::ErrorState &errorState) override
virtual bool	initFromFile (const std::string &path, nap::utility::ErrorState &errorState)
void	initFromDescriptor (const SurfaceDescriptor &surfaceDescriptor)
bool	save (const std::string &path, utility::ErrorState &errorState)
rtti::TypeInfo	getColorType () const
bool	empty () const
int	getWidth () const
int	getHeight () const
int	getNumberOfChannels () const
void *	getData ()
const void *	getData () const
size_t	getSizeInBytes () const
std::unique_ptr< BaseColor >	makePixel () const
void	getPixel (int x, int y, BaseColor &outPixel) const
template<typename T >
T	getPixel (int x, int y) const
void	setPixel (int x, int y, const BaseColor &color)
template<typename T >
void	setPixelColor (int x, int y, const T &color)
template<typename Type >
void	getRGBColor (int x, int y, RGBColor< Type > &outColor) const
template<typename Type >
RGBColor< Type >	getRGBColor (int x, int y) const
template<typename Type >
void	getRGBAColor (int x, int y, RGBAColor< Type > &outColor) const
template<typename Type >
RGBAColor< Type >	getRGBAColor (int x, int y) const
template<typename Type >
void	getColorValue (int x, int y, nap::EColorChannel channel, RColor< Type > &outValue) const
template<typename Type >
RColor< Type >	getColorValue (int x, int y, nap::EColorChannel channel) const
Public Member Functions inherited from Resource
	Resource ()
Public Member Functions inherited from Object
	Object ()
virtual	~Object ()
virtual void	onDestroy ()
	Object (Object &)=delete
Object &	operator= (const Object &)=delete
	Object (Object &&)=delete
Object &	operator= (Object &&)=delete

Public Attributes
SurfaceDescriptor	mSurfaceDescriptor
Signal	mBitmapUpdated
Public Attributes inherited from Object
std::string	mID
	Property: 'mID' unique name of the object. Used as an identifier by the system. More...

Additional Inherited Members
Static Public Member Functions inherited from Object
static bool	isIDProperty (rtti::Instance &object, const rtti::Property &property)

Description

2D image resource that is initially empty, there is no GPU data associated with this object. When initialized this object holds a set of 2D mapped pixels where every pixel value can have multiple channels. This object can be declared as a resource using one of the available data and color types. Every bitmap needs to have a width and height associated with it. When no settings are provided the bitmap contains: 512x512, RGB8 bit pixels. This object wraps a Bitmap and allocates the bitmap resource on init(). The properties associated with the bitmap are set when initialized from texture or file.

Inheritance diagram for Bitmap:

Collaboration diagram for Bitmap:

Constructor & Destructor Documentation

~Bitmap()

virtual ~Bitmap ( )

virtual

Member Function Documentation

empty()

bool empty

(

)

const

Returns

if the bitmap is empty This is the case when the bitmap has not been initialized

getColorType()

rtti::TypeInfo getColorType

(

)

const

Returns

the type of color associated with this bitmap

getColorValue() [1/2]

RColor< Type > getColorValue	(	int	x,
		int	y,
		nap::EColorChannel	channel
	)		const

Returns a copy of the color specified by channel. This call does not convert incompatible types and asserts when the underlying data types don't match

Parameters

x	the horizontal coordinate of the pixel
y	the vertical coordinate of the pixel
channel	the color channel to get the value for

Returns

copy of the color value specified by channel

getColorValue() [2/2]

void getColorValue	(	int	x,
		int	y,
		nap::EColorChannel	channel,
		RColor< Type > &	outValue
	)		const

Populates outValue with the color specified by channel. This call does not convert incompatible types and asserts when the underlying data types don't match.

Parameters

x	the horizontal coordinate of the pixel
y	the vertical coordinate of the pixel
channel	the color channel to get the value for
outValue	copy of the color value specified by channel

getData() [1/2]

void* getData

(

)

Returns

a pointer to the underlying data in memory

getData() [2/2]

const void* getData

(

)

const

Returns

a pointer to the underlying data in memory

getHeight()

int getHeight

(

)

const

Returns

the height of the bitmap, 0 when not initialized

getNumberOfChannels()

int getNumberOfChannels

(

)

const

Returns

number of color channels associated with this bitmap

getPixel() [1/2]

T getPixel	(	int	x,
		int	y
	)		const

return a color of type T with the color values of a pixel. This call converts the pixel data if necessary. Note that this call can be slow when iterating over the bitmap! Use the makePixel / getPixel combination above for faster results. Use this call to get a copy of the color values in the desired color format T where T can not be a color that points to external value in memory, ie: RGBColorData8 etc. Valid values for T are RGBColor8, RColorFloat etc.

Parameters

x	the horizontal coordinate of the pixel
y	the vertical coordinate of the pixel

Returns

color of pixel at given coordinates

getPixel() [2/2]

void getPixel	(	int	x,
		int	y,
		BaseColor &	outPixel
	)		const

Retrieves the color of a pixel at the x and y pixel coordinates. The color is a copy of the pixel values in the bitmap. The result is stored in outPixel. outPixel needs to be created using makePixel(), this ensures the right number of channels and bitmap value type of the color. outPixel needs to own it's color data and can't point to values in memory. This call does not convert outPixel if the types don't match. In that case this call will assert. To convert the fetched data call .convert() on outPixel.

// Create the pixel that will hold the original color value
auto source_color = mBitmap.makePixel();
 
// Create color that will hold the converted color values
RGBColor8 converted_color;
 
while(...)
{
       // retrieve pixel value and convert into requested color
       mBitmap.getPixel(x, y, *source_color);
       source_color->convert(converted_color);
}

Parameters

x	the horizontal pixel coordinate
y	the vertical pixel coordinate
outPixel	the pixel created using makePixel()

getRGBAColor() [1/2]

RGBAColor< Type > getRGBAColor	(	int	x,
		int	y
	)		const

Returns a copy of the RGBA values of a pixel as a color. This call asserts when the bitmap doesn't have 4 channels. This call does not convert incompatible types and asserts when the data types don't match.

Parameters

x	the horizontal coordinate of the pixel
y	the vertical coordinate of the pixel

Returns

the RGBA color values of the pixel at the requested coordinates

getRGBAColor() [2/2]

void getRGBAColor	(	int	x,
		int	y,
		RGBAColor< Type > &	outColor
	)		const

Populates outColor with the RGBA values of a pixel. This call asserts when the bitmap doesn't have 4 channels. This call does not convert incompatible types and asserts when the data types don't match.

Parameters

x	the horizontal coordinate of the pixel
y	the vertical coordinate of the pixel
outColor	the RGBA color values of the pixel at the requested coordinates

getRGBColor() [1/2]

RGBColor< Type > getRGBColor	(	int	x,
		int	y
	)		const

Returns the RGB values of a pixel as a color. This call asserts when the bitmap doesn't have 3 channels. This call does not convert incompatible types and asserts when the data types do not match.

Parameters

x	the horizontal coordinate of the pixel
y	the vertical coordinate of the pixel

Returns

the RGB values of a pixel as a color

getRGBColor() [2/2]

void getRGBColor	(	int	x,
		int	y,
		RGBColor< Type > &	outColor
	)		const

Populates outColor with the RGB values of a pixel. This call asserts when the bitmap doesn't have 3 channels. This call does not convert incompatible types and asserts when the data types do not match.

Parameters

x	the horizontal coordinate of the pixel
y	the vertical coordinate of the pixel
outColor	the RGB color values of the pixel at the requested coordinates

getSizeInBytes()

size_t getSizeInBytes

(

)

const

getSize

Returns total number of bytes associated with this image

getWidth()

int getWidth

(

)

const

Returns

the width of the bitmap, 0 when not initialized

init()

virtual bool init ( utility::ErrorState &  errorState )

overridevirtual

The bitmap is initialized using it's associated properties. This means memory is allocated based on the width, height, number of channels and type of the bitmap. Failing to call init will leave the underlying bitmap empty.

Parameters

errorState

contains the error message when initialization fails

Reimplemented from Object.

Reimplemented in BitmapFromFile.

initFromDescriptor()

void initFromDescriptor

(

const SurfaceDescriptor &

surfaceDescriptor

)

Initializes this bitmap based on the provided settings. Memory is allocated but the pixel data is NOT copied over

Parameters

surfaceDescriptor

the settings used to initialize this texture.

initFromFile()

virtual bool initFromFile ( const std::string &  path, nap::utility::ErrorState &  errorState  )

virtual

Initializes this bitmap from file. The settings associated with this bitmap will match the settings loaded from file. If you want to manually allocate pixel data call init() without a path.

Parameters

path	the path to the image on disk to load
errorState	contains the error if the image could not be loaded

Returns

if the bitmap loaded successfully

makePixel()

std::unique_ptr<BaseColor> makePixel

(

)

const

Creates a color that is compatible with the data stored in this bitmap. This is a utility function that works in conjunction with getPixel() and setPixel(). Making the pixel once before iterating over all the values in this map avoids unnecessary allocations.

// Create the pixel that will hold the original color value
auto source_color = mBitmap.makePixel();
 
// Create color that will hold the converted color values
RGBColor8 converted_color;
 
while(...)
{
       // retrieve pixel value and convert into requested color
       mBitmap.getPixel(x, y, *source_color);
       source_color->convert(converted_color);
}

Returns

a new pixel as a color that matches the amount of channels and data type of this bitmap

save()

bool save	(	const std::string &	path,
		utility::ErrorState &	errorState
	)

Writes this bitmap to the given location on disk with the specified image format

Parameters

path	the path including filename and image extension of the output file e.g. "targetFolder/MyOutputFile.png"
errorState	contains the error if the image could not be saved to disk

setPixel()

void setPixel	(	int	x,
		int	y,
		const BaseColor &	color
	)

Sets the color of a pixel at the x and y pixel coordinates. This call does not convert the color if the value types don't match, best to convert the color client side. It's allowed to give an input color can that has less color channels than a pixel in the bitmap. This means that an RGB color can be set to a pixel of an RGBA bitmap. To ensure matching data use makePixel() to create a pixel that is compatible with this bitmap. You can use the color conversion methods to convert any color into this bitmap's color space. This call asserts when the color types don't match and when the input color doesn't own it's data: points to values in memory.

Parameters

x	the horizontal pixel coordinate
y	the vertical pixel coordinate
color	the new pixel color

setPixelColor()

void setPixelColor	(	int	x,
		int	y,
		const T &	color
	)

Sets the color of a pixel at the x and y pixel coordinates. This call converts the incoming color when the underlying data types do not match. The given color can also point to values in memory, ie: the color doesn't own it's data but the data it owns is copied over. It's not recommended to use this call in a loop when you know it needs to convert the color. It's allowed to give an input color can that has less color channels than a pixel in the bitmap. This means that an RGB color can be set to a pixel of an RGBA bitmap.

Parameters

x	the horizontal pixel coordinate
y	the horizontal pixel coordinate
color	the new pixel color

Member Data Documentation

mBitmapUpdated

Signal mBitmapUpdated

Triggered by Texture2D when this bitmap is updated

mSurfaceDescriptor

SurfaceDescriptor mSurfaceDescriptor

These properties are read when initializing the bitmap as a resource These properties are set when initializing the bitmap from file or texture