Top level C++ mental ray interface extensions. More...

#include <mi_shader_if.h>

Public Types
enum	Filtertype
	see description above. More...
Public Member Functions
virtual Options *	getOptions (miTag string_options)
	Access to string options.
virtual miTag	createFramebuffer ()
	Framebuffer factory function.
virtual miTag	copyFramebuffer (miTag old_buffer_tag)
	Creates a copy of the framebuffer collection.
virtual LightList *	createLightList (miState state, miTag slist=0, int n=0)
	Internal function to create a light list.
virtual void	release ()
	Release (delete) the instance of the interface.
virtual LightList *	createLightList (miState state, const miVector &axis, miScalar spread_cos, miTag slist=0, int n=0)
	Used internally by LightIterator to create a light list.
virtual Edit_map_dbhandle *	createMap (const Map_declaration_base *map_declaration=0)
	Creation of map.
virtual Access_map_dbhandle *	accessMap (const miTag map_tag)
	Read-only access to a map in the DB.
virtual Edit_map_dbhandle *	editMap (const miTag map_tag)
	Read-write access to a map in the DB.
virtual Access_map_dbhandle *	accessMap (const char filename, Map_status status)
	Read-only access to a map to be read from file.
virtual Edit_map_dbhandle *	editMap (const char filename, Map_status status)
	Read-write access to a map to be read from file.
virtual Map_declaration_base *	createMapDeclaration (const miUint dimension)
	Creation of a map declaration.
virtual Map_declaration_base *	copyMapDeclaration (const Map_declaration_base other, Map_status status)
	Copy of a map declaration.
virtual Map_declaration_base *	copyMapDeclaration (const Map_element_base map_element, Map_status status)
	Copy of the declaration of a map element.
virtual Map_declaration_base *	copyMapDeclaration (const Map_base map, Map_status status)
	Copy of the declaration of a map.
virtual Map_element_base *	createMapElement (const Map_declaration_base *declaration=0)
	Creation of a map element.
virtual Map_element_base *	copyMapElement (const Map_element_base *other)
	Copy of a map element.
virtual Map_iterator_base *	createMapIterator (const Map_base map, Map_status status)
	Creation of a map iterator.
virtual Map_iterator_base *	copyMapIterator (const Map_iterator_base other, Map_status status)
	Copy of a map iterator.
virtual Map_lookup_base *	createMapLookup (const Map_base map, Map_status status)
	Creation of a map lookup.
virtual Map_lookup_base *	copyMapLookup (const Map_lookup_base other, Map_status status)
	Copy of a map lookup.
virtual Subdivision34 *	accessSubdivision34 (miTag tag)
	Provide access to (allocate) the Subdivision34 class.
virtual void	releaseSubdivision34 (const Subdivision34 *subdiv34)
	Release (delete) the Subdivision34 class.
virtual bool	lookup_filter_color_texture (miColor const color, miState const state, const miTag tex, Mip_remap &remap, miVector *coord)
	Elliptical texture filtering.
virtual bool	open_output_image (miImg_image &image, miState state, const size_t idx)
	Open an output image from an output shader.
virtual bool	close_output_image (miState *state, const size_t idx)
	Close an output image from an output shader.
virtual const void *	renderpass_get_cur_sample (miState *state, const size_t idx)
	Pass rendering related methods.
virtual const void *	renderpass_get_pass_sample (miState *state, const size_t idx)
	get the current pass sample value
virtual bool	renderpass_set_sample (miState state, const size_t idx, const void sample)
	set the new value for the current sample position
virtual size_t	renderpass_get_pass_number (miState *state)
	get the current pass number
virtual MISLightList *	createMISLightList (miState state, miTag slist=0, int n=0)
	Internal function to create a light list for multiple importance sampling (MIS).
virtual MISLightList *	createMISLightList (miState state, Access_bsdf &bsdf, miTag slist=0, int n=0)
	Internal function to create a light list for multiple importance sampling (MIS).
