Edit

Share via

XAudio2CreateVolumeMeter function (xaudio2fx.h)

  • Article

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

Syntax

HRESULT XAudio2CreateVolumeMeter(
  [in, out] IUnknown     **ppApo,
  [in]      UINT32 Flags DEFAULT
);

Parameters

[in, out] ppApo

Contains the created volume meter APO.

[in] 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: ``` syntax

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


</div>
<div> </div>
<h3><a id="Platform_Requirements"></a><a id="platform_requirements"></a><a id="PLATFORM_REQUIREMENTS"></a>Platform Requirements</h3>
Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)

## Requirements
| Requirement | Value |
| ---- |:---- |
| **Target Platform** | Windows |
| **Header** | xaudio2fx.h |
| **Library** | Xaudio2.lib |

## See also

<a href="/windows/desktop/xaudio2/how-to--create-an-effect-chain">How to: Create an Effect Chain</a>



<a href="/windows/desktop/api/xaudio2/nf-xaudio2-ixaudio2voice-seteffectparameters">IXAudio2Voice::SetEffectParameters</a>



<a href="/windows/desktop/api/xaudio2fx/ns-xaudio2fx-xaudio2fx_volumemeter_levels">XAUDIO2FX_VOLUMEMETER_LEVELS</a>



<a href="/windows/desktop/xaudio2/functions">XAudio2 Functions</a>