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

Top level object that defines an Image in Clarisse. The ImageCanvas contains a pyramid of mipmaps, which are computed on demand. Each mipmap is an instance of the ImageMap class. When modifying an ImageCanvas, modifications are always done for the top level image, accessible through the get_image() function. Other mipmaps are never directly editable. More...

Inheritance diagram for ImageCanvas:
ResourceData EventObject CoreCustomData CoreBaseObject CoreBaseType

Classes

struct  ResizeOptions
 This structure defines resizing options. More...
 

Public Member Functions

 ImageCanvas (bool empty=false)
 Base constructor.
 
 ImageCanvas (ImageMap &image_map)
 Build an ImageCanvas using the ImageMap parameter as a top level image.
 
 ImageCanvas (const unsigned int &x_size, const unsigned int &y_size, const unsigned int &num_channels, const unsigned int &tile_size=DEFAULT_TILE_SIZE)
 Builds an ready to use ImageCanvas using the given parameters.
 
 ImageCanvas (const int &x_pos, const int &y_pos, const unsigned int &x_size, const unsigned int &y_size, const unsigned int &num_channels, const unsigned int &tile_size=DEFAULT_TILE_SIZE)
 Builds an ready to use ImageCanvas using the given parameters.
 
bool create_image (const GMathVec4i *region=0, const ImagePixel::Depth &depth=ImagePixel::DEPTH_RGBA, const ImagePixel::BitDepth &bit_depth=ImagePixel::BIT_DEPTH_32, const ImagePixel::BitType &bit_type=ImagePixel::BIT_TYPE_FLOAT, const int &tile_size=DEFAULT_TILE_SIZE)
 Initialize the image.
 
void clear ()
 Clears the top level image. Image is set to dirty.
 
void clear (const GMathVec4i &visible_window, const GMathVec4i *data_window, unsigned int tile_size=0)
 Clears the top level image and sets up a new tile size.
 
bool dirty_image ()
 Invalidates the top level image and clears the mipmaps' dirtiness flags.
 
void dirty_channels (const CoreVector< CoreString > &channel_names)
 Invalidates the requested channels and clears the mipmaps' dirtiness flags.
 
void update_custom_channels (const CoreVector< CoreString > &to_remove, const CoreVector< CoreString > &to_add)
 Updates the list of channels in the image.
 
bool dirty_border (const GMathVec4i &region)
 Dirty all the tiles of all channels that intersect the region.
 
bool 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.
 
const int & get_x () const
 Returns the x coordinate of the top left corner.
 
const int & get_y () const
 Returns the y coordinate of the top left corner.
 
const int & get_width () const
 Returns the width of the image.
 
const int & get_height () const
 Returns the height of the image.
 
const unsigned int & get_tile_size () const
 Returns the size of internal tiles used to store pixels.
 
const CoreVector< const
GMathVec4i * > & 
get_canvas () const
 Returns the list of canvas, for all mipmaps.
 
const GMathVec4i & get_visible_window () const
 Returns the visible window of the image.
 
const CoreVector< const
GMathVec4i * > & 
get_visible_windows () const
 Returns the list of visible windows, for all mipmaps.
 
const CoreVector< const
GMathVec4i * > & 
get_data_windows () const
 Returns the list of data windows, for all mipmaps.
 
void get_pixel_nearest (ImageEvalContext &context, const MapEvalCtx &eval_ctx, GMathVec4f &color) const
 Returns the value of the pixel at the given coordinates.
 
void get_pixel_bilinear (ImageEvalContext &context, const MapEvalCtx &eval_ctx, GMathVec4f &color) const
 Returns the value of the pixel at the given coordinates, using bilinear filtering.
 
void get_pixel_mipmap_trilinear (ImageEvalContext &context, const MapEvalCtx &eval_ctx, GMathVec4f &color, const int &display_mipmap_level) const
 Returns the value of the pixel at the given coordinates, using trilinear filtering and mipmaps.
 
