本篇是创建游戏内核（20）的续篇，有关DirectAudio和DirectShow的基础知识请参阅用DirectX
Audio和DirectShow播放声音和音乐。
为了增强MUSIC_CHANNEL类的音乐回放特性，可以使用DLS类。
来看看类DLS的定义:
//======================================================================================
// This class encapsulates for downloadable sound.
//======================================================================================
typedef class DLS
{
public:
DLS();
~DLS();
IDirectMusicCollection8* get_dm_colletion();
BOOL create(SOUND_PTR sound);
BOOL load(const char* filename = NULL);
BOOL free();
long get_num_patches();
long get_patch(long index);
BOOL exists(long patch);
private:
SOUND_PTR _sound;
IDirectMusicCollection* _dm_collection;
} *DLS_PTR;
以及类DLS的实现：
//------------------------------------------------------------------------------
// Constructor, zero member data.
//------------------------------------------------------------------------------
DLS::DLS()
{
memset(this, 0, sizeof(*this));
}
//------------------------------------------------------------------------------
// Destructor, release DirectMusic resource.
//------------------------------------------------------------------------------
DLS::~DLS()
{
free();
}
//------------------------------------------------------------------------------
// Release DirectMusic collection object.
//------------------------------------------------------------------------------
BOOL DLS::free()
{
if(_sound == NULL || _sound->get_dm_loader() == NULL)
return FALSE;
if(_dm_collection)
{
if(FAILED(_sound->get_dm_loader()->ReleaseObjectByUnknown(_dm_collection)))
return FALSE;
}
release_com(_dm_collection);
return TRUE;
}
//------------------------------------------------------------------------------
// Create DLS object.
//------------------------------------------------------------------------------
BOOL DLS::create(SOUND_PTR sound)
{
free();
_sound = sound;
if(_sound == NULL || _sound->get_dm_loader() == NULL)
return FALSE;
return TRUE;
}
//------------------------------------------------------------------------------
// Load DirectMusic collection object from specified filename.
//------------------------------------------------------------------------------
BOOL DLS::load(const char* filename)
{
free();
if(_sound == NULL || _sound->get_dm_loader() == NULL)
return FALSE;
DMUS_OBJECTDESC object_desc;
ZeroMemory(&object_desc, sizeof(DMUS_OBJECTDESC));
object_desc.dwSize = sizeof(DMUS_OBJECTDESC);
object_desc.guidClass = CLSID_DirectMusicCollection;
if(filename == NULL)
{
// get the default collection
object_desc.guidObject = GUID_DefaultGMCollection;
object_desc.dwValidData = DMUS_OBJ_CLASS | DMUS_OBJ_OBJECT;
}
else
{
// get the colletion object
object_desc.dwValidData = DMUS_OBJ_CLASS | DMUS_OBJ_FILENAME | DMUS_OBJ_FULLPATH;
mbstowcs(object_desc.wszName, filename, MAX_PATH);
}
HRESULT rv = _sound->get_dm_loader()->GetObject(&object_desc,
IID_IDirectMusicCollection8, (LPVOID*)&_dm_collection);
if(rv != S_OK)
{
if(rv == DMUS_E_LOADER_FAILEDCREATE)
err_msg_box("The object could not be found or created.");
else if(rv == DMUS_E_LOADER_FAILEDOPEN)
err_msg_box("File open failed because the file does not exist or is locked.");
else if(rv == DMUS_E_LOADER_FORMATNOTSUPPORTED)
err_msg_box("The object cannot be loaded because the data format is not supported.");
else if(rv == DMUS_E_LOADER_NOCLASSID)
err_msg_box("No class identifier was supplied in the object description.");
else if(rv == E_FAIL)
err_msg_box("The method did not succeed.");
else if(rv == E_INVALIDARG)
err_msg_box("Invalid argument. Often, this error results from failing to initialize the dwSize member"
" of a structure before passing it to the method.");
else if(rv == E_OUTOFMEMORY)
err_msg_box("Insufficient memory to complete the task.");
else if(rv == E_POINTER)
err_msg_box("An invalid pointer, usually NULL, was passed as a parameter.");
else if(rv == REGDB_E_CLASSNOTREG)
err_msg_box("The object class is not registered.");
return FALSE;
}
return TRUE;
}
//------------------------------------------------------------------------------
// Return DirectMusic collection object.
//------------------------------------------------------------------------------
IDirectMusicCollection8* DLS::get_dm_colletion()
{
return _dm_collection;
}
//------------------------------------------------------------------------------
// Return number of patches in DirectMusic collection.
//------------------------------------------------------------------------------
long DLS::get_num_patches()
{
DWORD patch;
long index = 0;
// retrieves the patch number and name of an instrument by its index in the collection
while(_dm_collection->EnumInstrument(index, &patch, NULL, 0))
++index;
return index;
}
//------------------------------------------------------------------------------
// Return patch number by index of the instrument.
//------------------------------------------------------------------------------
long DLS::get_patch(long index)
{
DWORD patch;
if(_dm_collection == NULL)
return -1;
if(FAILED(_dm_collection->EnumInstrument(index, &patch, NULL, 0)))
return -1;
return (long) patch;
}
//------------------------------------------------------------------------------
// Judge whether specified patch exists.
//------------------------------------------------------------------------------
BOOL DLS::exists(long patch)
{
IDirectMusicInstrument8* dm_instrument;
if(_dm_collection == NULL)
return FALSE;
// retrieve an instrument by its patch number
if(FAILED(_dm_collection->GetInstrument(patch, &dm_instrument)))
return FALSE;
dm_instrument->Release();
return TRUE;
}
DLS类的惟一用途是包含单个DLS集。像MUSIC_CHANNEL类一样，也只能调用一次DLS::create函数，因为DLS::free函数只能释放一个已加载的DLS集。注意在DLS::load函数中，filename参数的缺省值为NULL，此缺省值指定了默认的DLS集。
调用DLS::get_num_patches函数可以得到类中所包含的乐器的数目。使用DLS::get_patch函数可以遍历每种乐器，得到它的音色（patch）数。使用DLS::exists函数可以检查在DLS集中是否存在某种特定的音色，如果此函数返回值为TRUE，就表示存在这种音色；否则表示不存在这种音色。
该类的实现可能并不完整，暂不提供测试代码。