MDL SDK API nvidia_logo_transpbg.gif Up
mi::neuraylib::IImage Class Referenceabstract

This interface represents a pixel image file. More...

#include <iimage.h>

Inheritance diagram for mi::neuraylib::IImage:

Public Member Functions

Modification of the scene element
virtual Sint32 reset_file (const char *filename, const char *selector=0)=0
 Sets the image to a file identified by filename. More...
 
virtual Sint32 reset_reader (IReader *reader, const char *image_format, const char *selector=0)=0
 Sets the image to the data provided by a reader. More...
 
virtual Sint32 reset_reader (IArray *reader, const char *image_format, const char *selector=0)=0
 Sets the image to the frame/uv-tile data provided by an array of readers. More...
 
virtual bool set_from_canvas (const ICanvas *canvas, const char *selector=0)=0
 Sets the image to the passed canvas (without sharing). More...
 
virtual bool set_from_canvas (ICanvas *canvas, const char *selector=0, bool shared=false)=0
 Sets the image to the passed canvas (possibly sharing the pixel data). More...
 
virtual bool set_from_canvas (const IArray *uvtiles, const char *selector=0)=0
 Sets the frames/uv-tiles of this image to the passed canvases (without sharing). More...
 
virtual bool set_from_canvas (IArray *uvtiles, const char *selector=0, bool shared=false)=0
 Sets the frames/uv-tiles of this image based to the passed canvases (possibly sharing the pixel data). More...
 
Methods related to frames of animated textures
virtual bool is_animated () const =0
 Indicates whether this image represents an animated texture. More...
 
virtual Size get_length () const =0
 Returns the number of frames of this image. Never zero. More...
 
virtual Size get_frame_number (Size frame_id) const =0
 Returns the frame number for a give frame ID. More...
 
virtual Size get_frame_id (Size frame_number) const =0
 Returns the frame ID for a given frame number. More...
 
Methods related to uvtiles
virtual bool is_uvtile () const =0
 Indicates whether this image represents a uvtile sequence. More...
 
virtual Size get_frame_length (Size frame_id) const =0
 Returns the number of uv-tiles for a given frame (or 0 if frame_id is out of bounds). More...
 
virtual Sint32 get_uvtile_uv (Size frame_id, Size uvtile_id, Sint32 &u, Sint32 &v) const =0
 Returns the u- and v- coordinates corresponding to a uv-tile ID. More...
 
virtual Size get_uvtile_id (Size frame_id, Sint32 u, Sint32 v) const =0
 Returns the uv-tile ID corresponding to u- and v-coordinates. More...
 
virtual void get_uvtile_uv_ranges (Size frame_id, Sint32 &min_u, Sint32 &min_v, Sint32 &max_u, Sint32 &max_v) const =0
 Returns the ranges of u- and v-coordinates. More...
 
Methods to query filenames, selector, and canvases
virtual const char * get_filename (Size frame_id, Size uvtile_id) const =0
 Returns the resolved file name of a mipmap of the image. More...
 
virtual const char * get_original_filename () const =0
 Returns the unresolved file as passed to reset_file(). More...
 
virtual const char * get_selector () const =0
 Returns the selector (or NULL). More...
 
virtual const ICanvasget_canvas (Size frame_id, Size uvtile_id, Uint32 level) const =0
 Returns a canvas with the pixel data of the image. More...
 
Properties of the canvases (convenience methods)
virtual const char * get_type (Size frame_id, Size uvtile_id) const =0
 Returns the pixel type of a mipmap. More...
 
virtual Uint32 get_levels (Size frame_id, Size uvtile_id) const =0
 Returns the number of levels in the mipmap pyramid. More...
 
virtual Uint32 resolution_x (Size frame_id, Size uvtile_id, Uint32 level) const =0
 Returns the horizontal resolution of a canvas. More...
 
virtual Uint32 resolution_y (Size frame_id, Size uvtile_id, Uint32 level) const =0
 Returns the vertical resolution of a canvas. More...
 
