CDXBaseNTo1 Virtual Functions

This section contains reference material for the CDXBaseNTo1 virtual functions that you can override to add functionality to your transform. At a minimum, you will need to override the OnExecute or WorkProc methods, so that your transform can generate its output from the inputs defined by the IDXTransform::Setup method.

For an overview of the role of these virtual functions in your transform, see How to Use the CDXBaseNTo1 Base Class.

Member Functions

DetermineBnds (2-D) Called by the base class to determine the output bounds of 2-D transforms.

DetermineBnds (3-D) Called by the base class to determine the output bounds of 3-D transforms.

OnExecute Called by the base class to cause a transform to produce its output.

OnFreeInstData Frees resources allocated by the OnInitInstData function.

OnGetObjectSize Called by the base class to determine the amount of data space currently occupied by the transform.

OnGetSurfacePickOrder Provides the base class with the necessary information to perform surface picking for the transform.

OnInitInstData Enables the transform to allocate resources or compute data that is to be shared across threads.

OnReleaseObjects Called to release resources when the transform is being set up with NULL inputs or outputs.

OnSetup Called after the base class has completed its setup.

OnSurfacePick Called by the base class to enable the derived transform to fully implement surface picking.

OnUpdateGenerationId Called by the base class to check the input and output data object generation IDs and increment the transform generation ID.

WorkProc Called in a response to the IDXTransform::Execute method to render a portion of the output space to the current output surface.

CDXBaseNTo1::DetermineBnds (2-D)

CDXBaseNTo1 Class

Called by the base class to determine the output bounds of 2-D transforms.

Syntax

virtual HRESULT DetermineBnds(
	CDXDBnds &Bnds
);

Parameters

Bnds
[in, out] On input, Bnds is equal to the union of the input bounds. On output, the derived method should return the size of the transform's output space.

Return Value

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

Remarks

If the transform does not alter the dimensions of the input to produce the output, the derived class doesn't need to override this method.

See Also

IDXSurface::GetBounds

CDXBaseNTo1::DetermineBnds (3-D)

CDXBaseNTo1 Class

Called by the base class to determine the output bounds of 3-D transforms.

Syntax

virtual HRESULT DetermineBnds(
	CDXCBnds &Bnds
);

Parameters

Bnds
[in, out] On input, Bnds is equal to the union of the input bounds. On output, the derived method should return the size of the transform's output space.

Return Value

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

Remarks

A simple implementation for 3-D transforms is to call the Microsoft® Direct3D® Retained Mode IDirect3DRMMeshBuilder3::GetBox method on the output mesh builder. Some transforms might be able to do this more efficiently than going through all the work to compute the result depending on the type of effect. For example, if a transform simply scales a mesh, it could compute the resulting bounds based on the input bounds, which are invariant, and the current scale factor. If the transform does not alter the dimensions of the input to produce the output, the derived class doesn't need to override this method.

CDXBaseNTo1::OnExecute

CDXBaseNTo1 Class

Called by the base class to cause a transform to produce its output.

Syntax

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

Parameters

pRequestID
[in] Pointer to the ID passed into the IDXTransform::Execute method by the caller. This ID should be passed to the task manager if OnExecute schedules any asynchronous work through the task manager. Otherwise, this parameter should be ignored.

pPortionBnds
[in] Pointer to the portion of the transform output space that should be rendered. If NULL, the entire output space is rendered. If a transform can't produce the specified region of the result, the transform should mask off the DXTMF_BOUNDS_SUPPORTED flag from the m_dwMiscFlags data member in the Active Template Library (ATL) CComObjectRootEx::FinalConstruct constructor method. Image transforms must be able to render regions of their output. Typically, 3-D transforms do not because Direct3D Retained Mode does not provide a convenient way to do this.

pPlacement
[in] Pointer to the position to place the result in the output coordinate space. If the transform does not support this capability, it should mask off the DXTMF_PLACEMENT_SUPPORTED flag from the m_dwMiscFlags data member in the FinalConstruct constructor method.

Return Value

Returns S_OK or an implementation-dependent error code.

Remarks

Typically, only 3-D transforms override this function. It can also be called for 2-D transforms if the m_ulMaxImageBands data member is set to zero in the FinalConstruct constructor method.

See Also

IDXTaskManager::ScheduleTasks

CDXBaseNTo1::OnFreeInstData

