IDXBaseObject Interface

The IDXBaseObject interface is used to manage the generation ID of an object. Every time an operation changes the state of an object, the generation ID is incremented. The following are examples of operations that change the generation IDs of objects.

Locking a surface with a read/write pointer.
Setting up a transform.
Changing the properties of a transform.
Changing the properties of a procedural surface.

When calling the IDXBaseObject::GetGenerationId method for a transform, the transform examines the generation IDs of all inputs. If they have changed, the transform's generation ID changes. If the ID has not changed since the last time a transform was executed or a surface was used, this indicates that the data has not changed. It may then be possible to skip execution of a transform Setup or the copying of a surface.

The IDXBaseObject interface is exposed on DXSurface objects and DXTransform objects.

IDXBaseObject Methods

GetGenerationId Retrieves the current generation ID for the surface.

GetObjectSize Retrieves the size, in bytes, of the data object (for example, a surface or buffer).

IncrementGenerationId Increments the surface generation ID manually.

IDXBaseObject::GetGenerationId

IDXBaseObject Interface

Retrieves the current generation ID for the object.

Syntax

HRESULT GetGenerationId(
    ULONG *pID
);

Parameters

pID
[out] Pointer to the location to store the generation ID.

Return Value

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

Remarks

Calling methods can use the generation ID to determine whether cached parameters are still valid. Transforms will examine all input generation IDs during this call. If any have changed, they will increment their own generation ID and cache the input's new generation ID.

IDXBaseObject::GetObjectSize

IDXBaseObject Interface

Retrieves the size, in bytes, of the data object (for example, a surface or buffer).

Syntax

HRESULT GetObjectSize(
    ULONG *pcbSize
);

Parameters

pcbSize
[out] Pointer to the location to store the object size, in bytes.

Return Value

Always returns S_OK.

Remarks

If the value returned to pcbSize is zero, the actual size of the object is indeterminate.

IDXBaseObject::IncrementGenerationId

IDXBaseObject Interface

Manually increments the object generation ID.

Syntax

HRESULT IncrementGenerationId(
    BOOL bRefresh
);

Parameters

bRefresh
[in] Boolean value indicating whether the object should refresh its data. If this value is FALSE, the generation ID number in the object is incremented and no further processing occurs. If the value is TRUE, the object should discard any cached information about other objects it holds references to and refresh the information as necessary. In the case of a DXSurface object, this causes it to discard its palette and run information and to re-examine the color key, pixel format, and height and width. In the case of a DXTransform object, this will force the transform to perform a new Setup operation using the current inputs and outputs, which will force the transform to re-examine the objects.

Return Value

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

Remarks

Objects that support IDXBaseObject are responsible for automatically incrementing their generation ID whenever they change state, so this method is rarely needed.
In some cases, clients might want to simply change the ID of an object to force a re-evaluation of an object. For example, if the contents of a window are lost, the client could increment the generation ID of a transform to force it to be executed again when the window is repainted. In this case, the caller would always specify a bRefresh value of FALSE.
In other cases, objects hold references to data that can be modified without the knowledge of the containing object. For example, if the client calls the IDXSurface::GetDirectDrawSurface method on a DXSurface and then modifies the DirectDrawSurface in some way (modifies the pixels, attaches a palette, sets a new color key, and so on), you should call IncrementGenerationId(TRUE) on the DXSurface to force it to re-examine the DirectDrawSurface. Transforms can cache information about the bounds and sample formats of input surfaces. If you change the bounds of a procedural surface, for example, you would need to refresh the transform object.

GetGenerationId	Retrieves the current generation ID for the surface.
GetObjectSize	Retrieves the size, in bytes, of the data object (for example, a surface or buffer).
IncrementGenerationId	Increments the surface generation ID manually.