virtual Uint32 resolution_z (Size frame_id, Size uvtile_id, Uint32 level) const =0
 Returns the number of layers of a canvas. More...
 
- Public Member Functions inherited from mi::neuraylib::IScene_element
virtual Element_type get_element_type () const =0
 Indicates the actual scene element represented by interfaces derived from this interface. More...
 
- Public Member Functions inherited from mi::neuraylib::IAttribute_set
virtual IDatacreate_attribute (const char *name, const char *type)=0
 Creates a new attribute name of the type type. More...
 
template<class T>
T * create_attribute (const char *name, const char *type)
 Creates a new attribute name of the type type. More...
 
template<class T>
T * create_attribute (const char *name)
 Creates a new attribute name of the type T. More...
 
virtual bool destroy_attribute (const char *name)=0
 Destroys the attribute name. More...
 
virtual const IDataaccess_attribute (const char *name) const =0
 Returns a const pointer to the attribute name. More...
 
template<class T>
const T * access_attribute (const char *name) const
 Returns a const pointer to the attribute name. More...
 
virtual IDataedit_attribute (const char *name)=0
 Returns a mutable pointer to the attribute name. More...
 
template<class T>
T * edit_attribute (const char *name)
 Returns a mutable pointer to the attribute name. More...
 
virtual bool is_attribute (const char *name) const =0
 Indicates existence of an attribute. More...
 
virtual const char * get_attribute_type_name (const char *name) const =0
 Returns the type of an attribute. More...
 
virtual Sint32 set_attribute_propagation (const char *name, Propagation_type value)=0
 Sets the propagation type of the attribute name. More...
 
virtual Propagation_type get_attribute_propagation (const char *name) const =0
 Returns the propagation type of the attribute name. More...
 
virtual const char * enumerate_attributes (Sint32 index) const =0
 Returns the name of the attribute indicated by index. More...
 
- Public Member Functions inherited from mi::base::IInterface
virtual Uint32 retain () const =0
 Increments the reference count. More...
 
virtual Uint32 release () const =0
 Decrements the reference count. More...
 
virtual const IInterfaceget_interface (const Uuid &interface_id) const =0
 Acquires a const interface from another. More...
 
template<class T>
const T * get_interface () const
 Acquires a const interface from another. More...
 
virtual IInterfaceget_interface (const Uuid &interface_id)=0
 Acquires a mutable interface from another. More...
 
template<class T>
T * get_interface ()
 Acquires a mutable interface from another. More...
 
virtual Uuid get_iid () const =0
 Returns the interface ID of the most derived interface. More...
 

Additional Inherited Members

- Public Types inherited from mi::base::Interface_declare< 0xca59b977, ... >
typedef Interface_declare< id1, ... > Self
 Own type. More...
 
typedef Uuid_t< id1, ... > IID
 Declares the interface ID (IID) of this interface. More...
 
- Public Types inherited from mi::base::Interface_declare< 0x8a2a4da9, ... >
typedef Interface_declare< id1, ... > Self
 Own type. More...
 
typedef Uuid_t< id1, ... > IID
 Declares the interface ID (IID) of this interface. More...
 
- Public Types inherited from mi::base::Interface_declare< 0x1bcb8d48, ... >
typedef Interface_declare< id1, ... > Self
 Own type. More...
 
typedef Uuid_t< id1, ... > IID
 Declares the interface ID (IID) of this interface. More...
 
- Public Types inherited from mi::base::IInterface
typedef Uuid_t<0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0> IID
 Declares the interface ID (IID) of this interface. More...
 
- Static Public Member Functions inherited from mi::base::Interface_declare< 0xca59b977, ... >
static bool compare_iid (const Uuid &iid)
 Compares the interface ID iid against the interface ID of this interface and of its ancestors. More...
 
- Static Public Member Functions inherited from mi::base::Interface_declare< 0x8a2a4da9, ... >
static bool compare_iid (const Uuid &iid)
 Compares the interface ID iid against the interface ID of this interface and of its ancestors. More...
 
