Click or drag to resize
DigitalRuneMaterials (*.drmat)

A material defines how a submesh is rendered: Which render passes are supported? Which effects are used? Which effect parameters (e.g. colors and textures) are used? See Materials and Material Instances.

This topic contains the following sections:

Material Definition (*.drmat File)

The material definition defines a material in DigitalRune Graphics. It is an XML file that uses the file extension drmat, for example Wood.drmat. Here is an example of a material definition:

Copy
<?xml version="1.0" encoding="utf-8"?>

<Material Name="CustomMaterial">
  <Pass Name="Default" Effect="BasicEffect" Profile="Any">
    <Parameter Name="DiffuseColor" Value="1,1,1" />
    <Parameter Name="SpecularColor" Value="1,1,1" />
    <Parameter Name="SpecularPower" Value="100" />
    <Texture Name="Texture" File="albedo.tga" />
  </Pass>
  <Pass Name="ShadowMap" Effect="DigitalRune/Materials/ShadowMap" Profile="HiDef" />
  <Pass Name="GBuffer" Effect="DigitalRune/Materials/GBufferNormal" Profile="HiDef">
    <Parameter Name="SpecularPower" Value="100" />
    <Texture Name="NormalTexture" Format="Normal" File="normal.tga" />
  </Pass>
  <Pass Name="Material" Effect="CustomMaterial.fx" Profile="HiDef">
    <Parameter Name="DiffuseColor" Value="1,1,1" />
    <Parameter Name="SpecularColor" Value="1,1,1" />
    <Parameter Name="CustomParameter" Value="0.95" />
    <Texture Name="DiffuseTexture" File="albedo.tga" />
    <Texture Name="SpecularTexture" File="specular.tga" />
  </Pass>
</Material>
Note Note

The material definition file is optional. If the model description file is missing or the model description does not assign a material to a submesh, then the model content processor searches for a material definition using the texture names.

For example, if an imported submesh uses a texture called Wood.tga, the model content processor tries to find a material definition file Wood.drmat in the folder that contains the texture. If a material definition is found, it is automatically assigned to the submesh. If no material definition is found, the submesh will use the default material stored in the model.

Material definitions can be changed or overwritten at runtime.

Using material definition files has several advantages:

  • Complex materials: The DigitalRune Graphics engine supports complex render pipelines, which may involve multiple render passes per model. For example, a light pre-pass (a.k.a. deferred lighting) render pipeline may start with a "ShadowMap" pass to render shadow-casting models into shadow maps. In the "GBuffer" pass the model is rendered into the G-Buffer. Then, after the renderer has lit the scene, the model is rendered again in the "Material" pass. Each render pass may require a different effect or different settings. Therefore, a material definition may include one or more render passes.

  • Shared materials: Materials can be shared between models. At design-time existing materials can be assigned to new models. At run-time shared materials are only loaded once and therefore require less resources. Renderers can sort submeshes based on their materials and thereby reduce the number of required render state changes.

A material definition defines one or more render passes where each pass can have different parameters and textures. The names of the render passes and number of render passes depends on the actual render pipeline implemented in the game. A render pipeline in DigitalRune Graphics may include any number of passes - including user-defined passes.

<Material>

The Material element is the root node of the XML file. It has the following attributes:

Attribute

Description

Examples

Name

Optional: The name of the material. Setting a name can be useful to identify a material at runtime (see property MaterialName).

Name="MaterialXYZ"

The Material element may contain one or more Pass elements.

<Pass>

The Pass element defines the settings for a specific render pass.

The Pass element has the following attributes:

Attribute

Description

Examples

Name

The name of the render pass.

Name="ShadowMap"

Effect

The DirectX Effect that is used in this render pass.

The value can be:

  • One of the XNA stock effects: AlphaTestEffect, BasicEffect, DualTextureEffect, EnvironmentMapEffect, SkinnedEffect

  • A prebuilt effect asset (see Predefined Effects). In this case the value is the asset name, which is used to load the effect at runtime.

  • A custom effect. In this case the value is the path of the effect file (.fx) relative to the material definition file.

Effect="SkinnedEffect"

Effect="DigitalRune/DeferredLighting/GBuffer"

Effect="../Effects/CustomEffect.fx"

Profile

Optional: Defines whether the render pass is designed for a certain graphics profile. The pass is ignored if it does not match the target profile of the game.

Allowed values are:

Value

Description

Reach

The render pass is only processed if the target profile of the game is Reach.

HiDef

The render pass is only processed if the target profile of the game is HiDef.

Any

The render pass is always processed.

The default value is Any

Profile="HiDef"

The Pass element may contain one or more Parameter and Texture elements.

<Parameter>

A DirectX Effect may define one or more effect parameters (shader constants). The Effect file may define default values for the effect parameter. This default value can be overridden using the Parameter element.

Currently only the following parameter types can be set in the material definition:

HLSL Type

Example

bool

<Parameter Name="EnableSkinning" Value="False" />

bool[]

<Parameter Name="Flags" Value="False,False,True,False" />

float

<Parameter Name="ReferenceAlpha" Value="0.9" />

float2

<Parameter Name="Offset" Value="0.5,0.5" />

float3

<Parameter Name="UpDirection" Value="0,1,0" />

float4

<Parameter Name="Color" Value="1,1,1,0.5" />

float[]

<Parameter Name="Values" Value="0,0.1,0.2,0.3,0.4" />

