IDXTransform Interface

The IDXTransform interface is used to set up a transform and cause it to produce its graphics output. This interface is exposed on all Microsoft® DirectX® Transform objects created with the IDXTransformFactory::CreateTransform method.

Input and output data objects are specified for transform objects in the IDXTransform::Setup method. This method accepts pointers to the data object's IUnknown interface, which enables transforms to support any number and type of data objects. If you provide only an output data object, then reading, modifying, and writing all occur on that object. The transform input and output data objects are typically DXSurfaces or Direct3DRMMeshBuilder3 objects, though this will depend on the individual transform.

All transforms on DXSurfaces support data access through either the IDXARGBReadPtr or IDXARGBReadWritePtr pointer modifier interfaces, or both. These interfaces provide simplified access to samples of the DXSurface in either of the following two pixel formats: ARGB32, or alpha premultiplied PMARGB32. These formats are defined for optimal alpha blending performance and to maintain precision for intermediate results. In addition, transforms also must support Component Object Model (COM) aggregation so that additional interface pointers can be passed to the client.

The IDXTransform interface inherits from the IDXBaseObject interface. You can use the methods in the IDXBaseObject interface to manage the generation ID.

Transforms can use discrete DXBNDS structures to describe DXSurfaces, or continuous DXBNDS structures for Direct3DRMMeshBuilder3 objects. The CDXBnds template helper class can take bounds of any type and convert them where necessary. Transforms should always work using bounds in their native coordinate type.

For information about creating a transform object and retrieving the IDXTransform interface, see the IDXTransformFactory interface.

IDXTransform Methods

Execute Executes the transform operation given the specified portion bounds and places the result in the destination data object.

GetInOutInfo Retrieves input or output information about the specified data object, and an optional pointer to it.

GetMiscFlags Retrieves flags that describe the behavior of the transform.

GetQuality Retrieves the quality level used to render the transform result.

MapBoundsIn2Out Maps the input coordinate space to the output coordinate space.

MapBoundsOut2In Maps the output coordinate space to the input coordinate space.

SetMiscFlags Sets transform flags that specify how to generate the output.

SetQuality Sets the quality level used to render the transform result.

Setup Defines the input and output data objects used in the transform.

IDXTransform::Execute

IDXTransform Interface

Executes the transform operation given the specified portion bounds and places the result in the destination data object.

Syntax

HRESULT Execute(
    const GUID *pRequestID,
    const DXBNDS *pPortionBnds,
    const DXVEC *pPlacement
);

Parameters

pRequestID
[in] Pointer to an optional request ID that identifies a scheduled task. If execution causes the work to be broken into parallel tasks that are scheduled with the Task Manager, this ID is associated with each of those tasks.

pPortionBnds
[in] Pointer to a DXBNDS structure that specifies the portion of the transform's output space to render. NULL implies that the transform's entire output space should be rendered. This parameter is used by a container in cases where only a portion of the output of the transform is needed for the final composition.

pPlacement
[in] Pointer to a DXVEC structure that specifies the position of the resulting object on the output object. For DXSurfaces, this value is an offset position from the upper-left corner of the output surface.

Return Value

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

Remarks

This method computes the result of applying the transform on the zero or more input objects and produces the output object specified by the IDXTransform::Setup method. It breaks the work into suitably sized pieces and spreads them evenly among the available processors in the system using the IDXTaskManager interface. The scheduled tasks are identified by the optional request ID parameter pRequestID. Another thread can use this ID to cancel transform execution.
If no output data was specified in the Setup method, this method will allocate and return an output data object containing the result.

IDXTransform::GetInOutInfo

IDXTransform Interface

Retrieves input or output information about the specified data object, and an optional pointer to it.

Syntax

HRESULT GetInOutInfo(
    BOOL bIsOutput,
    ULONG ulIndex,
    DWORD *pdwFlags,
    GUID *pIDs,
    ULONG *pcIDs,
    IUnknown **ppUnkCurrentObject
);

Parameters

bIsOutput
[in] Flag that specifies whether the requested data is for an input or an output object. Specify TRUE to indicate that the requested information is for an output data object. Specify FALSE for an input data object.

ulIndex
[in] Index of the data object as defined during the last call to the Setup method.

pdwFlags
[out] Pointer to flags indicating whether the input or output data object is required. DXINOUTF_OPTIONAL (a value of 1) indicates the input or output data object is not required. NULL (a value of 0) indicates the input or output data object is required.

pIDs
[out] Optional pointer to an array of globally unique identifiers (GUIDs) that is filled in by the transform. This specifies the desired data format (usually IIDs) in preferred order.

