DGSLEffect

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.

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);

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, IEffectLights, 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 enableSkinning is true, 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 to SetTexture(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).