mi::shader_v3::Options Class Reference

Access to string options. More...

#include <mi_shader_if.h>


Public Member Functions

virtual void	set (const char *name, bool value)=0
	Set a boolean option.
virtual void	set (const char name, const char value)=0
	Set a string option.
virtual void	set (const char *name, int value)=0
	Set an integer option.
virtual void	set (const char *name, float value)=0
	Set a floating point option.
virtual void	set (const char *name, float value1, float value2)=0
	Set a float double option.
virtual void	set (const char *name, float value1, float value2, float value3)=0
	Set a float triple option.
virtual void	set (const char *name, float value1, float value2, float value3, float value4)=0
	Set a float quadruple option.
virtual bool	get (const char name, bool value) const =0
	Get a boolean option.
virtual bool	get (const char name, const char *value) const =0
	Get a string option.
virtual bool	get (const char name, int value) const =0
	Get an integer option.
virtual bool	get (const char name, float value) const =0
	Get a floating point option.
virtual bool	get (const char name, float value1, float *value2) const =0
	Get a floating point double option.
virtual bool	get (const char name, float value1, float value2, float value3) const =0
	Get a floating point triple option.
virtual bool	get (const char name, float value1, float value2, float value3, float *value4) const =0
	Get a floating point quadruple option.
virtual bool	remove (const char *name)=0
	Delete a specific option.
virtual void	release ()=0
	Release (delete) the interface.

Detailed Description

Access to string options.

Up to version 3.4, options are hardcoded in the struct miOptions in shader.h. New options are implemented as arbitrary name - value pairs, where the name of the option is an arbitrary string, and the value can be a boolean, string, integration, float, 2, 3 or 4 floats.

A pointer to string options must be obtained with Interface::getOptions(). When the pointer is no longer needed then the Options::release() method must be called, like for example:

 mi::shader::Interface *iface = mi_get_shader_interface();
 mi::shader::Options *opt = iface->getOptions(string_options_tag);
 iface->release();
 opt->set("favorite color", "blue");
 opt->release();

Setting options

Set functions set the value of an option of a given name, overwriting any previous value. Previous values may be overwritten by values of a different type.

Note:: Options should only be set before rendering starts. It is undefined which value will be used if an option is set during rendering.

Getting options

All get functions return true and set the value if a matching option is found, or returns false leave the value unmodified if no matching option is found.

Strings and memory management

Strings passed as arguments are completely controlled by the caller; mental ray uses the strings briefly, or makes copies of the passed strings.

Strings returned by these functions are read-only and controlled by mental ray. The caller may use these only for a short time and may not delete them. Make a copy if the value is needed later.

Member Function Documentation

virtual void mi::shader_v3::Options::set	(	const char *	name,
		bool	value
	)			`[pure virtual]`

Set a boolean option.

Parameters:

	name	is the name of the option to set.
	value	is the new value of the option.

virtual void mi::shader_v3::Options::set	(	const char *	name,
		const char *	value
	)			`[pure virtual]`

Set a string option.

Parameters:

	name	is the name of the option to set.
	value	mental ray will make a copy of the passed string value, the passed argument is under control of the caller.

virtual void mi::shader_v3::Options::set	(	const char *	name,
		int	value
	)			`[pure virtual]`

Set an integer option.

Note:: Integer options may also be used as floating point values.

Parameters:

	name	is the name of the option to set.
	value	is the new value of the option.

virtual void mi::shader_v3::Options::set	(	const char *	name,
		float	value
	)			`[pure virtual]`

Set a floating point option.

Parameters:

	name	is the name of the option to set.
	value	is the new value of the option.

virtual void mi::shader_v3::Options::set	(	const char *	name,
		float	value1,
		float	value2
	)			`[pure virtual]`

Set a float double option.

Parameters:

	name	is the name of the option to set.
	value1	is the first component of the double.
	value2	is the second component of the double.

virtual void mi::shader_v3::Options::set	(	const char *	name,
		float	value1,
		float	value2,
		float	value3
	)			`[pure virtual]`

Set a float triple option.

