ImageMapChannel Class Reference

This class implements a image channel. It stores data, using a list of tiles, for one color, or custom data.
. More...

Inheritance diagram for ImageMapChannel:

Public Member Functions
int	get_tile_data_size () const
int	get_tile_pixel_count () const
int	get_tile_internal_size () const
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 CoreString &	get_name () const
	Returns the name of the chahnel.
const unsigned int &	get_index () const
	Returns the index of the channel in the ImageMap.
const ImageMap::KnownChannels &	get_id () const
	Returns the ID of the channel, if applicable. Returns -1 for a custom channel.
const ImageMap &	get_image () const
	Returns an reference on the channel parent's ImageMap.
const GMathBbox2i &	get_bounding_box () const
	Returns the bounding box of the channel, ie the area or data that has been written.
void	set_bounding_box (const GMathBbox2i &bbox)
	Sets the bounding box of the channel, ie the area or data that has been written.
virtual size_t	get_memory_size () const override
	Returns memory footprint of the channel.
void	clear_tiles ()
	Deletes all the tiles of the channel.
void	clear ()
	Deletes all the tiles of the channel and resets the bounding box.
void	clear (const GMathVec4i &region, unsigned int tile_size, bool dirty=true, const bool &update_bbox=true)
	Clears a specified region of the channel.
void	clear (const ImagePixel::BitDepth &bdepth, const ImagePixel::BitType &bit_type)
	Removes all tiles and sets a new BitDepth and a new BitType, that will be used later for tile creation.
void	clear_outside (const GMathVec4i &region, bool dirty=true)
	Clears all tiles outside the specified region.
void	reset ()
	Resets the channel. Remove all tiles. Resets all parameters like data formats, etc...
void	on_update_visible (const GMathBbox2i &old_region, const GMathBbox2i &new_region)
	Updates the image channels after the visible part of the region has been modified.
void	set_dirty (const GMathVec4i &region)
	Sets the dirtiness flag of the tiles in the specified region to true.
void	set_dirty_outside (const GMathVec4i &region)
	Sets the dirtiness flag of the tiles outside the specified region to true.
void	invalidate ()
	Invalidates the current channel. Data stored is considered dirty.
bool	is_invalid () const
void	dirty_border (const GMathVec4i &region)
	Dirty all the tiles of all channels that intersect the region.
void	convert_buffer (const float *in_data, unsigned char *out_buffer, const GMathVec4i &region)
	Converts a float buffer to the pixel format of the current channel.
void	create_tiles (const GMathVec4i &region, CoreVector< ImageMapTileHandle > *tiles_to_process=0, const float &value=0)
	Creates the tiles in the specified region if they don't exist.
void	fill_tiles (const unsigned char *data, const GMathVec4i &region, bool process_region_edges=true)
	Fills a region of the channel using raw data.
void	fill_tiles (const float *data, const GMathVec4i &region, bool process_region_edges=true)
	Fills a region of the channel using float data.
void	fill_uniform_value (const float &value, const GMathVec4i &region)
	Fills a region with a single value.
void	fill_clean_data (const ImageMapChannel &src_chan, const GMathVec4i &region)
	Copy the data from the clean tiles of the source image channel.
void	clamp_values (const float &min_value, const float &max_value, const GMathVec4i &region)
	Fills a region with a single value.
void	create_float_buffer_with_border (ImageEvalContext *ctx, const GMathVec4i &req_region, float *buffer) const
	Creates a float buffer representing the data for the specified region. Extra rows and columns are added on the edges of the region for bilinear filtering.
void	create_float_buffer (ImageEvalContext &context, const GMathVec4i &region, float *out_buffer, unsigned int channel_size, const ImagePixel::RepeatMode &x_mode, const ImagePixel::RepeatMode &y_mode) const
	Creates a float buffer representing the data for the specified region. If the requested region is bigger than the canvas of the image, the buffer will be filled using the repeat mode supplied.
float *	create_float_buffer (ImageEvalContext *ctx, const GMathVec4i &region, float *buffer=0) const
	Creates a float buffer representing the data for the specified region. Parts of the region that are outside of the image canvas will not be filled.
float *	create_float_buffer (ImageEvalContext *ctx, const int &x, const int &y, const unsigned int &width, const unsigned int &height, float *buffer=0) const
	See create_float_buffer above.
unsigned int	get_tile_size () const
	Returns the tile size (= width, height) for the current channel.
const unsigned int &	get_tile_count () const
	Returns the number of tiles that have been instanciated in the current channel.
