mental ray User Data Shaders

Version 3.9

Version 3.9.1.0
September 28 2010

Contents

User Data Shaders

This shader package provides a solution to a common problem with large number of scene elements which use the same material or shading graph just with slightly different parameters per element. Instead of creating a separate copy of the whole material for each scene element that would require the adjustment of a single parameter, the material parameters are dynamically driven by attributes defined on the current scene element. This way, the material definition, or the complex shading graph, can be created once, and customizations of the shading properties are done at the object or instance level of the scene. The following picture shows the general difference in scene layout.


Scene layout comparison.

The standard technique with individual materials for each object works well for scenes where many different materials are used for the majority of scene elements. The explicitly established dependencies also imply least runtime overhead. On the other hand, the user data solution allows to model the material once but still react to custom override parameters attached to the scene object. The values of the parameters are looked up dynamically during rendering which incurs additional execution time. However, the shaders ensure this is done just once per object per frame to keep the overhead small and usually negligible.

This package offers both components to implement such a workflow:

user data blocks
declarations for all kind of attribute types, to be attached to objects or instances,
user data shaders
for evaluation of the per element attributes at runtime and return of their value to the connected input parameter of a shader.

User Data Blocks

mib_data_bool
declare data
    "mib_data_bool"
    (
        string      "name",
        boolean     "value"
    )
end declare
mib_data_int
declare data
    "mib_data_int"
    (
        string      "name",
        integer     "value"
    )
end declare
mib_data_scalar
declare data
    "mib_data_scalar"
    (
        string      "name",
        scalar      "value"
    )
end declare
mib_data_vector
declare data
    "mib_data_vector"
    (
        string      "name",
        vector      "value"
    )
end declare
mib_data_color
declare data
    "mib_data_color"
    (
        string      "name",
        color       "value"
    )
end declare
mib_data_string
declare data
    "mib_data_string"
    (
        string      "name",
        string      "value"
    )
end declare
mib_data_texture
declare data
    "mib_data_texture"
    (
        string          "name",
        color texture   "value"
    )
end declare
mib_data_shader
declare data
    "mib_data_shader"
    (
        string      "name",
        shader      "value"
    )
end declare
mib_data_bool_array
declare data
    "mib_data_bool_array"
    (
        array string    "names",
        array boolean   "values"
    )
end declare
mib_data_int_array
declare data
    "mib_data_int_array"
    (
        array string    "names",
        array integer   "values"
    )
end declare
mib_data_scalar_array
declare data
    "mib_data_scalar_array"
    (
        array string    "names",
        array scalar    "values"
    )
end declare
mib_data_vector_array
declare data
    "mib_data_vector_array"
    (
        array string    "names",
        array vector    "values"
    )
end declare
mib_data_color_array
declare data
    "mib_data_color_array"
    (
        array string    "names",
        array color     "values"
    )
end declare
mib_data_string_array
declare data
    "mib_data_string_array"
    (
        array string    "names",
        array string    "values"
    )
end declare
mib_data_texture_array
declare data
    "mib_data_texture_array"
    (
        array string        "names",
        array color texture "values"
    )
end declare
mib_data_shader_array
declare data
    "mib_data_shader_array"
    (
        array string    "names",
        array shader    "values"
    )
end declare

User Data Shaders

mib_data_get_bool
declare shader
    boolean
    "mib_data_get_bool"
    (
        string      "name",
        boolean     "default"
    )
end declare
mib_data_get_int
declare shader
    integer
    "mib_data_get_int"
    (
        string      "name",
        integer     "default"
    )
end declare
mib_data_get_scalar
declare shader
    scalar
    "mib_data_get_scalar"
    (
        string      "name",
        scalar      "default"
    )
end declare
mib_data_get_vector
declare shader
    vector
    "mib_data_get_vector"
    (
        string      "name",
        vector      "default"
    )
end declare
mib_data_get_color
declare shader
    color
    "mib_data_get_color"
    (
        string      "name",
        color       "default"
    )
end declare
mib_data_get_string
declare shader
    string
    "mib_data_get_string"
    (
        string      "name",
        string      "default"
    )
end declare
mib_data_get_texture
declare shader
    color texture
    "mib_data_get_texture"
    (
        string          "name",
        color texture   "default"
    )
end declare
mib_data_get_shader
declare shader
    shader
    "mib_data_get_shader"
    (
        string      "name",
        shader      "default"
    )
end declare
mib_data_get_shader_bool
declare shader
    boolean
    "mib_data_get_shader_bool"
    (
        string      "name",
        boolean     "default"
    )
end declare
mib_data_get_shader_int
declare shader
    integer
    "mib_data_get_shader_int"
    (
        string      "name",
        integer     "default"
    )
end declare
mib_data_get_shader_scalar
declare shader
    scalar
    "mib_data_get_shader_scalar"
    (
        string      "name",
        shader      "default"
    )
end declare
mib_data_get_shader_vector
declare shader
    vector
    "mib_data_get_shader_vector"
    (
        string      "name",
        vector      "default"
    )
end declare
mib_data_get_shader_color
declare shader
    color
    "mib_data_get_shader_color"
    (
        string      "name",
        shader      "default"
    )
end declare

Usage

The user data related shaders are contained in the userdata library. The declaration of the shaders and data blocks can be found in the file userdata.mi. To use the shaders, the declaration file must be included and the library linked:

link "userdata.so"
$include "userdata.mi"

Example

This is an excerpt of a simple scene. It has a mib_data_color user data block attached to the instance inst of an object obj. The material mat assigned to that object has a surface shader with one input parameter diffuse connected to a mib_data_get_color shader which looks up the named attribute on the object, or instance, to drive its value. If the attribute can not be found on the current object then the value of the default parameter of the shader is returned instead.

data "red_diffuse"
    "mib_data_color" (
        "name"      "diffuse",
        "value"     1.0 0.0 0.0 # red
        )

object "obj"
    tagged
    data "red_diffuse"
    # ...
end object

shader "get_diffuse"
    "mib_data_get_color" (
        "name"      "diffuse"
        "default"   1.0 1.0 1.0 # white
    )

material "mat"
    "mib_illum_lambert" (
        "diffuse" = "get_diffuse"
        )
end material

instance "inst"
    "obj"
    material "mat"
end instance


Copyright (©) 1986-2011 by mental images GmbH