void get_pixel_mipmap_ewa (ImageEvalContext &context, const MapEvalCtx &eval_ctx, GMathVec4f &color, const double &anisotropy_factor, const int &display_mipmap_level) const
 Returns the value of the pixel at the given coordinates, using mipmaps and EWA interpolation.
 
void get_pixel_ewa (ImageEvalContext &context, const MapEvalCtx &eval_ctx, GMathVec4f &color, const double &anisotropy_factor, const int &display_mipmap_level) const
 Returns the value of the pixel at the given coordinates, using EWA interpolation.
 
void finalize (const bool &set_clean=true)
 Tidy the image after a render so it can be evaluated through a texture.
 
void compute_image_edges ()
 Computes an extra line of pixels on the edge of an image so the texture evaluation works properly.
 
void update_mip_canvas ()
 Recomputes the canvas of all mipmaps.
 
void set_canvas (const int &x_pos, const int &y_pos, const unsigned int &x_size, const unsigned int &y_size, const GMathVec4i *data_window=0)
 Set the canvas of the image ( image coordinates and size)
 
void set_canvas (const GMathVec4i &visible_window, const GMathVec4i *data_window=0)
 Set the canvas of the image ( image coordinates and size)
 
 operator const ImageMap * ()
 Set the x/y coordinates of the image.
 
 operator ImageMap * ()
 returns a pointer to the top level ImageMap in the mipmap pyramid
 
ImageMapget_image () const
 returns a pointer to the top level ImageMap in the mipmap pyramid
 
const ImageMapget_map () const
 returns a const pointer to the top level ImageMap in the mipmap pyramid
 
const ImageMapget_map (unsigned int map_index) const
 returns a const pointer to the ImageMap of the requested mipmap level
 
unsigned int get_theoric_tile_count () const
 Returns the theoric maximun tile count that the image can store/use, based on width/height.
 
ImageProxy get_proxy (int x, int y, int width, int height) const
 Returns an ImageProxy (used by filters) for the requested region.
 
void move_data (const int &offset_x, const int &offset_y)
 Shift the data of the image.
 
void create_from (const ImageCanvas &src, const int &offset_x=0, const int &offset_y=0, const GMathVec4i *region=0, const CoreBasicArray< CoreString > *channel_names=0)
 Fill the image using another one.
 
void copy_from (const ImageCanvas &src)
 Initialize image using data from another one.
 
void fill_clean_data (const ImageCanvas &src, const GMathVec4i &region)
 Copy the data from the clean tiles of the source image.
 
void blit_visible (const ImageCanvas &source, const GMathVec4i &region, const ImagePixel::BlitMode &mode=ImagePixel::BLIT_MODE_REPLACE)
 Copy data from the visible channels.
 
void process_visible (ImageMapCtx &ctx, ImageChannelProcess_callback process, void *user_data=0, const GMathVec4f *region=0)
 Apply a process on the visible channels of the image.
 
size_t get_memory_size () const
 Returns the memory footprint of the instance.
 
void compute_pixel_ray_intersection (const int &x, const int &y, GMathRay &ray, GeometryIntersection &intersection) const
 Compute the intersection beteween the image and the given ray.
 
ImageMapPyramidget_pyramid () const
 Returns a pointer to the ImageMap pyramid.
 
CoreAtomic32 * get_clean_maps () const
 Returns the count of mipmap that have been computed.
 
const bool & is_invalid () const
 Returns whether the image is invalid and will be reset.
 
void invalidate (const bool &invalid)
 Set the invalid flag.
 
void invalidate ()
 Invalidate the image for later reset.
 
const bool & is_dirty () const
 Returns whether the image is dirty (has not been completely computed)
 
void remove_dirtiness_flag ()
 Resets the image dirtiness flag.
 
const CoreHashTable
< CoreString, CoreVector
< CoreVariant > > & 
get_meta_data () const
 Returns the meta data attached to the image.
 
