This interface represents a pixel image file. More...
#include <iimage.h>
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 ICanvas * | get_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 IData * | create_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 IData * | access_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 IData * | edit_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 IInterface * | get_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 IInterface * | get_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... | |
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.
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.
|
pure virtual |
Returns a canvas with the pixel data of the image.
Note that it is not possible to manipulate the pixel data.
frame_id | The frame ID of the canvas. |
uvtile_id | The uv-tile ID of the canvas. |
level | The desired mipmap level. Level 0 is the highest resolution. |
NULL
in case of failure, e.g., because of an invalid uv-tile ID.
|
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().
frame_id | The frame ID of the mipmap. |
uvtile_id | The uv-tile ID of the mipmap. |
Returns the frame ID for a given frame number.
frame_number | The frame number of the frame. |
frame_number
is not a valid frame number. Returns the number of uv-tiles for a given frame (or 0 if frame_id
is out of bounds).
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.
frame_id | The frame ID of the frame. |
frame_id
is out of bounds.
|
pure virtual |
Returns the number of frames of this image. Never zero.
|
pure virtual |
Returns the number of levels in the mipmap pyramid.
frame_id | The frame ID of the mipmap. |
uvtile_id | The uv-tile ID of the mipmap to get the number of levels for. |
|
pure virtual |
Returns the unresolved file as passed to reset_file().
The method returns NULL
after default construction or calls to set_from_canvas().
|
pure virtual |
Returns the selector (or NULL
).
|
pure virtual |
Returns the pixel type of a mipmap.
frame_id | The frame ID of the mipmap. |
uvtile_id | The uv-tile ID of the mipmap to get the pixel type for. |
NULL
in case of an invalid frame ID or uv-tile ID.See Types for a list of supported pixel types.
|
pure virtual |
Returns the uv-tile ID corresponding to u- and v-coordinates.
frame_id | The frame ID of the frame. |
u | The u-coordinate of the uv-tile. |
v | The v-coordinate of the uv-tile.. |
|
pure virtual |
Returns the u- and v- coordinates corresponding to a uv-tile ID.
frame_id | The frame ID of the frame. |
uvtile_id | The uv-tile ID of the uv-tile. |
u | The u-coordinate of the uv-tile. |
v | The v-coordinate of the uv-tile. |
uvtile_id
is out of range.
|
pure virtual |
Returns the ranges of u- and v-coordinates.
frame_id | The frame ID of the frame. | |
[out] | min_u | Smallest u-coordinate for that frame. |
[out] | min_v | Smallest v-coordinate for that frame. |
[out] | max_u | Largest u-coordinate for that frame. |
[out] | max_v | Largest v-coordinate for that frame. |
|
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.
|
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.
|
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><UVTILE1></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.
filename | The filename of the image to load. |
selector | The selector, or NULL . See section 2.3.1 in [MDLLS] for details. |
NULL
pointer).
|
pure virtual |
Sets the image to the frame/uv-tile data provided by an array of readers.
reader | A static or dynamic array of structures of type Uvtile_reader . Such a structure has the following members:
|
image_format | The 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. |
selector | The selector, or NULL . See section 2.3.1 in [MDLLS] for details. |
NULL
pointer).
|
pure virtual |
Sets the image to the data provided by a reader.
reader | The reader that provides the data for the image. The reader needs to support absolute access. |
image_format | The 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. |
selector | The selector, or NULL . See section 2.3.1 in [MDLLS] for details. |
NULL
pointer).
|
pure virtual |
Returns the horizontal resolution of a canvas.
frame_id | The frame ID of the canvas. |
uvtile_id | The uv-tile ID of the canvas to get the resolution for. |
level | The desired mipmap level. Level 0 is the highest resolution. |
|
pure virtual |
Returns the vertical resolution of a canvas.
frame_id | The frame ID of the canvas. |
uvtile_id | The uv-tile ID of the canvas to get the resolution for. |
level | The desired mipmap level. Level 0 is the highest resolution. |
|
pure virtual |
Returns the number of layers of a canvas.
frame_id | The frame ID of the canvas. |
uvtile_id | The uv-tile ID of the canvas to get the resolution for. |
level | The desired mipmap level. Level 0 is the highest resolution. |
|
pure virtual |
Sets the frames/uv-tiles of this image to the passed canvases (without sharing).
uvtiles | A static or dynamic array of structures of type Uvtile . Such a structure has the following members:
|
selector | The 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(). |
true
if the pixel data of this image has been set correctly, and false
otherwise.
|
pure virtual |
Sets the image to the passed canvas (without sharing).
canvas | The 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. |
selector | The 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(). |
true
if the pixel data of this image has been set correctly, and false
otherwise.
|
pure virtual |
Sets the frames/uv-tiles of this image based to the passed canvases (possibly sharing the pixel data).
uvtiles | A static or dynamic array of structures of type Uvtile . Such a structure has the following members:
|
selector | The 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(). |
shared | If 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. |
true
if the pixel data of this image has been set correctly, and false
otherwise.
|
pure virtual |
Sets the image to the passed canvas (possibly sharing the pixel data).
canvas | The pixel data to be used by this image. |
selector | The 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(). |
shared | If 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. |
true
if the pixel data of this image has been set correctly, and false
otherwise.