mi::neuraylib::IImage_api Class Reference

Member Functions

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.

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.

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

pixel_type

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

Returns

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

virtual IBuffer* mi::​neuraylib::​IImage_api::create_buffer_from_canvas( const ICanvas* canvas, const char* image_format, const char* pixel_type, const char* quality) 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.

quality

The compression quality is an integer in the range from 0 to 100, where 0 is the lowest quality, and 100 is the highest quality.

Returns

The created buffer, or NULL in case of failure.

virtual ICanvas* mi::​neuraylib::​IImage_api::create_canvas( const char* pixel_type, Uint32 width, Uint32 height, Uint32 tile_width = 0, Uint32 tile_height = 0, Uint32 layers = 1, bool is_cubemap = false, Float32 gamma = 0.0f) const [pure virtual]

Creates a canvas with given pixel type, width, height, 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.

tile_width

The desired tile width. The special value 0 represents the canvas width.

tile_height

The desired tile height. The special value 0 represents the canvas 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.

virtual ICanvas* mi::​neuraylib::​IImage_api::create_canvas_from_buffer( const IBuffer* buffer, const char* image_format) 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.

Returns

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

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.

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

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

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.

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() or mi::neuraylib::IImport_api::import_canvas() 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 used by mi::neuraylib::IImage_plugin::test().

Returns

true if the image format is supported, false otherwise

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() or mi::neuraylib::IExport_api::export_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

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.