Material Definition Language API nvidia_logo_transpbg.gif Up
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
mi::neuraylib::IImage Class Referenceabstract

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. More...

Inheritance diagram for mi::neuraylib::IImage:
mi::base::Interface_declare< 0xca59b977, 0x30ee, 0x4172, 0x91, 0x53, 0xb7, 0x70, 0x2c, 0x6b, 0x3a, 0x76, neuraylib::IScene_element > mi::neuraylib::IScene_element mi::base::Interface_declare< 0x8a2a4da9, 0xe323, 0x452c, 0xb8, 0xda, 0x92, 0x45, 0x67, 0x85, 0xd7, 0x78, neuraylib::IAttribute_set > mi::neuraylib::IAttribute_set mi::base::Interface_declare< 0x1bcb8d48, 0x10c1, 0x4b3e, 0x9b, 0xfa, 0x06, 0x23, 0x61, 0x81, 0xd3, 0xe1 > mi::base::IInterface

Public Member Functions

virtual Sint32 reset_file (const char *filename)=0
 Sets the image to a file identified by filename. More...
 
virtual Sint32 reset_reader (IReader *reader, const char *image_format)=0
 Sets the image to the data provided by a reader. More...
 
virtual Sint32 reset_reader (IArray *reader, const char *image_format)=0
 Sets the image to the uv-tile data provided by an array of readers. More...
 
virtual const char * get_filename (Uint32 uvtile_id=0) const =0
 Returns the resolved file name of the file containing the image. More...
 
virtual const char * get_original_filename () const =0
 Returns the unresolved file as passed to reset_file(). More...
 
virtual bool set_from_canvas (const ICanvas *canvas)=0
 Sets the pixels of this image based on the passed canvas (without sharing). More...
 
virtual bool set_from_canvas (ICanvas *canvas, bool shared=false)=0
 Sets the pixels of this image based on the passed canvas (possibly sharing the pixel data). More...
 
virtual bool set_from_canvas (const IArray *uvtiles)=0
 Sets the pixels of the uv-tiles of this image based on the passed canvases (without sharing). More...
 
virtual bool set_from_canvas (IArray *uvtiles, bool shared=false)=0
 Sets the pixels of the uv-tiles of this image based on the passed canvases (possibly sharing the pixel data). More...
 
virtual const ICanvasget_canvas (Uint32 level=0, Uint32 uvtile_id=0) const =0
 Returns a canvas with the pixel data of the image. More...
 
virtual const char * get_type (Uint32 uvtile_id=0) const =0
 Returns the pixel type of the image. More...
 
virtual Uint32 get_levels (Uint32 uvtile_id=0) const =0
 Returns the number of levels in the mipmap pyramid. More...
 
virtual Uint32 resolution_x (Uint32 level=0, Uint32 uvtile_id=0) const =0
 Returns the horizontal resolution of the image. More...
 
virtual Uint32 resolution_y (Uint32 level=0, Uint32 uvtile_id=0) const =0
 Returns the vertical resolution of the image. More...
 
virtual Uint32 resolution_z (Uint32 level=0, Uint32 uvtile_id=0) const =0
 Returns the number of layers of the 3D image. More...
 
virtual Size get_uvtile_length () const =0
 Returns the number of uv-tiles of the image. More...
 
virtual Sint32 get_uvtile_uv (Uint32 uvtile_id, Sint32 &u, Sint32 &v) const =0
 Returns the u and v tile indices of the uv-tile at the given index. More...
 
virtual Uint32 get_uvtile_id (Sint32 u, Sint32 v) const =0
 
virtual bool is_uvtile () const =0
 Returns true if this image represents a uvtile/udim image sequence. More...
 
virtual void get_uvtile_uv_ranges (Sint32 &min_u, Sint32 &min_v, Sint32 &max_u, Sint32 &max_v) const =0
 Returns the ranges of u and v coordinates (or all values zero if is_uvtile() returns false). More...
 

Additional Inherited Members

- Public Types inherited from mi::base::Interface_declare< 0xca59b977, 0x30ee, 0x4172, 0x91, 0x53, 0xb7, 0x70, 0x2c, 0x6b, 0x3a, 0x76, neuraylib::IScene_element >
typedef Interface_declare< id1,
id2, id3, id4, id5, id6, id7,
id8, id9, id10, id11,
neuraylib::IScene_element
Self
 Own type. More...
 
typedef Uuid_t< id1, id2, id3,
id4, id5, id6, id7, id8, id9,
id10, id11 > 
IID
 Declares the interface ID (IID) of this interface. More...
 
- Static Public Member Functions inherited from mi::base::Interface_declare< 0xca59b977, 0x30ee, 0x4172, 0x91, 0x53, 0xb7, 0x70, 0x2c, 0x6b, 0x3a, 0x76, neuraylib::IScene_element >
static bool compare_iid (const Uuid &iid)
 Compares the interface ID iid against the interface ID of this interface and of its ancestors. 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

virtual const ICanvas* mi::neuraylib::IImage::get_canvas ( Uint32  level = 0,
Uint32  uvtile_id = 0 
) 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
levelThe desired mipmap level. Level 0 is the highest resolution.
uvtile_idThe uv-tile id of the canvas.
Returns
A canvas pointing to the pixel data of the image, or NULL in case of failure, e.g. because of an invalid tile id.
virtual const char* mi::neuraylib::IImage::get_filename ( Uint32  uvtile_id = 0) const
pure virtual

Returns the resolved file name of the file containing the image.

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

