Using Transforms in C++

To use a transform in a C++ application, you must be minimally familiar with a few key interfaces, methods, and objects. This section describes how to use an existing transform in a C++ application.

There are four key steps for creating a transform in your application. The client must first identify the desired transform, either specifically by class identifier (CLSID) or by using the component category manager to create the transform. After the desired transform has been identified, input and output objects (usually DXSurface and/or Direct3DRMMeshBuilder3 objects) must be created and initialized. The transform must then be set up and associated with these objects, and then the transform can be executed.

This process of creating a transform in your application is detailed in the following steps.

Step 1: Declare and Create the Transform Factory
Step 2: Create Transform Inputs and Output
Step 3: Set Up the Transform
Step 4: Execute the Transform

The following example code uses only DXSurfaces.

Step 1: Declare and Create the Transform Factory

Declare and create the DXTransformFactory (Transform Factory), and use the IDXTransformFactory::CreateTransform method to create and initialize the transform in one step (the following example creates the Compositor transform).

Note: You can alternately create the DXTransform object by using the CoCreateInstance method and initializing it with the IDXTransformFactory::InitializeTransform method.

//Create the Transform Factory.
IDXTransformFactory* pTransFact;
CoCreateInstance( CLSID_DXTransformFactory, NULL,
                 CLSCTX_INPROC, IID_IDXTransformFactory,
                 (void **)&pTransFact );

//Create the transform.
IDXTransform *pSomeTrans;
pTransFact->CreateTransform( NULL, 0, NULL, 0,
                 NULL, NULL, CLSID_DXTComposite,
                 IID_IDXTransform, (void **)&pSomeTrans );

Step 2: Create Transform Inputs and Output

After you have a pointer to a transform, you need to define the transform's inputs and its single output. These will either be DXSurface or Direct3DRMMeshBuilder3 objects, depending on the transform. To find out about the input and output types for a particular transform, consult the Transform Reference.

To create DXSurfaces, query the Transform Factory for the DXSurfaceFactory object and use it to create DXSurfaces and to return the IDXSurface pointer. You can use a number of methods on the IDXSurfaceFactory interface to create a DXSurface. The following example uses the IDXSurfaceFactory::LoadImage method to create a DXSurface containing image data.

// Query for IDXSurfaceFactory.
pTranFact->QueryInterface(IID_IDXSurfaceFactory,
                          (void**)&pSurfFactory);
pTranFact->Release();

// Create a DXSurface with an image loaded on it.
IDXSurface *pInSurf;
pSurfFactory ->LoadImage("image.png", NULL, NULL
                         &DDPF_PMARGB32, IID_IDXSurface,
                         (void**)&pInSurf );

// Create the output DXSurface for the transform.
IDXSurface *pOutSurf;
// Give it a size.
CDXDBnds bnds;
bnds.SetXYSize(100, 100);
pSurfFactory->CreateSurface(
                 NULL, NULL, &DDPF_PMARGB32, &bnds, 0, NULL,
                 IID_IDXSurface, (void**)&pOutSurf);

This creates an input DXSurface, a transform that can be applied to the surface, and a blank output DXSurface object on which to place a result.

For three-dimensional (3-D) transforms, you must create a Microsoft® Direct3D® Retained Mode object, and use it to create a Direct3DRMMeshBuilder3 object. Users of 3-D transforms should be aware that Direct3D Retained Mode must be set to use a right-handed coordinate system for all transforms. This is illustrated in the following code example. These example steps demonstrate how this is done.

    cpD3DRMv1->QueryInterface(
    IID_IDirect3DRM3, (LPVOID*)&m_cpD3DRM)
    m_cpD3DRM->GetOptions(&dwOptions);

    dwOptions &= ~D3DRMOPTIONS_LEFTHANDED;
    dwOptions |= D3DRMOPTIONS_RIGHTHANDED;

    m_cpD3DRM->SetOptions(dwOptions);

    hr=m_cpD3DRM->CreateMeshBuilder( &g_pOutMesh );

Step 3: Set Up the Transform

Use the IDXTransform::Setup method to associate the DXSurfaces or meshes with the transform, as shown in the following:

//Do transform set up and associate it with input and output
DXSurface objects.
pSomeTrans->Setup
( (IUnknown**)& pInSurf, 1, (IUnknown**)& pOutSurf, 1, 0);

In the previous case, there is one DXSurface input and one DXSurface output.

In addition, transforms that support the Progress property for animation need a pointer to an IDXEffect interface. This is done using the Component Object Model (COM) QueryInterface on the transform, as shown in the following.

hr = pSomeTrans->QueryInterface(
IID_IDXEffect, (void **)&g_pEffect );

You can use the returned interface pointer to call the IDXEffect::put_Progress method and to set the value for Progress.

Step 4: Execute the Transform

Use the IDXTransform::Execute method to execute the transform and write the resulting image to the destination at (0,0), as shown in the following:

//Set the offset boundaries for the result and execute.
pSomeTrans->Execute( NULL, NULL, NULL );

Now you can get the device context (DC) from the output DXSurface and blit the result to the display.

For animated effects, this call to Execute would correspond to one frame of the animation. To produce a flowing transition, you need to loop over changing values of Progress, calling put_Progress and Execute at each step.