void add_meta_data (const CoreString &name, const CoreVector< CoreVariant > &values)
 Adds a meta data to the image.
 
bool try_lock () const
 
void lock () const
 Wait until the canvas can be locked and lock it.
 
void unlock () const
 Unlock the canvas.
 
- Public Member Functions inherited from ResourceData
 ResourceData (const ResourceData &other)
 
ResourceImportDataget_import_data () const
 
void set_import_data (ResourceImportData *data)
 
virtual Core128BitHashKey get_hash_key () const
 Get the hash key of the resource.
 
virtual bool is_serializable () const
 Tell if the resource can be serialized or not.
 
virtual void * serialize (size_t &serial_size) const
 Serialize the resource data.
 
virtual bool deserialize (void *serial, const size_t &serial_size)
 Deserialize the resource data.
 
void advert_memory_changed () const
 Adverts that the memory usage of the resource has changed.
 
bool is_protected () const
 
- Public Member Functions inherited from EventObject
 EventObject ()
 Constructor.
 
 EventObject (const EventObject &src)
 Copy Constructor.
 
virtual ~EventObject ()
 Destructor.
 
void connect (EventObject &sender, const CoreString &event_id, EventMethod event_cb, void *data=0)
 Connects this to an object to listen to a specific event.
 
void connect (EventObject &sender, EventMethod event_cb, void *data=0)
 Connects this to an object to listen any of its events.
 
void raise_event (const CoreString &event_id) const
 sends an event
 
void connect (EventObject &sender, const CoreString &event_id, EventInfoMethod event_cb, void *data=0)
 Connects this to an object to listen to a specific event.
 
void connect (EventObject &sender, EventInfoMethod event_cb, void *data=0)
 Connects this to an object to listen any of its events.
 
void raise_event (const EventInfo &event_info) const
 sends an event
 
bool disconnect_all (EventObject &sender)
 Disconnects from all objects sender was listening on.
 
void disconnect_all ()
 Disconnects from all objects we were listening on.
 
void remove_all_connection ()
 Disconnects object from other objects it is listening to, and also disconnects all objects listening to it.
 
bool is_connected (EventObject &sender, const CoreString &event_id, void *data)
 
void set_mute (const bool &mute)
 Asks for object muting. This will increase or decrease the muting counter. Unmuting may not be immediat since it will happen only when counter reaches 0.
 
bool is_mute () const
 Returns if object is muted.
 
bool disconnect (EventObject &sender, const CoreString &event_id, EventMethod event_cb, void *data=0)
 Disconnects this from an object for a specific event.
 
bool disconnect (EventObject &sender, const CoreString &event_id, EventInfoMethod event_cb, void *data=0)
 
unsigned int get_sender_count () const
 
unsigned int get_receiver_count () const
 
- Public Member Functions inherited from CoreCustomData
 CoreCustomData (const CoreCustomData &src)
 
void add_custom_data (void *key, const bool &data)
 
void add_custom_data (void *key, const int &data)
 
void add_custom_data (void *key, const unsigned int &data)
 
void add_custom_data (void *key, const char *data)
 
void add_custom_data (void *key, const CoreString &data)
 
void add_custom_data (void *key, const double &data)
 
void add_custom_data (void *key, void *data)
 
void remove_custom_data (void *key)
 
void remove_all_custom_data ()
 
void set_custom_data (void *key, const bool &data)
 
void set_custom_data (void *key, const int &data)
 
void set_custom_data (void *key, const unsigned int &data)
 
void set_custom_data (void *key, const double &data)
 
void set_custom_data (void *key, const char *data)
 
void set_custom_data (void *key, const CoreString &data)
 
void set_custom_data (void *key, void *data)
 
void get_custom_data (void *key, bool &data) const
 
void get_custom_data (void *key, int &data) const
 
void get_custom_data (void *key, unsigned int &data) const
 