See Also
get_original_filename()
virtual Uint32 mi::neuraylib::IImage::get_levels ( Uint32  uvtile_id = 0) const
pure virtual

Returns the number of levels in the mipmap pyramid.

Parameters
uvtile_idThe uv-tile id of the canvas to get the number of levels for.
Returns
The number of levels or -1 in case of an invalid tile id.
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()
virtual const char* mi::neuraylib::IImage::get_type ( Uint32  uvtile_id = 0) const
pure virtual

Returns the pixel type of the image.

Parameters
uvtile_idThe uv-tile id of the canvas to get the pixel type for.
Returns
The pixel type or 0 in case of an invalid tile id. See Types for a list of supported pixel types.
virtual Uint32 mi::neuraylib::IImage::get_uvtile_id ( Sint32  u,
Sint32 
) const
pure virtual
Parameters
uThe u-component of the uv-tile
vThe v-component of the uv-tile
Returns
The uvtile-id or -1 of there is no tile with the given coordinates.
virtual Size mi::neuraylib::IImage::get_uvtile_length ( ) const
pure virtual

Returns the number of uv-tiles of the image.

virtual Sint32 mi::neuraylib::IImage::get_uvtile_uv ( Uint32  uvtile_id,
Sint32 u,
Sint32
) const
pure virtual

Returns the u and v tile indices of the uv-tile at the given index.

Parameters
uvtile_idThe uv-tile id of the canvas.
uThe u-component of the uv-tile
vThe v-component of the uv-tile
Returns
0 on success, -1 if uvtile_id is out of range.
virtual void mi::neuraylib::IImage::get_uvtile_uv_ranges ( Sint32 min_u,
Sint32 min_v,
Sint32 max_u,
Sint32 max_v 
) const
pure virtual

Returns the ranges of u and v coordinates (or all values zero if is_uvtile() returns false).

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

Returns true if this image represents a uvtile/udim image sequence.

virtual Sint32 mi::neuraylib::IImage::reset_file ( const char *  filename)
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
<UVTILE1> "_u"I"_v"I _u1_v1 1-based uv-tileset, expands to "_u"(u+1)"_v"(v+1)
Returns
  • 0: Success.
  • -1: Invalid parameters (NULL pointer).
  • -2: Failure to resolve the given filename, e.g., the file does not exist.
  • -3: Failure to open the file.
  • -4: No image plugin found to handle the file.
  • -5: The image plugin failed to import the file.
virtual Sint32 mi::neuraylib::IImage::reset_reader ( IReader reader,
const char *  image_format 
)
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.
Returns
  • 0: Success.
  • -1: Invalid parameters (NULL pointer).
  • -3: The reader does not support absolute access.
  • -4: No image plugin found to handle the data.
  • -5: The image plugin failed to import the data.
virtual Sint32 mi::neuraylib::IImage::reset_reader ( IArray reader,
const char *  image_format 
)
pure virtual

Sets the image to the 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-component of this uv-tile.
  • mi::Sint32 v
    The v-component 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.
Returns
  • 0: Success.
  • -1: Invalid parameters (NULL pointer).
  • -3: The reader does not support absolute access.
  • -4: No image plugin found to handle the data.
  • -5: The image plugin failed to import the data.
virtual Uint32 mi::neuraylib::IImage::resolution_x ( Uint32  level = 0,
Uint32  uvtile_id = 0 
) const
pure virtual

Returns the horizontal resolution of the image.

Parameters
levelThe desired mipmap level. Level 0 is the highest resolution.
uvtile_idThe uv-tile id of the canvas to get the resolution for.
Returns
The horizontal resolution or -1 in case of an invalid tile id.
virtual Uint32 mi::neuraylib::IImage::resolution_y ( Uint32  level = 0,
Uint32  uvtile_id = 0 
) const
pure virtual

Returns the vertical resolution of the image.

Parameters
levelThe desired mipmap level. Level 0 is the highest resolution.
uvtile_idThe uv-tile id of the canvas to get the resolution for.
Returns
The vertical resolution or -1 in case of an invalid tile id.
virtual Uint32 mi::neuraylib::IImage::resolution_z ( Uint32  level = 0,
Uint32  uvtile_id = 0 
) const
pure virtual

Returns the number of layers of the 3D image.

Parameters
levelThe desired mipmap level. Level 0 is the highest resolution.
uvtile_idThe uv-tile id of the canvas to get the resolution for.
Returns
The number of layers or -1 in case of an invalid tile id.
virtual bool mi::neuraylib::IImage::set_from_canvas ( const ICanvas canvas)
pure virtual

Sets the pixels of this image based on 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*,bool) instead.
Returns
true if the pixel data of this image has been set correctly, and false otherwise.
virtual bool mi::neuraylib::IImage::set_from_canvas ( ICanvas canvas,
bool  shared = false 
)
pure virtual

Sets the pixels of this image based on the passed canvas (possibly sharing the pixel data).

Parameters
canvasThe pixel data to be used by this image.
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*). 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.
virtual bool mi::neuraylib::IImage::set_from_canvas ( const IArray uvtiles)
pure virtual

Sets the pixels of the uv-tiles of this image based on the passed canvases (without sharing).

Parameters
uvtilesA static or dynamic array of structures of type Uvtile. Such a structure has the following members:
Returns
true if the pixel data of this image has been set correctly, and false otherwise.
virtual bool mi::neuraylib::IImage::set_from_canvas ( IArray uvtiles,
bool  shared = false 
)
pure virtual

Sets the pixels of the uv-tiles of this image based on 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:
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*). 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.