- Static Public Member Functions inherited from mi::base::Interface_declare< 0x1bcb8d48, ... >
static bool compare_iid (const Uuid &iid)
 Compares the interface ID iid against the interface ID of this interface and of its ancestors. More...
 
- Static Public Member Functions inherited from mi::base::IInterface
static bool compare_iid (const Uuid &iid)
 Compares the interface ID iid against the interface ID of this interface. More...
 

Detailed Description

This interface represents a pixel image file.

It supports different pixel types, 2D and 3D image data, and mipmap levels. Its main usage is in textures, see the mi::neuraylib::ITexture class.

The image coordinate system has its origin in the lower left corner in the case of 2D image data.

Editing and copying an image

Note that editing an existing image has unusual semantics that differ from all other DB elements. Usually, when editing a database element, an identical copy of the database element is created (the existing one cannot be used because it might be needed for other transactions, other scopes, or in case the transaction is aborted). For images, this implies a copy of all the pixel data which is very expensive.

There are only two mutable methods on this interface, reset_file() and set_from_canvas(); all other methods are const. Both methods eventually replace the entire pixel data anyway. Therefore, when an image is edited, the pixel data is not copied, but replaced by a dummy image of size 1x1. This approach saves the unneeded, but expensive copy of the original pixel data. When afterwards one of two methods above is called, the image uses the correct pixel data again.

Note that this also affects the results from methods like resolution_x(), etc. (if you want to know the resolution of an existing image without changing it, you should access the image, not edit it). Furthermore, you might end up with the dummy image if you do not call reset_file() or set_from_canvas() (or if these methods fail).

Note that using the transaction's copy function has the same semantics when used on an image. Thus after copying it is necessary to use either reset_file() or set_from_canvas() on the copy.

Member Function Documentation

 get_canvas()

virtual const ICanvas * mi::neuraylib::IImage::get_canvas ( Size  frame_id,
Size  uvtile_id,
Uint32  level 
) const
pure virtual

Returns a canvas with the pixel data of the image.

Note that it is not possible to manipulate the pixel data.

Parameters
frame_idThe frame ID of the canvas.
uvtile_idThe uv-tile ID of the canvas.
levelThe desired mipmap level. Level 0 is the highest resolution.
Returns
A canvas pointing to the pixel data of the image, or NULL in case of failure, e.g., because of an invalid uv-tile ID.

 get_filename()

virtual const char * mi::neuraylib::IImage::get_filename ( Size  frame_id,
Size  uvtile_id 
) const
pure virtual

Returns the resolved file name of a mipmap of the image.

The method returns NULL if there is no file associated with the mipmap, e.g., after default construction, calls to set_from_canvas(), or failures to resolve the file name passed to reset_file().

Parameters
frame_idThe frame ID of the mipmap.
uvtile_idThe uv-tile ID of the mipmap.
See also
get_original_filename()

 get_frame_id()

virtual Size mi::neuraylib::IImage::get_frame_id ( Size  frame_number) const
pure virtual

Returns the frame ID for a given frame number.

Parameters
frame_numberThe frame number of the frame.
Returns
The frame ID, or -1 if frame_number is not a valid frame number.

 get_frame_length()

virtual Size mi::neuraylib::IImage::get_frame_length ( Size  frame_id) const
pure virtual

Returns the number of uv-tiles for a given frame (or 0 if frame_id is out of bounds).

 get_frame_number()

virtual Size mi::neuraylib::IImage::get_frame_number ( Size  frame_id) const
pure virtual

Returns the frame number for a give frame ID.

This function is strictly monotonically increasing. Frame numbers are not necessarily consecutive, there can be missing frame numbers.

Parameters
frame_idThe frame ID of the frame.
Returns
The frame number, or -1 if frame_id is out of bounds.

 get_length()

virtual Size mi::neuraylib::IImage::get_length ( ) const
pure virtual

Returns the number of frames of this image. Never zero.

 get_levels()

virtual Uint32 mi::neuraylib::IImage::get_levels ( Size  frame_id,
Size  uvtile_id 
) const
pure virtual