void get_custom_data (void *key, double &data) const
 
void get_custom_data (void *key, CoreString &data) const
 
void get_custom_data (void *key, void *&data) const
 
- Public Member Functions inherited from CoreBaseObject
bool is_kindof (const CoreBaseObject &object) const
 
CoreString get_class_info_name () const
 
CoreString get_class_interface () const
 
const unsigned long & get_class_info_id () const
 
bool is_kindof (const CoreClassInfo &cinfo) const
 
virtual const CoreClassInfoget_class_info () const
 
bool operator== (const CoreBaseObject &obj) 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
 
bool operator== (const CoreBaseType &obj) const
 

Static Public Member Functions

static const ImageCanvasget_no_image ()
 Returns an empty image.
 
static const ImageCanvasget_default_image ()
 Returns a reference to the default canvas, containing the default ImageMap.
 
static ImageCanvasget_default_canvas (ImagePixel::RepeatMode u_mode=ImagePixel::RESET, ImagePixel::RepeatMode v_mode=ImagePixel::RESET)
 Returns a pointer to a canvas containing the default ImageMap.
 
static void resize (const ImageCanvas &src, ImageCanvas &destination, const int &width, const int &height, int filtering=0)
 Returns an RGBA image resized to the specified size using a particular filtering mode.
 
static void resize (const ImageCanvas &src, ImageCanvas &destination, ResizeOptions options, AppBase *app_base=nullptr)
 Resize an image using a particular filtering mode.
 
static void compute_uv_ray_intersection_x (const float &u, const float &v, const float &du, const float &dv, GMathRay &ray, GeometryIntersection &intersection)
 Compute the intersection beteween an arbitrary uv and the given ray.
 
static void compute_uv_ray_intersection_y (const float &u, const float &v, const float &du, const float &dv, GMathRay &ray, GeometryIntersection &intersection)
 
static void compute_uv_ray_intersection_z (const float &u, const float &v, const float &du, const float &dv, GMathRay &ray, GeometryIntersection &intersection)
 
static void compute_uv_ray_intersection_plus_x (const float &u, const float &v, const float &du, const float &dv, GMathRay &ray, GeometryIntersection &intersection)
 
static void compute_uv_ray_intersection_plus_y (const float &u, const float &v, const float &du, const float &dv, GMathRay &ray, GeometryIntersection &intersection)
 
static void compute_uv_ray_intersection_plus_z (const float &u, const float &v, const float &du, const float &dv, GMathRay &ray, GeometryIntersection &intersection)
 

Friends

class Image
 
class ImageProxy
 

Additional Inherited Members

- Public Types inherited from EventObject
typedef void(* EventInfoFunction )(EventObject &, const EventInfo &, void *)
 
typedef void(EventObject::* EventInfoMethod )(EventObject &, const EventInfo &, void *)
 
typedef void(* EventFunction )(EventObject &, const CoreString &, void *)
 
typedef void(EventObject::* EventMethod )(EventObject &, const CoreString &, void *)
 

Detailed Description

Top level object that defines an Image in Clarisse. The ImageCanvas contains a pyramid of mipmaps, which are computed on demand. Each mipmap is an instance of the ImageMap class. When modifying an ImageCanvas, modifications are always done for the top level image, accessible through the get_image() function. Other mipmaps are never directly editable.


Class Documentation

struct ImageCanvas::ResizeOptions

This structure defines resizing options.

Parameters
visible_windowregion of the destination image that will be visible. (canvas)
data_windowregion of the destination image that will be computed. (unless a render region is set)
filteringtype of filtering to apply (nearest, bilinear, trilinear, EWA)
width,heightsize of the destination image
filteringtype of filtering to apply (nearest, bilinear, trilinear, EWA)
keep_dest_bit_formatif set to false, the destination image is reset to use the source pixel format
Class Members
GMathVec4i data_window
int filtering
bool keep_dest_bit_format
const GMathVec4f * render_region
GMathVec4i visible_window

