This interface provides various utilities related to canvases and buffers. More...

#include <iimage_api.h>

Inheritance diagram for mi::neuraylib::IImage_api:

Public Member Functions
Factory methods for canvases and tiles
virtual ITile *	create_tile (const char *pixel_type, Uint32 width, Uint32 height) const =0
	Creates a tile with given pixel type, width, and height. More...

virtual ICanvas *	create_canvas (const char *pixel_type, Uint32 width, Uint32 height, Uint32 layers=1, bool is_cubemap=false, Float32 gamma=0.0f) const =0
	Creates a canvas with given pixel type, resolution, and layers. More...

virtual ICanvas_cuda *	create_canvas_cuda (Sint32 cuda_device_id, const char *pixel_type, Uint32 width, Uint32 height, Uint32 layers=1, Float32 gamma=0.0f) const =0
	Unused. More...

virtual IArray *	create_mipmap (const ICanvas *canvas, Float32 gamma_override=0.0f) const =0
	Creates a mipmap from the given canvas. More...

virtual ITile *	clone_tile (const ITile *tile) const =0
	Creates a copy of the passed tile. More...

virtual ICanvas *	clone_canvas (const ICanvas *canvas) const =0
	Creates a (deep) copy of the passed canvas. More...

Conversion between canvases and raw memory buffers
virtual Sint32	read_raw_pixels (Uint32 width, Uint32 height, const ICanvas canvas, Uint32 canvas_x, Uint32 canvas_y, Uint32 canvas_layer, void buffer, bool buffer_topdown, const char *buffer_pixel_type, Uint32 buffer_padding=0) const =0
	Reads raw pixel data from a canvas. More...

virtual Sint32	write_raw_pixels (Uint32 width, Uint32 height, ICanvas canvas, Uint32 canvas_x, Uint32 canvas_y, Uint32 canvas_layer, const void buffer, bool buffer_topdown, const char *buffer_pixel_type, Uint32 buffer_padding=0) const =0
	Writes raw pixel data to a canvas. More...

Conversion between canvases and encoded images
virtual IBuffer *	create_buffer_from_canvas (const ICanvas canvas, const char image_format, const char pixel_type, const IMap export_options=0) const =0
	Encodes the pixel data of a canvas into a memory buffer. More...

virtual ICanvas *	create_canvas_from_buffer (const IBuffer buffer, const char image_format, const char *selector=0) const =0
	Decodes the pixel data of a memory buffer into a canvas. More...

virtual ICanvas *	create_canvas_from_reader (IReader reader, const char image_format, const char *selector=0) const =0
	Decodes the pixel data from a reader into a canvas. More...

virtual bool	supports_format_for_decoding (const char image_format, IReader reader=0) const =0
	Indicates whether a particular image format is supported for decoding. More...

virtual bool	supports_format_for_encoding (const char *image_format) const =0
	Indicates whether a particular image format is supported for encoding. More...

Utility methods for canvases
virtual ITile *	convert (const ITile tile, const char pixel_type) const =0
	Converts a tile to a different pixel type. More...

virtual ICanvas *	convert (const ICanvas canvas, const char pixel_type) const =0
	Converts a canvas to a different pixel type. More...

virtual void	adjust_gamma (ITile *tile, Float32 old_gamma, Float32 new_gamma) const =0
	Sets the gamma value of a tile and adjusts the pixel data accordingly. More...

virtual void	adjust_gamma (ICanvas *canvas, Float32 new_gamma) const =0
	Sets the gamma value of a canvas and adjusts the pixel data accordingly. More...

Utility methods for pixel type characteristics
virtual Uint32	get_components_per_pixel (const char *pixel_type) const =0
	Returns the number of components per pixel type. More...

virtual Uint32	get_bytes_per_component (const char *pixel_type) const =0
	Returns the number of bytes used per pixel component. More...

Utility methods for RGBA channels
virtual const char *	get_pixel_type_for_channel (const char pixel_type, const char selector) const =0
	Returns the pixel type of an RGBA channel. More...

