BasicEffect

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

See also Effects

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

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

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(_countof(heaps), heaps);

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

commandList->DrawIndexedInstanced(...);

When dealing with lost device:

basicEffect.reset();

Further reading

BasicEffect optimizations in XNA Game Studio 4.0
BasicEffect: a misnomer?