mi::shader_v3::Options Class Reference

Access to string options. More...

#include <mi_shader_if.h>

List of all members.

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, 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, 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, 3 floats, 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 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::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 *  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,
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,
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,
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 void mi::shader_v3::Options::release (   )  [pure virtual]
 

release (delete) the interface

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

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

Copyright © 1986-2009 by mental images GmbH