NormalMapEffect

DirectXTK	Effects

NormalMapEffect effect extends BasicEffect to support normal-mapping and an optional specular map. It supports texture mapping, vertex coloring, directional per-pixel lighting, fog, and GPU instancing.

SkinnedNormalMapEffect extends NormalMapEffect to support vertex skinning. The skinned effect does not support per-vertex colors or GPU instancing.

Related tutorials: Using advanced shaders, Multistream rendering and instancing

classDiagram
class IEffect{
    <<Interface>>
    +Apply()
    +GetVertexShaderBytecode()
}
class IEffectMatrices{
    <<Interface>>
    +SetWorld()
    +SetView()
    +SetProjection()
    +SetMatrices()
}
class IEffectLights{
    <<Interface>>
    +SetAmbientLightColor()
    +SetLightEnabled()
    +SetLightDirection()
    +SetLightDiffuseColor()
    +SetLightSpecularColor()
    +EnableDefaultLighting()
}
class IEffectFog{
    <<Interface>>
    +SetFogEnabled()
    +SetFogStart()
    +SetFogEnd()
    +SetFogColor()
}
class NormalMapEffect{
    +SetDiffuseColor()
    +SetEmissiveColor()
    +SetSpecularColor()
    +SetSpecularPower()
    +DisableSpecular()
    +SetAlpha()
    +SetColorAndAlpha()
    +SetVertexColorEnabled()
    +SetBiasedVertexNormals()
    +SetTexture()
    +SetNormalTexture()
    +SetSpecularTexture()
    +SetInstancingEnabled()
}
NormalMapEffect --|> IEffect
NormalMapEffect --|> IEffectMatrices
NormalMapEffect --|> IEffectLights
NormalMapEffect --|> IEffectFog
class IEffectSkinning{
    <<Interface>>
    +SetWeightsPerVertex()
    +SetBoneTransforms()
    +ResetBoneTransforms()
}
class SkinnedNormalMapEffect
NormalMapEffect <|-- SkinnedNormalMapEffect 
SkinnedNormalMapEffect --|> IEffectSkinning

Header

#include <Effects.h>

Initialization

Construction requires a Direct3D 11 device.

std::unique_ptr<NormalMapEffect> effect;
effect = std::make_unique<NormalMapEffect>(device);

std::unique_ptr<SkinnedNormalMapEffect> effect;
effect = std::make_unique<SkinnedNormalMapEffect>(device);

For exception safety, it is recommended you make use of the C++ RAII pattern and use a std::unique_ptr or std::shared_ptr

Interfaces

NormalMapEffect supports IEffect, IEffectMatrices, IEffectLights, and IEffectFog

SkinnedNormalMapEffect also supports IEffectSkinning

Input layout

This effect requires SV_Position, NORMAL, and TEXCOORD0. If per-vertex colors are enabled, it also requires COLOR.

If instancing is enabled, this effect also requires these vertex elements:

"InstMatrix",  0, DXGI_FORMAT_R32G32B32A32_FLOAT
"InstMatrix",  1, DXGI_FORMAT_R32G32B32A32_FLOAT
"InstMatrix",  2, DXGI_FORMAT_R32G32B32A32_FLOAT

If skinning is used, the vertex layout requires BLENDINDICES and BLENDWEIGHT.

Properties

SetDiffuseColor: Sets the diffuse color of the effect. Defaults to white (1,1,1). Alpha channel (.w component) is ignored.
SetEmissiveColor: Sets the emissive color of the effect. Defaults to black (0,0,0).
SetSpecularColor: Sets the specular color of the effect. Defaults to white (1,1,1).
SetSpecularPower: Sets the specular power of the effect. Defaults to 16. Settings power to 0 can cause strange rendering artifacts.
DisableSpecular: Disables the specular lighting for the effect. Sets the color to black (0,0,0) and power to 1.
SetAlpha: Sets the alpha (transparency) of the effect. Defaults to 1 (fully opaque). This value is also used for binning opaque vs. transparent geometry.
SetColorAndAlpha: Sets the diffuse color of the effect and the alpha (transparency).
SetVertexColorEnabled: Enables per-vertex color. Defaults to false. Modifying this setting requires recreating associated input layouts, and enabling it requires COLOR.
SetTexture: Associates a texture shader resource view with the effect for the diffuse/albedo texture. Can be set to nullptr to remove a reference. Can optionally include an alpha channel as well.
SetNormalTexture: Associates a texture shader resource view with the effect for the normal map texture. Can be set to nullptr to remove a reference.
SetSpecularTexture: Associates a texture shader resource view with the effect for the specular texture. Can be set to nullptr.
SetBiasedVertexNormals: Enables support for compressed vertex normals which require *2 - 1 biasing at runtime such as DXGI_FORMAT_R10G10B10A2_UNORM.
SetInstancingEnabled: Enables support for per-vertex instancing by adding a per-vertex XMFLOAT3X4 transform matrix.

Normal maps

The normal-mapping textures used by this effect are tangent-space normal maps as opposed to object-space normal maps.

The normal map textures used by this effect are assumed to be _UNORM formats and therefore encoded using the 'x2 bias' model, i.e. the normal component's value range of -1 to +1 have been converted to 0 to +1. This is a simple encoding that is commonly used for normal texture maps since most file image formats don't support negative numbers. The conversion back to signed values is handled internally in the shader code.

The red (x) and green (y) channels are loaded from the texture, but blue (z) and alpha (w) channels are unused. The shader reconstructs the z component of the normal using z = sqrt( 1 - dot( xy, xy ) ). This has two positive benefits:

You can make use the DXGI_FORMAT_BC5_UNORM (i.e. 3Dc) for normal map texture compression without any shader or configuration changes.
Due to quantization effects, the actual unit length of the normal can drift, so this reconstruction can improve quality by effectively renormalizing the value.

Finally, the green (y) channel is used "as is" in the shader code. Some viewing and materials conventions can require the green channel to be inverted to properly 'push in' or 'push out'. This issue should be handled by modifying the texture content either offline or at load time. Because the shader reconstructs the z channel, an inverted y channel can result in black pixels on the model if it's backwards.

In content tools, this setting is usually called "OpenGL" vs. "Direct3D" normal maps. You can also use the texconv tool's -inverty switch.

Remarks

This effect implements the classic diffuse Lambertian shading with Phong specular highlights lighting model with the addition of per-pixel normals and lighting. Optionally the specular highlights can be implemented as a specular map.

Calls to SetLightingEnabled(false); will generate a C++ exception, and calls to SetPerPixelLighting are ignored.

For SkinnedNormalMapEffect, calls to SetInstancingEnabled(true); or SetVertexColorEnabled(true); will generate a C++ exception.

This effect always performs texturing, so if 'untextured' rendering is desired you must provide texture coordinates, and a sampler in slot 0. The class will default to a 1x1 texture with white (1,1,1,1) for the texture, and (0.5, 0.5) for the normal map (i.e. a 'smooth' surface). This is useful when using GPU instancing which is not supported by BasicEffect.