CDXBaseNTo1 Helper Functions
The CDXBaseNTo1 class helper functions are used for basic operations within transforms.
The most frequently used functions are those that retrieve pointers to the transform input and output surfaces. These functions include InputSurface, OutputSurface, InputMeshBuilder, and OutputMeshBuilder.
Many transforms use a value for the Progress property to determine its output for animation effects. This is usually set outside the transform by the IDXEffect::put_Progress method. The transform has access to that value through the GetEffectProgress helper function.
A transform is said to be dirty if any of its inputs or properties have changed. This terminology also applies to the transform inputs and output, which can change over time. If the transform is dirty, it should call the CDXBaseNTo1::OnSetup method, to reset itself and prepare for the next call to the IDXTransform::Execute method.
A number of other access functions determine if the transform output should be dithered or composited, and determine the pixel formats of the input and output surfaces.
CDXBaseNTo1 Helper Functions
ClearDirty Indicates to the transform that it is properly set up and ready to produce output. DoDither Determines whether the transform output should be dithered. DoOver Determines whether the transform output should be alpha blended over the output surface. GetEffectProgress Retrieves a value that indicates the current progress of the transform effect. GetNumInputs Retrieves the number of inputs used during the transform setup. HaveInput Tests whether an input data object is associated with the specified input index. HaveOutput Tests whether an output data object is associated with the transform. InputMeshBuilder Retrieves a pointer to a selected transform input mesh builder. InputSampleFormat Retrieves the pixel format type for the selected input surface. InputSurface Retrieves a pointer to the selected input surface. IsInputDirty Determines whether a transform input has changed since the last time this method was called. IsOutputDirty Determines whether an output has changed since the last time this method was called. IsTransformDirty Determines whether the the transform parameters or inputs have changed since the last time this method was called. NeedDestPMBuff Determines whether a temporary buffer is needed when calling a sample for surface read/write methods. NeedSrcPMBuff Determines whether a temporary buffer is needed when calling sample input methods on the IDXARGBReadPtr interface. OutputMeshBuilder Retrieves a pointer to the transform output mesh builder object. OutputSampleFormat Retrieves the pixel format type for the output surface. OutputSurface Retrieves a pointer to the output surface. SetDirty Increments the transform generation ID.
CDXBaseNTo1::ClearDirty
Indicates to the transform that it is properly set up and ready to produce output.
Syntax
void ClearDirty(void);
Return Value
No return value.
Remarks
Calling this function causes the IsTransformDirty method to return FALSE. This is commonly called at the end of OnSetup to indicate the transform is ready for a call to OnExecute.
CDXBaseNTo1::DoDither
Determines whether the transform output should be dithered.
Syntax
inline BOOL DoDither(void);
Return Value
Returns a Boolean value indicating whether to dither the output. If TRUE, the transform should dither its result to the output surface. If FALSE, it should write the new values unmodified.
Remarks
Transforms are expected to implement dithering in their output. This significantly improves the quality of results when rendering the output to low color-precision surfaces.
See Also
CDXBaseNTo1::DoOver
Determines whether the transform output should be alpha blended over the output surface.
Syntax
inline BOOL DoOver(void);
Return Value
Returns a Boolean value indicating how the transform output should be written on the destination surface. If TRUE, the transform output should be blended with the destination surface before writing to it. If FALSE, the output should be written directly to the destination surface, overwriting the current data.
Remarks
All transforms are expected to be able to blend their results with the output surface. This can provide significant performance increases by avoiding additional compositing steps.
See Also
DXOverArray, DXOverArrayMMX, IDXARGBReadPtr::OverArrayAndMove
CDXBaseNTo1::GetEffectProgress
Retrieves a value indicating the current progress of the transform effect.
Syntax
float GetEffectProgress(void);
Return Value
Returns a value from 0.0 to 1.0 for the transform Progress property.
Remarks
When an effect transform is executed, it should use this value to control the effect's progress. This is typically only useful if your transform produces a transition effect. You can ignore this value if your transform is not a time-varying effect.
See Also
CDXBaseNTo1::GetNumInputs
Retrieves the number of inputs used during the transform setup.
Syntax
ULONG GetNumInputs(void);
Return Value
Returns the number of transform inputs currently defined.
Remarks
Input indices referencing optional inputs can be NULL. You can test that an index has an associated surface with the HaveInput method.
See Also
CDXBaseNTo1::HaveInput
Tests whether an input data object is associated with the specified input index.
Syntax
BOOL HaveInput( ULONG i = 0 );
Parameters
- i
- [in] Index of the input to check.
Return Value
Returns a Boolean value that indicates whether a transform input has been defined. For multiple inputs, you can check each input by calling this function with the index of the input as the parameter.
See Also
CDXBaseNTo1::HaveOutput
Tests whether an output data object is associated with the transform.
Syntax
BOOL HaveOutput(void);
Return Value
Returns a Boolean value that indicates whether a transform output has been defined.
See Also
CDXBaseNTo1::InputMeshBuilder
Retrieves a pointer to a selected transform input mesh builder.
Syntax
IDirect3DRMMeshBuilder3 *InputMeshBuilder(
ULONG i = 0
);
Parameters
- i
- [in] Index of the requested input mesh.
Return Value
Returns a pointer to an IDirect3DRMMeshBuilder3 interface for the transform input.
Remarks
This function is useful for referencing input meshes within transform .dll routines.
See Also
CDXBaseNTo1::InputSampleFormat
Retrieves the pixel format type for the selected input surface.
Syntax
DXSAMPLEFORMATENUM InputSampleFormat(
ULONG i = 0
);
Parameters
- i
- [in] Index of the requested input surface (for transforms with multiple inputs).
Return Value
Returns a value from the DXSAMPLEFORMATENUM enumeration that represents the pixel format of the selected DXSurface.
CDXBaseNTo1::InputSurface
Retrieves a pointer to the selected input surface.
Syntax
IDXSurface * InputSurface(
ULONG i = 0
);
Parameters
- i
- [in] Index of the requested input surface (for transforms with multiple inputs).
Return Value
Returns a pointer to a surface that is the input for the transform.
See Also
CDXBaseNTo1::IsInputDirty
Determines whether a transform input has changed since the last time this method was called.
Syntax
bool IsInputDirty( ULONG i = 0 );
Parameters
- i
- [in] Index of the requested input surface (for transforms with multiple inputs).
Return Value
Returns a Boolean value that is TRUE if the specified transform input has changed since the last time this method was called, or FALSE otherwise.
See Also
CDXBaseNTo1::HaveInput, CDXBaseNTo1::InputSurface, CDXBaseNTo1::IsOutputDirty
CDXBaseNTo1::IsOutputDirty
Determines whether an output has changed since the last time this method was called.
Syntax
bool IsOutputDirty(void);
Return Value
Returns a Boolean value that is TRUE if the specified output has changed since the last time this method was called, or FALSE otherwise.
See Also
CDXBaseNTo1::HaveOutput, CDXBaseNTo1::OutputSurface, CDXBaseNTo1::IsInputDirty
CDXBaseNTo1::IsTransformDirty
Determines whether the the transform parameters or inputs have changed since the last time this method was called.
Syntax
BOOL IsTransformDirty(void);
Return Value
Returns a Boolean value that is TRUE if the transform generation ID has changed since the last time this method was called, or FALSE otherwise.
Remarks
If the transform inputs have changed or if the transforms properties have changed, the transform generation ID will be incremented and this method will return TRUE.
See Also
CDXBaseNTo1::ClearDirty, CDXBaseNTo1::IsInputDirty, CDXBaseNTo1::IsOutputDirty
CDXBaseNTo1::NeedDestPMBuff
Determines whether a temporary buffer is needed when calling a sample for surface read/write methods.
Syntax
BOOL NeedDestPMBuff(void);
Return Value
Returns TRUE to indicate that you need to allocate a sample buffer for surface read/write methods when using the IDXARGBReadWritePtr interface.
Remarks
If the native pixel format of your transform is PMARGB32, you will call methods such as IDXARGBReadWritePtr::PackPremultAndMove to write sample data. If the format of the output surface does not match, a temporary buffer is required by the output methods. The NeedDestPMBuff method tests for this condition and informs you if a buffer will need to be allocated or not.
See Also
CDXBaseNTo1::NeedSrcPMBuff
Determines whether a temporary buffer is needed when calling sample input methods on the IDXARGBReadPtr interface.
Syntax
BOOL NeedSrcPMBuff(
ULONG i = 0
);
Parameters
- i
- [in] Index of the specified input surface.
Return Value
Returns TRUE to indicate that you need to allocate a sample buffer for surface read methods.
Remarks
If the native pixel format of your transform is PMARGB32, you will call methods such as IDXARGBReadPtr::UnpackPremult to read sample data. If the format of the input surface does not match, a temporary buffer is required by the input methods. The NeedSrcPMBuff method tests for this condition and lets the implementer know if a buffer will need to be allocated or not.
See Also
CDXBaseNTo1::OutputMeshBuilder
Retrieves a pointer to the transform output Mesh Builder object.
Syntax
IDirect3DRMMeshBuilder3 *OutputMeshBuilder(void);
Return Value
Returns a pointer to an IDirect3DRMMeshBuilder3 interface for the transform output.
See Also
CDXBaseNTo1::OutputSampleFormat
Retrieves the pixel format type of the output surface.
Syntax
DXSAMPLEFORMATENUM OutputSampleFormat(void);
Return Value
Returns a value from the DXSAMPLEFORMATENUM enumeration that represents the pixel format of the output surface.
See Also
CDXBaseNTo1::OutputSurface
Retrieves a pointer to the output surface.
Syntax
IDXSurface *OutputSurface(void);
Return Value
Returns a pointer to a surface that is the output for the transform.
See Also
CDXBaseNTo1::SetDirty
Increments the transform generation ID.
Syntax
void SetDirty(void);
Return Value
No return value.
Remarks
This method causes the IsTransformDirty method to return TRUE the next time it is called. The method should be called after any aspect of the transform has changed that will affect the output result, such as when an input changes or a transform property changes.
You do not have to worry about tracking input changes unless you are caching a copy of the input. However, you must call this method after any of its properties change. If this method is not called, the transform's generation ID will not be incremented and the container will fail to use the Execute method on the transform because it will not think it needs to do so.
See Also
Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.