This class implements an Image object in Clarisse.
ModuleImage stores several images, for the various quality values available. ( see ModuleImageInfo )
The class implements several functions to access these images, launch image renders and perform various tasks on the object. More...

Inheritance diagram for ModuleImage:

Public Types
typedef void(*	InitRenderCallback )(void *data, const ModuleImageProgressInitInfo &init_data)
	Function called before starting a render.

typedef void(*	DrawRegionCallback )(void data, ImageHandle progress_image, const CoreVector< GMathVec4i > &regions)
	Function called when a new tile has been computed.

typedef void(*	HighlightRegionCallback )(void *data, const CoreVector< GMathVec4i > &regions)
	Function called to update the display of the regions being currently rendered.

typedef void(*	EndRenderCallback )(void data, ImageHandle progress_image)
	Function called when finishing a render.

typedef void(*	ProgressUpdateCallback )(void *data, const float &progress)
	Function called when the progress value of the image has changed.

Public Member Functions
void	destroy_all ()

const int &	get_width () const
	Returns the width of the image.

const int &	get_height () const
	Returns the height of the image.

ModuleLayer *	add_layer (const CoreString &class_name, const CoreString &layer_name)
	Adds a new layer to the image.

ModuleLayer *	add_layer (const CoreString &class_name, const CoreString &layer_name, const CoreString &source_full_name)

ModuleLayer *	get_active_layer () const
	Returns the layer currently selected.

void	set_active_layer (ModuleLayer *layer)
	Sets the layer selected.

const bool &	is_evaluating () const
	Returns true if a render is in progress.

float	get_progress () const
	Returns the current evaluation progress.

float	add_progress (float &amount)
	Increases the progress value.

void	add_sub_progress (float &amount)

ModuleImageQuality::Level	get_progress_quality () const
	Returns the quality being currently computed.

ImageHandle	get_image (const ModuleImageQuality::Level &quality)
	Returns a handle to the image for the specified quality. If the image is not already available, a render is started. The function returns only when the render is finished.

ImageHandle	get_image (const ModuleImageQuality::Level &quality, const bool &compute_all_qualities, const GMathVec4f *region=0)
	Returns a handle to the image for the specified quality. If the image is not already available, a render is started. The function returns only when the render is finished.

ImageHandle	get_image_async (ModuleImageQuality::Level &quality, const bool &compute_all_qualities=false, const GMathVec4f *region=0, const double &priority_offset=0.0)
	Launch the evaluation of the image with the specified quality if it is not available and return the best quality available.

void	compute_image (const ModuleImageQuality::Level &min, const ModuleImageQuality::Level &max, void requester, const GMathVec4f region, const double &priority_offset=0.0, const bool &propagate_dirtiness=false)
	Starts evalutions the for the qualities between min and max.

void	compute_image (const ModuleImageQuality::Level &min, const ModuleImageQuality::Level &max, const double &priority_offset=0.0, const bool &propagate_dirtiness=false)
	Starts evalutions for the qualities between min and max.

void	compute_image (const ModuleImageQuality::Level &min, const ModuleImageQuality::Level &max, void *requester, const double &priority_offset=0.0, const bool &propagate_dirtiness=false)
	Starts evalutions the for the qualities between min and max.

void	compute_image (const ModuleImageQuality::Level &quality, void requester, const GMathVec4f region, const double &priority_offset, const bool &propagate_dirtiness)
	Starts evalutions for the qualities between the minimum quality and the quality specified.

void	compute_image (const ModuleImageQuality::Level &quality, const double &priority_offset=0.0, const bool &propagate_dirtiness=false)
	Starts evalutions for the qualities between the minimum quality and the quality specified.

void	compute_image (const ModuleImageQuality::Level &quality, void *requester, const double &priority_offset=0.0, const bool &propagate_dirtiness=false)
	Starts evalutions for the qualities between the minimum quality and the quality specified.

void	stop_compute_image (void *requester=0)
	Tells the image that a requester does not need the image to be computed anymore.

bool	is_image_dirty (const ModuleImageQuality::Level &quality, const bool &strict=false) const
	Checks if the specified quality has already been computed.

bool	get_highest_quality_image (ImageHandle &image, ModuleImageQuality::Level &quality) const
	Returns the image of the highest quality available, if one exists.

void	check_need_to_dirty ()
	Check if the image is cropped by widget render region.

void	check_need_to_dirty_level (const ModuleImageQuality::Level &quality)
	Check if the image is cropped by widget render region in a specific quality.

