Edit

Share via

ID2D1Factory1::RegisterEffectFromString method (d2d1_1.h)

  • Article

Registers an effect within the factory instance with the property XML specified as a string.

Syntax

HRESULT RegisterEffectFromString(
  [in]           REFCLSID                    classId,
  [in]           PCWSTR                      propertyXml,
  [in, optional] const D2D1_PROPERTY_BINDING *bindings,
                 UINT32                      bindingsCount,
                 const PD2D1_EFFECT_FACTORY  effectFactory
);

Parameters

[in] classId

Type: REFCLSID

The identifier of the effect to be registered.

[in] propertyXml

Type: PCWSTR

A list of the effect properties, types, and metadata.

[in, optional] bindings

Type: const D2D1_PROPERTY_BINDING*

An array of properties and methods.

This binds a property by name to a particular method implemented by the effect author to handle the property. The name must be found in the corresponding propertyXml.

bindingsCount

Type: UINT32

The number of bindings in the binding array.

effectFactory

Type: PD2D1_EFFECT_FACTORY

The static factory that is used to create the corresponding effect.

Return value

Type: HRESULT

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

HRESULT Description
S_OK No error occurred.
E_OUTOFMEMORY Direct2D could not allocate sufficient memory to complete the call.
E_INVALIDARG An invalid parameter was passed to the returning function.

Remarks

Direct2D effects must define their properties at registration time via registration XML. An effect declares several required system properties, and can also declare custom properties. See Custom effects for more information about formatting the propertyXml parameter.

RegisterEffect is both atomic and reference counted. To unregister an effect, call UnregisterEffect with the classId of the effect.

Important  RegisterEffect does not hold a reference to the DLL or executable file in which the effect is contained. The application must independently make sure that the lifetime of the DLL or executable file completely contains all instances of each registered and created effect.
 
Aside from the built-in effects that are globally registered, this API registers effects only for this factory and derived device and device context interfaces.

Requirements

Requirement Value
Minimum supported client Windows 8 and Platform Update for Windows 7 [desktop apps | UWP apps]
Minimum supported server Windows Server 2012 and Platform Update for Windows Server 2008 R2 [desktop apps | UWP apps]
Target Platform Windows
Header d2d1_1.h
Library D2d1.lib
DLL D2d1.dll

See also

ID2D1Factory1

ID2D1Factory1::UnregisterEffect