Returns the number of levels in the mipmap pyramid.

Parameters
frame_idThe frame ID of the mipmap.
uvtile_idThe uv-tile ID of the mipmap to get the number of levels for.
Returns
The number of levels, or -1 in case of an invalid frame ID or uv-tile ID.

 get_original_filename()

virtual const char * mi::neuraylib::IImage::get_original_filename ( ) const
pure virtual

Returns the unresolved file as passed to reset_file().

The method returns NULL after default construction or calls to set_from_canvas().

See also
get_filename()

 get_selector()

virtual const char * mi::neuraylib::IImage::get_selector ( ) const
pure virtual

Returns the selector (or NULL).

 get_type()

virtual const char * mi::neuraylib::IImage::get_type ( Size  frame_id,
Size  uvtile_id 
) const
pure virtual

Returns the pixel type of a mipmap.

Parameters
frame_idThe frame ID of the mipmap.
uvtile_idThe uv-tile ID of the mipmap to get the pixel type for.
Returns
The pixel type, or NULL in case of an invalid frame ID or uv-tile ID.

See Types for a list of supported pixel types.

 get_uvtile_id()

virtual Size mi::neuraylib::IImage::get_uvtile_id ( Size  frame_id,
Sint32  u,
Sint32  v 
) const
pure virtual

Returns the uv-tile ID corresponding to u- and v-coordinates.

Parameters
frame_idThe frame ID of the frame.
uThe u-coordinate of the uv-tile.
vThe v-coordinate of the uv-tile..
Returns
The uv-tile ID, or -1 of there is no uv-tile with the given coordinates.

 get_uvtile_uv()

virtual Sint32 mi::neuraylib::IImage::get_uvtile_uv ( Size  frame_id,
Size  uvtile_id,
Sint32 u,
Sint32 v 
) const
pure virtual

Returns the u- and v- coordinates corresponding to a uv-tile ID.

Parameters
frame_idThe frame ID of the frame.
uvtile_idThe uv-tile ID of the uv-tile.
uThe u-coordinate of the uv-tile.
vThe v-coordinate of the uv-tile.
Returns
0 on success, -1 if uvtile_id is out of range.

 get_uvtile_uv_ranges()

virtual void mi::neuraylib::IImage::get_uvtile_uv_ranges ( Size  frame_id,
Sint32 min_u,
Sint32 min_v,
Sint32 max_u,
Sint32 max_v 
) const
pure virtual

Returns the ranges of u- and v-coordinates.

Parameters
frame_idThe frame ID of the frame.
[out]min_uSmallest u-coordinate for that frame.
[out]min_vSmallest v-coordinate for that frame.
[out]max_uLargest u-coordinate for that frame.
[out]max_vLargest v-coordinate for that frame.

 is_animated()

virtual bool mi::neuraylib::IImage::is_animated ( ) const
pure virtual

Indicates whether this image represents an animated texture.

The return value false implies that there is a single frame with frame number 0.

 is_uvtile()

virtual bool mi::neuraylib::IImage::is_uvtile ( ) const
pure virtual

Indicates whether this image represents a uvtile sequence.

The return value false implies that there is a single uv-tile (per frame) with u- and v- coordinates of 0.

 reset_file()

virtual Sint32 mi::neuraylib::IImage::reset_file ( const char *  filename,
const char *  selector = 0 
)
pure virtual

Sets the image to a file identified by filename.

Note that support for a given image format requires an image plugin capable of handling that format.

The filename can include one of the following three uv-tileset markers in the filename: <UDIM>, <UVTILE0>, or <UVTILE1>. The image refers then to a whole uv-tileset, a set of images used together as a single large two-dimensional image. The different markers indicate the different filename conventions that encode where each image file is placed in the uv texture space.

Marker Pattern (0,0) index Convention to format a (u, v)-index
<UDIM> DDDD 1001 UDIM, expands to the four digit number 1000+(u+1+v*10)
<UVTILE0> "_u"I"_v"I _u0_v0 0-based uv-tileset, expands to "_u"u"_v"v"</td> </tr> <tr> <td>&lt;UVTILE1&gt;</td> <td>"_u"I"_v"I</td> <td>_u1_v1</td> <td>1-based uv-tileset, expands to "_u"(u+1)"_v"(v+1)"

