Table of Contents

The file can contain multiple materials and maps definitions. The document should have this basic format:

<mtlLib>
 
    *<mapDefinition name="[string]">[map]</mapDefinition>
 
    *<materialDefinition name="[string]">[material]</materialDefinition>
 
</mtlLib>


Where [material] always expands to <material class=“[string]”>…</material> and [map] always expands to <map class=“[string]”>…</map> (see general format description).

Saving materials/maps to be referenced later

When one uses:

<materialDefinition name="materialName">[material]</materialDefinition>
or
<mapDefinition name="mapName">[map]</mapDefinition>


it can be referenced later in geometry by materialName/mapName, or inside another material/map definition afterward with:

<material class="Reference">materialName</material>
or
<map class="Reference">mapName</map>


This allows easy reuse of materials/maps without having to write the entire definition every time it is used. Note that the map names are first transformed to identifiers by replacing every character that is neither alphanumeric nor underscore (_) with underscore (_), and then converting to lower case. This means that Foo and foo are considered equal identifiers, as well as foo-bar and foo_bar

Material classes

Native


The basic universal shader. Most materials can be created with this shader. The properties map very closely to 3ds Max NativeMtl controls.

<material class="Native">
    ?<diffuse>[RGB]|[map]</diffuse>
 
    ?<reflect>
        <color>[RGB]|[map]</color>
        <ior>[float]|[map]</ior>
        <glossiness>[float]|[map]</glossiness>
        ?<anisotropy>[float]|[map]</anisotropy>
        ?<anisoRotation>[float]|[map]</anisoRotation>
        ?<anisotropyOrientationMode>Object|UVW</anisotropyOrientationMode>        
        ?<anisoTropyOrientationMappingChannel>[int]</anisoTropyOrientationMappingChannel>
    </reflect>
 
    ?<refract>
        <color>[RGB]|[map]</color>
        <ior>[float]|[map]</ior>
        <glossiness>[float]|[map]</glossiness>
        ?<dispersion>[float]</dispersion>
        ?<glassMode>Caustics|Thin|Hybrid</glassMode>
    </refract>
 
    ?<translucency>
        <color>[RGB]|[map]</color>
        <level>[RGB]|[map]</level>
    </translucency>
 
    ?<emission>
        <color>[RGB]|[map]</color>
        ?<glossiness>[float]</glossiness>
        ?<twosided>[bool]</twosided>
        ?<shadowcatcherIlluminator>[bool]</shadowcatcherIlluminator>
        ?<disableSampling>[bool]</disableSampling>
        ?<includeExclude>[includeList]</includeExclude>
        ?<ies>
            <file>[filename]</file>
            ?<sharpnessFake>[bool]</sharpnessFake>
            <tm>[TM]|[animTM]</tm>
        </ies>
    </emission>
 
    ?<volume>
        <attenuationDist>[float]</attenuationDist>
        <attenuationColor>[RGB]|[map]</attenuationColor>
        ?<emissionColor>[RGB]|[map]</emissionColor>
        ?<emissionDist>[float]</emissionDist>
        ?<scatteringAlbedo>[RGB]|[map]</scatteringAlbedo>
        ?<meanCosine>[float]</meanCosine>
        ?<singleScatteringOnly>[bool]</singleScatteringOnly>
        ?<mappingMode>Mapping2D|Mapping3D</mappingMode>
        ?<stepSize>[float]</stepSize>        
    </volume>
 
    ?<opacity>[RGB]|[map]</opacity>
 
    ?<bump>[map]</bump>
 
    ?<bgOverride>[map]</bgOverride>
 
    ?<alphaMode>default|white|black</alphaMode>
 
    ?<displacement>
        <map>[map]</map>
        <min>[float]</min>
        <max>[float]</max>
        ?<waterLevel>[float]</waterLevel>
    </displacement>
 
    ?<subsurface>       
        ?<level>[float]|[map]</level>
        ?<bleedColor>[RGB]|[map]</bleedColor>
        ?<radius>[float]|[map]</radius>
    </subsurface>
 
</material>
emission > disableSamplingWhen set to true, the emission changes to self-illumination
volume > mappingModeWhen set to Mapping 2D, textures are resolved at the volume boundary (resulting in a homogeneous volume). When set to Mapping 3D, textures are evaluated inside the volume along the ray relting in a true heterogeneous medium). Note that Mapping 3D works well only for textures with mapping based on position
volume > stepSizeWhen mapping mode is set to Mapping 3D, textures are sampled along the ray once per step. This parameter defines the length of the step and thus also a number of steps along the ray. Increasing the step size leads to faster rendering, but more noisier results. Decreasing the step size leads to slower rendering with higher quality result
displacement > minDisplacement value corresponding to black (0.0) texture value
displacement > maxDisplacement value corresponding to white (1.0) texture value
displacement > waterLevelIf sets, clips all texture values lower than this number. Any polygons/parts of polygons where the displacement map evaluates to a value lower than waterLevel will be removed
subsurface > levelControls how much will be skin defined by subsurface scattering as opposed to diffuse reflection. Settings this fraction to 0 results in no subsurface scattering, while settings the fraction to 1 results in full subsurface scattering and no diffuse reflection.
subsurface > colorDefines the color of subsurface scattering on a lit part of the surface.
subsurface > scatterColorDefines the scatter color of subsurface scattering, i.e. the color that can be observed in the shadowed parts of the material.
subsurface > radiusDefines the subsurface scattering radius, i.e. how far will the color bleed from a place that was hit by a light beam.