CDXBaseNTo1 Class

Frees resources allocated by the OnInitInstData method.

Syntax

virtual HRESULT OnFreeInstData(
	CDXTWorkInfoNTo1 &WorkInfo
);

Parameters

WorkInfo
[in] Reference to the work procedure information structure.

Return Value

Returns S_OK or an implementation-specific error code.

Remarks

This function will be called once for each call to IDXTransform::Execute.

CDXBaseNTo1::OnGetObjectSize

CDXBaseNTo1 Class

Called by the base class to determine the amount of data space currently occupied by the transform.

Syntax

virtual ULONG OnGetObjectSize(void);

Return Value

Returns the size of the object and its currently allocated resources, in bytes.

Remarks

The transform user can use this information to optimize memory usage in the system.

CDXBaseNTo1::OnGetSurfacePickOrder

CDXBaseNTo1 Class

Provides the base class with the necessary information to perform surface picking for the transform.

Syntax

virtual void OnGetSurfacePickOrder(
	const CDXDBnds &OutPoint,
	ULONG &ulInToTest,
	ULONG aInIndex[],
	BYTE aWeight[]
);

Parameters

OutPoint
[in] Coordinates indicating the point in the transform output space to use for surface picking.

ulInToTest
[out] Number of inputs to be tested by the transform.

aInIndex[]
[out] Array of input surface indices to test, in top to bottom order. The number of elements in the array is equal to m_ulMaxInputs. Any input whose bounds intersect OutPoint should be added to the list.

aWeight[]
[out] Overall weight that should be attributed to each input listed by aInIndex. The number of elements in the array is equal to m_ulMaxInputs. The weight of an input will be used in conjunction with the alpha weight of the corresponding hit pixel on the input. These weights are typically computed based on the progress of the current effect. For example, an alpha fade transition at 40 percent progress might attribute 60 percent of the result to input Image A, and 40 percent to input Image B. The weight values would be 153 and 102, respectively.

Return Value

No return value.

Remarks

This function is intended to simplify the picking implementation for the majority of surface transforms. The information passed back to the base class will be used to lock down the appropriate input surfaces in order, retrieve the correct sample, weight it based on the current effect progress, and return the correct pick information to the container. The base class will map the OutPoint to the input space coordinates by using the IDXTransform::MapBoundsOut2In method after this function returns. If the transform has multiple inputs whose coordinate spaces are not aligned at zero, the CDXBaseNTo1::OnSurfacePick function should be overridden instead.

CDXBaseNTo1::OnInitInstData

CDXBaseNTo1 Class

Enables the transform to allocate resources or compute any data that is to be shared across threads.

Syntax

virtual HRESULT OnInitInstData(
	CDXTWorkInfoNTo1 &WorkInfo,
	ULONG &ulNumBandsToDo
);

Parameters

WorkInfo
[in] CDXTWorkInfoNTo1 object that contains all the information needed by the work procedure to perform the rendering request.

ulNumBandsToDo
[in] Number of threads to use for the rendering request. The default is equal to the number of processors in the system. Ignore this parameter for optimal default behavior.

Return Value

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

Remarks

If the transform does not set the m_ulMaxImageBands data member, or if it sets it to a value greater than one, this function should be used for one-time initialization. Each thread will then execute a portion of the render request on each of the available processors. When all the bands have completed, the OnFreeInstData function is called to allow for any necessary cleanup.

See Also

CDXBaseNTo1::WorkProc

CDXBaseNTo1::OnReleaseObjects

CDXBaseNTo1 Class

Called to release resources when the transform is being set up with NULL inputs or outputs.

Syntax

virtual void OnReleaseObjects(void);

Return Value

No return value.

Remarks

Override this method to be notified when the transform is being set up with NULL inputs or outputs. This enables you to free memory allocated by transform from previous calls to the IDXTransform::Setup method.

CDXBaseNTo1::OnSetup

CDXBaseNTo1 Class

Called after the base class has completed its setup.

Syntax

virtual HRESULT OnSetup(
	DWORD  dwFlags
);

Parameters

dwFlags
[in] Flags that are passed in by the container through the IDXTransform::Setup method.

Return Value

Returns S_OK if successful, or an implementation-specific error code on failure. This value will be passed back to the transform user as the HRESULT return value for IDXTransform::Setup.