Constructor & Destructor Documentation

ImageCanvas::ImageCanvas ( bool  empty = false)
explicit

Base constructor.

Note
if empty is set to true, the mipmap pyramid will not be created.
ImageCanvas::ImageCanvas ( ImageMap image_map)
explicit

Build an ImageCanvas using the ImageMap parameter as a top level image.

Note
Do not destroy the ImageMap afterwards, no copy is made.
ImageCanvas::ImageCanvas ( const unsigned int &  x_size,
const unsigned int &  y_size,
const unsigned int &  num_channels,
const unsigned int &  tile_size = DEFAULT_TILE_SIZE 
)

Builds an ready to use ImageCanvas using the given parameters.

Note
The data type used is FLOAT. Image starts at (0.0)
ImageCanvas::ImageCanvas ( const int &  x_pos,
const int &  y_pos,
const unsigned int &  x_size,
const unsigned int &  y_size,
const unsigned int &  num_channels,
const unsigned int &  tile_size = DEFAULT_TILE_SIZE 
)

Builds an ready to use ImageCanvas using the given parameters.

Note
The data type used is FLOAT.

Member Function Documentation

void ImageCanvas::blit_visible ( const ImageCanvas source,
const GMathVec4i &  region,
const ImagePixel::BlitMode &  mode = ImagePixel::BLIT_MODE_REPLACE 
)

Copy data from the visible channels.

Parameters
regionpart of the image to copy
modecopy mode to use
void ImageCanvas::compute_image_edges ( )

Computes an extra line of pixels on the edge of an image so the texture evaluation works properly.

Note
This function will fill the image edges depending on repeat mode.
void ImageCanvas::copy_from ( const ImageCanvas src)

Initialize image using data from another one.

Note
All parameters of the source image are used, including data type, tile_size, etc...
void ImageCanvas::create_from ( const ImageCanvas src,
const int &  offset_x = 0,
const int &  offset_y = 0,
const GMathVec4i *  region = 0,
const CoreBasicArray< CoreString > *  channel_names = 0 
)

Fill the image using another one.

Parameters
offset_x,offset_yoffset to apply when copying data.
regionpart of the image to copy. The whole image will be copied if the pointer is null
channel_namesnames of the source channels to use. All channels are copied if the list is null.
Note
Up to four channels can be given as parameters. These channels in the source image are used to fill the RGBA channels in the destination image. Pixel data is converted if types do not match.
bool ImageCanvas::create_image ( const GMathVec4i *  region = 0,
const ImagePixel::Depth &  depth = ImagePixel::DEPTH_RGBA,
const ImagePixel::BitDepth &  bit_depth = ImagePixel::BIT_DEPTH_32,
const ImagePixel::BitType &  bit_type = ImagePixel::BIT_TYPE_FLOAT,
const int &  tile_size = DEFAULT_TILE_SIZE 
)

Initialize the image.

Note
After calling this function, the image is ready to be used in a render: tiles and their data are allocated.
const CoreVector<const GMathVec4i*>& ImageCanvas::get_canvas ( ) const
inline

Returns the list of canvas, for all mipmaps.

Deprecated:
const ImageMap* ImageCanvas::get_map ( unsigned int  map_index) const
inline

returns a const pointer to the ImageMap of the requested mipmap level

Note
The mipmap will be created on the fly if it doesn't exists or is invalid.
void ImageCanvas::get_pixel_bilinear ( ImageEvalContext context,
const MapEvalCtx eval_ctx,
GMathVec4f &  color 
) const

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

Parameters
MapEvalCtxstructure containing all the parameters needed to compute the pixel color.
void ImageCanvas::get_pixel_ewa ( ImageEvalContext context,
const MapEvalCtx eval_ctx,
GMathVec4f &  color,
const double &  anisotropy_factor,
const int &  display_mipmap_level 
) const

