ImageMapTile Class Reference

This object holds data for a region of a particular channel.
A tile has a fixed size, and is square.
Its buffer contains values for one channel only, for example R, G , B, Alpha or Z (depth). For filtering purpose we store not only the "visible" pixels of the region covered by the tile, but extra rows and columns (on top, left, right and bottom) as well. These extra pixels are copied from the tiles surrounding the current one.
HHH...HHH
HVV...VVH
HVV...VVH
...
HVV...VVH
HVV...VVH
HHH...HHH
These hidden pixels are managed internally, there is no need to take them into account when evaluating and writing in the tile: offset are automatically applied.
If a tile is uniform (ie has the same value in all its pixels), the data buffer is freed to save space, and the value is stored in a simple float variable. More...

Public Types
typedef void(*	GetFilteredColorCallBack )(const ImageMapTile &, const float &, const float &, float &)
typedef const float(*	GetColorCallBack )(const ImageMapTile &, const int &)
typedef void(*	ConvertColorCallBack )(unsigned char *outputBuffer, const float &colorValue)
typedef void(*	BlitCallBack )(unsigned char *, const unsigned char *, const unsigned int &)

Public Member Functions
const ImageMapChannel &	get_channel () const
	Returns a reference to the parent channel.
bool	is_dirty () const
	Returns whether the tile is dirty or not.
void	set_dirty_pixel_count (int count)
	Sets the dirtiness pixel count of the tile.
const int	get_x () const
	Returns the X coordinate of the tile (in pixels).
const int	get_y () const
	Returns the Y coordinate of the tile (in pixels).
unsigned int	get_width () const
	Returns the width of the tile.
unsigned int	get_height () const
	Returns the width of the tile.
const unsigned int	get_pixel_count () const
	Returns the number of pixels stored in the tile.
const int &	get_tile_x () const
	Returns the X coordinate of the tile (in tiles).
const int &	get_tile_y () const
	Returns the Y coordinate of the tile (in tiles).
const int	get_line_size () const
	Returns the length of a line in the buffer. Used to compute offsets in the buffer.
const int	get_line_size_bytes () const
bool	has_data_buffer () const
	Returns whether the tile has a buffer allocated (ie the tile is not uniform).
const GMathVec2f	get_coordinates_tile ()
	Returns the coordinates of the tile (in tiles).
const GMathBbox2f	get_bounding_box_tile ()
	Returns the bounding box of the tile (in tiles).
const ImagePixel::BitDepth &	get_bit_depth () const
	Returns the pixel bit depth.
const ImagePixel::BitType &	get_bit_type () const
	Returns the pixel bit type.
const unsigned int	get_channel_index () const
	Returns the index of the parent channel.
const unsigned int	get_count () const
	Returns the number of pixels stored in the buffer.
const unsigned char *	get_data () const
	Returns a const pointer to the data buffer. May be null if the tile is uniform.
void	get_pixel_nearest (float x, float y, float &color) const
	Pixel evaluation without filtering.
void	get_pixel_bilinear (const float &x, const float &y, float &color) const
	Pixel evaluation using bilinear filtering method.
float	get_color (const int &x, const int &y, bool xy_absolute=false) const
	Returns the color of the pixel at the specified coordinates.
void	get_bilinear_color (const float &x, const float &y, float &color) const
	See get_pixel_bilinear.
void	convert_color (unsigned char *output_buffer, const float &color_value) const
	Converts the float value to the data format and the tile and writes it to the buffer at the given location.
unsigned long	get_memory_size () const
	Returns the memory used by the tile.
void	clamp_values (const float &min_value, const float &max_value, const GMathVec4i &region)
	Returns the size of the buffer in memory.
void	set_data (ImageMapCtx &ctx, const int &px, const int &py, const float &value, bool xy_absolute=false)
	Sets a value for the specified coordinates.
bool	is_empty () const
	Returns true is the tile has no data: uniform with a value of 0.
void	clear (bool dirty=true, const GMathVec4i *region=0)
	Clears the tile.
void	clear_outside (bool dirty=true, const GMathVec4i *region=0)
	Clears the part of the tiles that is not in the specified region.
void	copy_buffer (const ImageMapTileHandle src)
	Fills the buffer of the current tile with data from the source.
