Using Audio Scripts

Scripts are collections of variables and routines authored in DirectMusic Producer. Although they consist mainly of text, scripts also contain a few binary parameters. For a conceptual overview, see Audio Scripts.

Load a script by using the IDirectMusicLoader8::GetObject method. Obtain the IDirectMusicScript8 interface, then call IDirectMusicScript8::Init to associate the script with a performance.

The following example function loads and initializes a script.

HRESULT LoadScript(IDirectMusicPerformance8 * pPerf, 
                                IDirectMusicLoader8* pLoader, 
                                WCHAR* wstrFileName,
                                IDirectMusicScript8** ppScript)
{
  DMUS_SCRIPT_ERRORINFO errInfo;
  HRESULT hr;
 
  if ((NULL == pPerf) || (NULL == pLoader))
  {
    return E_INVALIDARG;
  }
  if (SUCCEEDED(hr = pLoader->LoadObjectFromFile( 
    CLSID_DirectMusicScript, IID_IDirectMusicScript8,
    wstrFileName, (LPVOID*) ppScript)))
  {
    if (FAILED(hr = (*ppScript)->Init(pPerf, &errInfo)))
    {
      (*ppScript)->Release();
    }
  }
  return hr;
}

Apart from Init, the methods of IDirectMusicScript8 have three main purposes:

• Set and retrieve the value of variables declared in the script. Because script routines do not accept parameters, variables are the only way for the script and the application to exchange information.
• Call routines. A routine must finish executing before the application thread can continue.
• Enumerate routines and variables. These methods are of interest chiefly to script-editing applications.

All the methods of IDirectMusicScript8, except the enumeration methods, retrieve error information in a DMUS_SCRIPT_ERRORINFO structure. An error can occur if a variable is not found or code within a routine fails to execute.

Scripts can also be used without being directly loaded or called by the application. A segment authored in DirectMusic Producer can contain a script track that triggers calls to routines in one or more scripts.