neuray API Programmer's Manual

mi::neuraylib::IImage Class Reference

[Miscellaneous]

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

mi::base::Interface_declare\< ..., neuraylib::IScene_element \>Mixin class template for deriving new interface declarations. Common base interface for all scene elements.Common base interface for all scene elements. mi::base::Interface_declare\< ..., neuraylib::IAttribute_set \>Mixin class template for deriving new interface declarations. The attribute set comprises all attributes attached to a database element.The attribute set comprises all attributes attached to a database element. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. The basic extensible interface.The basic extensible interface.

Public Member Functions

virtual const ICanvas* get_canvas( Uint32 level = 0) const =0
Returns a canvas with the pixel data of the image. More...
virtual const char* get_filename() const =0
Returns the resolved file name of the file containing the image. More...
virtual Uint32 get_levels() const =0
Returns the number of levels in the mipmap pyramid.
virtual const char* get_original_filename() const =0
Returns the unresolved file as passed to reset_file(). More...
virtual const char* get_type() const =0
Returns the pixel type of the image. More...
virtual Sint32 reset_file( const char* filename) =0
Resets the underlying file to a new file given by filename. More...
virtual Uint32 resolution_x( Uint32 level = 0) const =0
Returns the horizontal resolution of the image. More...
virtual Uint32 resolution_y( Uint32 level = 0) const =0
Returns the vertical resolution of the image. More...
virtual Uint32 resolution_z( Uint32 level = 0) const =0
Returns the number of layers of the 3D image. 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...

Member Functions

virtual const ICanvas* mi::​neuraylib::​IImage::get_canvas( Uint32 level = 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

level
The 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.

virtual const char* mi::​neuraylib::​IImage::get_filename() 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() const [pure virtual]

Returns the number of levels in the mipmap pyramid.

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() const [pure virtual]

Returns the pixel type of the image. See Types for a list of supported pixel types.

virtual Sint32 mi::​neuraylib::​IImage::reset_file( const char* filename) [pure virtual]

Resets the underlying file to a new file given by filename. 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).
  • -2: Failure to resolve the given filename, e.g., the file does not exist.
virtual Uint32 mi::​neuraylib::​IImage::resolution_x( Uint32 level = 0) const [pure virtual]

Returns the horizontal resolution of the image.

Parameters

level
The desired mipmap level. Level 0 is the highest resolution.
virtual Uint32 mi::​neuraylib::​IImage::resolution_y( Uint32 level = 0) const [pure virtual]

Returns the vertical resolution of the image.

Parameters

level
The desired mipmap level. Level 0 is the highest resolution.
virtual Uint32 mi::​neuraylib::​IImage::resolution_z( Uint32 level = 0) const [pure virtual]

Returns the number of layers of the 3D image.

Parameters

level
The desired mipmap level. Level 0 is the highest resolution.
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

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*, 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

canvas
The pixel data to be used by this image.
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*). 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.