pcIDs
[in, out] Pointer to the length of the pIDs array on entry and the number of returned GUIDs on exit. If the pIDs parameter is NULL, nothing is returned.

ppUnkCurrentObject
[out] Optional address of a pointer to the IUnknown interface on the input or output object being enumerated.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. This method returns S_FALSE if the transform doesn't support the requested input or output value.

Remarks

This method enables you to determine the number and types of input and output for a transform from the the transform itself. For any data objects currently associated with an input or output, you can also request a pointer to that object. This is optional, and can be NULL if the transform was not previously set up.

IDXTransform::GetMiscFlags

IDXTransform Interface

Retrieves flags that describe the behavior of the transform.

Syntax

HRESULT GetMiscFlags(
    DWORD *pdwMiscFlags
);

Parameters

pdwMiscFlags
[out] Pointer to flags which can be any combination of values in the DXTMISCFLAGS enumeration.

Return Value

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

Remarks

The constructor of the transform sets the transform flags to indicate the transform's behavior. You need to use GetMiscFlags to find out what the transform's flags are before using IDXTransform::SetMiscFlags to change the flags. Note that you can only change the DXTMF_BLEND_WITH_OUTPUT and DXTMF_DITHER_OUTPUT flags. The remaining flags are inherent properties of the transform and cannot be changed by IDXTransform::SetMiscFlags.
If the DXTMF_BOUNDS_SUPPORTED flag is set, you can specify a DXBNDS structure in the IDXTransform::Execute method. If the DXTMF_PLACEMENT_SUPPORTED flag is set, you can specify a DXVEC structure in IDXTransform::Execute. If either of these flags is not set, then the transform expects you to specify a corresponding NULL in place of the parameter. Failing to do this will cause an error in the call to the Execute method.

IDXTransform::GetQuality

IDXTransform Interface

Retrieves the quality level used to render the transform result.

Syntax

HRESULT GetQuality(
    float fQuality
);

Parameters

fQuality
[out] Number from 0 to 1 that specifies the quality level.

Return Value

Returns one of the following HRESULT values.

S_OK Success.

E_POINTER Bad pointer for fQuality.

E_NOTIMPL The transform does not support a quality level.

Remarks

The Quality property is often used to specify the rendering quality of the transform result. However, not all transforms support this property. For more information on its role in DirectX Transform, see the Author's Guide.

IDXTransform::MapBoundsIn2Out

IDXTransform Interface

Maps the input coordinate space to the output coordinate space.

Syntax

HRESULT MapBoundsIn2Out(
    DXBNDS *pInBounds,
    ULONG ulNumInBnds,
    ULONG ulOutIndex,
    DXBNDS *pOutBounds
);

Parameters

pInBounds

[in] Pointer to an array of DXBNDS input bounds structures to map. If NULL, the currently defined bounds of the inputs are used.

ulNumInBnds

[in] Number of structures pointed to by the pInBounds parameter.

ulOutIndex

[in] Index of the output coordinate space in which to store the result. This is usually index zero, because most transforms have only one output.

pOutBounds

[out] Pointer to the resulting output bounds.

Return Value

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

Remarks

This method returns the bounds of the object that will be produced if the IDXTransform::Execute method is called, based on the current property settings.
Note that if the transform doesn't use the extent of one or more of the inputs in calculating the extent of the output, it can simply ignore them. The caller of the method will typically provide these extents.
When you have more than one output, you need to specify which output space should correspond to the result. If there is only one output, the dwOutIndex value should be zero.

IDXTransform::MapBoundsOut2In

IDXTransform Interface

Maps the output coordinate space to the input coordinate space.

Syntax

HRESULT MapBoundsOut2In(
    ULONG ulOutIndex,
    DXBNDS *pOutBounds,
    ULONG ulInIndex,
    DXBNDS *pInBounds
);

Parameters

ulOutIndex

[in] Index of the output referred to by pOutBounds. This is usually index zero, because most transforms have only one output.

pOutBounds

[in] Pointer to the DXBNDS output bounds to be mapped.

ulInIndex

[in] Index of the input referred to by pInBounds.

pInBounds

[out] Pointer to the resulting input bounds.

Return Value

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

Remarks

This method returns the output bounds of the object that will be produced if the IDXTransform::Execute method is called, based on the current property settings.

IDXTransform::SetMiscFlags

IDXTransform Interface

Sets transform flags that specify how to generate the output.

Syntax

HRESULT SetMiscFlags(
    DWORD dwMiscFlags
);

Parameters

dwMiscFlags

