TSLDirectImportRaster Class Reference

Detailed Description

This class manages an image buffer, for use with import/export functionality

Classes
struct	RasterChannelData
union	RasterChannelData.m_value

Public Types
enum	RasterType { RasterTypeUnknown , RasterTypeRGB , RasterTypeGreyScale , RasterTypePaletted }
	The type of raster. More...
enum	RasterChannelFormat {   RasterChannelFormatUnknown , RasterChannelFormatUInt8 , RasterChannelFormatUInt16 , RasterChannelFormatInt16 ,   RasterChannelFormatUInt32 , RasterChannelFormatInt32 , RasterChannelFormatFloat32 , RasterChannelFormatFloat64 }
	The format of the colour channels. More...
enum	RasterChannelDefinition {   RasterChannelDefinitionUnknown , RasterChannelDefinitionPaletted , RasterChannelDefinitionGreyScale , RasterChannelDefinitionRed ,   RasterChannelDefinitionGreen , RasterChannelDefinitionBlue , RasterChannelDefinitionAlpha }
	How a channel within the raster should be interpreted. More...

Public Member Functions
	TSLDirectImportRaster ()
	Constructor.
void	destroy ()
	Destroy this object.
bool	allocate (const TSLMUExtent &extent, uint32_t width, uint32_t height, uint32_t originX, uint32_t originY, uint32_t originWidth, uint32_t originHeight, uint8_t channels=3, TSLDirectImportRaster::RasterType rasterType=TSLDirectImportRaster::RasterTypeRGB, TSLDirectImportRaster::RasterChannelFormat channelFormat=TSLDirectImportRaster::RasterChannelFormatUInt8, uint8_t redChannelOffset=0, uint8_t greenChannelOffset=1, uint8_t blueChannelOffset=2, uint8_t alphaChannelOffset=3)
bool	valid () const
uint32_t	width () const
	Query the width of the image in pixels.
uint32_t	height () const
	Query the height of the image in pixels.
uint32_t	originX () const
	Query the X component of the raster's origin in the original data, in pixels.
uint32_t	originY () const
	Query the Y component of the raster's origin in the original data, in pixels.
uint32_t	originWidth () const
	Query the width of the region this raster represents in the original data.
uint32_t	originHeight () const
	Query the height of the region this raster represents in the original data.
uint8_t	channels () const
	Query the number of channels in the image.
RasterType	type () const
	Query the raster type.
RasterChannelFormat	channelFormat () const
	Query the raster channel format.
uint8_t	redChannelOffset () const
	Query the offset for the red channel.
uint8_t	greenChannelOffset () const
	Query the offset for the green channel.
uint8_t	blueChannelOffset () const
	Query the offset for the blue channel.
uint8_t	alphaChannelOffset () const
	Query the offset for the alpha channel.
uint32_t	paletteSize () const
	Query the size of the palette.
void	paletteSize (uint32_t size)
bool	getPalette (uint32_t index, TSLRGBA &rgba) const
bool	setPalette (uint32_t index, const TSLRGBA &rgba)
const void *	data () const
void *	data ()
void	deleteData ()
uint32_t	channelStride () const
	The size of each channel in bytes.
uint32_t	pixelStride () const
	The size of each pixel in bytes.
uint32_t	rowStride () const
	The size of each row in bytes.
bool	getChannelData (uint32_t x, uint32_t y, uint8_t index, RasterChannelData &data) const
bool	setChannelData (uint32_t x, uint32_t y, uint8_t index, const RasterChannelData &data)
uint32_t	dataSize () const
	Query the size of the image buffer in bytes.
bool	getNoDataValue (uint32_t index, RasterChannelData &val) const
bool	setNoDataValue (uint32_t index, const RasterChannelData &val)
TSLMUExtent &	extent ()
void *	operator new (size_t size) TSL_NO_THROW
void *	operator new (size_t size, char *filename, int line)

---

Class Documentation

