BasicEffect

DirectXTK	Effects

This is a native Direct3D 12 implementation of the built-in BasicEffect from XNA Game Studio 4 (Microsoft.Xna.Framework.Graphics.BasicEffect) which supports texture mapping, vertex coloring, directional vertex lighting, directional per-pixel lighting, and fog.

See also Effects

Related tutorials: Simple rendering, Line drawing and anti-aliasing, 3D shapes

classDiagram
class EffectFlags{
    <<enumeration>>
    Fog
    Lighting
    PerPixelLighting
    Texture
    VertexColor
    BiasedVertexNormals 
}
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 BasicEffect{
    +SetDiffuseColor()
    +SetEmissiveColor()
    +SetSpecularColor()
    +SetSpecularPower()
    +DisableSpecular()
    +SetAlpha()
    +SetColorAndAlpha()
    +SetTextureEnabled()
    +SetTexture()
}
BasicEffect .. EffectFlags
BasicEffect --|> IEffect
BasicEffect --|> IEffectMatrices
BasicEffect --|> IEffectLights
BasicEffect --|> IEffectFog

Loading

Header

#include <Effects.h>

Initialization

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

std::unique_ptr<BasicEffect> effect;

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

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

effect = std::make_unique<BasicEffect>(device, EffectFlags::Lighting, 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

Interfaces

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

Input layout

This effect requires SV_Position, NORMAL if lighting is enabled (EffectFlags::Lighting or EffectFlags::PerPixelLighting), COLOR if per-vertex colors are enabled (EffectFlags::VertexColor), and TEXCOORD0 if texturing is enabled (EffectFlags::Texture).

Properties

• 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).

• SetTexture: Associates a texture and sampler descriptor with the effect. Must have used EffectFlags::Texture to enable texturing. Can optionally include an alpha channel as well.

Remember the caller is responsible for setting the correct texture descriptor heap and sampler descriptor heap at render time when the effect is applied via SetDescriptorHeaps. See Effects for more information.

Example

Here is an example of creating and using a basic effect instance:

std::unique_ptr<DirectX::BasicEffect> basicEffect;

When creating device-dependent resources:

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

EffectPipelineStateDescription pd(
    &Vertex::InputLayout,
    CommonStates::AlphaBlend,
    CommonStates::DepthDefault,
    CommonStates::None,
    rtState);

basicEffect = std::make_unique<BasicEffect>(device,
    EffectFlags::Texture
    | EffectFlags::Lighting
    | EffectFlags::Fog, pd);

basicEffect->EnableDefaultLighting();
basicEffect->SetDiffuseColor(Colors::Red);
basicEffect->SetFogColor(Colors::CornflowerBlue);
basicEffect->SetFogStart(fogstart);
basicEffect->SetFogEnd(fogend);
basicEffect->SetTexture( resourceDescriptors->GetGpuHandle(Descriptors::MyTexture),
    states->LinearWrap() );

When the window size is changed is where you typically set the projection:

basicEffect->SetProjection(projection);

A view matrix is computed based on user input and camera settings:

basicEffect->SetView(view);

Then to render:

ID3D12DescriptorHeap* heaps[] = { resourceDescriptors->Heap(), states->Heap() };
commandList->SetDescriptorHeaps(static_cast<UINT>(std::size(heaps)), heaps);

basicEffect->SetWorld(world);
basicEffect->Apply(commandList);

commandList->DrawIndexedInstanced(...);

When dealing with lost device:

basicEffect.reset();

Remarks

The EffectFlags::BiasedVertexNormals is supported by this effect. This flag should be used if the vertex data contains normals encoded as biased data such as DXGI_FORMAT_R10G10B10A2_UNORM.

This effect implements the classic diffuse Lambertian shading with Phong specular highlights lighting model.

See Microsoft Docs

Further reading

BasicEffect optimizations in XNA Game Studio 4.0
SpriteBatch and BasicEffect for C++ Direct3D 11
BasicEffect: a misnomer?