XAudio2CreateWithSharedContexts
Creates a new XAudio2 object and returns a pointer to its IXAudio2 interface.Syntax
Parameters
ppXAudio2 _Outptr_Type: IXAudio2** If the operation is successful, it returns a pointer to an IXAudio2 object. Flags _In_
Type: UINT32 Flags that specify the behavior of the IXAudio2 object.
XAudio2Processor _In_
Type: XAUDIO2_PROCESSOR An XAUDIO2_PROCESSOR type value that specifies which CPU to use. Passing XAUDIO2_USE_DEFAULT_PROCESSOR allows XAudio2 to choose the ideal processor at runtime. Specifying a processor might interfere with the scheduler’s ability to schedule threads effectively across processors. Instead, pass the XAUDIO2_USE_DEFAULT_PROCESSOR value. SharedShapeContexts _In_
Type: PXAUDIO2_SHARED_SHAPE_CONTEXTS Pointer to SHARED_SHAPE_CONTEXTS. This parameter is specific to XBOX One and allows a title to share SHAPE and XMA resources with XAudio2. The default is NULL.
Return value
Type: XAUDIO2_STDAPI If the function succeeds, it returnsS_OK. If one or more of the arguments are invalid, the function returns an error code.
Remarks
XAudio2CreateWithSharedContexts works the same way as the XAudio2Create function. It takes one extra parameter to allow state for the Scalable Hardware Audio Processing Engine (SHAPE) on XBOX One to be shared across multiple IXAudio2 instances. PXAUDIO2_SHARED_SHAPE_CONTEXTS is a pointer to the shared state. XAudio2 uses SHAPE contexts for XMA playback. As a feature, XMA was introduced with XBOX 360. If you use XAudio2 to play XMA audio in the XBOX 360 version of your game, or in an XBOX One game based on the older XBOX One Software Development Kit, it is essential to know that the Microsoft Game Development Kit (GDK) continues to support XMA and SHAPE contexts.
To play XMA-format audio, your app does not have to use the XAudio2CreateWithSharedContexts flag because the XAudio2 instance creates its own SHAPE contexts. XAudio2CreateWithSharedContexts is optimized for apps that have multiple XAudio2 instances. It allows the app to allocate a single set of SHAPE contexts and efficiently share them across instances.
The
XAudio2Processor parameter should use the XAUDIO2_USE_DEFAULT_PROCESSOR pointer to allow the system to make the appropriate processor selection, unless the app is designed to select a specific processor.XAudio2Create parameter and XAudio2CreateWithSharedContexts function use flags that are applicable to games that only play XMA format audio. An app fails to play XMA content if the XAUDIO2_DO_NOT_USE_SHAPE flag is used. With XBOX 360, XMA audio is decoded in the software or hardware, which requires SHAPE contexts. The new version of the Microsoft Game Development Kit (GDK) supports XMA decoding in hardware. Specifying this flag will effectively break the XMA playback.
If the function calls its own SHAPE contexts, it uses the XAUDIO2_DO_NOT_SHARE_SHAPE_CONTEXTS flag to specify that the SHAPE contexts are for exclusive use by this XAudio2 instance. It is not recommended to specify this flag when not providing SHAPE contexts (for example, by invoking XAudio2Create) because when XAudio2 creates its own SHAPE contexts, they are shared.
You can also use the flag XAUDIO2_EXCLUDE_FROM_GAME_DVR_CAPTURE. Setting this flag prevents the game DVR from recording the audio from the mastering voice.
The header also defines the AUDCLNT_STREAMFLAGS_EXCLUDE_FROM_GAME_DVR_CAPTURE flag. Pass this flag to IAudioClient::Initialize to disable the game DVR from recording audio played by that IAudioClient. If your game uses XAudio2, use the XAUDIO2_EXCLUDE_FROM_GAME_DVR_CAPTURE flag instead for this purpose.
For more information, see Getting started with XAudio2.
Requirements
Header: xaudio2Xbox.h Library: xaudio2.lib Supported platforms: XBOX One family consoles and XBOX Series consolesConceptual documentation
See also
Overview of XAudio2XAudio2 Key Concepts
xaudio2xbox