TSLDirectImportRaster::RasterChannelData.m_value

union TSLDirectImportRaster::RasterChannelData.m_value

The raster channel data The contents of m_format determines which of these values must be read.

Class Members
float	m_float32	RasterChannelFormatFloat32.
double	m_float64	RasterChannelFormatFloat64.
int16_t	m_int16	RasterChannelFormatInt16.
int32_t	m_int32	RasterChannelFormatInt32.
uint16_t	m_uint16	RasterChannelFormatUInt16.
uint32_t	m_uint32	RasterChannelFormatUInt32.
uint8_t	m_uint8	RasterChannelFormatUInt8.

Member Enumeration Documentation

RasterChannelDefinition

enum TSLDirectImportRaster::RasterChannelDefinition

How a channel within the raster should be interpreted.

Enumerator
RasterChannelDefinitionUnknown	The channel contains unknown data.
RasterChannelDefinitionPaletted	The channel contains indexes to the palette.
RasterChannelDefinitionGreyScale	The channel contains greyscale data.
RasterChannelDefinitionRed	Red.
RasterChannelDefinitionGreen	Green.
RasterChannelDefinitionBlue	Blue.
RasterChannelDefinitionAlpha	Alpha.

RasterChannelFormat

enum TSLDirectImportRaster::RasterChannelFormat

The format of the colour channels.

Enumerator
RasterChannelFormatUnknown	The colour channel format is unknown.
RasterChannelFormatUInt8	Each colour channel is an unsigned 8 bit integer (uint8_t) This format should be used for paletted images
RasterChannelFormatUInt16	Each colour channel is an unsigned 16 bit integer (uint16_t)
RasterChannelFormatInt16	Each colour channel is a signed 16 bit integer (int16_t)
RasterChannelFormatUInt32	Each colour channel is an unsigned 32 bit integer (uint32_t)
RasterChannelFormatInt32	Each colour channel is a signed 32 bit integer (int32_t)
RasterChannelFormatFloat32	Each colour channel is a 32 bit floating point value (float)
RasterChannelFormatFloat64	Each colour channel is a 64 bit floating point value (double)

RasterType

enum TSLDirectImportRaster::RasterType

The type of raster.

Enumerator
RasterTypeUnknown	Unknown type.
RasterTypeRGB	The default raster type This type covers all non-greyscale images including RGB/RGBA etc, and any single-channel image which is not greyscale. Values in each channel represent the values of each colour. The channels may be in any order, and should have the rgba channel offsets set accordingly.
RasterTypeGreyScale	A greyscale image Greyscale images may only have 1 channel Values in the channel represent the value of a pixel
RasterTypePaletted	A paletted image Paletted images may only have 1 channel Values in the channel represent an entry in the palette

Constructor & Destructor Documentation

TSLDirectImportRaster()

TSLDirectImportRaster::TSLDirectImportRaster

(

)

Constructor.

Member Function Documentation

allocate()

bool TSLDirectImportRaster::allocate	(	const TSLMUExtent &	extent,
		uint32_t	width,
		uint32_t	height,
		uint32_t	originX,
		uint32_t	originY,
		uint32_t	originWidth,
		uint32_t	originHeight,
		uint8_t	channels = 3,
		TSLDirectImportRaster::RasterType	rasterType = TSLDirectImportRaster::RasterTypeRGB,
		TSLDirectImportRaster::RasterChannelFormat	channelFormat = TSLDirectImportRaster::RasterChannelFormatUInt8,
		uint8_t	redChannelOffset = 0,
		uint8_t	greenChannelOffset = 1,
		uint8_t	blueChannelOffset = 2,
		uint8_t	alphaChannelOffset = 3 )

Allocate the image buffer.

Any existing image buffer will be deleted. Any existing palette will be cleared.

The default arguments will create an RGB image, with 3 unsigned 8 bit colour channels (24 bit RGB).

Loading Mask data from a File

