When Reference Counts will Change (Windows Embedded CE 6.0)

1/6/2010

There are several DirectDraw methods that affect the reference count of a surface, and a few that affect other objects you can associate with a surface. You can think of these situations as surface-only changes and cross-object changes.

  • Surface-only changes
    Surface-only changes, as the name states, only affect the reference count of a surface object.

    For example, you might use the IDirectDraw::EnumSurfaces to enumerate the current surfaces that fit a particular description. When the method invokes the callback function that you provide, it passes a pointer to an IDirectDrawSurface interface, but it increments the reference count for the object before your application receives the pointer.

    It is your responsibility to release the object when you are finished with it. This will typically be at the end of your callback routine, or later if you choose to keep the object.

    Most other surface-only changes affect the reference counts of complex surfaces, such as a flipping chain. Reference counts are a little more tricky for complex surfaces, because (in most cases) DirectDraw treats a complex surface as if it was a single object, even though it is a set of surfaces.

  • Cross-object changes
    Cross-object reference count changes occur when you create an association between a surface and another object that performs a task for the surface, such as a clipper.

    The IDirectDrawSurface::SetClipper method increments the reference count of the object being attached. After they are attached, the surface manages them; if the surface is released, it automatically releases any objects it is using.

    (For this reason, some applications release the interface for the object after these calls succeed. This is a perfectly valid practice.)

    Once a clipper is attached to a surface, you can call the IDirectDrawSurface::GetClipper method to retrieve them again.

    Because these methods return a copy of an interface pointer, they implicitly increment the reference count for the object being retrieved.

    When you are done with the interfaces, do not forget to release them — the objects that the interfaces represent will not disappear so long as the surface they are attached to still holds a reference to them.

See Also

Concepts

COM Reference Count Semantics for Surfaces