[in] Value or combination of values from the DXTMISCFLAGS enumeration that specifies how the transform generates output. You can specify one or both of the following values.

DXTMF_BLEND_WITH_OUTPUT

The transform will perform a composite over the output surface when writing the result.

DXTMF_DITHER_OUTPUT

The transform will perform a dither of its result into the output surface.

Return Value

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

Remarks

Setting the DXTMF_BLEND_WITH_OUTPUT flag causes the transform to composite the result over the output surface samples. This reduces memory swapping that occurs if the result sample actually replaces the sample in the output buffer.
The constructor of the transform sets the transform flags, depending on the kind of transform. You need to use the IDXTransform::GetMiscFlags method to find out what the transform's flags are before using SetMiscFlags to change the flags. Note that you can only change the DXTMF_BLEND_WITH_OUTPUT and DXTMF_DITHER_OUTPUT flags. The remaining flags are inherent properties of the transform and cannot be changed by IDXTransform::SetMiscFlags.
If the DXTMF_BOUNDS_SUPPORTED flag is set, you can specify a DXBNDS structure in the IDXTransform::Execute method. If the DXTMF_PLACEMENT_SUPPORTED flag is set, you can specify a DXVEC structure in IDXTransform::Execute. If either of these flags is not set, then the transform expects you to specify a corresponding NULL in place of the parameter. Failing to do this will cause an error in the call to the Execute method.
The constructor sets the DXTMF_BLEND_WITH_OUTPUT flag by default. You can reset this flag.

IDXTransform::SetQuality

IDXTransform Interface

Sets the quality level used to render the transform result.

Syntax

HRESULT SetQuality(
    float fQuality
);

Parameters

fQuality
[in] Number from 0 to 1 that specifies the quality level.

Return Value

Returns one of the following HRESULT values.

S_OK Success.

E_INVALIDARG The fQuality parameter is not between 0 and 1.

E_NOTIMPL The transform does not support a quality level.

Remarks

The Quality property is often used to specify the rendering quality of the transform result. However, not all transforms support this property. For more discussion on the role of this property, see the Author's Guide.

IDXTransform::Setup

IDXTransform Interface

Defines the input and output data objects used in the transform.

Syntax

HRESULT Setup(
	IUnknown * const *punkInputs,
	ULONG ulNumInputs,
	IUnknown * const *punkOutputs,
	ULONG ulNumOutputs,
	DWORD dwFlags
);

Parameters

punkInputs: [in] Pointer to an array of one or more data objects to be used for input.
ulNumInputs: [in] Number of data object interface pointers in the input array.
punkOutputs: [in] Pointer to an array of one or more data objects where data will be written.
ulNumOutputs: [in] Number of data object interface pointers in the output array.
dwFlags: [in] Reserved.

Return Value

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

Remarks

This method is used to perform a required, one-time setup before the Execute method is used. The correct number of input and output data objects depends on the implementation of the transform. Transitions are usually one-in/one-out objects, whereas procedural objects have no inputs.
If you use this method, you should try to optimize your code for subsequent calls to Setup. For example, if a transform is passed a new DXSurface, but the height, width, and pixel format have not changed, it might not be necessary to execute all portions of the Setup method again. For examples of how to optimize multiple calls to Setup, see the sample code for the Wipe and Ripple transforms.
To clear a transform, you should use Setup with the dwFlags parameter equal to zero and the number of inputs and outputs equal to zero. This is also referred to as an unsetup. If the punkInputs and the punkOutputs parameters are NULL, and it is a quick setup, the current input and output objects are released. If the transform is used again on data of the same type, you must use Setup again for the transform.
The IDXTransformFactory::InitializeTransform method also uses the Setup method.

Execute	Executes the transform operation given the specified portion bounds and places the result in the destination data object.
GetInOutInfo	Retrieves input or output information about the specified data object, and an optional pointer to it.
GetMiscFlags	Retrieves flags that describe the behavior of the transform.
GetQuality	Retrieves the quality level used to render the transform result.
MapBoundsIn2Out	Maps the input coordinate space to the output coordinate space.
MapBoundsOut2In	Maps the output coordinate space to the input coordinate space.
SetMiscFlags	Sets transform flags that specify how to generate the output.
SetQuality	Sets the quality level used to render the transform result.
Setup	Defines the input and output data objects used in the transform.

S_OK	Success.
E_POINTER	Bad pointer for fQuality.
E_NOTIMPL	The transform does not support a quality level.

S_OK	Success.
E_INVALIDARG	The fQuality parameter is not between 0 and 1.
E_NOTIMPL	The transform does not support a quality level.