The filename can also include a sequence marker for the frame number of animated textures: <#...> (with a non-zero count of '#' characters). The marker matches any non-negative integral number of at most as many digits as there are '#' characters in the sequence marker. The number may have leading zeros, which are ignored for its numerical interpretation. Multiple occurrences of the same number is undefined behavior (can happen in case of leading zeros).

Images without sequences marker are treated as a single frame with frame number 0. Images without uv-tileset marker are treated as a single uv-tile (per frame) with u- and v-coordinates of 0.

Parameters
filenameThe filename of the image to load.
selectorThe selector, or NULL. See section 2.3.1 in [MDLLS] for details.
Returns
  • 0: Success.
  • -1: Invalid parameters (NULL pointer).
  • -3: No image plugin found to handle the file.
  • -4: Failure to resolve the given filename, e.g., the file does not exist.
  • -5: Failure to open the resolved file.
  • -7: The image plugin failed to import the file.
  • -10: Failure to apply the given selector.
See also
mi::neuraylib::IMdl_factory::create_texture() for a way to create a texture based on an MDL file path instead of a filename.

 reset_reader() [1/2]

virtual Sint32 mi::neuraylib::IImage::reset_reader ( IArray reader,
const char *  image_format,
const char *  selector = 0 
)
pure virtual

Sets the image to the frame/uv-tile data provided by an array of readers.

Parameters
readerA static or dynamic array of structures of type Uvtile_reader. Such a structure has the following members:
  • mi::Sint32 u
    The u-coordinate of this uv-tile.
  • mi::Sint32 v
    The v-coordinate of this uv-tile.
  • mi::Size frame
    The frame number of this uv-tile.
  • mi::neuraylib::IReader* reader
    The reader that provides the data for this uv-tile. The reader needs to support absolute access.
image_formatThe image format of the data, e.g., "jpg". Note that support for a given image format requires an image plugin capable of handling that format.
selectorThe selector, or NULL. See section 2.3.1 in [MDLLS] for details.
Returns
  • 0: Success.
  • -1: Invalid parameters (NULL pointer).
  • -3: No image plugin found to handle the file.
  • -6: The reader does not support absolute access.
  • -7: The image plugin failed to import the data.
  • -10: Failure to apply the given selector.
  • -11: Invalid reader array (empty, wrong element type, or invalid array slots or struct fields).
  • -12: Repeated u/v coordinates (per frame).

 reset_reader() [2/2]

virtual Sint32 mi::neuraylib::IImage::reset_reader ( IReader reader,
const char *  image_format,
const char *  selector = 0 
)
pure virtual

Sets the image to the data provided by a reader.

Parameters
readerThe reader that provides the data for the image. The reader needs to support absolute access.
image_formatThe image format of the data, e.g., "jpg". Note that support for a given image format requires an image plugin capable of handling that format.
selectorThe selector, or NULL. See section 2.3.1 in [MDLLS] for details.
Returns
  • 0: Success.
  • -1: Invalid parameters (NULL pointer).
  • -3: No image plugin found to handle the file.
  • -6: The reader does not support absolute access.
  • -7: The image plugin failed to import the data.
  • -10: Failure to apply the given selector.

 resolution_x()

virtual Uint32 mi::neuraylib::IImage::resolution_x ( Size  frame_id,
Size  uvtile_id,
Uint32  level 
) const
pure virtual

Returns the horizontal resolution of a canvas.

Parameters
frame_idThe frame ID of the canvas.
uvtile_idThe uv-tile ID of the canvas to get the resolution for.
levelThe desired mipmap level. Level 0 is the highest resolution.
Returns
The horizontal resolution, or -1 in case of an invalid frame ID, uv-tile ID, or level.

 resolution_y()

virtual Uint32 mi::neuraylib::IImage::resolution_y ( Size  frame_id,
Size  uvtile_id,
Uint32  level 
) const
pure virtual