void	blit (ImageMapCtx &ctx, unsigned char *buffer, const GMathVec4i &region, const ImagePixel::BlitMode &mode=ImagePixel::BLIT_MODE_REPLACE)
	Copies the content the source buffer in the current tile using the specified copy mode.
void	blit (ImageMapCtx &ctx, const ImageMapTileHandle tile, ImageMapCtx &src_ctx, const ImagePixel::BlitMode &mode=ImagePixel::BLIT_MODE_REPLACE)
	Copies the content of a tile from source to destination using the specified copy mode.
void	process (ImageMapCtx &ctx, ImageChannelProcess_callback process, void *user_data=0)
	Applies a process on each pixel of the tile.
float *	get_write_data (ImageMapCtx &ctx) const
	Returns a work buffer. The same buffer will be used by the update_data function. (See below)
float *	get_data (ImageMapCtx &ctx) const
	Returns a work buffer.
float *	get_data (ImageMapCtx &ctx, const int &px, const int &py, const int &size_x, const int &size_y) const
	Returns a work buffer for the region specified.
void	update_data (ImageMapCtx &ctx)
	Updates the contents of the tile using the data buffer that is stored in the specified context.
void	update_data (ImageMapCtx &ctx, const int &px, const int &py, const int &size_x, const int &size_y)
	Updates a region of the tile using the data buffer that is stored in the specified context.
bool	write_data (const float *data, const int &px, const int &py, const int &size_x, const int &size_y)
	Copies the contents of the input buffer in the tile.
const unsigned int	get_pixel_index (const int &x, const int &y) const
	Returns the pixel index for the specified coordinates.
void	fill (const float &value, const GMathVec4i *region=0)
	Set a value on the whole tile. If the tile becomes uniform, the data buffer is freed.
void	check_uniformity ()
	Check if the tile is uniform. If so, the data buffer is freed and the color value is stored aside.
void	check_uniformity_interior ()
void	clear_buffer ()
void	free_buffer ()
	Free the data buffer.
void	allocate_buffer (bool set=true)
	Allocate the data buffer.
bool	is_uniform () const
void	set_uniform ()
float	get_uniform_value () const
void	set_uniform_value (float value)

Static Public Member Functions
static void	convert_color (unsigned char *output_buffer, const float &color_value, const ImagePixel::BitDepth &bit_depth, const ImagePixel::BitType &bit_type)

Static Public Attributes
static GetFilteredColorCallBack	get_bilinear_color_func [ImagePixel::BIT_DEPTH_MAX][ImagePixel::BIT_TYPE_MAX]
static GetFilteredColorCallBack	get_bicubic_color_func [ImagePixel::BIT_DEPTH_MAX][ImagePixel::BIT_TYPE_MAX]
static GetColorCallBack	get_color_func [ImagePixel::BIT_DEPTH_MAX][ImagePixel::BIT_TYPE_MAX]
static ConvertColorCallBack	convert_color_func [ImagePixel::BIT_DEPTH_MAX][ImagePixel::BIT_TYPE_MAX]
static BlitCallBack	blit_func [ImagePixel::BLIT_MODE_MAX][ImagePixel::BIT_DEPTH_MAX][ImagePixel::BIT_TYPE_MAX]

Friends
class	ImageMapChannel
class	ImageTileFactory
class	ImageIOLoad
class	ImageIOSave
struct	MemoryPageImageMapTile

Detailed Description

This object holds data for a region of a particular channel.
A tile has a fixed size, and is square.
Its buffer contains values for one channel only, for example R, G , B, Alpha or Z (depth). For filtering purpose we store not only the "visible" pixels of the region covered by the tile, but extra rows and columns (on top, left, right and bottom) as well. These extra pixels are copied from the tiles surrounding the current one.
HHH...HHH
HVV...VVH
HVV...VVH
...
HVV...VVH
HVV...VVH
HHH...HHH
These hidden pixels are managed internally, there is no need to take them into account when evaluating and writing in the tile: offset are automatically applied.
If a tile is uniform (ie has the same value in all its pixels), the data buffer is freed to save space, and the value is stored in a simple float variable.

Member Function Documentation

void ImageMapTile::allocate_buffer

(

bool

set = true

)

Allocate the data buffer.

Parameters

set	Clear the buffer with 0's if set to true and if tile is uniform.

void ImageMapTile::blit	(	ImageMapCtx &	ctx,
		unsigned char *	buffer,
		const GMathVec4i &	region,
		const ImagePixel::BlitMode &	mode = ImagePixel::BLIT_MODE_REPLACE
	)