virtual ICanvas *	extract_channel (const ICanvas canvas, const char selector) const =0
	Extracts an RGBA channel from a canvas. More...

virtual ITile *	extract_channel (const ITile tile, const char selector) const =0
	Extracts an RGBA channel from a tile. More...

virtual IBuffer *	deprecated_create_buffer_from_canvas (const ICanvas canvas, const char image_format, const char pixel_type, const char quality, bool force_default_gamma) const =0

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< 0x4c25a4f0, ... >
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< 0x4c25a4f0, ... >
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 provides various utilities related to canvases and buffers.

Note that create_buffer_from_canvas() and create_canvas_from_buffer() encode and decode pixel data to/from memory buffers.

Image export options

Various methods for image export support options to control details of the export process. The following general options are currently supported:

bool "force_default_gamma": If enabled, adjusts the gamma value of the exported pixel data according to the pixel type chosen for export (1.0 for HDR pixel types, 2.2 for LDR pixel types). Default: false.

The following format-specific options are currently supported:

mi::Uint32 "jpg:quality": The quality of JPG compression in the range from 0 to 100, where 0 is the lowest quality, and 100 is the highest. Default: 100.
std::string "exr:data_type": Indicates the desired data type of the channels. Possible values: "Float16" and "Float32". Default: "Float32".
bool "exr:create_multipart_for_alpha": If enabled, and if the pixel type has an alpha channel, creates an OpenEXR multipart image where the RGB and alpha channels are split into two subimages named "rgb" and "alpha". The advantage is that with a separate subimage the alpha channel can be kept unassociated without violating the OpenEXR specification. Default: false.

Member Function Documentation

^◆ adjust_gamma() [1/2]

virtual void mi::neuraylib::IImage_api::adjust_gamma	(	ICanvas *	canvas,
		Float32	new_gamma
	)		const

pure virtual

Sets the gamma value of a canvas and adjusts the pixel data accordingly.

The alpha channel (if present) is always linear and not affected by this operation.

Note: Gamma adjustments are always done in pixel type "Color" or "Rgb_fp". If necessary, the pixel data is converted forth and back automatically (which needs temporary buffers).

Parameters

canvas	The canvas whose pixel data is to be adjusted.
new_gamma	The new gamma value.

^◆ adjust_gamma() [2/2]

virtual void mi::neuraylib::IImage_api::adjust_gamma	(	ITile *	tile,
		Float32	old_gamma,
		Float32	new_gamma
	)		const

pure virtual

Sets the gamma value of a tile and adjusts the pixel data accordingly.

The alpha channel (if present) is always linear and not affected by this operation.

Note: Gamma adjustments are always done in pixel type "Color" or "Rgb_fp". If necessary, the pixel data is converted forth and back automatically (which needs temporary buffers).

Parameters

tile	The tile whose pixel data is to be adjusted.
old_gamma	The old gamma value.
new_gamma	The new gamma value.

^◆ clone_canvas()

virtual ICanvas * mi::neuraylib::IImage_api::clone_canvas ( const ICanvas * canvas ) const

pure virtual

Creates a (deep) copy of the passed canvas.

^◆ clone_tile()

virtual ITile * mi::neuraylib::IImage_api::clone_tile ( const ITile * tile ) const

pure virtual

Creates a copy of the passed tile.

^◆ convert() [1/2]

virtual ICanvas * mi::neuraylib::IImage_api::convert	(	const ICanvas *	canvas,
		const char *	pixel_type
	)		const

pure virtual

Converts a canvas to a different pixel type.

Note: This method creates a copy if the passed-in canvas already has the desired pixel type. (It cannot return the passed-in canvas since this would require a const cast.) If performance is critical, you should compare pixel types yourself and skip the method call if pixel type conversion is not needed.)

The conversion converts a given pixel as follows:

