This project is now hosted on GitHub
. This site is being maintained for now, but please move to using GitHub
This is a native Direct3D 11 implementation of the five built-in effects from XNA Game Studio, providing identical functionality and API:
- BasicEffect supports texture mapping, vertex coloring, directional lighting, and fog
- AlphaTestEffect supports per-pixel alpha testing
- DualTextureEffect supports two layer multitexturing (for lightmaps or detail textures)
- EnvironmentMapEffect supports cubic environment mapping
- SkinnedEffect supports skinned animation with up to 72 bones and 1, 2, or 4 bone influences per vertex.
DirectX Tool Kit also includes the following built-in effects:
- DGSLEffect which supports the Visual Studio Shader Designer (DGSL) content pipeline both with and without skinned animation with up to 8 textures.
Using advanced shaders
Creating custom shaders with DGSL
Writing custom shaders
The built-in effect constructors requires a Direct3D 11 device.
std::unique_ptr<BasicEffect> effect(new BasicEffect(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
The DGSLEffect constructor takes a pixelShader instance. If null, it uses one of the three built-in default materials: Unlit, Lambert, and Phong. This class assumes the pixel shader provided is signature compatible with the built-in DGSL vertex shader, and
will work for the feature level of the device.
std::unique_ptr<DGSLEffect> effect(new DGSLEffect(device,pixelShader));
Set effect parameters
The built-in effects default to a standard lighting and color set
- Matrices are all set to identity
- Ambient, diffuse, and emissive colors default to black
- Fully opaque (alpha set to 1)
- Specular defaults to white with a power of 16
- Default lights are set to white with no specular highlight and a default direction of [0, -1, 0]. All lights are disabled by default.
The EnableDefaultLighting method sets up a standard three light setup (key, fill, and back) with some ambient light and some soft specular highlights.
: To disable specular highlights on a material with BasicEffect, SkinnedEffect and DGSLEffect; DisableSpecular sets the specular color to black [0,0,0] and the specular power to 1. A specular power of 0 can result in strange rendering artifacts.
- EnvironmentMapEffect always uses vertex lighting, but does not support per-pixel lighting
- SkinnedEffect always uses vertex or per-pixel lighting
- DGSLEffect always uses per-pixel lighting if lighting is supported by the effect. It also supports a UV Transform for the texture coordinates, viewport information, and a time variable which may or may not be used by a given DGSL pixel shader. Fog settings
are not supported by this effect, but could be 'baked in' to a given DGSL pixel shader.
Draw using the effect
require a texture sampler in both slots 0 and 1. DGSLEffect can require up to 8 texture samplers. The other textured effects only require a texture sampler in slot 0.
only set a texture sampler in slot 0 by default.
sets a sampler in slots 0 and 1.
requires two sets of texture coordinates, while the other textured effects only require a single set.
loaded from VBO or CMO, and
only define a single set of texture coordinates in their vertex buffers so they can't be used with DualTextureEffect.
To create an input layout matching the effect vertex shader input signature:
// First, configure effect parameters the way you will be using it. Turning
// lighting, texture map, or vertex color on/off alters which vertex shader
// is used, so GetVertexShaderBytecode will return a different blob after
// you alter these parameters. If you create an input layout using a
// BasicEffect that had lighting disabled, but then later enable lighting,
// that input layout will no longer match as it will not include the
// now-necessary normal vector.
void const* shaderByteCode;
For the built-in effects, the trigger for needing to create a new layout would be:
- Enabling or disabling lighting (which requires a vertex normal)
- Enabling or disabling per vertex color (which requires a vertex color value)
- Enabling or disabling textures (which requires vertex texture coordinates)
- Changing effect class (BasicEffect <-> SkinnedEffect or DGSLEffect)
DGSLEffect is typically used with VertexPositionNormalTangentColorTexture or VertexPositionNormalTangentColorTextureSkinning.
The built-in effects support a number of different settings, some of which are organized into more 'generic' interfaces.
- IEffect is the basic interface for all effects which includes applying it to the device context and obtaining the shader information needed to create a Direct3D 11
input layout with a signature that matches the effect's shader. Remember that a given Effect instance could return a different shader based on internal state.
- IEffectMatrices is the interface for setting an effects' world, view, and projection matrices. All the built-in effects support this interface.
- IEffectLights is the interface for controlling the effects' lighting computations and settings. This is supported by BasicEffect, EnvironmentMapEffect,
SkinningEffect, and DGSLEffect
- IEffectFog is the interface to control the effects' fog settings. This is supported by BasicEffect, AlphaTestEffect, DualTextureEffect, EnvironmentMapEffect,
- IEffectSkinning is the interface to control skinned animation settings. This is supported by DGSLEffect and SkinnedEffect. This includes setting the bone
transform matrices, and optimizing the number of bone influences per vertex to process (1, 2, or 4; defaults to 4).
The built-in effects work equally well for both right-handed and left-handed coordinate systems. The one difference is that the fog settings start & end for left-handed coordinate systems need to be negated (i.e. SetFogStart(6), SetFogEnd(8) for right-handed
coordinates becomes SetFogStart(-6), SetFogEnd(-8) for left-handed coordinates).
Feature Level Notes
The built-in shaders are compiled using the vs_4_0_level_9_1 and ps_4_0_level_9_1 profiles to support all feature levels.
The compiled shaders are integrated into the DirectXTK library to avoid the need for runtime compilation, shader reflection, or deploying compiled shader binary files (.cso).
The DGSLEffect includes built-in support for the three default materials: Unlit, Lambert, and Phong. These built-in DGSL materials support all feature levels, as does the built-in DGSL-compatible vertex shader. Visual Studio Shader Designer (DGSL) .DGSL.CSO
files support Feature Level 10.0+. The DGSLEffectFactory
automatically attempts to locate a suitably named standard .CSO on Feature Level 9.x which is a manually
created fall-back shader. The method for creating these fall-back shaders is to use "Export to HLSL..." from the Visual Studio Shader Designer, then modify that .hlsl file so it will successfully compile with ps_4_0_level_9_1 or ps_4_0_level_9_3
(whichever is your minimum supported feature level).
Creation is fully asynchronous, so you can instantiate multiple effect instances at the same time on different threads. Each instance only supports drawing from one thread at a time, but you can simultaneously draw on multiple threads if you create a separate
effect instance per Direct3D 11 deferred context.