Remarks

The transform might need to override this function to obtain information about the input and output data objects if the transform needs that information to generate the output.

CDXBaseNTo1::OnSurfacePick

CDXBaseNTo1 Class

Called by the base class to enable the derived transform to fully implement surface picking.

Syntax

virtual HRESULT OnSurfacePick(
	const CDXDBnds &OutPoint,
	ULONG &ulInputIndex,
	CDXDVec &InVec
);

Parameters

OutPoint
[in] Coordinates of the point in the transform output space to use for surface picking.

ulInputIndex
[out] Index of the input that was hit.

InVec
[out] Point on the input that was hit, in terms of the input coordinate space.

Return Value

Returns one of the following HRESULT values.

S_FALSE No inputs were at the indicated OutPoint. Hitting a sample with an alpha value of zero is considered a miss.

S_OK One of the inputs was chosen, so the returned information is valid.
DXT_S_HITOUTPUT The output surface was hit at the indicated pPoint, but it was not one of the input surfaces. Procedural surfaces, which have no input surface, can only return this value and not a surface index.

See Also

CDXBaseNTo1::OnGetSurfacePickOrder, IDXSurfacePick

CDXBaseNTo1::OnUpdateGenerationId

CDXBaseNTo1 Class

Called by the base class to check the input and output data object generation IDs and increment the transform generation ID.

Syntax

virtual void OnUpdateGenerationId(void);

Return Value

No return value.

Remarks

You only need to override this derived method if you are directly changing the generation of your transform. If not, reference counting is managed properly by the base class.

See Also

CDXBaseNTo1::IsInputDirty, CDXBaseNTo1::IsOutputDirty, CDXBaseNTo1::IsTransformDirty

CDXBaseNTo1::WorkProc

CDXBaseNTo1 Class

Called in a response to the IDXTransform::Execute method to render a portion of the output space to the current output surface.

Syntax

virtual HRESULT WorkProc(
	const CDXTWorkInfoNTo1 &WorkInfo,
	BOOL *pbContinueProcessing
);

Parameters

WorkInfo
[in] CDXTWorkInfoNTo1 object used to describe the rendering request.

pbContinueProcessing
[in] Pointer to a Boolean value that is managed externally by the IDXTaskManager interface to control execution of this function. At the start of the method, you should check this value to determine if execution is being prematurely canceled. If TRUE, the work procedure should clean up and exit immediately.

Return Value

Returns S_OK if succeeded, or an implementation-specific error code on failure.

Remarks

This function can be called simultaneously on multiple threads for a given data request. The base class can divide a data request into multiple pieces to be executed on all available processors. If this function is not reentrant, the m_ulMaxImageBands data member must be set to 1 in the FinalConstruct constructor method to assure that this function is called only once per execution request on a single thread. Because the work procedure must be able to render any region of the output space, parallelization on multiprocessor machines is automatic for to the developer, as long as the work procedure is reentrant.

DetermineBnds (2-D)	Called by the base class to determine the output bounds of 2-D transforms.
DetermineBnds (3-D)	Called by the base class to determine the output bounds of 3-D transforms.
OnExecute	Called by the base class to cause a transform to produce its output.
OnFreeInstData	Frees resources allocated by the OnInitInstData function.
OnGetObjectSize	Called by the base class to determine the amount of data space currently occupied by the transform.
OnGetSurfacePickOrder	Provides the base class with the necessary information to perform surface picking for the transform.
OnInitInstData	Enables the transform to allocate resources or compute data that is to be shared across threads.
OnReleaseObjects	Called to release resources when the transform is being set up with NULL inputs or outputs.
OnSetup	Called after the base class has completed its setup.
OnSurfacePick	Called by the base class to enable the derived transform to fully implement surface picking.
OnUpdateGenerationId	Called by the base class to check the input and output data object generation IDs and increment the transform generation ID.
WorkProc	Called in a response to the IDXTransform::Execute method to render a portion of the output space to the current output surface.

S_FALSE	No inputs were at the indicated OutPoint. Hitting a sample with an alpha value of zero is considered a miss.
S_OK	One of the inputs was chosen, so the returned information is valid.
DXT_S_HITOUTPUT	The output surface was hit at the indicated pPoint, but it was not one of the input surfaces. Procedural surfaces, which have no input surface, can only return this value and not a surface index.