IEffect

DirectXTK	Effects

This is the abstract interface implemented by all effects in DirectX Tool Kit, and is typically used as the 'base' reference.

classDiagram
class IEffect{
    <<Interface>>
    +Apply()
}
class IEffectMatrices{
    <<Interface>>
    +SetWorld()
    +SetView()
    +SetProjection()
    +SetMatrices()
}
class IEffectLights{
    <<Interface>>
    +SetAmbientLightColor()
    +SetLightEnabled()
    +SetLightDirection()
    +SetLightDiffuseColor()
    +SetLightSpecularColor()
    +EnableDefaultLighting()
}
class IEffectFog{
    <<Interface>>
    +SetFogStart()
    +SetFogEnd()
    +SetFogColor()
}
class IEffectSkinning{
    <<Interface>>
    +SetBoneTransforms()
    +ResetBoneTransforms()
}
IEffect .. IEffectMatrices
IEffect .. IEffectLights
IEffect .. IEffectFog
IEffect .. IEffectSkinning

Loading

class DirectX::IEffect;

Usage

Drawing

The Apply method is used to set the Pipeline State Object (PSO) and root signature for drawing with the effect. This includes updating and setting the required constants consumed by these shaders.

The caller must ensure that the bound vertex and index buffer and primitive topology match the PSO in the effect.

Texturing effects require the GPU handle to the descriptor for the texture, and the caller must ensure the proper descriptor heap is active before applying the effect.

effect->Apply( commandList );

commandList->IASetVertexBuffers(0, 1, &vertexBufferView);
commandList->IASetIndexBuffer(&indexBufferView);
commandList->IASetPrimitiveTopology(D3D_PRIMITIVE_TOPOLOGY_TRIANGLELIST);

commandList->DrawIndexedInstanced(indexCount, 1, 0, 0, 0);

Input Layouts

Direct3D 12 Pipeline State Objects (PSO) include the specific input layout provided as a D3D12_INPUT_LAYOUT_DESC at creation time. If a different input layout is required, the caller must create a new effect to match that input layout.

Built-in Effect Notes

All built-in effects require the SV_Position semantic.

Effect	Layout requirements
AlphaTestEffect	This effect requires TEXCOORD0 and COLOR if per-vertex colors are enabled.
BasicEffect	This effect requires NORMAL if lighting is enabled, COLOR if per-vertex colors are enabled, and TEXCOORD0 if texturing is enabled.
DebugEffect	This effect requires NORMAL and TEXCOORD0. If per-vertex colors are enabled, it also requires COLOR.
DualTextureEffect	This effect requires TEXCOORD0 and TEXCOORD1.
EnvironmentMapEffect	This effect requires NORMAL and TEXCOORD0.
NormalMapEffect	This effect requires NORMAL , TEXCOORD0, and TANGENT. If per-vertex colors are enabled, it also requires COLOR.
PBREffect	This effect requires NORMAL and TEXCOORD0.
SkinnedEffect	This effect requires NORMAL, TEXCOORD0, BLENDINDICES, and BLENDWEIGHT.
SkinnedNormalMapEffect	This effect requires NORMAL , TEXCOORD0, TANGENT, BLENDINDICES, and BLENDWEIGHT. If per-vertex colors are enabled, it also requires COLOR.
SkinnedPBREffect	This effect requires NORMAL, TEXCOORD0, BLENDINDICES, and BLENDWEIGHT.

Implementing the interface

This method must be defined by classes that implement this interface:

void __cdecl Apply(_In_ ID3D12GraphicsCommandList* commandList) override;

The interface supports move semantics, but not copy semantics.

Exceptions

Error reporting uses the standard C++ exceptions std::exception, std::invalid_argument, std::runtime_error, std::logic_error, or std::bad_alloc.

Effect implementations may throw additional exceptions defined in <stdexcept> or <system_error>.

Remarks

An IEffect in DirectX Toolkit for DX12 typically owns a single ID3D12PipelineState object and references a ID3D12RootSignature object--typically the root signature is 'shared' between all instances of the effect, while there's a 1:1 mapping for PSOs. Therefore, all shader selection and input layout choices are made at creation time, leaving only shader constants or a few adjustable state values that can be modified at runtime.

Built-in effects have all their shader code integrated into the library, so no shader files are needed at runtime.