Clarisse 4.0 SP5b SDK  4.0.0.0.5.1
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
Classes | Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Friends | List of all members
ModuleImage Class Reference

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:
ModuleProjectItem ModuleObject OfModule ResourceUser EventObject CoreCustomData CoreBaseObject CoreBaseType

Classes

struct  ImageProgressInitInfo
 

Public Types

enum  Quality {
  QUALITY_UNKNOWN = -1,
  QUALITY_ONE_SIXTEENTH,
  QUALITY_ONE_EIGHTH,
  QUALITY_ONE_QUARTER,
  QUALITY_HALF,
  QUALITY_FULL,
  QUALITY_COUNT
}
 Defines the list of qualities that are available in an image.
Each quality is linked to a multiply factor that is applied on the Image when rendering the image.
. More...
 
enum  ResolutionMultiplierPreset {
  RESOLUTION_MULTIPLIER_25 = 0,
  RESOLUTION_MULTIPLIER_50,
  RESOLUTION_MULTIPLIER_100,
  RESOLUTION_MULTIPLIER_200,
  RESOLUTION_MULTIPLIER_400,
  RESOLUTION_MULTIPLIER_75,
  RESOLUTION_MULTIPLIER_150,
  RESOLUTION_MULTIPLIER_COUNT
}
 
typedef void(* ImageLevelUpdateCallback )(void *data, const Quality &quality, ImageHandle image)
 Function called when a render is finished.
 
typedef void(* InitRenderCallback )(void *data, const ImageProgressInitInfo &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.
 
ModuleLayeradd_layer (const CoreString &class_name, const CoreString &layer_name)
 Adds a new layer to the image.
 
ModuleLayeradd_layer (const CoreString &class_name, const CoreString &layer_name, const CoreString &source_full_name)
 
ModuleLayerget_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)
 
Quality get_progress_quality () const
 Returns the quality being currently computed.
 
ImageHandle get_image (const Quality &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 Quality &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 (Quality &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 Quality &min, const Quality &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 Quality &min, const Quality &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 Quality &min, const Quality &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 Quality &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 Quality &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 Quality &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 Quality &quality, const bool &strict=false) const
 Checks if the specified quality has already been computed.
 
bool get_highest_quality_image (ImageHandle &image, Quality &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 Quality &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.
 
ModuleLayerget_layer_xy (const unsigned int &x, const unsigned int &y, const Quality &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, ImageLevelUpdateCallback 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 ModuleImage::Quality &quality, const int &width, const int &height, const GMathVec4f *render_region) const
 Resize an image.
 
void image_level_update (const Quality &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) 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.
 
Quality 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_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
 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 Quality &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 Quality &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 Quality &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 const char * get_quality_name (const Quality &quality)
 Returns a readable name for a quality.
 
static double get_quality_level (const Quality &quality)
 Returns the progress value for a quality. The value gives the image progress when starting to computed the specified quality.
 
static bool is_valid_quality (const Quality &quality)
 Checks if the specified quality is valid.
 
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)
 Function called when an attribute of the image object changes.
 
virtual void module_constructor (OfObject &object)
 Function called when creating an image object. This function calls the module_constructor callback of the object.
 
void build_image (const Quality &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
 

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.


Class Documentation

struct ModuleImage::ImageProgressInitInfo
Class Members
ImageHandle * previous_image
ImageHandle * progress_image
Quality quality

Member Enumeration Documentation

Defines the list of qualities that are available in an image.
Each quality is linked to a multiply factor that is applied on the Image when rendering the image.
.

Note
The QUALITY_UNKNOWN value is for internal use only. Do not use!
Enumerator:
QUALITY_UNKNOWN 

Internal value, do not use.

QUALITY_ONE_SIXTEENTH 

Height and width are divided by 16.

QUALITY_ONE_EIGHTH 

Height and width are divided by 8.

QUALITY_ONE_QUARTER 

Height and width are divided by 4.

QUALITY_HALF 

Height and width are divided by 2.

QUALITY_FULL 

Full image size.

QUALITY_COUNT 

Enum item count.

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
dataPointer 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_renderFunction called when starting a render.
end_renderFunction called when finishing a render.
draw_regionFunction called when a new tile has been computed.
highlight_regionFunction called to update the display of the regions being currently rendered.
bool ModuleImage::add_image_level_update_callback ( void *  data,
ImageLevelUpdateCallback  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
dataPointer 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_updateFunction 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_nameOfClass of the layer to add. Any class inheriting from ModuleLayer can be added. Other will fail.
layer_nameName 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
amountAmount 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
dataPointer 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_updatefunction callback that will be called.
void ModuleImage::build_image ( const Quality 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
qualityQuality to compute.
regionIf not null, this parameter is used as render region.
void ModuleImage::compute_image ( const Quality min,
const Quality 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
minMinimum quality to compute.
maxMaximum quality to compute.
requesterPointer to the object that requested the render.
regionRender region.
priority_offsetPriority of the render.
propagate_dirtinessTells the evaluation _ to propagete dirtiness after each quality evaluation is complete.
void ModuleImage::compute_image ( const Quality min,
const Quality 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 Quality& min, const Quality& max, void requester, const GMathVec4f region, const double& priority_offset, const bool& propagate_dirtiness = false) const;
void ModuleImage::compute_image ( const Quality min,
const Quality 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 Quality& min, const Quality& max, void requester, const GMathVec4f region, const double& priority_offset, const bool& propagate_dirtiness = false) const;
void ModuleImage::compute_image ( const Quality 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 Quality& min, const Quality& max, void requester, const GMathVec4f region, const double& priority_offset, const bool& propagate_dirtiness = false) const;
void ModuleImage::compute_image ( const Quality 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 Quality& quality, void requester, const GMathVec4f region, const double& priority_offset, const bool& propagate_dirtiness) const;
void ModuleImage::compute_image ( const Quality 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 Quality& 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,
Quality quality 
) const

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

Parameters
qualityMinimum 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 Quality 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
qualityImage 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 Quality 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
qualityImage quality to evaluate
compute_all_qualitiesIf true, also evaluates qualities lower to the specified one
regionRegion 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 ( Quality 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
qualityImage quality to evaluate
compute_all_qualitiesIf true, also evaluates qualities lower to the specified one
regionRegion to render
priority_offsetOffset 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 Quality quality 
) const

Returns the first non transparent layer at the specified coordinates.

Note
The function is used for picking
ModuleImage::Quality 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_classIf 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.
bool ModuleImage::is_image_dirty ( const Quality quality,
const bool &  strict = false 
) const

Checks if the specified quality has already been computed.

Parameters
qualityQuality to check
strictIf 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
attrthe attribute that is changing
valuethe new value
indexthe value index
datacallback 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
requesterpointer 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 
) const

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

Parameters
regionRegion of the image to update.
set_progressIf set, the progress value is updated using the number of pixels in the region.