> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AcpHalAllocateShapeContexts

> AcpHalAllocateShapeContexts

# AcpHalAllocateShapeContexts

Allocates context arrays for the Scalable Hardware Audio Processing Engine (SHAPE) and XBOX Media Audio (XMA).

## Syntax

```cpp theme={null}
HRESULT AcpHalAllocateShapeContexts(  
         SHAPE_CONTEXTS* contextArrays  
)  
```

### Parameters

*contextArrays*   \_Inout\_\
Type: [SHAPE\_CONTEXTS\*](/reference/audio/acphal/structs/shape_contexts)

On input, the context should contain the requested size of the context arrays. If the function succeeds, the context is populated with the allocated arrays. Refer to the [SHAPE\_DMA\_CONTEXT](/reference/audio/shapedmacontext/structs/shape_dma_context), [SHAPE\_EQCOMP\_CONTEXT](/reference/audio/shapeeqcompcontext/structs/shape_eqcomp_context), [SHAPE\_FILTVOL\_CONTEXT](/reference/audio/shapefiltvolcontext/structs/shape_filtvol_context), [SHAPE\_PCM\_CONTEXT](/reference/audio/shapepcmcontext/structs/shape_pcm_context), [SHAPE\_SRC\_CONTEXT](/reference/audio/shapesrccontext/structs/shape_src_context), and [SHAPE\_XMA\_CONTEXT](/reference/audio/shapexmacontext/structs/shape_xma_context) structures.

### Return value

Type: HRESULT

If the method succeeds, it returns `S_OK`. If the method fails, it returns one of the following codes (partial list):

| Return code                | Description                               |
| -------------------------- | ----------------------------------------- |
| E\_INVALIDARG              | One or more of the arguments are invalid. |
| E\_OUTOFMEMORY             | Memory allocation failed.                 |
| ACP\_E\_ALREADY\_ALLOCATED | The context arrays are already allocated. |

## Remarks

Call this method to allocate contexts for an Audio Control Processor (ACP) client before calling [AcpHalCreate](/reference/audio/acphal/functions/acphalcreate).

Unless there's a subsequent call to [AcpHalReleaseShapeContexts](/reference/audio/acphal/functions/acphalreleaseshapecontexts), this method should be called only once.

The number of Sample Rate Convertor (SRC) contexts must equal the sum of the number of pulse-code modulation (PCM) contexts and the number of XMA contexts.

## Requirements

**Header:** acphal.h

**Library:** acphal.lib

**Supported platforms:** XBOX One family consoles and XBOX Series consoles

## See also

[AcpHalReleaseShapeContexts](/reference/audio/acphal/functions/acphalreleaseshapecontexts)\
[AcpHalCreate](/reference/audio/acphal/functions/acphalcreate)\
[AcpHal](/reference/audio/acphal/acphal_members)


## Related topics

- [AcpHal](/reference/audio/acphal/acphal_members.md)
- [SHAPE_CONTEXTS](/reference/audio/acphal/structs/shape_contexts.md)
- [AcpHalReleaseShapeContexts](/reference/audio/acphal/functions/acphalreleaseshapecontexts.md)
- [AcpHalCreate](/reference/audio/acphal/functions/acphalcreate.md)
- [IAcpHal::Connect](/reference/audio/acphal/interfaces/IAcpHal/methods/iacphal_connect.md)