EffectFactory

This is a helper object primarily used by the Model loader implementations to provide sharing of material Effects. This can be used standalone as well, and allows access to any existing ‘materials’ definitions already created.

It uses a simple case-sensitive string-based (wide-character) map for finding effect instances that have already been created by the factory, which avoid duplication of resources in complex models and scenes.

Header

#include <Effects.h>

Initialization

The EffectFactory constructor requires a Direct3D 12 device, assuming you don't have any textures used in your effects.

std::unique_ptr<EffectFactory> fxFactory;
fxFactory = std::make_unique<EffectFactory>( device );

To use textures in your effects, you need to provide your resource heaps typically from EffectTextureFactory:

states = std::make_unique<CommonStates>(device);

fxFactory = std::make_unique<EffectFactory>( device,
    modelResources->Heap(), states->Heap() );

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

Creating effects

Fill out the EffectInfo structure, then call CreateEffect to obtain an Effects instance. If the info.name string is provided then any already created effect from the factory that has the same name will be returned as a shared instance rather than a new instance created. If there is a name match, then all the other parameters in the EffectInfo are ignored. Otherwise a new effect is created from the provided EffectInfo parameters.

std::shared_ptr<IEffect> CreateEffect(
    const EffectInfo& info,
    const EffectPipelineStateDescription& opaquePipelineState,
    const EffectPipelineStateDescription& alphaPipelineState,
    const D3D12_INPUT_LAYOUT_DESC& inputLayout,
    int textureDescriptorOffset = 0,
    int samplerDescriptorOffset = 0);

The opaquePipelineState and alphaPipelineState pipeline states are selected based on the value of info.alphaValue by comparing to 1.0. These can both point to the same pipeline state description if desired. The inputLayout of these pipeline state descriptions should be nullptr. See EffectPipelineStateDescription for more details.

The textureDescriptorOffset and samplerDescriptorOffset values are used as base values when computing the proper descriptor index from info.samplerIndex and info.samplerIndex2.

The standard factory will create instances of BasicEffect. If info.enableSkinning is true, it returns SkinnedEffect instances instead. If info.enableDualTexture is true, it returns a DualTextureEffect instance. If info.enableNormalMaps is true, then it returns a NormalMapEffect instance. They are kept in distinct 'sharing' lists since they have different input layout requirements.

Interfaces

The EffectFactory is a concrete implementation of the IEffectFactory interface, and provides a default implementation and caching policy. This allows the developer to create their own custom version of the Effect Factory by deriving from IEffectFactory, which can be used with Model loaders. This could be used for alternative caching policies, substituting special Effects triggered material name, etc.

Sharing

You can control the sharing cache with two methods that are implemented for EffectFactory.

This method sets the sharing mode which defaults to true. By setting it to false, CreateEffect will always return a new instance rather than returning a cached instance.

fxFactory->SetSharing( false );

This method clears the sharing cache, which might not release all the instances if they are referenced by other objects.

fxFactory->ReleaseCache();

Effects options

Because of the DirectX 12 Pipeline State Object (PSO) model, all effect options must be determined at the time the effect is created.

EnablePerPixelLighting is used to determine if EffectFlags::PerPixelLighting will be used. This defaults to true.
EnableNormalMapEffect is used to determine of NormalMapEffect is used for models containing normal-map textures. This defaults to true. If set to false, it will use BasicEffect instead for these materials.
EnableFogging is used to determine if EffectFlags::Fog will be used. This defaults to false.