The Name of a parameter is the case-sensitive name as it is declared in the DirectX Effect file (.fx).

<Texture>

Textures can be referenced using the Texture element. The element defines the name, path, and preprocessing settings.

Examples:

Copy
<Texture Name="DiffuseTexture" File="diffuse.tga" />
<Texture Name="SpecularTexture" File="specular.tga" />
<Texture Name="AlphaMask" ReferenceAlpha="0.9" ScaleAlphaToCoverage="True" File="mask.tga" />
<Texture Name="NormalMap" Format="Normal" File="normal.tga" />
<Texture Name="LookupTable" Format="Color" GenerateMimaps="False" PremultiplyAlpha="False" InputGamma="1.0" OutputGamma="1.0" File="lut.tga" />

The Texture element has the following attributes.

Attribute

Description

Examples

Name

The name of the texture parameter in the Effect file.

Name="DiffuseTexture"

File

The path of the source image relative to the material definition. Supported file types: .bmp, .dds, .dib, .hdr, .jpg, .pfm, .png, .ppm, and .tga.

File="textures/diffuse.tga"

Format

Optional: Determines the surface format of the processed texture.

Allowed values are:

Value

Description

NoChange

The texture format of the input texture is not changed by the content processor.

Color

The texture format of the input texture is converted to SurfaceFormat.Color (32-bit ARGB format with alpha, 8 bits per channel) by the content processor.

Dxt

The texture format of the input texture is converted to an appropriate DXT compression by the content processor. If the input texture contains fractional alpha values, it is converted to DXT5 format; otherwise it is converted to DXT1.

Normal

The texture format of the input texture is converted to DXT5nm by the content processor. This format reduces compression artifacts when storing normal maps. The x-component of the normal is stored in the Alpha channel and the y-component is stored in the Green channel. The z-component needs to be reconstructed in the pixel shader.

NormalInvertY

Same as Normal, except that the y-component of the normal vector is inverted. (See below.)

The default value is Dxt

Format="NormalInvertY"

ColorKey

Optional: Enables color keying. The value is the key color (RGBA as byte values). All pixels that match the specified color are replaced with transparent black. Color keying is disabled by default.

ColorKey="255,0,255,255"

GenerateMipmaps

Optional: Generates a full chain of mipmaps for the texture. Already existing mipmaps are not replaced.

Allowed values are: True or False.

The default value is True.

GenerateMipmaps="True"

InputGamma

Optional: Specifies the gamma value of the source image.

The default value is 2.2.

InputGamma="2.2"

OutputGamma

Optional: Specifies the gamma value of the output texture. This value is the gamma that is expected by the DirectX Effect that reads the texture.

The default value is 2.2.

OutputGamma="2.2"

PremultiplyAlpha

Optional: If enabled, source image is converted to premultiplied alpha format.

Allowed values are: True or False.

The default value is True.

PremultiplyAlpha="False"

ResizeToPowerOfTwo

Optional: If enabled, the source image is resized to the next largest power of two.

Allowed values are: True or False.

The default value is False.

ResizeToPowerOfTwo="True"

ReferenceAlpha

Optional: Specifies the reference alpha value, which is used in the alpha test. This attribute is only relevant if the source image has an alpha channel, the DirectX Effect performs an alpha test, GenerateMipmaps and ScaleAlphaToCoverage are enabled.

The default value is 0.9.

ReferenceAlpha="0.95"

ScaleAlphaToCoverage

Optional: Specifies whether the alpha of the mipmaps should be scaled to achieve the same alpha test coverage as the source images. This attribute is only relevant if the source image has an alpha channel, the DirectX Effect performs an alpha test, and GenerateMipmaps is enabled.

Allowed values are: True or False.

The default value is False.

ScaleAlphaToCoverage="True"

Alpha masks

Textures can have an alpha channel, which can be used for alpha testing or alpha blending. However, textures with alpha require special treatment. The problem is described here in more detail: "Computing Alpha Mipmaps", by Ignacio Castaño (The Witness Blog)

The required correction described in the article can be enabled by setting the attributes ReferenceAlpha and ScaleAlphaToCoverage.

Example:

Copy
<Texture Name="DiffuseWithAlphaTexture" ReferenceAlpha="0.9" ScaleAlphaToCoverage="True" File="albedo_mask.tga" />

The ReferenceAlpha needs to be the value, which is used for alpha testing in the DirectX Effect. If the reference alpha value is unknown, use a value close to 1.

Normal maps

Different content creation tools can use different tangent space bases when creating normal maps. Depending on the content creation tool you need to encode the normal map using either Format="Normal" or Format="NormalInvertY".

For example, consider a normal map containing two truncated pyramids. Here are the resulting normal maps using two different tangent space bases.

Format="Normal"
Normal
Format="NormalInvertY"
Normal InvertY
Automatic creation of missing material definition files

The DigitalRune model content processor will automatically create a default material definition (*.drmat) file if it cannot find any. The material definition is placed in the same folder as the texture of the submesh and uses the file name of the texture. For example, if a submesh uses a texture called Wood.tga, the model content processor creates a default material definition file Wood.drmat in the folder that contains the texture. You can edit this file to set the desired material properties.

Note Note

If the imported submesh does not use any textures, no default material definition is created.

The automatic generation of missing model descriptions can be turned off using a property of the content processor.

See Also