Copies the content the source buffer in the current tile using the specified copy mode.

Parameters

buffer	Source buffer
region	Portion of the tile to copy
mode	Copy mode.

void ImageMapTile::blit	(	ImageMapCtx &	ctx,
		const ImageMapTileHandle	tile,
		ImageMapCtx &	src_ctx,
		const ImagePixel::BlitMode &	mode = ImagePixel::BLIT_MODE_REPLACE
	)

Copies the content of a tile from source to destination using the specified copy mode.

Parameters

ctx	Unused
tile	Source tile
src_ctx	Unused
mode	Copy mode.

void ImageMapTile::check_uniformity

(

)

Check if the tile is uniform. If so, the data buffer is freed and the color value is stored aside.

Note

This feature is used to save memory space and speed up evaluation. It has no effect on render

void ImageMapTile::clamp_values	(	const float &	min_value,
		const float &	max_value,
		const GMathVec4i &	region
	)

Returns the size of the buffer in memory.

Clamp the values of the pixel between the two specified values in the requested region.

void ImageMapTile::clear	(	bool	dirty = true,
		const GMathVec4i *	region = 0
	)

Clears the tile.

Parameters

dirty	Sets the dirtiness flag of the tiles in the region to the specified value.
region	(Optional) Region to clear. The whole tile is clear if value is null.

void ImageMapTile::clear_outside	(	bool	dirty = true,
		const GMathVec4i *	region = 0
	)

Clears the part of the tiles that is not in the specified region.

Parameters

dirty	Sets the dirtiness flag of the tiles that are cleared to the specified value.
region	Region to spare. If null, the whole tile is cleared.

float ImageMapTile::get_color	(	const int &	x,
		const int &	y,
		bool	xy_absolute = false
	)		const

Returns the color of the pixel at the specified coordinates.

Parameters

x,y	Pixel coordinates.
xy_absolute	If set to true, tells the function that the coordiantes are pixel coordinates in the image. In this case the coordinates of the tiles will be deduced before reading the data.

float * ImageMapTile::get_data

(

ImageMapCtx &

ctx

)

const

Returns a work buffer.

Note

Unlike the get_write_data function, the buffer returned is initialized first with the contents of the tile.

float * ImageMapTile::get_data	(	ImageMapCtx &	ctx,
		const int &	px,
		const int &	py,
		const int &	size_x,
		const int &	size_y
	)		const

Returns a work buffer for the region specified.

Note

Unlike the get_write_data function, the buffer returned is initialized first with the contents of the tile.

const unsigned int ImageMapTile::get_pixel_index ( const int &  x, const int &  y  ) const

inline

Returns the pixel index for the specified coordinates.

Note

Coordinates need to take hidden pixels into account.

float * ImageMapTile::get_write_data

(

ImageMapCtx &

ctx

)

const

Returns a work buffer. The same buffer will be used by the update_data function. (See below)

Note

Typically if you need to update a region of the tile, you will need to call get_write_data, write/work with the buffer returned, then call update_data using the same ImageMapCtx to update the contents of the tile.
The buffer returned is not initialized with the tile's content.

void ImageMapTile::process	(	ImageMapCtx &	ctx,
		ImageChannelProcess_callback	process,
		void *	user_data = 0
	)

Applies a process on each pixel of the tile.

Parameters

process	function callback that will be called on each pixel of the tile.
user_data	custom data that can be used to store parameters.

void ImageMapTile::set_data	(	ImageMapCtx &	ctx,
		const int &	px,
		const int &	py,
		const float &	value,
		bool	xy_absolute = false
	)

Sets a value for the specified coordinates.

Parameters

ctx	Context (unused)
px,py	Pixel coordinates.
value	Value to convert and write in the buffer.
xy_absolute	If set to true, tells the function that the coordiantes are pixel coordinates in the image. In this case the coordinates of the tiles will be deduced before writing the data.

bool ImageMapTile::write_data	(	const float *	data,
		const int &	px,
		const int &	py,
		const int &	size_x,
		const int &	size_y
	)

Copies the contents of the input buffer in the tile.

Parameters

data	Input buffer.
px,py,width,height	Region of the tile in which the function will write.

Returns

true if this write has cleaned the tile. ie. dirty pixel count is now 0.

Note

The function will copy size_x * size_y pixels from the input buffer.