Floating-point values are linearly mapped to integers as follows: 0.0f is mapped to 0 and 1.0f is mapped to 255 or 65535, respectively. Note that the pixel type "Sint8" is treated as the corresponding unsigned integer type "Uint8" here. Floating-point values are clamped to [0.0f, 1.0f] beforehand. The reverse conversion uses the corresponding inverse mapping.
Single-channel formats are converted to grey-scale RGB formats by duplicating the value in each channel.
RGB formats are converted to single-channel formats by mixing the RGB channels with weights 0.27f for red, 0.67f for green, and 0.06f for blue.
If an alpha channel is added, the values are set to 1.0f, 255, or 65535 respectively.
The pixel type "Float32<4>" is treated in the same way as "Color", "Float32<3>" in the same way as "Rgb_fp", and "Sint32" in the same way as "Rgba".
The pixel type "Rgbe" is converted via "Rgb_fp". Similarly, "Rgbea" is converted via "Color".
"Float32<2>" is converted to single-channel formats by averaging the two channels. If "Float32<2>" is converted to three- or four-channel formats, the blue channel is set to 0.0f, or 0, respectively. Conversion of single-channel formats to "Float32<2>" duplicates the channel. Conversion of three- or four-channel formats to "Float32<2>" drops the third and fourth channel.

Parameters

canvas	The canvas to convert (or to copy).
pixel_type	The desired pixel type. See Types for a list of supported pixel types. If this pixel type is the same as the pixel type of `canvas`, then a copy of the canvas is returned.

Returns: A canvas with the requested pixel type, or NULL in case of errors (canvas is NULL, or pixel_type is not valid).

^◆ convert() [2/2]

virtual ITile * mi::neuraylib::IImage_api::convert	(	const ITile *	tile,
		const char *	pixel_type
	)		const

pure virtual

Converts a tile to a different pixel type.

Note: This method creates a copy if the passed-in tiles already has the desired pixel type. (It cannot return the passed-in tile since this would require a const cast.) If performance is critical, you should compare pixel types yourself and skip the method call if pixel type conversion is not needed.)

See convert(const ICanvas*,const char*)constfor details of the conversion process.

Parameters

tile	The tile to convert (or to copy).
pixel_type	The desired pixel type. See Types for a list of supported pixel types. If this pixel type is the same as the pixel type of `tile`, then a copy of the tile is returned.

Returns: A tile with the requested pixel type, or NULL in case of errors (tile is NULL, or pixel_type is not valid).

^◆ create_buffer_from_canvas()

virtual IBuffer * mi::neuraylib::IImage_api::create_buffer_from_canvas	(	const ICanvas *	canvas,
		const char *	image_format,
		const char *	pixel_type,
		const IMap *	export_options = `0`
	)		const

pure virtual

Encodes the pixel data of a canvas into a memory buffer.

Parameters

canvas	The canvas whose contents are to be used.
image_format	The desired image format of the image, e.g., `"jpg"`. Note that support for a given image format requires an image plugin capable of handling that format.
pixel_type	The desired pixel type. See Types for a list of supported pixel types. Not every image plugin supports every pixel type. If the requested pixel type is not supported, the argument is ignored and one of the supported formats is chosen instead.
export_options	See Image export options for supported options.

Returns: The created buffer, or NULL in case of failure.

^◆ create_canvas()

virtual ICanvas * mi::neuraylib::IImage_api::create_canvas	(	const char *	pixel_type,
		Uint32	width,
		Uint32	height,
		Uint32	layers = `1`,
		bool	is_cubemap = `false`,
		Float32	gamma = `0.0f`
	)		const

pure virtual

Creates a canvas with given pixel type, resolution, and layers.

This factory function allows to create instances of the abstract interface mi::neuraylib::ICanvas based on an internal default implementation. However, you are not obligated to use this factory function and the internal default implementation. It is absolutely fine to use your own (correct) implementation of the mi::neuraylib::ICanvas interface.

Parameters

