XAudio2Create

Creates a new XAudio2 object and returns a pointer to its IXAudio2 interface.

Syntax

XAUDIO2_STDAPI XAudio2Create(
         IXAudio2 **ppXAudio2,
         UINT32 Flags = 0,
         XAUDIO2_PROCESSOR XAudio2Processor = XAUDIO2_DEFAULT_PROCESSOR,
         SHARED_SHAPE_CONTEXTS *pSharedShapeContexts = nullptr
)  

Parameters

ppXAudio2
Type: IXAudio2 **

[out] If the operation is successful, returns a pointer to an IXAudio2 object.

Flags
Type: UINT32 

Flags that specify the behavior of the IXAudio2 object. See Remarks for more details.

XAudio2Processor
Type: XAUDIO2_PROCESSOR 

One define from the following table.

Specifying a processor should generally be avoided because it can interfere with the scheduler’s ability to schedule threads effectively across processors. Instead, pass the XAUDIO2_DEFAULT_PROCESSOR value.

pSharedShapeContexts
Type: SHARED_SHAPE_CONTEXTS *

[in] Pointer to SHARED_SHAPE_CONTEXTS. This parameter is Xbox One specific, and allows a title to share SHAPE and XMA resources with XAudio2 (see Remarks). The default is NULL.

Return value

Type: XAUDIO2_STDAPI 

Returns S_OK if successful, an error code otherwise. See XAudio2 Error Codes for descriptions of XAudio2 specific error codes.

Remarks

If you create an XAudio2 instance in a title for the Game OS, whether you intend to render XMA voices or not, by default, 512 XMA contexts are allocated. This will cause any other SHAPE context allocations to fail. This is by design as the most common scenario for XAudio2 in the Game OS is for XMA voice playback.

If you do not want XAudio2 to use any XMA/SHAPE resources, pass the flag XAUDIO2_DO_NOT_USE_SHAPE to XAudio2Create. This will prevent XAudio2 from allocating any SHAPE/XMA resources. All XMA voice allocations will fail with this flag set.

If you want to share SHAPE/XMA resources with XAudio2, you need to allocate the SHAPE/XMA contexts before creating XAudio2 with a call to AcpHalAllocateShapeContexts, then pass an appropriately initialized SHARED_SHAPE_CONTEXTS structure to XAudio2Create. This will allow you to specify how many of each context type XAudio2 can use exclusively, or share with other AcpHal clients.

If you create multiple instances of XAudio2 with the default creation parameters, they will all share the same SHAPE context pool.

If you want to create multiple instances of XAudio2 but only have one of these instances use SHAPE/XMA, pass the flag XAUDIO2_DO_NOT_SHARE_SHAPE_CONTEXTS to XAudio2Create.

If you want to define unique allocations of SHAPE/XMA contexts for XAudio2 you need to allocate the contexts before creating the XAudio2 instances with a call to AcpHalAllocateShapeContexts, and then pass appropriately initialized SHARED_SHAPE_CONTEXTS structures to each instance when you create them.

Important Do not use the seventh processing core (logical core 6) for XAudio2 thread affinity assignment. Because the seventh core’s time is governed by the hypervisor, the audio renderer might not receive enough time to complete processing for a frame, which can cause audio glitches.

Note that the flag XAUDIO2_VOICE_USE_SHAPE (defined in xaudio2.h) has no effect.

Game chat creates an instance of XAudio2 with the XAUDIO2_DO_NOT_USE_SHAPE flag set to prevent it from allocating and using SHAPE/XMA resources.

Requirements

Header: Declared in xaudio2.h.

Library: Use xaudio2.lib.