mental ray Core Utility Shaders

Version 3.13

Contents

• Introduction
• Alembic
  • abcimport
• Ptex
  • mib_ptex_lookup
  • mib_ptex_lookup_x
• UV Tiling
  • mib_tiled_texture
• Usage

Core Utility Shaders

This shader package provides core extensions to mental ray implemented as plugins, shaders, or phenomena. They are intended to support developing industry standards and connect them to the machinery of mental ray. They are often based on third-party libraries, which are built into these shaders. Latest updates and improvements of the standards can be quickly incorporated into these utilities without updating mental ray itself.

The package contains an Alembic import module to load geometry data and scene hierarchies from files in this format into mental ray's scene database, either immediately or on demand during rendering. The Ptex texture lookup shader helps to read and apply these special textures to geometry and connect them to other materials and shaders in the scene. Finally, the UV Tiling utility shader supports a simple workflow to utilize such texture schemes with mental ray. It implements all common UV tile texture naming conventions and will automatically create an optimal representation of the many textures inside the renderer that can take benefit of the existing texture pipeline and integrates well with its features, like texture caching.

Alembic

Alembic is an open graphics interchange framework that allows to store finally baked geometry data of an animated scene in an application independent format. The shader supports to load the complete content of the archive, or just specific parts, either immediately or on demand during rendering only.

The shader implements the following conventions to assign materials to individual elements in the Alembic archive, which are not provided by Alembic itself. To relate existing mental ray materials, a custom property "material" with a string value can be specified on an object. The shader looks up a material with that name in the main scene and, if found, assigns it to the object in the mental ray scene. As a special extension, if a property "adskDiffuseColor" of type "color" is specified in the archive, the shader will auto-create a purely diffuse BSDF with that value as the color, and assign this material to the object.

abcimport

declare data
    geometry "abcimport" (
        string      "filename",
        scalar      "time"              default -1.0,
        boolean     "assembly"          default off,
        string      "select",
        integer     "fps"               default 24,
        integer     "subdivisions"      default 0,
        boolean     "facesetmaterials"  default on
    )
end declare

filename

The file name of the Alembic archive to load. The global mental ray assembly search path is applied when looking for the file.

time

The evaluation time. If not 0.0, take the time from the shader, otherwise, use the current camera frame time during rendering.

assembly

If enabled, create an assembly in mental ray for the Alembic content to prepare for on-demand loading of the Alembic geometry during rendering. Otherwise, create the scene geometry and instances immediately in the mental ray scene database.

select

If set, select a DAG path within the Alembic archive and enable all elements on and below the path, towards the leaf, for import. The DAG path is expected to be the forwards slash ("/") character. For example, the setting "/root/group/node" will load only the geometry of that DAG sub-graph.

fps

The number of frames per second for the current animation.

subdivisions

The number of regular subdivision levels (parametric approximation) for hair, NURBS surfaces, trim curves and subdivision meshes (ccmesh) geometry. Note, that an override approximation on the parent instance is respected for subdivision meshes and NURBS surfaces.

facesetmaterials

When enabled, the face set name on the Alembic geometry is interpreted as a material name. Those materials need to be defined in the scene before calling this shader in this mode.

Ptex

Ptex is a texture mapping system that does not depend on UV texture coordinates.

The shader requires that additional information is computed by mental ray. This can be enabled either globally, using the registry setting "{_MI_REG_CCMESH_PTEX}", or per object with the "bary" property. The shader also needs texture differential information, unless used only for displacement. For secondary rays, the mental ray "ray differentials" should be turned on.

mib_ptex_lookup

declare phenomenon
    color
    "mib_ptex_lookup" (
        string          "filename",
        scalar          "width"             default 1.0,
        scalar          "blur"              default 0.0,
        integer         "filtertype"        default 4,
        boolean         "interpolate_level" default off,
        scalar          "filter_sharpness"  default 1.0,

        ## these parameters are taken if face_index is >= 0
        scalar          "duv_dx_u"          default 0.0,
        scalar          "duv_dx_v"          default 0.0,
        scalar          "duv_dy_u"          default 0.0,
        scalar          "duv_dy_v"          default 0.0,
        scalar          "bary_v0x",
        scalar          "bary_v0y",
        scalar          "bary_v1x",
        scalar          "bary_v1y",
        scalar          "bary_v2x",
        scalar          "bary_v2y",
        integer         "face_index"        default -1
    )