virtual bool	lookup_filter_color_texture (miColor const color, miState const state, const miTag tex, Mip_remap &remap, miVector *coord, Filtertype ft, miScalar blur)
	see description above.
Static Public Member Functions
static Interface *	get (int version=mi_ray_interface_version)
	Acquire an instance of the interface.

Detailed Description

Top level C++ mental ray interface extensions.

This class is the top level access to the C++ shader interface extensions. All other C++ extensions like mi::shader::Options and mi::shader::LightIterator are accessible through this class.

An instance of the Interface must be acquired by calling mi_get_shader_interface() or the static method Interface::get(). When the interface is no more needed, it must be released by calling Interface::release():

 mi::shader::Interface *iface = mi::shader::Interface::get();
 // do something with it...
 iface->release();

The C++ interface extensions are implemented as virtual functions in this interface struct in order to avoid linking and symbol lookup problems. The interface is defined in the header file mi_shader_if.h.

Member Enumeration Documentation

enum mi::shader_v3::Interface::Filtertype

see description above.

Parameters:

color	result color
state	current rendering state
tex	tag of database element miSCENE_IMAGE (the texture)
remap	reference to derived class Mip_remap providing implementation of texture coordinate transformation and remapping
coord	2d texture coordinates (only x and y used).
ft	specifies interpolation type for the lookup

Member Function Documentation

virtual Access_map_dbhandle* mi::shader_v3::Interface::accessMap ( const miTag map_tag ) [virtual]

Read-only access to a map in the DB.

This function is wrapped by the Access_map class and should not be used directly

Parameters:

map_tag database tag of the map

Returns:: pointer to the map

virtual Access_map_dbhandle* mi::shader_v3::Interface::accessMap	(	const char *	filename,
		Map_status *	status
	)		`[virtual]`

Read-only access to a map to be read from file.

This function is wrapped by the Access_map class and should not be used directly

Parameters:

filename	the file name of the map to read
status	a status code

Returns:: pointer to the map

virtual Subdivision34* mi::shader_v3::Interface::accessSubdivision34 ( miTag tag ) [virtual]

Provide access to (allocate) the Subdivision34 class.

Parameters:

tag	is the MI::SDS::Subdiv34 class tag

virtual bool mi::shader_v3::Interface::close_output_image	(	miState *	state,
		const size_t	idx
	)		`[virtual]`

Close an output image from an output shader.

Parameters:

state	current rendering state
idx	the real index into the buffer array, retrieved from fb->get_index(buf_name, idx)

Returns:: returns true on success, false if the index is out of range, or this was not called from an output shader

Referenced by mi::shader_v3::Access_out_img::~Access_out_img(), and mi::shader_v3::Edit_out_img::~Edit_out_img().

virtual miTag mi::shader_v3::Interface::copyFramebuffer ( miTag old_buffer_tag ) [virtual]

Creates a copy of the framebuffer collection.

Parameters:

old_buffer_tag A database tag for the framebuffer to copy

Returns:: a database tag for a copy of framebuffer collection.

virtual Map_declaration_base* mi::shader_v3::Interface::copyMapDeclaration	(	const Map_declaration_base *	other,
		Map_status *	status
	)		`[virtual]`

Copy of a map declaration.

This function is wrapped by the Map_declaration class and should not be used directly

Parameters:

other	is the handle of the declaration to copy
status	is a status code

Returns:: pointer to the newly copied map declaration

virtual Map_declaration_base* mi::shader_v3::Interface::copyMapDeclaration	(	const Map_element_base *	map_element,
		Map_status *	status
	)		`[virtual]`

Copy of the declaration of a map element.

This function is wrapped by the Map_declaration class and should not be used directly

Parameters:

map_element	is the map element to get a copy of the decl from
status	is a status code

Returns:: pointer to the newly copied map declaration

virtual Map_declaration_base* mi::shader_v3::Interface::copyMapDeclaration	(	const Map_base *	map,
		Map_status *	status
	)		`[virtual]`

Copy of the declaration of a map.

This function is wrapped by the Map_declaration class and should not be used directly

Parameters:

