 Important: |
|---|
| This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. |
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::EnumSurfacesto 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
IDirectDrawSurface5interface, 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 IDirectDrawSurface5::GetAttachedSurfaceand IDirectDrawSurface5::AddAttachedSurfacemethods increment reference counts of surfaces, and IDirectDrawSurface5::DeleteAttachedSurfacedecrements 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 Surfacesfor 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 IDirectDrawSurface5::SetClipperand IDirectDrawSurface5::SetPalettemethods 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 IDirectDrawSurface5::GetClipperand IDirectDrawSurface5::GetPalettemethods 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 themthe objects that the interfaces represent won't disappear so long as the surface they are attached to still holds a reference to them.
Last updated on Tuesday, May 18, 2004