XAudio2CreateVolumeMeter

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

Syntax

HRESULT XAudio2CreateVolumeMeter(
         IUnknown **ppApo,
         UINT32 Flags
)  

Parameters

ppApo
Type: IUnknown **

[out] Contains the created volume meter APO.

Flags
Type: UINT32 

The value of this parameter must be 0.

Return value

Type: HRESULT 

See XAudio2 Error Codes for descriptions of XAudio2 specific error codes.

Remarks

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

Because XAudio2CreateVolumeMeter calls CoCreateInstance, 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.

#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 GetEffectParameters method when the XAPO is bound to the audio graph.

Note

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

C++C++ 

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

</td></tr>

</table>

For more information on volume metering, refer to the white paper:

• Xbox One Audio Mixing and Monitoring: Best Practices

Requirements

Header: Declared in xaudio2fx.h.

Library: Use xaudio2.lib.