AlphaTestEffect

DirectXTK	Effects

This is a native Direct3D 12 implementation of the built-in AlphaTestEffect from XNA Game Studio 4 (Microsoft.Xna.Framework.Graphics.AlphaTestEffect) which supports per-pixel alpha testing, vertex color, and fogging.

See also Effects

classDiagram
class EffectFlags{
    <<enumeration>>
    Fog
    VertexColor
}
class IEffect{
    <<Interface>>
    +Apply()
}
class IEffectMatrices{
    <<Interface>>
    +SetWorld()
    +SetView()
    +SetProjection()
    +SetMatrices()
}
class IEffectFog{
    <<Interface>>
    +SetFogStart()
    +SetFogEnd()
    +SetFogColor()
}
class AlphaTestEffect{
    +SetDiffuseColor()
    +SetAlpha()
    +SetColorAndAlpha()
    +SetTexture()
    +SetReferenceAlpha()
}
AlphaTestEffect .. EffectFlags
AlphaTestEffect --|> IEffect
AlphaTestEffect --|> IEffectMatrices
AlphaTestEffect --|> IEffectFog

Loading

class DirectX::AlphaTestEffect :
    public DirectX::IEffect,
    public DirectX::IEffectMatrices,
    public DirectX::IEffectFog

Header

#include <Effects.h>

Initialization

Construction requires a Direct3D 12 device, optional effect flags, and state description:

std::unique_ptr<AlphaTestEffect> effect;

RenderTargetState rtState(m_deviceResources->GetBackBufferFormat(),
    m_deviceResources->GetDepthBufferFormat());

EffectPipelineStateDescription pd(
    &InputLayout,
    CommonStates::Opaque,
    CommonStates::DepthDefault,
    CommonStates::CullCounterClockwise,
    rtState);

effect = std::make_unique<AlphaTestEffect>(device, EffectFlags::None, pd);

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

AlphaTestEffect(ID3D12Device* device, int effectFlags,
    const EffectPipelineStateDescription& pipelineDescription,
    D3D12_COMPARISON_FUNC alphaFunction = D3D12_COMPARISON_FUNC_GREATER);

The constructor takes one additional optional parameter that controls the test function:

D3D12_COMPARISON_FUNC
D3D12_COMPARISON_FUNC_LESS
D3D12_COMPARISON_FUNC_LESS_EQUAL
D3D12_COMPARISON_FUNC_GREATER_EQUAL
D3D12_COMPARISON_FUNC_GREATER
D3D12_COMPARISON_FUNC_EQUAL
D3D12_COMPARISON_FUNC_NOT_EQUAL
D3D12_COMPARISON_FUNC_NEVER
D3D12_COMPARISON_FUNC_ALWAYS

Interfaces

AlphaTestEffect supports IEffect, IEffectMatrices, and IEffectFog. EffectFlags::Fog is required to enable fogging.

Input layout

This effect requires SV_Position and TEXCOORD0. It requires COLOR if per-vertex colors are enabled (EffectFlags::VertexColor).

Properties

• SetTexture: Associates a texture and sampler descriptor with the effect.

• SetReferenceAlpha: Sets the alpha reference value for the test.

Exceptions

The ctor can throw std::invalid_argument or std::bad_alloc.

Apply can throw std::runtime_error for invalid alphaFunction modes or if there's no texture or sampler set.

The property methods of this implementation do not throw C++ exceptions.

Remarks

Does not support lighting (EffectFlags::Lighting or EffectsFlags::PerPixelLighting). The EffectFlags::BiasedVertexNormals flag is ignored by this effect.

The EffectFlags::Texture flag is always enabled for this effect, so use or absence of this flag is ignored for this effect.

This effect is primarily used to implement techniques that relied on legacy Direct3D 9 alpha testing render state. This effect is independent of the depth/stencil tests set in D3D12_DEPTH_STENCIL_DESC.DepthFunc and StencilFunc.