IEffectLights

DirectXTK	Effects

This abstract interface controls directional lighting. Settings for this interface can influence the choice of shader permutation and input layout signature. This interface is implemented by BasicEffect, EnvironmentMapEffect, NormalMapEffect, PBREffect, and SkinningEffect if created with EffectFlags::Lighting or EffectFlags::PerPixelLighting.

Effects that implement this interface require NORMAL semantic data in the vertex input layout.

class DirectX::IEffectLights

Usage

Obtaining the interface

There are two methods used in DirectX Tool Kit. For simple cases, just maintain a reference directly to the desired effect class:

std::shared_ptr<BasicEffect> effect(device, EffectFlags::Lighting, pd);

...

effect->SetLightEnabled( 0, true );

static const XMVECTORF32 light { 0.f, -1.f, 0.f, 0.f };
effect->SetLightDirection( 0, light );

For more general cases where a number of effect classes can be in use (such as Model which uses a mix of BasicEffect, DualTextureEffect, and/or SkinnedEffect), use Run-Time Type Information (RTTI) to obtain the interface.

std::shared_ptr<BasicEffect> effect(device, EffectFlags::Lighting, pd);

...

auto ilights = dynamic_cast<IEffectLights*>( effect.get() );
if ( ilights )
{
    ilights->SetLightEnabled( 0, true );

    static const XMVECTORF32 light { 0.f, -1.f, 0.f, 0.f };
    ilights->SetLightDirection( 0, light );
}

Controlling lights

The IEffectLights interface supports 1, 2, or 3 directional lights (MaxDirectionalLights is 3) with an ambient light setting. The lights support both diffuse and specular color, and some effects support per-pixel lighting (enabled by creating with EffectFlags::PerPixelLighting).

The direction vector for the light is assumed to be normalized, and is pointing towards the objects it lights.

The default lighting set by EnableDefaultLighting consist of three lights:

• Ambient: (0.05333332, 0.09882354, 0.1819608)
• Light 0: Direction (-0.5265408, -0.5735765, -0.6275069), Diffuse (1, 0.9607844, 0.8078432), Specular (1, 0.9607844, 0.8078432)
• Light 1: Direction (0.7198464, 0.3420201, 0.6040227), Diffuse (0.9647059, 0.7607844, 0.4078432), Specular (0, 0, 0)
• Light 2: Direction (0.4545195, -0.7660444, 0.4545195), Diffuse (0.3231373, 0.3607844, 0.3937255), Specular (0.3231373, 0.3607844, 0.3937255).

Built-in Effect Notes

AlphaTestEffect, DualTextureEffect

These built-in effects do not support this interface.

BasicEffect

Supports up to 3 directional lights with vertex or per-pixel lighting, optionally using per-vertex colors. Materials definitions include diffuse color, specular color, specular power, and emissive color. Light definitions include ambient color, diffuse color, specular color, and specular power. Note that the standard lighting model does not include an ambient material color.

EnvironmentMapEffect

This effect always implements vertex or per-pixel lighting with no specular highlights and 3 directional lights, so the SetLightSpecularColor method is not supported for this effect.

NormalMapEffect, SkinnedNormalMapEffect

This effect always implements per-pixel lighting.

PBREffect, SkinnedPBREffect

This effect always implements per-pixel lighting, and implements up to three directional lights combined with Imaged-Based Lighting (IBL). The SetAmbientLightColor and SetLightSpecularColor methods are not supported for this effect.

SkinnedEffect

This shader always implements lighting with 3 directional lights.

Implementing the interface

These methods must be defined by classes that implement this interface:

void XM_CALLCONV SetAmbientLightColor(FXMVECTOR value) override;

void __cdecl SetLightEnabled(int whichLight, bool value) override;
void XM_CALLCONV SetLightDirection(int whichLight, FXMVECTOR value) override;
void XM_CALLCONV SetLightDiffuseColor(int whichLight, FXMVECTOR value) override;
void XM_CALLCONV SetLightSpecularColor(int whichLight, FXMVECTOR value) override;

void __cdecl EnableDefaultLighting() override;

The constant MaxDirectionalLights is defined as 3.

The interface supports move semantics, but not copy semantics.

Exceptions

The methods SetLightEnabled, SetLightDirection, SetLightDiffuseColor, and SetLightSpecularColor for built-in effects can throw std::invalid_argument.

The other methods implemented by the built-in effects do not throw C++ exceptions.