Returns the vertical resolution of a canvas.

Parameters
frame_idThe frame ID of the canvas.
uvtile_idThe uv-tile ID of the canvas to get the resolution for.
levelThe desired mipmap level. Level 0 is the highest resolution.
Returns
The vertical resolution, or -1 in case of an invalid frame ID, uv-tile ID, or level.

 resolution_z()

virtual Uint32 mi::neuraylib::IImage::resolution_z ( Size  frame_id,
Size  uvtile_id,
Uint32  level 
) const
pure virtual

Returns the number of layers of a canvas.

Parameters
frame_idThe frame ID of the canvas.
uvtile_idThe uv-tile ID of the canvas to get the resolution for.
levelThe desired mipmap level. Level 0 is the highest resolution.
Returns
The number of layers, or -1 in case of an invalid frame ID, uv-tile ID, or level.

 set_from_canvas() [1/4]

virtual bool mi::neuraylib::IImage::set_from_canvas ( const IArray uvtiles,
const char *  selector = 0 
)
pure virtual

Sets the frames/uv-tiles of this image to the passed canvases (without sharing).

Parameters
uvtilesA static or dynamic array of structures of type Uvtile. Such a structure has the following members:
selectorThe selector, or NULL. See section 2.3.1 in [MDLLS] for details. Note that the selector is not applied to the canvas, the information is just stored for retrieval via get_selector().
Returns
true if the pixel data of this image has been set correctly, and false otherwise.

 set_from_canvas() [2/4]

virtual bool mi::neuraylib::IImage::set_from_canvas ( const ICanvas canvas,
const char *  selector = 0 
)
pure virtual

Sets the image to the passed canvas (without sharing).

Parameters
canvasThe pixel data to be used by this image. Note that the pixel data is copied, not shared. If sharing is intended, use mi::neuraylib::IImage::set_from_canvas(mi::neuraylib::ICanvas*,const char*,bool) instead.
selectorThe selector, or NULL. See section 2.3.1 in [MDLLS] for details. Note that the selector is not applied to the canvas, the information is just stored for retrieval via get_selector().
Returns
true if the pixel data of this image has been set correctly, and false otherwise.

 set_from_canvas() [3/4]

virtual bool mi::neuraylib::IImage::set_from_canvas ( IArray uvtiles,
const char *  selector = 0,
bool  shared = false 
)
pure virtual

Sets the frames/uv-tiles of this image based to the passed canvases (possibly sharing the pixel data).

Parameters
uvtilesA static or dynamic array of structures of type Uvtile. Such a structure has the following members:
selectorThe selector, or NULL. See section 2.3.1 in [MDLLS] for details. Note that the selector is not applied to the canvas, the information is just stored for retrieval via get_selector().
sharedIf false (the default), the pixel data is copied from canvas and the method does the same as mi::neuraylib::IImage::set_from_canvas(const mi::neuraylib::ICanvas*,const char*). If set to true, the image uses the canvases directly (doing reference counting on the canvas pointers). You must not modify the canvas contents after this call.
Returns
true if the pixel data of this image has been set correctly, and false otherwise.

 set_from_canvas() [4/4]

virtual bool mi::neuraylib::IImage::set_from_canvas ( ICanvas canvas,
const char *  selector = 0,
bool  shared = false 
)
pure virtual

Sets the image to the passed canvas (possibly sharing the pixel data).

Parameters
canvasThe pixel data to be used by this image.
selectorThe selector, or NULL. See section 2.3.1 in [MDLLS] for details. Note that the selector is not applied to the canvas, the information is just stored for retrieval via get_selector().
sharedIf false (the default), the pixel data is copied from canvas and the method does the same as mi::neuraylib::IImage::set_from_canvas(const mi::neuraylib::ICanvas*,const char*). If set to true, the image uses the canvas directly (doing reference counting on the canvas pointer). You must not modify the canvas content after this call.
Returns
true if the pixel data of this image has been set correctly, and false otherwise.