After raster data has been returned from the driver it may be masked using a separate mask file. This file must be a 1-bit mask, the same size as the source data.

In order to support this the driver must provide additional parameters when allocating the raster in order to scale/tile the mask accordingly.

The originX and originY arguments specify the offset of the allocated raster in relation to the top-left of the source data. When returning an overview this is the value before scaling/adjustments for the overview.

The originWidth and originHeight arguments specify the region in the source data this raster relates to. For non-overview rasters this will be the same as the width and height parameters. For overview raster this is the width and height of the returned region, before scaling/adjustments for the overview.

Raster type specific

• The colour channel offsets will only be used if rasterType is RasterTypeRGB.
• The palette will not be used if rasterType is RasterTypeRGB
• Paletted images may only have channelFormat == RasterChannelFormalUInt8
• The allocated buffer will be initialised with the value 0x00.

Parameters

extent	Extent of the image in the input/data's coordinate system.
width	Width of the image in pixels.
height	Height of the image in pixels.
originX	The X component of this raster's origin in the original data, in pixels.
originY	The Y component of this raster's origin in the original data, in pixels.
originWidth	The width of this raster in the original data.
originHeight	The height of this raster in the original data.
channels	The number of channels in the image.
rasterType	The type of the image
redChannelOffset	Offset of the red channel, from the start of each pixel.
greenChannelOffset	Offset of the green channel, from the start of each pixel.
blueChannelOffset	Offset of the blue channel, from the start of each pixel.
alphaChannelOffset	Offset of the alpha channel, from the start of each pixel.

Returns

true if the buffer was allocated, false otherwise

alphaChannelOffset()

uint8_t TSLDirectImportRaster::alphaChannelOffset

(

)

const

Query the offset for the alpha channel.

blueChannelOffset()

uint8_t TSLDirectImportRaster::blueChannelOffset

(

)

const

Query the offset for the blue channel.

channelFormat()

RasterChannelFormat TSLDirectImportRaster::channelFormat

(

)

const

Query the raster channel format.

channels()

uint8_t TSLDirectImportRaster::channels

(

)

const

Query the number of channels in the image.

channelStride()

uint32_t TSLDirectImportRaster::channelStride

(

)

const

The size of each channel in bytes.

data() [1/2]

void * TSLDirectImportRaster::data

(

)

Query a pointer to the image buffer

The start of the buffer corresponds to the top-left of the image The format of the buffer is defined by the arguments passed to allocate

data() [2/2]

const void * TSLDirectImportRaster::data

(

)

const

Query a pointer to the image buffer

The start of the buffer corresponds to the top-left of the image The format of the buffer is defined by the arguments passed to allocate

dataSize()

uint32_t TSLDirectImportRaster::dataSize

(

)

const

Query the size of the image buffer in bytes.

deleteData()

void TSLDirectImportRaster::deleteData

(

)

Delete the image buffer

This method may be called to delete the image buffer, in order to reduce memory usage.

After calling this method valid() will return false, however all other data such as image dimensions and extent will remain unmodified.

destroy()

void TSLDirectImportRaster::destroy

(

)

Destroy this object.

extent()

TSLMUExtent & TSLDirectImportRaster::extent

(

)

Query the extent of the image

Returns

The images extent in the input/data's coordinate system

getChannelData()

bool TSLDirectImportRaster::getChannelData	(	uint32_t	x,
		uint32_t	y,
		uint8_t	index,
		RasterChannelData &	data ) const

Query data from a raster channel

Note

This function will be much slower than accessing the data buffer directly

Parameters

x	Horizontal pixel offset from the top-left
y	Vertical pixel offset from the top-left
index	Channel index, as passed to allocate
data	Storage for the returned value

Returns

true if data was populated, false otherwise

getNoDataValue()

bool TSLDirectImportRaster::getNoDataValue	(	uint32_t	index,
		RasterChannelData &	val ) const

Query the 'no data' value for a channel

