Microsoft DirectX 9.0 SDK Update (Summer 2004) |
Cache Management
When an object is cached, the same instance of the object is always returned by the IDirectMusicLoader8::GetObject method.
The cache stores a pointer to the object. The memory for the object itself is managed by COM, and is not released until the reference count reaches zero. It is important to remember that clearing an object from the cache is not the same as releasing your application's COM reference to it.
Caching is used extensively in the file-loading process to resolve links to objects. For example, two segments could reference the same
Here's another example. A band object relies on the loader to keep the General MIDI
By default, caching is enabled for all object classes. You can disable caching for an object class, or for all objects, by using the IDirectMusicLoader8::EnableCache method. This method can also be used to re-enable caching for any or all object classes.
If you want to clear the cache without disabling future caching, use the IDirectMusicLoader8::ClearCache method. It's not necessary to call this method before terminating your application, because the cache is automatically cleared when the loader is released. ClearCache is only useful if the application soundtrack is changing completely, with all new instruments and source files.
Note Regardless of whether caching is enabled, the loader keeps a private cache of object descriptors. When you load an object from a stream, a reference to the IStream is cached with the descriptor, and if that object is subsequently reloaded, it will be loaded from the same stream. When you load an object from a memory location, the address and buffer size are cached, and if the address is subsequently reused for another object, the incorrect number of bytes might be loaded. To ensure that the private cache of object descriptors is cleared, you can do one of the following:
- If caching is enabled, call ClearCache.
- If caching is not enabled, either destroy the loader and create a new one, or call IDirectMusicLoader8::SetSearchDirectory with the fClear parameter set to TRUE.
To cache a single object when general caching is disabled, pass it to the IDirectMusicLoader8::CacheObject method.
You can remove an object from the cache, ensuring that it will be loaded again on the next call to GetObject, by using the IDirectMusicLoader8::ReleaseObject or IDirectMusicLoader8::ReleaseObjectByUnknown method. It is a good idea to call one of these methods before calling Release on an object, especially a segment. If you don't, a reference to the object remains in the cache, so the object continues to exist. As well as taking up memory, the object might retain certain state information. In the case of a segment, any instance that you load later will be taken from the cache, and the start point and loop points will be the same as they were when the previous instance was destroyed.
See Also
© 2004 Microsoft Corporation. All rights reserved.