CoreArray< ModuleLayer * >	get_layers () const
	Returns list of layers of the image.

CoreArray< ModuleLayer * >	get_all_layers () const
	Returns list of all layers of the image.

const CoreArray< ModuleLayer * > &	get_active_layers () const
	Returns list of active layers of the image.

void	dirty_layers_list ()
	Invalidates layers list, will be synchronized on next get call.

ModuleLayer *	get_layer_xy (const unsigned int &x, const unsigned int &y, const ModuleImageQuality::Level &quality) const
	Returns the first non transparent layer at the specified coordinates.

const double &	get_resolution_multiplier () const
	Returns the resolution multiplier of the image.

int	get_dirtiness () const
	Returns the dirtiness values that have been set on the image the since the last complete render.

void	dirty_layers (GMathBbox2f old_bbox, GMathBbox2f new_bbox)

const bool &	has_render_region () const
	Returns whether the image has a render region set or not.

const GMathVec4f &	get_render_region_bbox () const
	Returns the values of the render region box.

bool	add_image_level_update_callback (void *data, ModuleImageLevelUpdateCallback on_image_level_update)
	This function registers a new "image level update" callback item. The callback function is called every time a new render is finished (for each quality).

void	remove_image_level_update_callback (void *data)
	Removes an image level updated receiver.

unsigned int	get_image_level_update_receivers_count () const
	Returns the number of items that are registered and receive image level updates.

void	resize_image (const ImageCanvas &source, ImageCanvas &dest, const ModuleImageQuality::Level &quality, const int &width, const int &height, const GMathVec4f *render_region) const
	Resize an image.

void	image_level_update (const ModuleImageQuality::Level &quality)
	Call the image level update callbacks for all registered requesters.

ImageProgress *	get_image_progress ()
	Returns the object that manages the progress image in clarisse.

void	update_region (const GMathVec4i &region, bool set_progress=true, float progress=-1.0f) const
	This function indicates that a new region of the image has been computed.

bool	add_draw_region_callback (void *data, InitRenderCallback init_render, EndRenderCallback end_render, DrawRegionCallback draw_region, HighlightRegionCallback highlight_region)
	This function registers a new "draw region" callback item. These callbacks are used to be able to display / updates parts of the image being currently rendered as soon as new part is computed.

void	remove_draw_region_callback (void *data)
	Removes a "draw region" receiver.

unsigned int	get_draw_region_receivers_count () const
	Returns the number of items that are registered and receive "draw region" updates.

CoreVector< GMathVec4i > *	get_current_render_bucket_list ()
	Returns a list of all the buckets that are currently being computed.

bool	add_progress_update_callback (void *data, ProgressUpdateCallback on_progress_update)
	This function registers a new progress update item.

void	remove_progress_update_callback (void *data)
	Removes a progress update receiver.

unsigned int	get_progress_update_receivers_count () const
	Returns the number of items that are registered and receive progress updates.

ModuleImageQuality::Level	get_nearest_quality (const unsigned int &w, const unsigned int h) const
	Returns the first quality for which the size of the image is greater than the parameters given. If none is found, QUALITY_FULL is returned.

void	get_scene_objects (CoreSet< ModuleSceneObject * > &objects) const
	Returns the list of all the objects that are used in the scenes rendered by the 3D layers of the image.

void	get_scene_objects (CoreSet< OfObjectHandle > &objects, const OfContext *working_context=0) const
	Returns the list of all the objects that are used in the scenes rendered by the 3D layers of the image.

void	get_scene_items (CoreSet< ModuleSceneItem * > &scene_items) const
	Returns the list of all the items that are used in the scenes rendered by the 3D layers of the image.

const CoreSet< OfObject * > &	get_referenced_objects (OfClass *stop_on_class=0) const
	Returns the list of all the objects referenced by the image, at any depth.

const char *	get_progress_buffer ()


virtual size_t	get_memory_size () const override
	Returns the memory used by the current instance.

unsigned long	get_last_computed_image_time () const
	Returns the last computed time of the image in second.

double	get_evaluation_frame () const
	Returns the frame of evaluation.

void	dirty_image ()
	Sets the dirtiness flag for all qualities.

void	dirty_image_level (const ModuleImageQuality::Level &quality) const
	Sets the dirtiness flag for a quality.

const double &	get_display_ratio () const

void	set_display_ratio (const double &value)