Returns the value of the pixel at the given coordinates, using EWA interpolation.

Parameters
MapEvalCtxstructure containing all the parameters needed to compute the pixel color.
void ImageCanvas::get_pixel_mipmap_ewa ( ImageEvalContext context,
const MapEvalCtx eval_ctx,
GMathVec4f &  color,
const double &  anisotropy_factor,
const int &  display_mipmap_level 
) const

Returns the value of the pixel at the given coordinates, using mipmaps and EWA interpolation.

Parameters
MapEvalCtxstructure containing all the parameters needed to compute the pixel color.
void ImageCanvas::get_pixel_mipmap_trilinear ( ImageEvalContext context,
const MapEvalCtx eval_ctx,
GMathVec4f &  color,
const int &  display_mipmap_level 
) const

Returns the value of the pixel at the given coordinates, using trilinear filtering and mipmaps.

Parameters
MapEvalCtxstructure containing all the parameters needed to compute the pixel color.
void ImageCanvas::get_pixel_nearest ( ImageEvalContext context,
const MapEvalCtx eval_ctx,
GMathVec4f &  color 
) const

Returns the value of the pixel at the given coordinates.

Parameters
MapEvalCtxstructure containing all the parameters needed to compute the pixel color.
bool ImageCanvas::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.
ImageCanvas::operator const ImageMap * ( )
inline

Set the x/y coordinates of the image.

Set the wdith and height of the image

returns a const pointer to the top level ImageMap in the mipmap pyramid

void ImageCanvas::process_visible ( ImageMapCtx ctx,
ImageChannelProcess_callback  process,
void *  user_data = 0,
const GMathVec4f *  region = 0 
)

Apply a process on the visible channels of the image.

Parameters
processfunction callback that will be called on each pixel
user_datacustom data that can be used to store parameters
regionpart of the image the process will be applied on.
void ImageCanvas::resize ( const ImageCanvas src,
ImageCanvas destination,
const int &  width,
const int &  height,
int  filtering = 0 
)
static

Returns an RGBA image resized to the specified size using a particular filtering mode.

Parameters
srcsource image
destdestination image
width,heightsize of the destination image
filteringtype of filtering to apply (nearest, bilinear, trilinear, EWA)
Note
This is a simple function to call to build a thumbnail. Custom channels are ignored.
void ImageCanvas::resize ( const ImageCanvas src,
ImageCanvas destination,
ResizeOptions  options,
AppBase app_base = nullptr 
)
static

Resize an image using a particular filtering mode.

Parameters
srcsource image
destdestination image
optionsresizing options
app_baseapplication used to create progress bars
void ImageCanvas::set_canvas ( const int &  x_pos,
const int &  y_pos,
const unsigned int &  x_size,
const unsigned int &  y_size,
const GMathVec4i *  data_window = 0 
)

Set the canvas of the image ( image coordinates and size)

Note
This function does not reset or modify any of the channels or image data.
Parameters
x_pos/y_pos/x_size/y_sizecoordinates of the visible part of the image
data_windowoptional data window. If null, the data window is initialised using the image coordinates.
void ImageCanvas::set_canvas ( const GMathVec4i &  visible_window,
const GMathVec4i *  data_window = 0 
)
inline

Set the canvas of the image ( image coordinates and size)

Note
This function does not reset or modify any of the channels or image data.
Parameters
visible_windowcoordinates of the visible part of the image
data_windowdefines region of the image that has data. If null, the data window is initialised using the visible_window.
bool ImageCanvas::try_lock ( ) const

Try to lock the canvas but don't wait if it's already locked.

Returns
true if the canvas was succesfully locked, false otherwise.
void ImageCanvas::update_custom_channels ( const CoreVector< CoreString > &  to_remove,
const CoreVector< CoreString > &  to_add 
)

Updates the list of channels in the image.

Parameters
to_removethese channels will be removed if they exists
to_removethese channels will be added if they don't.