When Reference Counts will Change

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 IDirectDraw4::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 IDirectDrawSurface4 interface, but it increments the reference count for the object before your application receives the pointer. It's 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. In short, the IDirectDrawSurface4::GetAttachedSurface and IDirectDrawSurface4::AddAttachedSurface methods increment reference counts of surfaces, and IDirectDrawSurface4::DeleteAttachedSurface decrements the reference count. These methods don't affect the counts of any surfaces attached to the current surface. See the references for these methods and Reference Counts for Complex Surfaces for a additional details.

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 or a palette.

The IDirectDrawSurface4::SetClipper and IDirectDrawSurface4::SetPalette methods increment 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 or palette is attached to a surface, you can call the IDirectDrawSurface4::GetClipper and IDirectDrawSurface4::GetPalette methods 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're done with the interfaces, don't forget to release them—the objects that the interfaces represent won't disappear so long as the surface they are attached to still holds a reference to them.