unsigned int	get_tile_index (const int &px, const int &py) const
	Returns the index of the tile at the specified coordinates.
void	get_pixel_coordinates (float in_x, float in_y, float &out_x, float &out_y, const ImagePixel::RepeatMode &x_mode, const ImagePixel::RepeatMode &y_mode, const GMathVec4i &canvas) const
	Computes coordinates for a given pixel, depending on region, repeat mode.
bool	is_tile_compatible (const ImageMapChannel &channel) const
	Returns whether the current tile is compatible with the specified channel. To be compatible, it must have the size data format, the same tile size, so that copy/blending/etc... functions can work with data from the current tile and data from the given channel.
ImageMapTileHandle	get_tile (const unsigned int &index) const
	Returns the tile at the specified index.
ImageMapTileHandle	get_tile (const int &px, const int &py, ImageMapTileHandle *last_tile=0, bool create=false) const
	Returns the tile for the given coordinates.
ImageMapTileHandle	get_tile (ImageEvalContext &context, const int &px, const int &py) const
	Returns the tile for the given coordinates.
void	get_tiles (CoreVector< ImageMapTileHandle > &array, const GMathVec4i &region, bool clean_only=false) const
	Returns a list of all the tiles existing in the specified region.
void	blit (char *buffer, const GMathVec4i &region, const ImagePixel::BlitMode &mode=ImagePixel::BLIT_MODE_REPLACE)
	Copies the content the source buffer in the current channel using the specified copy mode.
void	blit (ImageMapCtx &ctx, char *buffer, const GMathVec4i &region, const ImagePixel::BlitMode &mode=ImagePixel::BLIT_MODE_REPLACE)
	See function above.
void	blit (const ImageMapChannel &channel, const GMathVec4i &region, const ImagePixel::BlitMode &mode=ImagePixel::BLIT_MODE_REPLACE)
	Copies the content of a tile from source to destination using the specified copy mode.
void	blit (ImageMapCtx &ctx, const ImageMapChannel &channel, ImageMapCtx &src_ctx, const GMathVec4i &region, const ImagePixel::BlitMode &mode=ImagePixel::BLIT_MODE_REPLACE)
	See function above.
void	process (ImageChannelProcess_callback process, void *user_data=0)
	Apploes a process on each pixel of the image.
void	process (ImageMapCtx &ctx, ImageChannelProcess_callback process, void *user_data=0, const GMathVec4i *region=0)
	Applies a process on each pixel of the image in the specified region.
void	get_pixel_nearest (ImageEvalContext &context, float x, float y, const GMathVec4i &canvas, float &color, const ImagePixel::RepeatMode &x_mode=ImagePixel::DEFAULT, const ImagePixel::RepeatMode &y_mode=ImagePixel::DEFAULT) const
	Returns the value of the pixel at the given coordinates.
void	get_pixel_bilinear (ImageEvalContext &context, const float &x, const float &y, const GMathVec4i &canvas, float &color, const ImagePixel::RepeatMode &x_mode=ImagePixel::DEFAULT, const ImagePixel::RepeatMode &y_mode=ImagePixel::DEFAULT) const
	Returns the value of the pixel at the given coordinates, using bilinear filtering.
bool	get_dirty_tiles (const GMathVec4i &region, CoreArray< ImageMapTileHandle > &sorted_tiles, CoreArray< bool > &dirtiness_flag, const unsigned int &items_count)
	Returns a list of dirty tiles for the specified region.
void	get_sorted_tiles (const GMathVec4i &region, CoreArray< ImageMapTileHandle > &sorted_tiles, const unsigned int &items_count, bool allow_empty=true)
	Returns a sorted list of tiles pointers for the specified region.
bool	copy_from (const ImageMapChannel &channel, const GMathVec4i *region=0, const bool &keep_name=false)
	Copies data fromo another channel.
bool	fill_from (const ImageMapChannel &sourcechannel, const GMathVec4i &src_data_region, const GMathVec4i &dest_data_region)
	Fills a channel using the content of the source channel.
void	finalize (ImageEvalContext &context, const GMathVec4i &region, const bool &set_clean=true)
	Fill tiles region edges and check tile uniformity.
void	get_clean_tiles (const GMathVec4i &region, CoreArray< ImageMapTileHandle > &sorted_tiles, const unsigned int &items_count)
	Returns a list of clean tiles for the specified region.