pixel_type	The desired pixel type. See Types for a list of supported pixel types.
width	The desired width.
height	The desired height.
layers	The desired number of layers (depth). Must be 6 for cubemaps.
is_cubemap	Flag that indicates whether this canvas represents a cubemap.
gamma	The desired gamma value. The special value 0.0 represents the default gamma which is 1.0 for HDR pixel types and 2.2 for LDR pixel types.

Returns: The requested canvas, or NULL in case of invalid pixel type, width, height, layers, or cubemap flag, or memory allocation failures.

^◆ create_canvas_cuda()

virtual ICanvas_cuda * mi::neuraylib::IImage_api::create_canvas_cuda	(	Sint32	cuda_device_id,
		const char *	pixel_type,
		Uint32	width,
		Uint32	height,
		Uint32	layers = `1`,
		Float32	gamma = `0.0f`
	)		const

pure virtual

Unused.

This method exists only for technical reasons (ABI compatibility). Calling it results in unspecified behavior.

^◆ create_canvas_from_buffer()

virtual ICanvas * mi::neuraylib::IImage_api::create_canvas_from_buffer	(	const IBuffer *	buffer,
		const char *	image_format,
		const char *	selector = `0`
	)		const

pure virtual

Decodes the pixel data of a memory buffer into a canvas.

Parameters

buffer	The buffer that holds the encoded pixel data.
image_format	The image format of the buffer, 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.

Returns: The canvas with the decoded pixel data, or NULL in case of failure.

^◆ create_canvas_from_reader()

virtual ICanvas * mi::neuraylib::IImage_api::create_canvas_from_reader	(	IReader *	reader,
		const char *	image_format,
		const char *	selector = `0`
	)		const

pure virtual

Decodes the pixel data from a reader into a canvas.

Parameters

reader	The reader that provides the data for the image. The reader needs to support absolute access.
image_format	The image format of the buffer, 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.

Returns: The canvas with the decoded pixel data, or NULL in case of failure.

^◆ create_mipmap()

virtual IArray * mi::neuraylib::IImage_api::create_mipmap	(	const ICanvas *	canvas,
		Float32	gamma_override = `0.0f`
	)		const

pure virtual

Creates a mipmap from the given canvas.

Note: The base level (the canvas that is passed in) is not included in the returned canvas array.

Parameters

canvas	The canvas to create the mipmap from.
gamma_override	If this parameter is different from zero, it is used instead of the canvas gamma during mipmap creation.

Returns: An array of type mi::IPointer containing pointers to the miplevels of type mi::neuraylib::ICanvas. If no mipmap could be created, NULL is returned.

^◆ create_tile()

virtual ITile * mi::neuraylib::IImage_api::create_tile	(	const char *	pixel_type,
		Uint32	width,
		Uint32	height
	)		const

pure virtual

Creates a tile with given pixel type, width, and height.

This factory function allows to create instances of the abstract interface mi::neuraylib::ITile based on an internal default implementation. However, you are not obligated to use this factory function and the internal default implementation. It is absolutely fine to use your own (correct) implementation of the mi::neuraylib::ITile interface.

Parameters

pixel_type	The desired pixel type. See Types for a list of supported pixel types.
width	The desired width.
height	The desired height.

Returns: The requested tile, or NULL in case of invalid pixel type, width, or height, or memory allocation failures.

^◆ extract_channel() [1/2]

virtual ICanvas * mi::neuraylib::IImage_api::extract_channel	(	const ICanvas *	canvas,
		const char *	selector
	)		const

pure virtual

Extracts an RGBA channel from a canvas.

Parameters

canvas	The canvas to extract a channel from.
selector	The RGBA channel selector.

Returns: The extracted channel, or NULL in case of invalid pixel type/ channel selector combinations (see get_pixel_type_for_channel()).

^◆ extract_channel() [2/2]

virtual ITile * mi::neuraylib::IImage_api::extract_channel	(	const ITile *	tile,
		const char *	selector
	)		const

pure virtual

Extracts an RGBA channel from a tile.

Parameters

tile	The tile to extract a channel from.
selector	The RGBA channel selector.