Rayswitch


Allows for different ray types to be shaded differently. This is very useful for all sorts of hacks (such as disabling visibility in GI, making material invisible in reflections, manipulating color bleeding, … All children are optional - when not present, material is invisible for that type of rays. “Normal” slot includes global illumination.

<material class="Rayswitch">
    ?<normal>[material]</normal>
    ?<direct>[material]</direct>
    ?<reflect>[material]</reflect>
    ?<refract>[material]</refract>
</material>

Layered


Layered material has one base material, and 1-n layers. When shaded, first the base material is evaluated, and then all layers. Each layer is evaluated and blended on top of all previous layers using the weight parameter (result = weight * newLayer + (1 - weight) * result):

<material class="Layered">
    <base>[material]</base>
    +<layer>
        <weight>[float]|[map]</weight>
        [material]
    </layer>
</material>

Shadowcatcher


A special fake for compositing. It has a limited subset of the native material, plus some extra options that allows using it for compositing rendered imagery on top of live footage.

<material class="ShadowCatcher">
    <shadingMode>final|composite|finalNoAlpha</shadingMode>
    ?<projectionMode>none|backplate|environment</projectionMode>
    ?<projectAllMaps>[bool]</projectAllMaps>
    ?<shadowAmount>[float]</shadowAmount>
    ?<offscreenOverride>[RGB]|[map]</offscreenOverride>
 
    <emission>[RGB]|[map]</emission>
 
    ?<reflect>
        <color>[RGB]|[map]</color>
        <ior>[float]|[map]</ior>
        <glossiness>[float]|[map]</glossiness>
    </reflect>
 
    ?<bump>[map]</bump>
 
 
</material>
shadingModeFinal means that both the photo background (defined in emission slot) and the CG footage will be present in the resulting render. The image can be saved and used as-is. Composite means that only the CG footage will be present (but the emission slot will still be used to create shadows/alpha for compositing).
projectionModenone means that the textures will be used as-is. Backplate/environment means that the textures will be reprojected to create contact shadows (to make the CG footage “touch” the background).
projectAllMapsIf true, the projectionMode will be used also for bump/reflections maps (not only emission)
shadowAmountModifies the amount of shadows in the picture by changing the albedo of the shadow catcher
offscreenOverrideIf defined and used together with projectionMode screen, then this color/map will be returned for geometry outside of camera frustrum (that cannot be screen-mapped)
emissionThe captured live footage goes into this slot (it should be also added to the direct visibility override slot of scene environment

HairMtl


Hair material, mainly used for hair and fur. The properties map very closely to 3ds Max HairMtl controls.

<material class="HairMtl">
    ?<tint>[RGB]|[map]</tint>
    ?<melanin>[float]|[map]</melanin>
    ?<pheomelanin>[float]|[map]</pheomelanin>
    ?<melaninRandomize>[float]</melaninRandomize>
    ?<colorlessSpecular>[RGB]|[map]</colorlessSpecular>
    ?<coloredSpecular>[RGB]|[map]</coloredSpecular>
    ?<transmission>[RGB]|[map]</transmission>
    ?<glossiness>[float]|[map]</glossiness>
    ?<colorlessGlossiness>[float]|[map]</colorlessGlossiness>
    ?<softness>[float]|[map]</softness>
    ?<highlightShift>[float]|[map]</highlightShift>
    ?<ior>[float]|[map]</ior>
    ?<glintStrength>[float]|[map]</glintStrength>
    ?<diffuseColor>[RGB]|[map]</diffuseColor>
    ?<opacity>[RGB]|[map]</opacity>
    ?<bump>[map]</bump>
</material>
tintMultiplier for the hair color defined by melanin and pheomelanin. Settings this value to black will lead to completely black hair, while setting it to white leads to hair color defined only by pheomelanin and melanin controls. For physically plausible results it is recommended to use only melanin and pheomelanin controls and use hair color as only additional hair dye.
melaninControls the absorption inside hair fibers by settings the total amount of melanin pigments in hair. The value equal to 0 leads to white hair, while value of 1 leads to completely black hair. The intermediate values then give physically plausible hair color.
pheomelaninControls the relative amount of reddish pheomelanin pigment among the hair pigments and hence the hair redness. Value of 0 leads to 100% of eumelanin (brown pigment) and value of 1 leads to 100% of pheomelanin (reddish pigment).
melaninRandomizeControls the randomization of pigment amount in hair. Value of 0 leads to no randomization, value of 1 leads to completely random amount of hair pigment for each hair strand.
colorlessSpecularMultiplier of the primary (colorless) specular lobe. For physically plausible results it is recommended to keep this value as pure white.
coloredSpecularMultiplier of the secondary (colored) specular lobe. For physically plausible results it is recommended to keep this value as pure white.
transmissionMultiplier of the transmission lobe. For physically plausible results it is recommended to keep this value as pure white.
glossinessControls the glossiness of hair along the hair length. Value of 0 leads to very rough/diffuse hair, while value of 1 leads to most specular hair.
colorlessGlossinessMultiplier of glossiness parameter for the primary (colorless) specular lobe. Increasing the value will lead to decreasing the width of primary (colorless) specular lobe compared to other lobes (colored specular, transmission).
softnessControls the overall softness of hair by changing the hair roughness along the hair width. Value of 0 leads to least soft hair (high specularity along the hair width), while value of 1 leads to most soft hair.
highlightShiftShifts the highlights on hair by changing the angle of scales on the hair fiber. Value of 0 will lead to identical position of colorless and colored specular highlights, increasing the value separates the highlights more.
iorControls the index of refraction on hair surface. Value of 1.55 is recommended for physically plausible results. Inreasing the value will lead to higher specularity of hair.
glintStrengthControls the strength of random glints (i.e. caustics caused by internal reflection within elliptical hair fibers). Value of 0 results in no random glints, value of 1 leads to most apparent random glints. Increasing the glints strength leads to overall decrease in colored specular, since the energy is now more focused in the random glints.
diffuseColorControls the diffuseness of hair. Value of 0 leads to fully specular hair, while value of 1 results in fully diffuse scattering. For physically plausible results this value should be set to black.
opacity

Controls the opacity of hair. Value of 0 leads to completely transparent hair, value of 1 leads to opaque hair.

Settings the opacity value to anything else than 1 leads to significant drop in performance.

bumpBump mapping

SkinMtl


Skin material, mainly used for skin. The properties map very closely to 3ds Max SkinMtl controls.

<material class="SkinMtl">
    <skinColor>[RGB]|[map]</skinColor>
    ?<sssRadiusScale>[float]</sssRadiusScale>
    ?<sssFraction>[float]|[map]</sssFraction>
    ?<sssMode>Directional|Diffusion</sssMode>
    +<subsurface>
        <index>[int]</index>
        ?<scatterColor>[RGB]|[map]</scatterColor>
        ?<radius>[float]|[map]</radius>
        ?<weight>[float]|[map]</weight>
    </subsurface>
    +<reflection>
        <index>[int]</index>
        ?<color>[RGB]|[map]</color>
        ?<ior>[float]|[map]</ior>
        ?<glossiness>[float]|[map]</glossiness>
    </reflection>
    ?<opacity>[RGB]|[map]</opacity>
    ?<bump>[map]</bump>
</material>
skinColorControls overall skin color as it is observed on a fully lit surface.
sssRadiusScaleControls the size of the subsurface scattering of all layers. Serves as a multiplier of each layer radius.
sssFractionControls how much will be skin defined by subsurface scattering as opposed to diffuse reflection. A value of 0 results in no subsurface scattering, while a value of 1 results in full subsurface scattering and no diffuse reflection.
subsurfaceDefines properties of one subsurface layer, currently up to 3 subsurface layers are supported.
subsurface > indexSubsurface layer index (0-2).
subsurface > scatterColorDefines the scatter color of subsurface scattering, i.e. the color that can be observed in the shadowed parts of the material.
subsurface > radiusDefines the subsurface scattering radius, i.e. how far will the color scatter from a place that was hit by a light beam.
subsurface > weightDefines how much this layer defines the material subsurface scattering as opposed to other subsurface layers. A value of 1 means that this layer has full influence on the overall subsurface scattering, while a value of 0 means the layer is not used at all.
reflectionDefines properties of one reflection layer, currently up to 2 reflection layers are supported.
reflection > indexReflection layer index (0-1).
reflection > colorDefines a color tint of the specular reflection.
reflection > iorControls the index of refraction of this reflection layer. Value of 1.4 is default. Increasing the value will lead to higher specularity of hair.
reflection > glossinessControls the glossiness of this reflection layer. Value of 0 leads to very rough/diffuse layer, while value of 1 leads to most specular layer.
opacity

Controls the opacity of skin. Value of 0 leads to completely transparent skin, value of 1 leads to opaque skin.

Settings the opacity value to anything else than 1 leads to significant drop in performance.

bumpBump mapping

EnviroPortal


Contains no properties. Used to create environment light portals to optinally use in interior windows. Is not visible in the scene, but rather just used as sampling hint.