mi::IShader Class Reference

This interface represents shaders. More...

Inheritance diagram for mi::IShader:

Public Member Functions
virtual const char *	get_shader_class () const =0
	Returns the name of the corresponding shader class. More...

Additional Inherited Members
Public Types inherited from mi::base::Interface_declare< 0x78951593, 0x519d, 0x4259, 0x91, 0xd3, 0x3b, 0x03, 0xbc, 0x7a, 0x9a, 0x42, IScene_element >
typedef Interface_declare< id1, id2, id3, id4, id5, id6, id7, id8, id9, id10, id11, IScene_element >	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< 0x78951593, 0x519d, 0x4259, 0x91, 0xd3, 0x3b, 0x03, 0xbc, 0x7a, 0x9a, 0x42, IScene_element >
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 represents shaders.

A shader is a user supplied programs that allow parts of the graphics pipeline to be customized giving users control over the final look of the rendered imagery.

Note

MetaSL is deprecated. Support for MetaSL might be removed in future releases. Use MDL instead.

Shader Input and Output Parameters

As with most programs, a shader takes a given set of inputs, does various computations on this set of inputs, and produces a set of outputs. The inputs of a shader are referred to as input parameters and the outputs of a shader are referred to as output parameters. The set of allowed input and output parameters, and their default values, is specified by the mi::IShader_class of which this mi::IShader is an instance. (The relation between an mi::IShader_class and an mi::IShader is analogous to the relation between a C++ class and an instance of a C++ class.)

Input and Output Parameters and Attributes

For historical reasons this API exposes all shader input and output parameters as attributes of an mi::IShader instance. (For more information on attributes, refer to the mi::IAttribute_set documentation. Note also that using the interface mi::IAttribute_set to create attributes that do not appear as input parameters on the corresponding mi::IShader_class is not supported.)

Overriding Input Parameters

A given mi::IShader instance may have all allowed input parameters present, a subset of the allowed input parameters present, or no input parameters present. The presence or absence of a given input parameter depends upon how the mi::IShader instance was created and how it was edited after creation. If an mi::IShader was created as the result of an mi::IShader_class::create_function() call, it has all allowed input parameters present and they are set to their default values (or 0 if no default was defined). If an mi::IShader was the result of an mi::IShader_class::create_shader() call, it has no input parameters present. If an mi::IShader was the result of an import, then it may have all allowed input parameters present, a subset of the allowed input parameters present, or no input parameters present. The details depend upon the file imported. In addition, an mi::IShader can be edited to add or remove allowed input parameters.

The presence of input parameters on an mi::IShader instance is used to override the default values of the input parameters specified on the corresponding mi::IShader_class. For example, if an mi::IShader_class has an input parameter "input" of type Color that has a default value and a corresponding mi::IShader instance, without the input parameter "input" present, is executed with no input supplied to the input "input", then the default value for "input" from the corresponding mi::IShader_class will be used. However, if, in the same situation, the mi::IShader instance has the input parameter "input" present, then the value of this input parameter on the mi::IShader instance will be used, overriding the default value on the corresponding mi::IShader_class.

Output Parameters

A given mi::IShader instance always has no output parameters present independent of its means of construction. As the output values of an mi::IShader are computed as a result of running the shader program, there is no need to have them present as their values are always computed.

Shader's mi::IShader_connections Interface

An mi::IShader supports the mi::IShader_connections interface, obtainable through the standard get_interface() methods. This interface can be used to "connect shader instances together", the output of one mi::IShader instance, the source, can be used as the input of a second mi::IShader instance, the target, creating an adhoc graph of shaders. mi::IShader_connections can also be used to remove connections between mi::IShader instances and to examine existing connections between mi::IShader instances.

Using mi::IShader_connections::add_connection()

Edge data, information indicating how mi::IShader's are connected, is always stored in the target mi::IShader. Thus, to access or edit edge data you must obtain the mi::IShader_connections interface of the target mi::IShader. Using this mi::IShader_connections interface you can then access and edit edge data.

For example, if there is an mi::IShader named "Target" with an input parameter named "input" of type Color and an mi::IShader named "Source" with an output parameter named "output" of type Color, then one can connect the output parameter "output" of the mi::IShader "Source" to the input parameter "input" of the mi::IShader "Target" as follows:

// Obtain the IShader_connections interface to the IShader "Target"

mi::base::Handle<mi::IShader_connections> target(
    transaction->edit<mi::IShader_connections>("Target"));

// Add a connection from "output" of "Source" shader to "input" of "Target" shader
target->add_connection("input","Source.output");

Similarly, with the same mi::IShader instances as above, if you only wished to connect the output parameter member "output.r" of the mi::IShader "Source" to the input parameter member "input.r" of the mi::IShader "Target", then you can do so as follows:

// Obtain the IShader_connections interface to the IShader "Target"

mi::base::Handle<mi::IShader_connections> target(
    transaction->edit<mi::IShader_connections>("Target"));

// Add a connection from "output.r" of "Source" shader to "input.r" of "Target" shader
target->add_connection("input.r","Source.output.r");

Using mi::IShader_connections::remove_connection()

