IDXTransformFactory Interface

The IDXTransformFactory interface is used to instantiate and initialize a transform. It is created by calling the CoCreateInstance method and specifying CLSID_DXTransformFactory as the class identifier (CLSID) and IID_IDXTransformFactory as the interface ID.

The IDXTransformFactory::CreateTransform method can be used to create and initialize a transform in one step. Alternatively, you can use the Component Object Model (COM) CoCreateInstance method to create the transform and initialize it by using the IDXTransformFactory::InitializeTransform method. After the transform has been created and initialized, it can be executed by using IDXTransform::Setup and then IDXTransform::Execute.

IDXTransformFactory also provides support services to transforms through the IServiceProvider interface. An important service this interface provides is access to the IDXSurfaceFactory interface, which is exposed when the DXTransformFactory (Transform Factory) is created. A pointer to the DXSurfaceFactory (Surface Factory) can be obtained by calling the QueryService method on IDXTransformFactory with SID_DXSurfaceFactory as the service ID. The pointer to the Surface Factory can then be used to create a DXSurface. Furthermore, task management, Microsoft® DirectDraw®, and Microsoft Direct3D® Retained Mode services are created and added to the factory upon first query by default. You can add additional service providers through the IDXTransformFactory::SetService method. These services can be requested later, potentially by different transforms. A transform will typically try to obtain a service from the factory before it instantiates and adds a new one. This avoids duplication of identical servers across the simultaneously active transforms.

For more information on how to use this interface in your application, see the About Transforms and DXSurfaces overview article.

This interface inherits from the standard COM interface IServiceProvider.

IDXTransformFactory Methods

CreateTransform Creates and initializes a transform.

InitializeTransform Initializes a transform that has already been created by the caller.

SetService Adds a service provider to the Transform Factory.

IDXTransformFactory::CreateTransform

IDXTransformFactory Interface

Creates and initializes a transform.

Syntax

HRESULT CreateTransform(
    IUnknown **punkInputs,
    ULONG ulNumInputs,
    IUnknown **punkOutputs,
    ULONG ulNumOutputs,
    IPropertyBag *pInitProps,
    IErrorLog *pErrLog,
    REFCLSID TransCLSID,
    REFIID TransIID,
    void **ppTransform
);

Parameters

punkInputs
[in, size_is(ulNumInputs)] Pointer to an array of input data object interface pointers that the transform will use. Specify NULL if the transform does not use any inputs.

ulNumInputs
[in] Number of data objects referred to by the punkInputs parameter. Can be zero if the transform does not use any inputs.

punkOutputs
[in, size_is(ulNumOutputs)] Pointer to an array of output data object interface pointers. Can be NULL.

ulNumOutputs
[in] Number of data objects referred to by the punkOutputs parameter.

pInitProps
[in] Pointer to an optional property bag used to initialize the transform. Can be NULL.

pErrLog
[in] Pointer to an optional error log object used during property persistence. Can be NULL.

TransCLSID
[in] CLSID of the transform to create.

TransIID
[in] Interface ID of the transform type to return.

ppTransform
[out] Address of a pointer to the requested interface from the newly created transform.

Return Value

Returns one of the following HRESULT values.

S_OK Success.
E_POINTER A bad pointer was passed to the method.
REGDB_E_CLASSNOTREG A specified class is not registered in the registration database.
S_FALSE The interface is not supported.

Remarks

If the number of inputs and outputs is set to zero, this method will not use Setup on the transform. This enables you to create a transform and defer setup until a later time.

IDXTransformFactory::InitializeTransform

IDXTransformFactory Interface

Initializes a transform that has already been created by the caller.

Syntax

HRESULT InitializeTransform(
    IDXTransform *pTransform,
    IUnknown **punkInputs,
    ULONG ulNumInputs,
    IUnknown **punkOutputs,
    ULONG ulNumOutputs,
    IPropertyBag *pInitProps,
    IErrorLog *pErrLog
);

Parameters

pTransform
[in] Pointer to the transform to initialize.

punkInputs
[in, size_is(ulNumInputs)] Pointer to an array of input data object interfaces that will be used by the transform. Specify NULL if the transform does not use any inputs.

ulNumInputs
[in] Number of data objects referred to by the punkInputs parameter.

punkOutputs
[in, size_is(ulNumOutputs)] Pointer to an array of output data object interfaces that will be used by the transform. Can be NULL.

ulNumOutputs
[in] Number of data objects referred to by the punkOutputs parameter.

pInitProps
[in] Pointer to an optional property bag used to initialize the transform. Can be NULL.

pErrLog
[in] Pointer to an optional error log object used during property persistence. Can be NULL.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This method is used to properly initialize a transform that was created by a user. It uses the IDXTransform::Setup method to define the input and output data objects used in the transform.

IDXTransformFactory::SetService

IDXTransformFactory Interface

Adds a service provider to the Transform Factory.

Syntax

HRESULT SetService(
    REFGUID guidService,
    IUnknown *pUnkService,
    BOOL bWeakReference
);

Parameters

guidService
[in] GUID used to identify the service.

pUnkService
[in] Pointer to a service provider interface.
bWeakReference
[in] Flag indicating whether the reference to the service provider object should be a weak reference. If TRUE, the reference is weak; otherwise, the reference is strong. A strong reference causes the factory to reference count the service. A weak reference should be requested where there is potential for cyclic dependencies. See the Remarks section for more information about weak and strong references.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

To remove the service specified by guidService, set the pUnkService parameter to NULL.
Additional services that can be added to a Transform Factory include DirectDraw or Direct3D Retained Mode.
A strong reference (also called a lock) keeps an object active and running. As long as a strong reference to an object exists, the object should not shut down. A weak reference does not prevent an object from shutting down. For example, if a client is using a child process, its parent must stay running because the child cannot live independently of the parent. When there is a strong reference on the child, the child holds a strong reference on the parent. But if a client is not using the child, the simple existence of the child should not keep the parent active.
In a normal state, the parent should not hold a strong reference on the child, but instead hold a weak reference on the child. Thus, when all clients release the child, the child will shut down because there are no other strong references. This is usually handled by maintaining a lock count on the object separate from the reference count. When the lock count is zero, the object attempts to also make its reference count zero, for example, by sending a close notification and disconnecting all external connections.

CreateTransform	Creates and initializes a transform.
InitializeTransform	Initializes a transform that has already been created by the caller.
SetService	Adds a service provider to the Transform Factory.

S_OK	Success.
E_POINTER	A bad pointer was passed to the method.
REGDB_E_CLASSNOTREG	A specified class is not registered in the registration database.
S_FALSE	The interface is not supported.