Returns: The extracted channel, or NULL in case of invalid pixel type/ channel selector combinations (see get_pixel_type_for_channel()).

^◆ get_bytes_per_component()

virtual Uint32 mi::neuraylib::IImage_api::get_bytes_per_component ( const char * pixel_type ) const

pure virtual

Returns the number of bytes used per pixel component.

For example, for the pixel type "Color" the method returns 4 because its components are of type mi::Float32 which needs 4 bytes. Returns 0 in case of invalid pixel types.

See also: get_components_per_pixel()

^◆ get_components_per_pixel()

virtual Uint32 mi::neuraylib::IImage_api::get_components_per_pixel ( const char * pixel_type ) const

pure virtual

Returns the number of components per pixel type.

For example, for the pixel type "Color" the method returns 4 because it consists of four components R, G, B, and A. Returns 0 in case of invalid pixel types.

See also: get_bytes_per_component()

^◆ get_pixel_type_for_channel()

virtual const char * mi::neuraylib::IImage_api::get_pixel_type_for_channel	(	const char *	pixel_type,
		const char *	selector
	)		const

pure virtual

Returns the pixel type of an RGBA channel.

Invalid pixel type/selector combinations are:

pixel_type is not an RGB or RGBA pixel type
selector is not an RGBA channel selector
selector is "A", but pixel_type has no alpha channel

Parameters

pixel_type	The pixel type of the mipmap/canvas/tile.
selector	The RGBA channel selector.

Returns: Returns PT_UNDEF for invalid pixel type/selector combinations. Otherwise, returns PT_SINT8 or PT_FLOAT32, depending on pixel_type.

^◆ read_raw_pixels()

virtual Sint32 mi::neuraylib::IImage_api::read_raw_pixels	(	Uint32	width,
		Uint32	height,
		const ICanvas *	canvas,
		Uint32	canvas_x,
		Uint32	canvas_y,
		Uint32	canvas_layer,
		void *	buffer,
		bool	buffer_topdown,
		const char *	buffer_pixel_type,
		Uint32	buffer_padding = `0`
	)		const

pure virtual

Reads raw pixel data from a canvas.

Reads a rectangular area of pixels from a canvas (possibly spanning multiple tiles), converts the pixel type if needed, and writes the pixel data to buffer in memory. Management of the buffer memory is the responsibility of the caller.

Parameters

width	The width of the rectangular pixel area.
height	The height of the rectangular pixel area.
canvas	The canvas to read the pixel data from.
canvas_x	The x-coordinate of the lower-left corner of the rectangle.
canvas_y	The y-coordinate of the lower-left corner of the rectangle.
canvas_layer	The layer of the canvas that holds the rectangular area.
buffer	The buffer to write the pixel data to.
buffer_topdown	Indicates whether the buffer stores the rows in top-down order.
buffer_pixel_type	The pixel type of the buffer. See Types for a list of supported pixel types.
buffer_padding	The padding between subsequent rows of the buffer in bytes.

Returns

0: Success.
-1: Invalid parameters (NULL pointer).
-2: width or height is zero.
-3: Invalid pixel type of the buffer.
-4: The rectangular area [canvas_x, canvas_x + width) x [canvas_y, canvas_y + height) exceeds the size of the canvas, or canvas_layer is invalid.

^◆ supports_format_for_decoding()

virtual bool mi::neuraylib::IImage_api::supports_format_for_decoding	(	const char *	image_format,
		IReader *	reader = `0`
	)		const

pure virtual

Indicates whether a particular image format is supported for decoding.

Support for a given image format requires an image plugin capable of handling that format. This method allows to check whether such a plugin has been loaded for a particular format.

Decoding is used when the image is converted into a canvas from a memory buffer or a file . Note that even if this method returns true, create_canvas_from_buffer() can still fail for a particular image if that image uses an unsupported feature.

Parameters

image_format	The image format in question, e.g., `"jpg"`.
reader	An optional reader

Returns: true if the image format is supported, false otherwise