end declare

mib_ptex_lookup_x

declare shader 
    struct {
        color   "color",
        scalar  "alpha",
        boolean "has_alpha"
        }
    "mib_ptex_lookup" (
        string          "filename",
        scalar          "width"             default 1.0,
        scalar          "blur"              default 0.0,
        integer         "filtertype"        default 4,
        boolean         "interpolate_level" default off,
        scalar          "filter_sharpness"  default 1.0,

        ## these parameters are taken if face_index is >= 0
        scalar          "duv_dx_u"          default 0.0,
        scalar          "duv_dx_v"          default 0.0,
        scalar          "duv_dy_u"          default 0.0,
        scalar          "duv_dy_v"          default 0.0,
        scalar          "bary_v0x",
        scalar          "bary_v0y",
        scalar          "bary_v1x",
        scalar          "bary_v1y",
        scalar          "bary_v2x",
        scalar          "bary_v2y",
        integer         "face_index"        default -1
    )
end declare

filename

The .ptx file to use.

width

To scale the filter width.

blur

The blur amount to add to filter width [0..1].

filtertype

The type of filter to use.

• 0 - Point-sampled (no filtering)
• 1 - Bi-linear interpolation
• 2 - Box filter
• 3 - Gaussian filter
• 4 - General bi-cubic filter (uses sharpness option)
• 5 - B-Spline (equivalent to bi-cubic w/ sharpness=0)
• 6 - Catmull-Rom (equivalent to bi-cubic w/ sharpness=1)
• 7 - Mitchell (equivalent to bi-cubic w/ sharpness=2/3)

interpolate_level

Enable interpolation between mipmap pyramid levels.

filter_sharpness

Control Bi-cubic filter (only).

face_index

Specify the base face index of the source polygons. If the index value is >= 0, then the differential and bary parameters have to be given in the respective parameters. If the differentials are not known, they must be set to zero. The bary parameters must be given for each vertex of the triangle hit, and refer to the barycentric position in the base face of the source polygons.

The shader returns a color value for 1-dimensional (scalar) textures with all rgba components set to the same value. For 3-dimensional (color) textures, color is set to the lookup value. For 4-dimensional textures, the rgba color components are set accordingly. If a valid alpha channel is specified, and in case of 1-dimensional textures, the return value has_alpha is set to true and alpha contains the lookup value.

UV Tiling

This shader helps to use UV tiled texture mapping with mental ray. It implements common naming schemes of third-party tools, but also supports completely custom tile layouts.

mib_tiled_texture

declare shader
    color texture
    "mib_tiled_texture" (
        integer     "mode"      default 0,
        integer     "utiles"    default 10,
        scalar      "filter",
        string      "colorprofile",
        vector      "uvCoord",
        string      "texture_dir",
        array struct "texture_info" {
            string      "filename",
            vector      "tile_coord"
        }
    )
end declare

mode

Set the UV tiling convention.

• 0 - UDIM
• 1 - 1-based uU_vV (Autodesk Mudbox)
• 2 - 0-based uU_vV (Pixologic ZBrush)
• 3 - Custom (tile info given in texture_info array (0-based)

utiles

Number of tiles in U direction, except for mode 3.

filter

The mental ray texture filter scale value to be used for all texture tiles.

colorprofile

The mental ray color profile used for all texture tiles.

uvCoord

The UV lookup coordinates.

texture_dir

The directory containing the texture files.

texture_info.filename
texture_info.tile_coord

Custom texture tiles to be used.

Usage

The core utility shaders are contained in the coreutil library. The declaration of the shaders and phenomena can be found in the file voreutil.mi. To use the shaders, the declaration file must be included and the library linked:

link "coreutil.so"
$include "coreutil.mi"