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 > disableSampling | When set to true, the emission changes to self-illumination |
| volume > mappingMode | When 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 > stepSize | When 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 > min | Displacement value corresponding to black (0.0) texture value |
| displacement > max | Displacement value corresponding to white (1.0) texture value |
| displacement > waterLevel | If 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 > level | Controls 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 > color | Defines the color of subsurface scattering on a lit part of the surface. |
| subsurface > scatterColor | Defines the scatter color of subsurface scattering, i.e. the color that can be observed in the shadowed parts of the material. |
| subsurface > radius | Defines 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>
| shadingMode | Final 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). |
| projectionMode | none 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). |
| projectAllMaps | If true, the projectionMode will be used also for bump/reflections maps (not only emission) |
| shadowAmount | Modifies the amount of shadows in the picture by changing the albedo of the shadow catcher |
| offscreenOverride | If 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) |
| emission | The 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>
| tint | Multiplier 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. |
| melanin | Controls 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. |
| pheomelanin | Controls 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). |
| melaninRandomize | Controls 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. |
| colorlessSpecular | Multiplier of the primary (colorless) specular lobe. For physically plausible results it is recommended to keep this value as pure white. |
| coloredSpecular | Multiplier of the secondary (colored) specular lobe. For physically plausible results it is recommended to keep this value as pure white. |
| transmission | Multiplier of the transmission lobe. For physically plausible results it is recommended to keep this value as pure white. |
| glossiness | Controls 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. |
| colorlessGlossiness | Multiplier 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). |
| softness | Controls 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. |
| highlightShift | Shifts 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. |
| ior | Controls 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. |
| glintStrength | Controls 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. |
| diffuseColor | Controls 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. |
| bump | Bump 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>
| skinColor | Controls overall skin color as it is observed on a fully lit surface. |
| sssRadiusScale | Controls the size of the subsurface scattering of all layers. Serves as a multiplier of each layer radius. |
| sssFraction | Controls 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. |
| subsurface | Defines properties of one subsurface layer, currently up to 3 subsurface layers are supported. |
| subsurface > index | Subsurface layer index (0-2). |
| subsurface > scatterColor | Defines the scatter color of subsurface scattering, i.e. the color that can be observed in the shadowed parts of the material. |
| subsurface > radius | Defines the subsurface scattering radius, i.e. how far will the color scatter from a place that was hit by a light beam. |
| subsurface > weight | Defines 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. |
| reflection | Defines properties of one reflection layer, currently up to 2 reflection layers are supported. |
| reflection > index | Reflection layer index (0-1). |
| reflection > color | Defines a color tint of the specular reflection. |
| reflection > ior | Controls 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 > glossiness | Controls 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. |
| bump | Bump 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.