unsigned long long &	get_timestamp ()
unsigned long long &	get_component_id ()
Public Member Functions inherited from CoreBaseObject
bool	is_kindof (const CoreBaseObject &object) const
CoreString	get_class_info_name () const
const unsigned long &	get_class_info_id () const
virtual bool	is_kindof (const CoreClassInfo &cinfo) const
virtual const CoreClassInfo &	get_class_info () const
template<class T >
T *	cast ()
template<class T >
const T *	cast () const
Public Member Functions inherited from CoreBaseType
bool	is_kindof (const CoreClassInfo &cinfo) const

Friends
class	FillFromPoolTask
class	ImageMap
class	ImageMapTile
class	ModuleImage

Additional Inherited Members
Static Public Member Functions inherited from CoreBaseObject
static const CoreClassInfo &	class_info ()
template<class T >
static T *	cast (CoreBaseObject *object)
template<class T >
static const T *	cast (const CoreBaseObject *object)

Detailed Description

This class implements a image channel. It stores data, using a list of tiles, for one color, or custom data.
.

Member Function Documentation

void ImageMapChannel::blit	(	char *	buffer,
		const GMathVec4i &	region,
		const ImagePixel::BlitMode &	mode = ImagePixel::BLIT_MODE_REPLACE
	)

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

Parameters

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

void ImageMapChannel::blit	(	const ImageMapChannel &	channel,
		const GMathVec4i &	region,
		const ImagePixel::BlitMode &	mode = ImagePixel::BLIT_MODE_REPLACE
	)

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

Parameters

source	Source channel
region	Portion of the channel to copy
mode	Copy mode.

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

Fills a region with a single value.

Note

After calling this function, all the tiles that are completely included in the specified region will be uniform, hence won't have a data buffer anymore.

void ImageMapChannel::clear	(	const GMathVec4i &	region,
		unsigned int	tile_size,
		bool	dirty = true,
		const bool &	update_bbox = true
	)

Clears a specified region of the channel.

Parameters

region	Region to clear.
tile_size	Tile size to set. If the tile size is different from the current one, all tiles will be deleted. Otherwise only the tiles in the specified region will be cleared.
dirty	Sets the dirtiness flag of the tiles in the region to the specified value.
update_bbox	Updates the bounding box of the channel using the region paramater.

void ImageMapChannel::clear_outside	(	const GMathVec4i &	region,
		bool	dirty = true
	)

Clears all tiles outside the specified region.

Parameters

region	Region to spare.
dirty	Sets the dirtiness flag of the tiles that are cleared to the specified value.

bool ImageMapChannel::copy_from	(	const ImageMapChannel &	channel,
		const GMathVec4i *	region = 0,
		const bool &	keep_name = false
	)

Copies data fromo another channel.

Parameters

channel	Source channel
region	Region to copy. If not supplied, copy all tiles.
keep_name	Whether to use the source channel name or keep the actual one.

void ImageMapChannel::create_float_buffer	(	ImageEvalContext &	context,
		const GMathVec4i &	region,
		float *	out_buffer,
		unsigned int	channel_size,
		const ImagePixel::RepeatMode &	x_mode,
		const ImagePixel::RepeatMode &	y_mode
	)		const

Creates a float buffer representing the data for the specified region. If the requested region is bigger than the canvas of the image, the buffer will be filled using the repeat mode supplied.

Parameters

context	Context used for caching and evaluation purposes
region	Region to process
out_buffer	Buffer in which data will be written. It must be created before calling the function. Its size must be equal channel_size
channel_size	Size of the data for the current channel.
x_mode,y_mode	Repeat that should be used if the requested region is bigger than the ImageCanvas.

float * ImageMapChannel::create_float_buffer	(	ImageEvalContext *	ctx,
		const GMathVec4i &	region,
		float *	buffer = 0
	)		const

Creates a float buffer representing the data for the specified region. Parts of the region that are outside of the image canvas will not be filled.

Parameters

context	Context used for caching and evaluation purposes
region	Region to process
out_buffer	Buffer in which data will be written. If supplied, its size must be at least region[2] * region[3]. If not supplied it will be instanciated in the function. Its deletion must be handled by the caller of the function.

Creates or returns a float array of the region starting at (x0, y0) and of size (width, height) When the optional buffer is specified, no buffer is allocated (no need to delete it) and the returned array is the specified buffer.

Functions used from upper classes for processing

void ImageMapChannel::create_float_buffer_with_border	(	ImageEvalContext *	ctx,
		const GMathVec4i &	req_region,
		float *	buffer
	)		const

