XAudio2CreateVolumeMeter function (xaudio2fx.h)

Creates a new volume meter audio processing object (APO) and returns a pointer to it.

Syntax

HRESULT XAudio2CreateVolumeMeter(
  IUnknown     **ppApo,
  UINT32 Flags DEFAULT
);

Parameters

ppApo

Contains the created volume meter APO.

DEFAULT

Flags that specify the behavior of the APO. The value of this parameter must be 0.

Return value

If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

For information on creating new effects for use with XAudio2, see the XAPO Overview.

Windows
Because XAudio2CreateVolumeMeter calls CoCreateInstance on Windows, the application must have called the CoInitializeEx method before calling XAudio2CreateVolumeMeter. XAudio2Create has the same requirement, which means CoInitializeEx typically will be called long before XAudio2CreateVolumeMeter is called.

A typical calling pattern on Windows would be as follows:

#ifndef _XBOX
CoInitializeEx(NULL, COINIT_MULTITHREADED);
#endif
IXAudio2* pXAudio2 = NULL;
HRESULT hr;
if ( FAILED(hr = XAudio2Create( &pXAudio2, 0, XAUDIO2_DEFAULT_PROCESSOR ) ) )
    return hr;
...
IUnknown * pVolumeMeterAPO;
XAudio2CreateVolumeMeter(&pVolumeMeterAPO);

 

The xaudio2fx.h header defines the AudioVolumeMeter class GUID as a cross-platform audio processing object (XAPO).

class __declspec(uuid("4FC3B166-972A-40CF-BC37-7DB03DB2FBA3")) AudioVolumeMeter;

XAudio2CreateVolumeMeter returns this object as a pointer to a pointer to IUnknown in the ppApo parameter. Although you can query the IXAPO and IXAPOParameters interfaces from this IUnknown, you typically never use these interfaces directly. Instead, you use them when you create a voice to add them as part of the effects chain.

The volume meter uses the XAUDIO2FX_VOLUMEMETER_LEVELS parameter structure that you access via the IXAudio2Voice::GetEffectParameters method when the XAPO is bound to the audio graph.

Note  XAudio2CreateVolumeMeter is an inline function in xaudio2fx.h that calls CreateAudioVolumeMeter:

XAUDIO2FX_STDAPI CreateAudioVolumeMeter(_Outptr_ IUnknown** ppApo);
__inline HRESULT XAudio2CreateVolumeMeter(_Outptr_ IUnknown** ppApo, UINT32 /*Flags*/ DEFAULT(0))
{
    return CreateAudioVolumeMeter(ppApo);
}
 

Platform Requirements

Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)

Requirements

   
Target Platform Windows
Header xaudio2fx.h
Library Xaudio2.lib

See also

How to: Create an Effect Chain

IXAudio2Voice::SetEffectParameters

XAUDIO2FX_VOLUMEMETER_LEVELS

XAudio2 Functions