Material Definition Language API nvidia_logo_transpbg.gif Up
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
mi::neuraylib::IImage_api Class Referenceabstract

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

Inheritance diagram for mi::neuraylib::IImage_api:
mi::base::Interface_declare< 0x4c25a4f0, 0x2bac, 0x4ce6, 0xb0, 0xab, 0x4d, 0x94, 0xbf, 0xfd, 0x97, 0xa5 > mi::base::IInterface

Public Member Functions

Factory methods for canvases and tiles
virtual ICanvascreate_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 =0
 Creates a canvas with given pixel type, width, height, and layers. More...
 
virtual ITilecreate_tile (const char *pixel_type, Uint32 width, Uint32 height) const =0
 Creates a tile with given pixel type, width, and height. 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 char *quality) const =0
 Encodes the pixel data of a canvas into a memory buffer. More...
 
virtual ICanvascreate_canvas_from_buffer (const IBuffer *buffer, const char *image_format) const =0
 Decodes the pixel data of a memory buffer 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 ICanvasconvert (const ICanvas *canvas, const char *pixel_type) const =0
 Converts a canvas to a different pixel type. 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...
 
virtual IArraycreate_mipmaps (const ICanvas *canvas, Float32 gamma_override=0.0f) const =0
 Creates mipmaps from the given canvas. More...
 

Additional Inherited Members

- Public Types inherited from mi::base::Interface_declare< 0x4c25a4f0, 0x2bac, 0x4ce6, 0xb0, 0xab, 0x4d, 0x94, 0xbf, 0xfd, 0x97, 0xa5 >
typedef Interface_declare< id1,
id2, id3, id4, id5, id6, id7,
id8, id9, id10, id11,
IInterface
Self
 Own type. More...
 
typedef Uuid_t< id1, id2, id3,
id4, id5, id6, id7, id8, id9,
id10, id11 > 
IID
 Declares the interface ID (IID) of this interface. More...
 
- Static Public Member Functions inherited from mi::base::Interface_declare< 0x4c25a4f0, 0x2bac, 0x4ce6, 0xb0, 0xab, 0x4d, 0x94, 0xbf, 0xfd, 0x97, 0xa5 >
static bool compare_iid (const Uuid &iid)
 Compares the interface ID iid against the interface ID of this interface and of its ancestors. 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.

Member Function Documentation

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
canvasThe canvas whose pixel data is to be adjusted.
new_gammaThe 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.

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
canvasThe canvas to convert (or to copy).
pixel_typeThe 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).
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
canvasThe canvas whose contents are to be used.
image_formatThe 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_typeThe 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.
qualityThe 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_typeThe desired pixel type. See Types for a list of supported pixel types.
widthThe desired width.
heightThe desired height.
tile_widthThe desired tile width. The special value 0 represents the canvas width.
tile_heightThe desired tile height. The special value 0 represents the canvas height.
layersThe desired number of layers (depth). Must be 6 for cubemaps.
is_cubemapFlag that indicates whether this canvas represents a cubemap.
gammaThe 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
bufferThe buffer that holds the encoded pixel data.
image_formatThe 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 IArray* mi::neuraylib::IImage_api::create_mipmaps ( const ICanvas canvas,
Float32  gamma_override = 0.0f 
) const
pure virtual

Creates mipmaps from the given canvas.

Note
The base level (the canvas that is passed in) is not included in the returned canvas array.
Parameters
canvasThe canvas to create the mipmaps from.
gamma_overrideIf 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 mipmaps of type mi::neuraylib::ICanvas. If no mipmaps could be created, NULL is returned.
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_typeThe desired pixel type. See Types for a list of supported pixel types.
widthThe desired width.
heightThe 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
widthThe width of the rectangular pixel area.
heightThe height of the rectangular pixel area.
canvasThe canvas to read the pixel data from.
canvas_xThe x-coordinate of the lower-left corner of the rectangle.
canvas_yThe y-coordinate of the lower-left corner of the rectangle.
canvas_layerThe layer of the canvas that holds the rectangular area.
bufferThe buffer to write the pixel data to.
buffer_topdownIndicates whether the buffer stores the rows in top-down order.
buffer_pixel_typeThe pixel type of the buffer. See Types for a list of supported pixel types.
buffer_paddingThe 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() can still fail for a particular image if that image uses an unsupported feature.

Parameters
image_formatThe image format in question, e.g., "jpg".
readerAn optional reader
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() can still fail if the given canvas uses an unsupported feature, e.g., multiple layers.

Parameters
image_formatThe 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
widthThe width of the rectangular pixel area.
heightThe height of the rectangular pixel area.
canvasThe canvas to write the pixel data to.
canvas_xThe x-coordinate of the lower-left corner of the rectangle.
canvas_yThe y-coordinate of the lower-left corner of the rectangle.
canvas_layerThe layer of the canvas that holds the rectangular area.
bufferThe buffer to read the pixel data from.
buffer_topdownIndicates whether the buffer stores the rows in top-down order.
buffer_pixel_typeThe pixel type of the buffer. See Types for a list of supported pixel types.
buffer_paddingThe 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.