This value may be different for each channel The Direct Import SDK will ignore any pixel which matches one of these values.

Parameters

index	The channel offset, as passed to allocate
val	Storage for the 'no data' value

Returns

true if a value was present, false otherwise

getPalette()

bool TSLDirectImportRaster::getPalette	(	uint32_t	index,
		TSLRGBA &	rgba ) const

Query an entry from the palette

Parameters

index	The palette index to query
rgba	Will be set to the palette entry

Returns

true if the palette was read, false otherwise

greenChannelOffset()

uint8_t TSLDirectImportRaster::greenChannelOffset

(

)

const

Query the offset for the green channel.

height()

uint32_t TSLDirectImportRaster::height

(

)

const

Query the height of the image in pixels.

operator new() [1/2]

void * TSLDirectImportRaster::operator new

(

size_t

size

)

Overridden allocation to redirect to MapLink

operator new() [2/2]

void * TSLDirectImportRaster::operator new	(	size_t	size,
		char *	filename,
		int	line )

When included in an MFC application in debug mode, the debug new expects this to be here. Override it and return the same as the normal one. The library must include it when compiled in release mode, since the user's application may be in debug mode.

originHeight()

uint32_t TSLDirectImportRaster::originHeight

(

)

const

Query the height of the region this raster represents in the original data.

originWidth()

uint32_t TSLDirectImportRaster::originWidth

(

)

const

Query the width of the region this raster represents in the original data.

originX()

uint32_t TSLDirectImportRaster::originX

(

)

const

Query the X component of the raster's origin in the original data, in pixels.

originY()

uint32_t TSLDirectImportRaster::originY

(

)

const

Query the Y component of the raster's origin in the original data, in pixels.

paletteSize() [1/2]

uint32_t TSLDirectImportRaster::paletteSize

(

)

const

Query the size of the palette.

paletteSize() [2/2]

void TSLDirectImportRaster::paletteSize

(

uint32_t

size

)

Set the size of the palette

New palette entries will be initialised to black, with an alpha of 0xff

pixelStride()

uint32_t TSLDirectImportRaster::pixelStride

(

)

const

The size of each pixel in bytes.

redChannelOffset()

uint8_t TSLDirectImportRaster::redChannelOffset

(

)

const

Query the offset for the red channel.

rowStride()

uint32_t TSLDirectImportRaster::rowStride

(

)

const

The size of each row in bytes.

setChannelData()

bool TSLDirectImportRaster::setChannelData	(	uint32_t	x,
		uint32_t	y,
		uint8_t	index,
		const RasterChannelData &	data )

Set data for a raster channel

Note

This function will be much slower than accessing the data buffer directly

Parameters

x	Horizontal pixel offset from the top-left
y	Vertical pixel offset from the top-left
index	Channel index, as passed to allocate
data	The value to set. data.m_format must match the format of the image.

Returns

true if the data was set, false otherwise

setNoDataValue()

bool TSLDirectImportRaster::setNoDataValue	(	uint32_t	index,
		const RasterChannelData &	val )

Set the 'no data' value for a channel

This value may be different for each channel The Direct Import SDK will ignore any pixel which matches one of these values.

Parameters

index	The channel offset, as passed to allocate
val	The 'no data' value for the channel

Returns

true if the value was set, false otherwise

setPalette()

bool TSLDirectImportRaster::setPalette	(	uint32_t	index,
		const TSLRGBA &	rgba )

Set an entry in the palette

Parameters

index	The palette index to query
rgba	The rgba value to set

Returns

true if the palette entry was set, false otherwise

type()

RasterType TSLDirectImportRaster::type

(

)

const

Query the raster type.

valid()

bool TSLDirectImportRaster::valid

(

)

const

Query whether the object is valid

A raster is considered valid if a buffer has been allocated.

Returns

true if the raster is valid, false otherwise

width()

uint32_t TSLDirectImportRaster::width

(

)

const

Query the width of the image in pixels.