map	is the map to get a copy of the declaration from
status	is a status code

Returns:: pointer to the newly copied map declaration

virtual Map_element_base* mi::shader_v3::Interface::copyMapElement ( const Map_element_base * other ) [virtual]

Copy of a map element.

This function is wrapped by the Map_element class and should not be used directly

Parameters:

other is the element to copy

Returns:: pointer to the newly copied map element

virtual Map_iterator_base* mi::shader_v3::Interface::copyMapIterator	(	const Map_iterator_base *	other,
		Map_status *	status
	)		`[virtual]`

Copy of a map iterator.

This function is wrapped by the map_iterator_access/edit classes and should not be used directly

Parameters:

other	is the iterator to copy
status	is a status code

Returns:: pointer to the newly copied map iterator

virtual Map_lookup_base* mi::shader_v3::Interface::copyMapLookup	(	const Map_lookup_base *	other,
		Map_status *	status
	)		`[virtual]`

Copy of a map lookup.

This function is wrapped by the Map_lookup class and should not be used directly

Parameters:

other	is the lookup to copy
status	is a status code

Returns:: pointer to the newly created map lookup

virtual miTag mi::shader_v3::Interface::createFramebuffer ( ) [virtual]

Framebuffer factory function.

Returns:: a database tag for an empty framebuffer collection.

virtual LightList* mi::shader_v3::Interface::createLightList	(	miState *	state,
		miTag *	slist = `0`,
		int	n = `0`
	)		`[virtual]`

Internal function to create a light list.

Deprecated:

This may be used to generate light iterators. This method is needed by the LightIterator::LightIterator() constructor. Usually there is no need to invoke this method directly.

Parameters:

state	provided the method with the current rendering state. From the state the current instance light list may be deduced.
slist	is an optional list of light tags. If provided, this list will be used instead of the default instance light list.
n	gives the number of light tags in the optional light list.

Returns:: the method returns a pointer to a LightList.

virtual LightList* mi::shader_v3::Interface::createLightList	(	miState *	state,
		const miVector &	axis,
		miScalar	spread_cos,
		miTag *	slist = `0`,
		int	n = `0`
	)		`[virtual]`

Used internally by LightIterator to create a light list.

This may be used to generate light iterators. This method is needed by the LightIterator::LightIterator() constructor. Usually there is no need to invoke this method directly.

Parameters:

state	provided the method with the current rendering state. From the state the current instance light list may be deduced.
axis	specifies the axis for the light cone. The value should be normalized.
spread_cos	specifies the cosine of the angle to the light cone axis.
slist	is an optional list of light tags. If provided, this list will be used instead of the default instance light list.
n	gives the number of light tags in the optional light list.

Returns:: the method returns a pointer to a LightList.

virtual Edit_map_dbhandle* mi::shader_v3::Interface::createMap ( const Map_declaration_base * map_declaration = 0 ) [virtual]

Creation of map.

This function is wrapped by the Edit_map class and should not be used directly.

Parameters:

map_declaration is the declaration (possibly NULL) of the new map

Returns:: pointer to the newly created map

virtual Map_declaration_base* mi::shader_v3::Interface::createMapDeclaration ( const miUint dimension ) [virtual]

Creation of a map declaration.

This function is wrapped by the Map_declaration class and should not be used directly

Parameters:

dimension is the dimension of the position

Returns:: pointer to the newly created map declaration

virtual Map_element_base* mi::shader_v3::Interface::createMapElement ( const Map_declaration_base * declaration = 0 ) [virtual]

Creation of a map element.

This function is wrapped by the Map_element class and should not be used directly

Parameters:

declaration is the (possible) declaration to use

Returns:: pointer to the newly created map element

virtual Map_iterator_base* mi::shader_v3::Interface::createMapIterator	(	const Map_base *	map,
		Map_status *	status
	)		`[virtual]`

Creation of a map iterator.

This function is wrapped by the Access_map_iterator/edit classes and should not be used directly

Parameters:

map	is the map to attach the iterator to
status	is a status code