Creates a float buffer representing the data for the specified region. Extra rows and columns are added on the edges of the region for bilinear filtering.

Note

This function is primarily used by viewers to fill display buffers. The output buffer must be instanciated before calling the function. Its size must be (region[2] + 2) * (region[3] + 2 )

void ImageMapChannel::create_tiles	(	const GMathVec4i &	region,
		CoreVector< ImageMapTileHandle > *	tiles_to_process = 0,
		const float &	value = 0
	)

Creates the tiles in the specified region if they don't exist.

Parameters

tiles_to_process	If supplied all tiles of the region are added to the array.
value	Tiles are initialised using this value.

void ImageMapChannel::dirty_border

(

const GMathVec4i &

region

)

Dirty all the tiles of all channels that intersect the region.

bool ImageMapChannel::fill_from	(	const ImageMapChannel &	sourcechannel,
		const GMathVec4i &	src_data_region,
		const GMathVec4i &	dest_data_region
	)

Fills a channel using the content of the source channel.

Parameters

sourcechannel	Source channel
src_data_region	region of the source image in which data will be read
dest_data_region	region of the destination image in which data will be written. The dest region will be filled with extra data using the EDGE repeat mode if bigger that the source data region.

void ImageMapChannel::fill_tiles	(	const unsigned char *	data,
		const GMathVec4i &	region,
		bool	process_region_edges = true
	)

Fills a region of the channel using raw data.

Parameters

data	typeless buffer containing the data to write in the channel.
region	Region to write.
process_region_edges	Enables the filling of extra data on the region's edge for texture filtering.

Note

The data buffer must hold enough data: no pointer checking is done. Data type and format must be correctly set in the channel before calling this function. The function will attempt to read region[2] * region[3] * bit_depth bytes.

void ImageMapChannel::fill_tiles	(	const float *	data,
		const GMathVec4i &	region,
		bool	process_region_edges = true
	)

Fills a region of the channel using float data.

Parameters

float	buffer containing the data to write in the channel.
region	Region to write.
process_region_edges	Enables the filling of extra data on the region's edge for texture filtering.

void ImageMapChannel::fill_uniform_value	(	const float &	value,
		const GMathVec4i &	region
	)

Fills a region with a single value.

Note

After calling this function, all the tiles that are completely included in the specified region will be uniform, hence won't have a data buffer anymore.

void ImageMapChannel::get_clean_tiles	(	const GMathVec4i &	region,
		CoreArray< ImageMapTileHandle > &	sorted_tiles,
		const unsigned int &	items_count
	)

Returns a list of clean tiles for the specified region.

Parameters

[in]	region	Region of the image that will be used.
[out]	sorted_tiles	Return value. The size of the array must be set before calling the function.
[in]	items_count	number of tiles in each array.

Note

The function works like get_sorted_tiles, with only one differences: tiles will not never be created.

bool ImageMapChannel::get_dirty_tiles	(	const GMathVec4i &	region,
		CoreArray< ImageMapTileHandle > &	sorted_tiles,
		CoreArray< bool > &	dirtiness_flag,
		const unsigned int &	items_count
	)

Returns a list of dirty tiles for the specified region.

Parameters

[in]	region	Region of the image that will be used.
[out]	sorted_tiles	Array of CoreArray. The size of the array must be at least 4 (number of channels that are used).
[out]	dirtiness_flag	This array indicates whether or not a dirty tile exists at each spot.
[out]	items_count	number of tiles in each array.

Note

The function works like get_sorted_tiles, but with some differences:
Tiles are always created if they don't exist. An empty cell means the tile at this spot is clean.
dirtiness_flag[i] will be set to true if at list one CoreArray have a tile set at index i. (ie one channel has a dirty tile at this spot)

void ImageMapChannel::get_pixel_bilinear	(	ImageEvalContext &	context,
		const float &	x,
		const float &	y,
		const GMathVec4i &	canvas,
		float &	color,
		const ImagePixel::RepeatMode &	x_mode = ImagePixel::DEFAULT,
		const ImagePixel::RepeatMode &	y_mode = ImagePixel::DEFAULT
	)		const

Returns the value of the pixel at the given coordinates, using bilinear filtering.

Parameters

	context	Context used for caching purposes
	x,y	Coordinates of the pixel to evaluates in the channel.
	canvas	Current working region
[out]	color	Returned value
	x_mode,y_mode	Repeat mode to use if the pixel is on the edge of the canvas.

