|
|
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)=0 |
| Sets the image to the passed canvas (without sharing). More...
|
|
virtual bool | set_from_canvas (ICanvas *canvas, 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)=0 |
| Sets the frames/uv-tiles of this image to the passed canvases (without sharing). More...
|
|
virtual bool | set_from_canvas (IArray *uvtiles, bool shared=false)=0 |
| Sets the frames/uv-tiles of this image based to the passed canvases (possibly sharing the pixel data). More...
|
|
|
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...
|
|
|
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...
|
|
|
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...
|
|
|
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...
|
|
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.
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" |
<UVTILE1> | "_u"I"_v"I | _u1_v1 | 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
-
filename | The filename of the image to load. |
selector | The selector, or NULL . See section 2.3.1 in [MDLLS] for details. |
- 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.
- 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.