Returns:: pointer to the newly created map iterator

virtual Map_lookup_base* mi::shader_v3::Interface::createMapLookup	(	const Map_base *	map,
		Map_status *	status
	)		`[virtual]`

Creation of a map lookup.

This function is wrapped by the Map_lookup class and should not be used directly

Parameters:

map	is the map to attach the lookup to
status	is a status code

Returns:: pointer to the newly created map lookup

virtual MISLightList* mi::shader_v3::Interface::createMISLightList	(	miState *	state,
		miTag *	slist = `0`,
		int	n = `0`
	)		`[virtual]`

Internal function to create a light list for multiple importance sampling (MIS).

This may be used to generate light iterators for MIS. This method is needed by the MISLightIterator::MISLightIterator() constructor. Usually there is no need to invoke this method directly.

Parameters:

state	provided the method with the current rendering state. From the state the current instance light list may be deduced.
slist	is an optional list of light tags. If provided, this list will be used instead of the default instance light list.
n	gives the number of light tags in the optional light list.

Returns:: the method returns a pointer to a MISLightList.

virtual MISLightList* mi::shader_v3::Interface::createMISLightList	(	miState *	state,
		Access_bsdf &	bsdf,
		miTag *	slist = `0`,
		int	n = `0`
	)		`[virtual]`

Internal function to create a light list for multiple importance sampling (MIS).

This may be used to generate light iterators for MIS. This method is needed by the MISLightIterator::MISLightIterator() constructor. Usually there is no need to invoke this method directly.

Parameters:

state	provided the method with the current rendering state. From the state the current instance light list may be deduced.
bsdf	is the BSDF to use.
slist	is an optional list of light tags. If provided, this list will be used instead of the default instance light list.
n	gives the number of light tags in the optional light list.

Returns:: the method returns a pointer to a MISLightList.

virtual Edit_map_dbhandle* mi::shader_v3::Interface::editMap ( const miTag map_tag ) [virtual]

Read-write access to a map in the DB.

This function is wrapped by the Edit_map class and should not be used directly

Parameters:

map_tag database tag of the map

Returns:: pointer to the map

virtual Edit_map_dbhandle* mi::shader_v3::Interface::editMap	(	const char *	filename,
		Map_status *	status
	)		`[virtual]`

Read-write access to a map to be read from file.

This function is wrapped by the Edit_map class and should not be used directly

Parameters:

filename	the file name of the map to read
status	a status code

Returns:: pointer to the map

static Interface* mi::shader_v3::Interface::get ( int version = mi_ray_interface_version ) [inline, static]

Acquire an instance of the interface.

This static method is equivalent to the function mi_get_shader_interface(), see there fore more information. This static function can be used as follows:

 mi::shader::Interface *iface = mi::shader::Interface::get();

Parameters:

version is the version number of the requested interface class, usually no version argument needs to be passed.

Returns:: The returned pointer points to an object in mental ray which contains the interface functions as virtual methods (hence it is possible to call the interface routines from a dynamically loaded library without resolving the routine in a symbol table). The caller may not attempt to modify or delete the returned object but should call the mi::shader::Interface::release() method when done.

References mi_get_shader_interface().

virtual Options* mi::shader_v3::Interface::getOptions ( miTag string_options ) [virtual]

Access to string options.

This may later be extended to also access all other options from the miOptions structure. This function can be used as follows:

 Options *stringOptions = interface->getOptions(options->string_options);

Parameters:

string_options is the tag of the string options, taken from the string_options field of the miOptions structure to be read or modified. It must be valid throughout the use of the Options instance.

Returns:: A pointer to an interface class. The Options::release() method should be called when done.

virtual bool mi::shader_v3::Interface::lookup_filter_color_texture	(	miColor *const	color,
		miState *const	state,
		const miTag	tex,
		Mip_remap &	remap,
		miVector *	coord
	)		`[virtual]`

Elliptical texture filtering.

Parameters:

color	result color
state	current rendering state
tex	tag of database element miSCENE_IMAGE (the texture)
remap	reference to derived class Mip_remap providing implementation of texture coordinate transformation and remapping
coord	2d texture coordinates (only x and y used).

Returns:: returns true on success, false if for example the input texture does not have the type miSCENE_IMAGE.

virtual bool mi::shader_v3::Interface::lookup_filter_color_texture	(	miColor *const	color,
		miState *const	state,
		const miTag	tex,
		Mip_remap &	remap,
		miVector *	coord,
		Filtertype	ft,
		miScalar	blur
	)		`[virtual]`

see description above.

Parameters:

color	result color
state	current rendering state
tex	tag of database element miSCENE_IMAGE (the texture)
remap	reference to derived class Mip_remap providing implementation of texture coordinate transformation and remapping
coord	2d texture coordinates (only x and y used).
ft	specifies interpolation type for the lookup
blur	specifies blur factor for lookup, (1 = default, >1: blur)

virtual bool mi::shader_v3::Interface::open_output_image	(	miImg_image *&	image,
		miState *	state,
		const size_t	idx
	)		`[virtual]`

Open an output image from an output shader.

Parameters:

image	the returned image pointer
state	current rendering state
idx	the real index into the buffer array, retrieved from fb->get_index(buf_name, idx)

Returns:: returns true on success, false if the index is out of range, or this was not called from an output shader

Referenced by mi::shader_v3::Access_out_img::Access_out_img(), and mi::shader_v3::Edit_out_img::Edit_out_img().

virtual void mi::shader_v3::Interface::release ( ) [virtual]

Release (delete) the instance of the interface.

An interface acquired with mi_get_shader_interface() or mi::shader::Interface::get() must be released with this call when done. The call may delete the object, and the interface may no longer be used afterwards.

Referenced by mi::shader_v3::Access_fb::~Access_fb(), mi::shader_v3::Access_interface::~Access_interface(), mi::shader_v3::Access_out_img::~Access_out_img(), mi::shader_v3::Access_subdivision34::~Access_subdivision34(), mi::shader_v3::Edit_fb::~Edit_fb(), and mi::shader_v3::Edit_out_img::~Edit_out_img().

virtual void mi::shader_v3::Interface::releaseSubdivision34 ( const Subdivision34 * subdiv34 ) [virtual]

Release (delete) the Subdivision34 class.

Parameters:

subdiv34 is the pointer returned by accessSubdivision34

Referenced by mi::shader_v3::Access_subdivision34::~Access_subdivision34().

virtual const void* mi::shader_v3::Interface::renderpass_get_cur_sample	(	miState *	state,
		const size_t	idx
	)		`[virtual]`

Pass rendering related methods.

get the current sample value

Parameters:

state	current rendering state
idx	framebuffer index to return value from

Returns:: a pointer to the current sample value of the current sample possition of the framebuffer at index idx

Referenced by mi::shader_v3::Merge_pass::get_cur_sample().

virtual size_t mi::shader_v3::Interface::renderpass_get_pass_number ( miState * state ) [virtual]

get the current pass number

Parameters:

state current rendering state

Returns:: the index number of the current rendering pass

Referenced by mi::shader_v3::Merge_pass::get_cur_pass_number().

virtual const void* mi::shader_v3::Interface::renderpass_get_pass_sample	(	miState *	state,
		const size_t	idx
	)		`[virtual]`

get the current pass sample value

Parameters:

state	current rendering state
idx	framebuffer index to return value from

Returns:: a pointer to the sample value of the current pass of the current sample possition of the framebuffer at index idx

Referenced by mi::shader_v3::Merge_pass::get_pass_sample().

virtual bool mi::shader_v3::Interface::renderpass_set_sample	(	miState *	state,
		const size_t	idx,
		const void *	sample
	)		`[virtual]`

set the new value for the current sample position

Parameters:

state	current rendering state
idx	framebuffer index to set the value in
sample	pointer to the sample value to set

Returns:: true if the sample could be set false if there was an error

Referenced by mi::shader_v3::Merge_pass::set_sample().

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

Member Function Documentation