Parameters:

	name	is the name of the option to set.
	value1	is the first component of the triple.
	value2	is the second component of the triple.
	value3	is the third component of the triple.

virtual void mi::shader_v3::Options::set	(	const char *	name,
		float	value1,
		float	value2,
		float	value3,
		float	value4
	)			`[pure virtual]`

Set a float quadruple option.

Parameters:

	name	is the name of the option to set.
	value1	is the first component of the quadruple.
	value2	is the second component of the quadruple.
	value3	is the third component of the quadruple.
	value4	is the third component of the quadruple.

virtual bool mi::shader_v3::Options::get	(	const char *	name,
		bool *	value
	)			const `[pure virtual]`

Get a boolean option.

Parameters:

	name	is the name of the option to look up
	value	will be set on success, and left unchanged otherwise.

Returns:: true if an option of the given name and type is found, false otherwise.

virtual bool mi::shader_v3::Options::get	(	const char *	name,
		const char **	value
	)			const `[pure virtual]`

Get a string option.

Parameters:

	name	is the name of the option to look up
	value	The returned string value is only value for a short time, and may not be modified or deleted by the caller. The caller should make a copy of the string if needed.

Returns:: true if an option of the given name and type is found, false otherwise.

virtual bool mi::shader_v3::Options::get	(	const char *	name,
		int *	value
	)			const `[pure virtual]`

Get an integer option.

Parameters:

	name	is the name of the option to look up
	value	will be set on success, and left unchanged otherwise.

Returns:: true if an option of the given name and type is found, false otherwise.

virtual bool mi::shader_v3::Options::get	(	const char *	name,
		float *	value
	)			const `[pure virtual]`

Get a floating point option.

If the value of the named option is an integer then the integer is converted to a floating point number and returned in value.

Parameters:

	name	is the name of the option to look up
	value	will be set on success, and left unchanged otherwise.

Returns:: true if an option of the given name and type is found, false otherwise.

virtual bool mi::shader_v3::Options::get	(	const char *	name,
		float *	value1,
		float *	value2
	)			const `[pure virtual]`

Get a floating point double option.

This can be used for 2 dimensional vectors.

Parameters:

	name	is the name of the option to look up
	value1	will be set to the first component on success, and left unchanged otherwise.
	value2	will be set to the second component on success, and left unchanged otherwise.

Returns:: true if an option of the given name and type is found, false otherwise.

virtual bool mi::shader_v3::Options::get	(	const char *	name,
		float *	value1,
		float *	value2,
		float *	value3
	)			const `[pure virtual]`

Get a floating point triple option.

This can be used for RGB colors or 3 dimensional vectors.

Parameters:

	name	is the name of the option to look up
	value1	will be set to the first component on success, and left unchanged otherwise.
	value2	will be set to the second component on success, and left unchanged otherwise.
	value3	will be set to the third component on success, and left unchanged otherwise.

Returns:: true if an option of the given name and type is found, false otherwise.

virtual bool mi::shader_v3::Options::get	(	const char *	name,
		float *	value1,
		float *	value2,
		float *	value3,
		float *	value4
	)			const `[pure virtual]`

Get a floating point quadruple option.

This can be used for RGBA colors or 4 dimensional homogenous vectors.

Parameters:

	name	is the name of the option to look up
	value1	will be set to the first component on success, and left unchanged otherwise.
	value2	will be set to the second component on success, and left unchanged otherwise.
	value3	will be set to the third component on success, and left unchanged otherwise.
	value4	will be set to the fourth component on success, and left unchanged otherwise.

Returns:: true if an option of the given name and type is found, false otherwise.

virtual bool mi::shader_v3::Options::remove ( const char * name ) [pure virtual]

Delete a specific option.

This can be used to remove unneeded options.

Returns:: true if an option of the given name and type is found, false otherwise.

virtual void mi::shader_v3::Options::release ( ) [pure virtual]

Release (delete) the interface.

This should be called when done. It may release the Options object.

mi::shader_v3::Options Class Reference

Public Member Functions

Detailed Description

Setting options

Getting options

Strings and memory management

Member Function Documentation