void ImageMapChannel::get_pixel_coordinates	(	float	in_x,
		float	in_y,
		float &	out_x,
		float &	out_y,
		const ImagePixel::RepeatMode &	x_mode,
		const ImagePixel::RepeatMode &	y_mode,
		const GMathVec4i &	canvas
	)		const

Computes coordinates for a given pixel, depending on region, repeat mode.

Parameters

in_x,in_y	Input coordinates, that can be of any values (can point to a pixel outside the image)
out_x,out_y	Output coordinates, which will point to a pixel inside the image.
x_mode,y_mode	Repeat mode to use in the calculus.

void ImageMapChannel::get_pixel_nearest	(	ImageEvalContext &	context,
		float	x,
		float	y,
		const GMathVec4i &	canvas,
		float &	color,
		const ImagePixel::RepeatMode &	x_mode = ImagePixel::DEFAULT,
		const ImagePixel::RepeatMode &	y_mode = ImagePixel::DEFAULT
	)		const

Returns the value of the pixel at the given coordinates.

Parameters

	context	Context used for caching purposes
	x,y	Coordinates of the pixel to evaluates in the channel.
	canvas	Current working region
[out]	color	Returned value
	x_mode,y_mode	Repeat mode to use if the pixel is on the edge of the canvas.

void ImageMapChannel::get_sorted_tiles	(	const GMathVec4i &	region,
		CoreArray< ImageMapTileHandle > &	sorted_tiles,
		const unsigned int &	items_count,
		bool	allow_empty = true
	)

Returns a sorted list of tiles pointers for the specified region.

Parameters

[in]	region	Region of the image that will be used.
[out]	sorted_tiles	Array of CoreArray. The size of the array must be at least 4 (number of channels that are used).
[out]	items_count	number of tiles in each array.
[in]	allow_empty	if set to false, tiles will be created if needed (if no tile exists at a particular spot). If set to true, some cells of the arrays may be null.

Note

Each CoreArray contains the tiles of the region for one channel and are resized to match the number of tiles that may be contained in the specified region. Then for each tile of each channel, we compute the index of the tile in the output array using the tile's coordinates => all i-th tiles of every CoreArray have the same coordinates.

ImageMapTileHandle ImageMapChannel::get_tile	(	const int &	px,
		const int &	py,
		ImageMapTileHandle *	last_tile = 0,
		bool	create = false
	)		const

Returns the tile for the given coordinates.

Parameters

px,py	Coordinates to look for.
last_tile	Optional parameter that is used to speed up the search process
create	If set to true, a tile will be created if none was found.

ImageMapTileHandle ImageMapChannel::get_tile	(	ImageEvalContext &	context,
		const int &	px,
		const int &	py
	)		const

Returns the tile for the given coordinates.

Parameters

context	Context used for caching purposes.
px,py	Coordinates to look for.

unsigned int ImageMapChannel::get_tile_size ( ) const

inline

Returns the tile size (= width, height) for the current channel.

Note

The value is read from the parent image. All channels in one ImageMap have the same tile size.

void ImageMapChannel::get_tiles	(	CoreVector< ImageMapTileHandle > &	array,
		const GMathVec4i &	region,
		bool	clean_only = false
	)		const

Returns a list of all the tiles existing in the specified region.

Parameters

array	Return value
region	Part of the channel to scan
clean_only	If set to true, returns only the tiles that are not dirty

void ImageMapChannel::invalidate ( )

inline

Invalidates the current channel. Data stored is considered dirty.

Note

This function differs from calling the clear function with a dirtiness flag set to true: it does not actually modifies any data, only sets a flag so that tile are set to dirty the next time they are accessed.

void ImageMapChannel::on_update_visible	(	const GMathBbox2i &	old_region,
		const GMathBbox2i &	new_region
	)

Updates the image channels after the visible part of the region has been modified.

Note

This function is used by the render region feature to make sure that the parts of the image are correctly set before rendering. Tiles outside the region are cleared and set to clean, tiles inside or cutting the region are set to dirty, so they are recomputed in the next render.

void ImageMapChannel::process	(	ImageChannelProcess_callback	process,
		void *	user_data = 0
	)

Apploes a process on each pixel of the image.

Parameters

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

void ImageMapChannel::process	(	ImageMapCtx &	ctx,
		ImageChannelProcess_callback	process,
		void *	user_data = 0,
		const GMathVec4i *	region = 0
	)

Applies a process on each pixel of the image in the specified region.

Parameters

ctx	Evaluation context
process	function callback that will be called on each pixel
user_data	custom data that can be used to store parameters
region	part of the image the process will be applied on.