You can also use the interface mi::IShader_connections to remove connections between mi::IShader instances. For example, with the same mi::IShader instances as above, you can remove the connection created in the first code example as follows:

// Obtain the IShader_connections interface to the IShader "Target"

mi::base::Handle<mi::IShader_connections> target(
    transaction->edit<mi::IShader_connections>("Target"));

// Remove the connection to "input" of "Target" shader
target->remove_connection("input");

Similarly, with the same mi::IShader instances as above, you can remove the connection created in the second code example as follows:

// Obtain the IShader_connections interface to the IShader "Target"

mi::base::Handle<mi::IShader_connections> target(
    transaction->edit<mi::IShader_connections>("Target"));

// Remove the connection to "input.r" of "Target" shader
target->remove_connection("input.r");

Using mi::IShader_connections::get_connection_length()

In addition, you can use the interface mi::IShader_connections to examine connections. For example, with the same mi::IShader instances as above, you can connect the output parameter member "output.r" of the mi::IShader "Source" to the input parameter member "input.r" of the mi::IShader "Target" and the output parameter member "output.g" of the mi::IShader "Source" to the input parameter member "input.g" of the mi::IShader "Target", then examine the number of connections that are made to the input parameter "input" of the mi::IShader "Target" as follows:

// Obtain the IShader_connections interface to the IShader "Target"

mi::base::Handle<mi::IShader_connections> target(
    transaction->edit<mi::IShader_connections>("Target"));

// Add a connection from "output.r" of "Source" shader to "input.r" of "Target" shader
target->add_connection("input.r","Source.output.r");

// Add a connection from "output.g" of "Source" shader to "input.g" of "Target" shader
target->add_connection("input.g","Source.output.g");

// Obtain the number of connections to "input" of "Target" shader

mi::Uint32 input_length = target->get_connection_length("input");

Upon completion, this code snippet should set input_length to 2, assuming of course that there were no connections to the input parameter "input" before this code snippet was executed.

Using mi::IShader_connections::get_connection_source_selector()

Beyond examining how many connections target a given input parameter, one can also examine the sources that target a given input parameter. For example, with the same mi::IShader instances as above, you can connect the output parameter member "output.r" of the mi::IShader "Source" to the input parameter member "input.r" of the mi::IShader "Target" and the output parameter member "output.g" of "Source" to the input parameter member "input.g" of "Target" then examine the sources of the connections to the input parameter "input" as follows:

// Obtain the IShader_connections interface to the IShader "Target"

mi::base::Handle<mi::IShader_connections> target(
    transaction->edit<mi::IShader_connections>("Target"));

// Add a connection from "output.r" of "Source" shader to "input.r" of "Target" shader
target->add_connection("input.r","Source.output.r");

// Add a connection from "output.g" of "Source" shader to "input.g" of "Target" shader
target->add_connection("input.g","Source.output.g");

// Obtain the number of connections to "input" of "Target" shader

mi::Uint32 input_length = target->get_connection_length("input");

// Loop over the connections to "input" of "Target" shader

for(mi::Uint32 index = 0; index < input_length; ++index) {
    // Obtain source at index targeting the input parameter "input"

    const char* source_selector = target->get_connection_source_selector("input",index);

    // Use source_selector in some way

}

In the above loop the string source_selector takes on the values "Source.output.r" and "Source.output.g", assuming of course there are no other connections targeting "input". Note, the order in which these strings appear in the above loop is undefined. "Source.output.r" may appear first and "Source.output.g" may appear second or "Source.output.g" may appear first and "Source.output.r" may appear second.

Using mi::IShader_connections::get_connection_target_selector()

In addition the interface mi::IShader_connections allows you to examine which members of an input parameter have connections targeting them. If we connect the output parameter member "output.r" of "Source" to the input parameter member "input.r" of "Target" and the output parameter member "output.g" of "Source" to the input parameter member "input.g" of "Target", as in the previous example, then we can examine which members of the input parameter "input" have connections targeting them as follows:

// Obtain the IShader_connections interface to the IShader "Target"

mi::base::Handle<mi::IShader_connections> target(
    transaction->edit<mi::IShader_connections>("Target"));

// Add a connection from "output.r" of "Source" shader to "input.r" of "Target" shader
target->add_connection("input.r","Source.output.r");

// Add a connection from "output.g" of "Source" shader to "input.g" of "Target" shader
target->add_connection("input.g","Source.output.g");

// Obtain the number of connections to "input" of "Target" shader

mi::Uint32 input_length = target->get_connection_length("input");

// Loop over the connections to "input" of "Target" shader

for(mi::Uint32 index = 0; index < input_length; ++index) {
    // Obtain the member targeted by the index connection to "input"

    const char* target_selector = target->get_connection_target_selector("input",index);

    // Use target_selector in some way

}

In the above loop the string target_selector takes on the values "r" and "g", assuming of course there are no other connections targeting "input". Note, the order in which these strings appear in the above loop is undefined."r" may appear first and "g" may appear second or "g" may appear first and "r" may appear second.

Member Function Documentation

virtual const char* mi::IShader::get_shader_class ( ) const

pure virtual

Returns the name of the corresponding shader class.

The type of the shader class is mi::IShader_class. (This is effectively the MetaSL function name of the shader implementation.)