mental ray User Data Shaders

Version 3.11

mental ray user data shader

Contents

• Introduction
• User Data Blocks
  • mib_data_bool
  • mib_data_int
  • mib_data_scalar
  • mib_data_vector
  • mib_data_color
  • mib_data_string
  • mib_data_texture
  • mib_data_shader
  • mib_data_bool_array
  • mib_data_int_array
  • mib_data_scalar_array
  • mib_data_vector_array
  • mib_data_color_array
  • mib_data_string_array
  • mib_data_texture_array
  • mib_data_shader_array
• User Data Shaders
  • mib_data_get_bool
  • mib_data_get_int
  • mib_data_get_scalar
  • mib_data_get_vector
  • mib_data_get_color
  • mib_data_get_string
  • mib_data_get_texture
  • mib_data_get_shader
  • mib_data_get_shader_bool
  • mib_data_get_shader_int
  • mib_data_get_shader_scalar
  • mib_data_get_shader_vector
  • mib_data_get_shader_color
• Usage
• Example

User Data Shaders

This shader package provides a solution to a common problem with large number of scene elements that use the same material or shading graph just with slightly different parameters per element. Instead of creating a copy of the whole material for each scene element just to adjust a single parameter, a single material is shared between all elements that has its input parameters driven dynamically 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. One exceptional instance of an object should be painted in red while all other instances should carry a default color of white. To achieve this, a mib_data_color user data block defining a red diffuse color is attached to the instance inst of an object obj. The material mat assigned to the instance has a surface shader driven by one input parameter diffuse that is connected to a mib_data_get_color shader. That one looks up the named attribute on the instance and returns its value, here a red color. If the attribute can not be found on the current instance the value of the default parameter of the shader is returned instead, in this example a white color.

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

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

object "obj"
    tagged
    # ...
end object

instance "inst"
    "obj"
    data "red_diffuse"
    material "mat"
end instance