Architecture

In order to properly use Microsoft DirectX Transform objects and interfaces, it is important to know what they are and how they all relate to one another.

This article contains the following sections.

• Object Hierarchy
• Lookup Tables
• Surface Modifiers

Object Hierarchy

The following illustration depicts some of the important Component Object Model (COM) objects used in Microsoft DirectX Transform. Each box represents a COM object with interfaces, and the arrow pointing to each box indicates the method used to create it.

All operations start when you create a DXTransformFactory object (Transform Factory). This is done with a standard COM method, CoCreateInstance, which returns an IDXTransformFactory interface pointer you can use to access the object. You can use this interface to create instances of transforms and then use them in your code. The method that does is IDXTransformFactory::CreateTransform, which returns an IDXTransform interface pointer to your requested object.

After you create a transform, you need to prepare it to produce output. Most transforms have a number of custom properties that you can adjust to affect the output. These properties are listed for each transform in the Visual Filters and Transitions Reference, with explanations of how these properties control the output. Transforms that can produce animated transitions from static input images will support the IDXEffect interface. This interface includes methods to control the IDXEffect::Progress of the animation and to store the suggested IDXEffect::get_Duration of the effect. This object is created by calling the COM QueryInterface method on the transform object and requesting a pointer to the IDXEffect interface.

The Transform Factory that was previously mentioned is also a service provider for a DXSurfaceFactory object (Surface Factory). This object is responsible for creating the DXSurface objects used for transform inputs and output. To obtain pointer to a Surface Factory, you need to call the COM QueryInterface method, requesting a pointer to the IDXSurfaceFactory interface. With this interface, you can create empty DXSurfaces by calling the IDXSurfaceFactory::CreateSurface method. You can create a DXSurface and load an image into it at the same time with the IDXSurfaceFactory::LoadImage method.

People who use transforms will use DXSurface pointers to set up their transform. People who use DXSurface to create transforms or for image applications also need to access the sample of each surface. There are two kinds of access to DXSurface, both of which are obtained through the IDXSurface::LockSurface method. If you are only reading samples of a DXSurface, you call this method, requesting a pointer to the IDXARGBReadPtr interface. If you are writing samples to an output DXSurface, you instead request a pointer to an IDXARGBReadWritePtr interface.

Lookup Tables

There are Microsoft DirectX Transform interfaces that do lookup table corrections for images. These corrections can change the brightness, contrast, color balance, or opacity of the entire image. Lookup tables also can do more sophisticated image manipulation, such as gamma correction, threshold filtering, and color inversion. For a given lookup table, you have the ability to specify any number of the operations to be performed in any order.

To use a lookup table for your image, you must first use the COM CoCreateInstance method, requesting a pointer to an IDXLUTBuilder (Lookup Table Builder) interface. This interface contains methods that you can use to define the lookup table operations and their order. When you are finished, you call the QueryInterface method on the IDXLUTBuilder, requesting a pointer to an IDXLookupTable interface. From there, you can either use the lookup table directly on image samples, or you can associate it with a DXSurfaceModifier object (Surface Modifier) by using the IDXSurfaceModifier::SetLookup method.

Surface Modifiers

DXSurfaceModifier objects (Surface Modifiers) enable you to change such things as the brightness or opacity of a foreground image and place the result over a background image. You can save many steps in combining and adjusting images by using a Surface Modifier, and it also enables you to place images over tiled backgrounds.

The Surface Modifier object is created by calling the COM CoCreateInstance method, requesting a pointer to an IDXSurfaceModifier interface. The relations among the Surface Modifier and other Microsoft DirectX Transform objects are shown in the following illustration.

A Surface Modifier can have a foreground DXSurface associated with it. This association is made with the IDXSurfaceModifier::SetForeground method. A background DXSurface can also be set with the IDXSurfaceModifier::SetBackground method. There are parameters in this method that enable the image to be positioned or tiled across the DXSurface output.

Another object that can be used by a Surface Modifier is a lookup table object. A lookup table object is created with the IDXLUTBuilder interface and is assigned to the Surface Modifier through the IDXSurfaceModifier::SetLookup method.

The Surface Modifier object exposes an IDXSurface interface, which makes it seem to be a DXSurface. You can use this pointer to read samples from the modified surface, or you can attach it directly to a transform input. In reality, when samples are read through the Surface Modifier's IDXSurface pointer, the Surface Modifier performs all the lookup table operations on the foreground surface, alpha blends the result onto the background surface, and returns the samples to the calling routine.