Clarisse 5.0 SP8 SDK  5.0.5.8.0
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
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

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.
 
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)
 
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.
 
ModuleLayerget_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
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,
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
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 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
qualityModuleImageQuality::Level to compute.
regionIf 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
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 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
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 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
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 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
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 ( 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
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 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_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.
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_contextContext in which the caller want to consider the objects
[out]objectsoutputs 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
qualityModuleImageQuality::Level 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,
float  progress = -1.0f 
) 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.
progressOptional 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.