| DirectXTK | Effects |
|---|
DGSLEffect is a DirectX Tool Kit implementation of the Visual Studio Shader Designer (DGSL) content pipeline with up to 8 textures.
SkinnedDGSLEffect extends DGSLEffect with vertex skinning.
See also DGSLEffectFactory
Related tutorials: Creating custom shaders with DGSL
classDiagram
class IEffect{
<<Interface>>
+Apply()
+GetVertexShaderBytecode()
}
class IEffectMatrices{
<<Interface>>
+SetWorld()
+SetView()
+SetProjection()
+SetMatrices()
}
class IEffectLights{
<<Interface>>
+SetLightingEnabled()
+SetAmbientLightColor()
+SetLightEnabled()
+SetLightDirection()
+SetLightDiffuseColor()
+SetLightSpecularColor()
+EnableDefaultLighting()
}
class DGSLEffect{
+SetAmbientColor()
+SetDiffuseColor()
+SetEmissiveColor()
+SetSpecularColor()
+SetSpecularPower()
+DisableSpecular()
+SetAlpha()
+SetColorAndAlpha()
+SetUVTransform()
+SetViewport()
+SetTime()
+SetAlphaDiscardEnable()
+SetVertexColorEnabled()
+SetTextureEnabled()
+SetTexture()
}
DGSLEffect --|> IEffect
DGSLEffect --|> IEffectMatrices
DGSLEffect --|> IEffectLights
class IEffectSkinning{
<<Interface>>
+SetWeightsPerVertex()
+SetBoneTransforms()
+ResetBoneTransforms()
}
class SkinnedDGSLEffect
DGSLEffect <|-- SkinnedDGSLEffect
SkinnedDGSLEffect --|> IEffectSkinning
Header
#include <Effects.h>
Initialization
Construction requires a Direct3D 11 device and a pixelShader instance.
std::unique_ptr<DGSLEffect> effect;
effect = std::make_unique<DGSLEffect>(device, pixelShader);
std::unique_ptr<SkinnedDGSLEffect> effect;
effect = std::make_unique<SkinnedDGSLEffect>(device, pixelShader);
If the pixelShader instance is 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.
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
DGSLEffect supports IEffect, IEffectMatrices, and IEffectLights.
SkinnedDGSLEffect also supports IEffectSkinning.
Fog settings are not supported by this effect, but could be 'baked in' to a given DGSL pixel shader.
Input layout
This effect requires SV_Position, NORMAL , TANGENT , and TEXCOORD0.
If skinning is used, it also requires BLENDINDICES and BLENDWEIGHT
DGSLEffect is typically used with VertexPositionNormalTangentColorTexture--and SkinnedDGSLEffect with VertexPositionNormalTangentColorTextureSkinning--which match the vertex structures used by CMO files. See VertexTypes
Properties
-
SetAmbientColor: Sets the ambient color of the material. Defaults to black (0,0,0). Note that other built-in effects do not make use of the ambient material color assuming they react equally to all ambient light in the scene.
-
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).
-
SetUVTransform: The DGSL effects can apply a UV transform.
-
SetViewport: DGSL shaders can reference the size of the viewport.
-
SetTime: DGSL shaders can animate based on a time value.
-
SetAlphaDiscardEnable: DGSL shaders can optionally use alpha discard.
-
SetVertexColorEnabled: Enables per-vertex color. Defaults to false. Modifying this setting requires recreating associated input layouts, and enabling it requires
COLOR. -
SetTextureEnabled: Enables texturing. Defaults to false. Modifying this setting requires recreating associated input layouts, and enabling it requires
TEXCOORD0. -
SetTexture: Associates a texture shader resource view with the effect, which can support up to 8 textures (MaxTextures is 8). Can be set to nullptr to remove a reference:
SetTexture(value);is equivalent toSetTexture(0, value);,
Feature Level Notes
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).
Remarks
DGSL shaders always use per-pixel lighting if lighting is supported by the effect.
If using compressed vertex normals which require *2 - 1 biasing at runtime such as DXGI_FORMAT_R10G10B10A2_UNORM, this should be implemented directly in the pixel shader.
DGSL shaders can require up to 8 texture samplers. GeometricPrimitive and SpriteBatch only set a texture sampler in slot 0 by default, Model sets a sampler in slots 0 and 1. Note that it only makes use of a single set of texture coordinates no matter how many textures are used.
DGSL shaders support up to 4 directional lights, while the other built-in shaders only support 3 (i.e. DGSLEffect::MaxDirectionalLights is 4).
Further reading
BasicEffect optimizations in XNA Game Studio 4.0
Visual Studio 3D StarterKit
For Use
- Universal Windows Platform apps
- Windows desktop apps
- Windows 11
- Windows 10
- Windows 8.1
- Windows 7 Service Pack 1
- Xbox One
Architecture
- x86
- x64
- ARM64
For Development
- Visual Studio 2022
- Visual Studio 2019 (16.11)
- clang/LLVM v12 - v18
- MinGW 12.2, 13.2
- CMake 3.20
Related Projects
DirectX Tool Kit for DirectX 12
Tools
All content and source code for this package are subject to the terms of the MIT License.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.