^◆ supports_format_for_encoding()

virtual bool mi::neuraylib::IImage_api::supports_format_for_encoding ( const char * image_format ) const

pure virtual

Indicates whether a particular image format is supported for encoding.

Support for a given image format requires an image plugin capable of handling that format. This method allows to check whether such a plugin has been loaded for a particular format.

Encoding is used when the image is converted from a canvas into a memory buffer or a file. . Note that even if this method returns true, create_buffer_from_canvas() can still fail if the given canvas uses an unsupported feature, e.g., multiple layers.

Parameters

image_format The image format in question, e.g., "jpg".

Returns: true if the image format is supported, false otherwise

^◆ write_raw_pixels()

virtual Sint32 mi::neuraylib::IImage_api::write_raw_pixels	(	Uint32	width,
		Uint32	height,
		ICanvas *	canvas,
		Uint32	canvas_x,
		Uint32	canvas_y,
		Uint32	canvas_layer,
		const void *	buffer,
		bool	buffer_topdown,
		const char *	buffer_pixel_type,
		Uint32	buffer_padding = `0`
	)		const

pure virtual

Writes raw pixel data to a canvas.

Reads a rectangular area of pixels from a buffer in memory, converts the pixel type if needed, and writes the pixel data to a canvas (possibly spanning multiple tiles). Management of the buffer memory is the responsibility of the caller.

Parameters

width	The width of the rectangular pixel area.
height	The height of the rectangular pixel area.
canvas	The canvas to write the pixel data to.
canvas_x	The x-coordinate of the lower-left corner of the rectangle.
canvas_y	The y-coordinate of the lower-left corner of the rectangle.
canvas_layer	The layer of the canvas that holds the rectangular area.
buffer	The buffer to read the pixel data from.
buffer_topdown	Indicates whether the buffer stores the rows in top-down order.
buffer_pixel_type	The pixel type of the buffer. See Types for a list of supported pixel types.
buffer_padding	The padding between subsequent rows of the buffer in bytes.

Returns

0: Success.
-1: Invalid parameters (NULL pointer).
-2: width or height is zero.
-3: Invalid pixel type of the buffer.
-4: The rectangular area [canvas_x, canvas_x + width) x [canvas_y, canvas_y + height) exceeds the size of the canvas, or canvas_layer is invalid.

Public Member Functions

Additional Inherited Members

Detailed Description

Image export options

Member Function Documentation

◆ adjust_gamma() [1/2]

◆ adjust_gamma() [2/2]

◆ clone_canvas()

◆ clone_tile()

◆ convert() [1/2]

◆ convert() [2/2]

◆ create_buffer_from_canvas()

◆ create_canvas()

◆ create_canvas_cuda()

◆ create_canvas_from_buffer()

◆ create_canvas_from_reader()

◆ create_mipmap()

◆ create_tile()

◆ extract_channel() [1/2]

◆ extract_channel() [2/2]

◆ get_bytes_per_component()

◆ get_components_per_pixel()

◆ get_pixel_type_for_channel()

◆ read_raw_pixels()

◆ supports_format_for_decoding()

◆ supports_format_for_encoding()

◆ write_raw_pixels()

^◆ adjust_gamma() [1/2]

^◆ adjust_gamma() [2/2]

^◆ clone_canvas()

^◆ clone_tile()

^◆ convert() [1/2]

^◆ convert() [2/2]

^◆ create_buffer_from_canvas()

^◆ create_canvas()

^◆ create_canvas_cuda()

^◆ create_canvas_from_buffer()

^◆ create_canvas_from_reader()

^◆ create_mipmap()

^◆ create_tile()

^◆ extract_channel() [1/2]

^◆ extract_channel() [2/2]

^◆ get_bytes_per_component()

^◆ get_components_per_pixel()

^◆ get_pixel_type_for_channel()

^◆ read_raw_pixels()

^◆ supports_format_for_decoding()

^◆ supports_format_for_encoding()

^◆ write_raw_pixels()