const GMathVec4i &	get_overscan () const
	Returns the overscan, in pixel for the full image (full quality and res multiplier set to one.

GMathVec4f	get_overscan_ratio () const
	Returns the overscan values (ratio).

bool	update_overscan ()
	Updates the overscan variables from the object attribute values.

GMathVec4i	get_data_window (const ModuleImageQuality::Level &quality) const
	Returns the data window that is defined by the image.

const GMathVec4f &	get_max_overscan () const
	Returns the largest data window that is defined by the image and its layers for the current render.

GMathVec4i	calc_max_pixel_overscan (const ModuleImageQuality::Level &quality) const
	Returns the largest data window in pixels that is defined by the image and its layers for the current render.

float	get_progress_pixel_percent () const
	For internal use.

void	set_progress_pixel_count (int count, int max)
	For internal use.

void	set_rman_interface (RManInterface *rman)
	For internal use.

RManInterface *	get_rman_interface ()
	For internal use.

void	init_progress_count ()
	For internal use.

Static Public Member Functions
static void	limited_region_validator (const OfAttr &attr, double &value, unsigned int index, void *data)

Protected Member Functions
virtual void	on_attribute_change (const OfAttr &attr, int &dirtiness, const int &dirtiness_flags) override
	Function called when an attribute of the image object changes.

virtual void	module_constructor (OfObject &object) override
	Function called when creating an image object. This function calls the module_constructor callback of the object.

void	build_image (const ModuleImageQuality::Level &quality, const GMathVec4f *region=0)
	Computes the image. This function will compute all the layers of the image and comp them. It should not be called directly to access an image. The get_image() function should be used instead.

Friends
class	ModuleImageEvalList

class	ImageProgress

Additional Inherited Members
Static Public Attributes inherited from ModuleObject
static constexpr unsigned int	null_variation = 0
	Key of the null resource variation.

Detailed Description

This class implements an Image object in Clarisse.
ModuleImage stores several images, for the various quality values available. ( see ModuleImageInfo )
The class implements several functions to access these images, launch image renders and perform various tasks on the object.

Member Function Documentation

bool ModuleImage::add_draw_region_callback	(	void *	data,
		InitRenderCallback	init_render,
		EndRenderCallback	end_render,
		DrawRegionCallback	draw_region,
		HighlightRegionCallback	highlight_region
	)

This function registers a new "draw region" callback item. These callbacks are used to be able to display / updates parts of the image being currently rendered as soon as new part is computed.

Parameters

data	Pointer used to identify the callback. The pointer is passed to the callbacks as first paramater. We usually use the pointer to the requester. The same pointer need to be given to use the remove the callback function.

See Also: remove_draw_region_callback.

Parameters

init_render	Function called when starting a render.
end_render	Function called when finishing a render.
draw_region	Function called when a new tile has been computed.
highlight_region	Function called to update the display of the regions being currently rendered.

bool ModuleImage::add_image_level_update_callback	(	void *	data,
		ModuleImageLevelUpdateCallback	on_image_level_update
	)

This function registers a new "image level update" callback item. The callback function is called every time a new render is finished (for each quality).

Parameters

data	Pointer used to identify the callback. The pointer is passed to the callbacks as first parameter. We usually use the pointer to the requester. The same pointer need to be given to use the remove the callback function.

See Also: remove_image_level_update_callback.

Parameters

on_image_level_update Function called when a render is done.

ModuleLayer * ModuleImage::add_layer	(	const CoreString &	class_name,
		const CoreString &	layer_name
	)

Adds a new layer to the image.

Parameters

class_name	OfClass of the layer to add. Any class inheriting from ModuleLayer can be added. Other will fail.
layer_name	Name of the layer.

Note: The functions returns the layer that have been created if the function is successfull.
The added layer becomes the active layer.

float ModuleImage::add_progress ( float & amount )

Increases the progress value.

Parameters

amount Amount of progress to add, typically the number of pixels that have been computed. The value is multiplied by a ratio that takes into account the size of the image, the number of layers, etc... before being added.

bool ModuleImage::add_progress_update_callback	(	void *	data,
		ProgressUpdateCallback	on_progress_update
	)

This function registers a new progress update item.

Parameters

data	Pointer used to identify the callback. The pointer is passed to the callback as first paramater. We usually use the pointer to the requester. The same pointer need to be given to use the remove the callback function.

See Also: remove_progress_update_callback.

Parameters

on_progress_update function callback that will be called.

void ModuleImage::build_image	(	const ModuleImageQuality::Level &	quality,
		const GMathVec4f *	region = `0`
	)

protected

Computes the image. This function will compute all the layers of the image and comp them. It should not be called directly to access an image. The get_image() function should be used instead.

Parameters

quality	ModuleImageQuality::Level to compute.
region	If not null, this parameter is used as render region.

void ModuleImage::compute_image	(	const ModuleImageQuality::Level &	min,
		const ModuleImageQuality::Level &	max,
		void *	requester,
		const GMathVec4f *	region,
		const double &	priority_offset = `0.0`,
		const bool &	propagate_dirtiness = `false`
	)

Starts evalutions the for the qualities between min and max.

Parameters

min	Minimum quality to compute.
max	Maximum quality to compute.
requester	Pointer to the object that requested the render.
region	Render region.
priority_offset	Priority of the render.
propagate_dirtiness	Tells the evaluation _ to propagete dirtiness after each quality evaluation is complete.

void ModuleImage::compute_image	(	const ModuleImageQuality::Level &	min,
		const ModuleImageQuality::Level &	max,
		const double &	priority_offset = `0.0`,
		const bool &	propagate_dirtiness = `false`
	)

inline

Starts evalutions for the qualities between min and max.

See Also: void compute_image(const ModuleImageQuality::Level& min, const ModuleImageQuality::Level& max, void requester, const GMathVec4f region, const double& priority_offset, const bool& propagate_dirtiness = false) const;

void ModuleImage::compute_image	(	const ModuleImageQuality::Level &	min,
		const ModuleImageQuality::Level &	max,
		void *	requester,
		const double &	priority_offset = `0.0`,
		const bool &	propagate_dirtiness = `false`
	)

inline

Starts evalutions the for the qualities between min and max.

See Also: void compute_image(const ModuleImageQuality::Level& min, const ModuleImageQuality::Level& max, void requester, const GMathVec4f region, const double& priority_offset, const bool& propagate_dirtiness = false) const;

void ModuleImage::compute_image	(	const ModuleImageQuality::Level &	quality,
		void *	requester,
		const GMathVec4f *	region,
		const double &	priority_offset,
		const bool &	propagate_dirtiness
	)

Starts evalutions for the qualities between the minimum quality and the quality specified.

See Also: void compute_image(const ModuleImageQuality::Level& min, const ModuleImageQuality::Level& max, void requester, const GMathVec4f region, const double& priority_offset, const bool& propagate_dirtiness = false) const;

void ModuleImage::compute_image	(	const ModuleImageQuality::Level &	quality,
		const double &	priority_offset = `0.0`,
		const bool &	propagate_dirtiness = `false`
	)

inline

Starts evalutions for the qualities between the minimum quality and the quality specified.

See Also: void compute_image(const ModuleImageQuality::Level& quality, void requester, const GMathVec4f region, const double& priority_offset, const bool& propagate_dirtiness) const;

void ModuleImage::compute_image	(	const ModuleImageQuality::Level &	quality,
		void *	requester,
		const double &	priority_offset = `0.0`,
		const bool &	propagate_dirtiness = `false`
	)

inline

Starts evalutions for the qualities between the minimum quality and the quality specified.

See Also: void compute_image(const ModuleImageQuality::Level& quality, void requester, const GMathVec4f region, const double& priority_offset, const bool& propagate_dirtiness) const;

int ModuleImage::get_dirtiness ( ) const

inline

Returns the dirtiness values that have been set on the image the since the last complete render.

Note: The value is reset when the highest quality of the image has been computed. Dirtiness values are aggregated each time the on_attribute_change function is called.

bool ModuleImage::get_highest_quality_image	(	ImageHandle &	image,
		ModuleImageQuality::Level &	quality
	)		const

Returns the image of the highest quality available, if one exists.

Parameters

quality Minimum quality required.

Note: The function returns false if no image of a quality greater or equal to the parameter given is found, true otherwise.

ImageHandle ModuleImage::get_image ( const ModuleImageQuality::Level & quality )

Returns a handle to the image for the specified quality. If the image is not already available, a render is started. The function returns only when the render is finished.

Parameters

quality Image quality to evaluate

Returns: a handle to the evaluated image

Note: Do not call from the mainloop if the requested quality is not already computed.

See Also: ModuleImage::compute_image

ImageHandle ModuleImage::get_image	(	const ModuleImageQuality::Level &	quality,
		const bool &	compute_all_qualities,
		const GMathVec4f *	region = `0`
	)

Returns a handle to the image for the specified quality. If the image is not already available, a render is started. The function returns only when the render is finished.

Parameters

quality	Image quality to evaluate
compute_all_qualities	If true, also evaluates qualities lower to the specified one
region	Region to render

Returns: a handle to the evaluated image

Note: Do not call from the mainloop if the requested quality is not already computed.

See Also: ModuleImage::compute_image

ImageHandle ModuleImage::get_image_async	(	ModuleImageQuality::Level &	quality,
		const bool &	compute_all_qualities = `false`,
		const GMathVec4f *	region = `0`,
		const double &	priority_offset = `0.0`
	)

Launch the evaluation of the image with the specified quality if it is not available and return the best quality available.

Parameters

quality	Image quality to evaluate
compute_all_qualities	If true, also evaluates qualities lower to the specified one
region	Region to render
priority_offset	Offset to apply to the priority of the evaluation

Returns: a handle to the best image available

Note: This method is blocking the mainloop

See Also: ModuleImage::compute_image

ModuleLayer * ModuleImage::get_layer_xy	(	const unsigned int &	x,
		const unsigned int &	y,
		const ModuleImageQuality::Level &	quality
	)		const

Returns the first non transparent layer at the specified coordinates.

Note: The function is used for picking

ModuleImageQuality::Level ModuleImage::get_nearest_quality	(	const unsigned int &	w,
		const unsigned int	h
	)		const

Returns the first quality for which the size of the image is greater than the parameters given.
If none is found, QUALITY_FULL is returned.

Note: This function is mainly used when a resized version of the image is created.

float ModuleImage::get_progress ( ) const

Returns the current evaluation progress.

Note: The value returned depend on the quality being computed: the progress value is equal to the percentage of completion of the current quality mulitplied to the quality ratio, plus cumulative progress of previous qualities.
For example, if the full quality is 25% done, the current progress value will be 0.5 (cumulative value) + 25% / 0.5(full quality ratio) = 0.625.

const char * ModuleImage::get_progress_buffer ( )

const CoreSet< OfObject * > & ModuleImage::get_referenced_objects ( OfClass * stop_on_class = 0 ) const

Returns the list of all the objects referenced by the image, at any depth.

Parameters

stop_on_class If a class is specified, the function gathering objects will not include objects referenced by instances of this class.
Example: If you are referencing another image through a layer image or a texture map, and don't want to list objects of the image referenced, you'll need to pass the "Image" class to the function.

void ModuleImage::get_scene_objects	(	CoreSet< OfObjectHandle > &	objects,
		const OfContext *	working_context = `0`
	)		const

Returns the list of all the objects that are used in the scenes rendered by the 3D layers of the image.

Parameters

[in]	working_context	Context in which the caller want to consider the objects
[out]	objects	outputs handles of objects in the given context

bool ModuleImage::is_image_dirty	(	const ModuleImageQuality::Level &	quality,
		const bool &	strict = `false`
	)		const

Checks if the specified quality has already been computed.

Parameters

quality	ModuleImageQuality::Level to check
strict	If set to true, the function will return true only the requested quality is computed. If set to false, the function will return true if the requested quality or a better one is available.

void ModuleImage::limited_region_validator	(	const OfAttr &	attr,
		double &	value,
		unsigned int	index,
		void *	data
	)

static

Callback to validate the "limited_region" attribute of the ImageView, Image and Layer. It ensures the render region width and height are >= 0.

Parameters

attr	the attribute that is changing
value	the new value
index	the value index
data	callback data (unused here)

void ModuleImage::stop_compute_image ( void * requester = 0 )

Tells the image that a requester does not need the image to be computed anymore.

    The evaluation will be really stopped when no requester is left for the current quality.

Parameters

requester pointer to the object that requested the image. If no requester is given, all requesters are removed and the computation is stopped.

void ModuleImage::update_region	(	const GMathVec4i &	region,
		bool	set_progress = `true`,
		float	progress = `-1.0f`
	)		const

This function indicates that a new region of the image has been computed.

Parameters

region	Region of the image to update.
set_progress	If set, the progress value is updated using the number of pixels in the region.
progress	Optional progress (between 0 and 1) to set. This is only used when `set_progress` is true. Any negative value will default back to the progress being automatically updated.

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Additional Inherited Members

Detailed Description

Member Function Documentation