neuray API Programmer's Manual

mi::neuraylib::IImage_plugin Class Reference

[Extensions and Plugins]

Description

Abstract interface for image plugins. The image plugin API allows to add support for third-party image formats. Such an image format will then be supported in import, export, and streaming operations. The image plugin API comprises the interfaces mi::neuraylib::IImage_plugin and mi::neuraylib::IImage_file. It also uses the interfaces mi::neuraylib::IReader, mi::neuraylib::IWriter, and mi::neuraylib::ITile.

Image plugins need to return MI_NEURAY_IMAGE_PLUGIN_TYPE in mi::base::Plugin::get_type().

A plugin to support a certain image format is selected as follows. For import operations the file header is presented to each plugin for testing. Each plugin indicates whether it recognizes the header format and whether it can handle the image format. For export operations a matching plugin is selected according to the file name extension (see mi::neuraylib::IImage_plugin::get_file_extension()).

The abstract base class for plugins.The abstract base class for plugins.

Public Member Functions

virtual bool  exit( IPlugin_api* plugin_api) =0
De-initializes the plugin. More...
virtual const char* get_file_extension( Uint32 index) const =0
Returns the index -th supported file extension. More...
virtual const char* get_name() const =0
Returns the name of the plugin. More...
virtual Impexp_priority get_priority() const =0
Returns the priority of the image plugin. More...
virtual const char* get_supported_type( Uint32 index) const =0
Returns the index -th supported pixel type for exporting. More...
virtual bool  init( IPlugin_api* plugin_api) =0
Initializes the plugin. More...
virtual IImage_file* open_for_reading( IReader* reader) const =0
Creates an object that reads an image to file. More...
virtual IImage_file* open_for_writing( IWriter* writer, const char* pixel_type, Uint32 resolution_x, Uint32 resolution_y, Uint32 nr_of_layers, Uint32 miplevels, bool is_cubemap, Float32 gamma, Uint32 quality) const =0
Creates an object that writes an image to a file. More...
virtual bool  test( const Uint8* buffer, Uint32 file_size) const =0
Indicates whether the image plugin can handle a given file header. More...

Member Functions

virtual bool mi::​neuraylib::​IImage_plugin::exit( IPlugin_api* plugin_api) [pure virtual]

De-initializes the plugin.

Parameters

plugin_api
Provides access to API components available for plugins.

Returns

true in case of success, and false otherwise.

virtual const char* mi::​neuraylib::​IImage_plugin::get_file_extension( Uint32 index) const [pure virtual]

Returns the index -th supported file extension.

Parameters

index
The index of the file extensions to be returned.

Returns

The index -th supported file extension, NULL if index is out of bounds.

virtual const char* mi::​neuraylib::​IImage_plugin::get_name() const [pure virtual]

Returns the name of the plugin. For image plugins, typically the name of the image format is used, for example, "jpeg".

Note:

This method from mi::base::Plugin is repeated here only for documentation purposes.

virtual Impexp_priority mi::​neuraylib::​IImage_plugin::get_priority() const [pure virtual]

Returns the priority of the image plugin. The priority expresses the confidence of the plugin that its test() method can identify the file and that the file format is fully supported.

virtual const char* mi::​neuraylib::​IImage_plugin::get_supported_type( Uint32 index) const [pure virtual]

Returns the index -th supported pixel type for exporting. The pixel types should be ordered, from index 0 for the most common to the least useful type. See Types for a list of supported pixel types.

Parameters

index
The index of the pixel type to be returned.

Returns

The index -th supported pixel type, NULL if index is out of bounds.

virtual bool mi::​neuraylib::​IImage_plugin::init( IPlugin_api* plugin_api) [pure virtual]

Initializes the plugin.

Parameters

plugin_api
Provides access to API components available for plugins.

Returns

true in case of success, and false otherwise.

virtual IImage_file* mi::​neuraylib::​IImage_plugin::open_for_reading( IReader* reader) const [pure virtual]

Creates an object that reads an image to file. This method is called to start an image import operation.

Parameters

reader
A reader representing the file to read from.

Returns

The object that reads the image from file.

virtual IImage_file* mi::​neuraylib::​IImage_plugin::open_for_writing( IWriter* writer, const char* pixel_type, Uint32 resolution_x, Uint32 resolution_y, Uint32 nr_of_layers, Uint32 miplevels, bool is_cubemap, Float32 gamma, Uint32 quality) const [pure virtual]

Creates an object that writes an image to a file. This method is called to start an image export operation.

Parameters

writer
A writer representing the file to write to.
pixel_type
The pixel type of the image tiles. This is one of the pixel types returned by get_supported_type().
resolution_x
The resolution of the image in x direction.
resolution_y
The resolution of the image in y direction.
nr_of_layers
The number of layers in the image.
miplevels
The number of mipmap levels in the image.
is_cubemap
true if the image is supposed to be cubemap, false otherwise.
gamma
The gamma value of the image.
quality
The desired compression 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. Support for compression quality is optional.

Returns

The object that writes the image to a file.

virtual bool mi::​neuraylib::​IImage_plugin::test( const Uint8* buffer, Uint32 file_size) const [pure virtual]

Indicates whether the image plugin can handle a given file header.

Parameters

buffer
A buffer containing the first 512 bytes of the file. For very short files the buffer might be even smaller (as indicated by file_size).
file_size
The total size of the file.

Returns

true if the plugin can handle the file, false otherwise.