IncrementGenerationId method

Manually increments the object generation ID.

Syntax

HRESULT retVal = object.IncrementGenerationId(bRefresh);

Parameters

  • bRefresh [in]
    Type: BOOL

    BOOL 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 that 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, height, and width. In the case of a IDXTransform object, this forces the transform to perform a new IDXTransform::Setup operation using the current inputs and outputs, which forces the transform to re-examine the objects.

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 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 always specifies 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 DirectDrawSurface 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 IDXBaseObject::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 need to refresh the transform object.

See also

IDXBaseObject::GetGenerationId