> ## 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.

# SetShapeDmaNumFrames

> SetShapeDmaNumFrames

# SetShapeDmaNumFrames

Sets the number of Direct Memory Access (DMA) frames.

## Syntax

```cpp theme={null}
HRESULT SetShapeDmaNumFrames(  
         SHAPE_DMA_CONTEXT* context,  
         UINT32 numFrames  
)  
```

### Parameters

*context*   \_Inout\_\
Type: [SHAPE\_DMA\_CONTEXT\*](/reference/audio/shapedmacontext/structs/shape_dma_context)

Pointer to a [SHAPE\_DMA\_CONTEXT](/reference/audio/shapedmacontext/structs/shape_dma_context) structure.

*numFrames*   \
Type: UINT32

Number of frames.

### Return value

Type: HRESULT

HRESULT success or error code.

## Remarks

You can prevent blocked DMA commands by ensuring that your audio buffer is sufficiently large and that data is streamed at regular intervals (related to the buffer size). For example, if you are streaming four hardware frames at a time, ensure that some multiple of those frames (at least double-buffered at eight frames) are in the buffer so the hardware can write ahead of the title's read pointer. Alternatively, you could enforce emptying of the buffer before submitting the next flowgraph (consume, update DMA read pointer, and then submit the flowgraph). For more details, see [Blocked commands](/build/console-features/audio/overviews/shape-overview#ID4EBGAC) in [Overview of SHAPE](/build/console-features/audio/overviews/shape-overview).

The Direct Memory Access (DMA) system supports read and write functionality with automatic float-to-integer and integer-to-float conversion. The DMA system uses circular buffers containing de-interleaved samples in 128-sample blocks.

The DMA processor allows the Scalable Hardware Audio Processing Engine (SHAPE) to send data from mix buffers to main system memory and retrieve data from main system into the mix buffers for further processing. DMA is done on a block basis, transferring one audio frame of data at a time. To facilitate block-interleaved data, a skip value specifies the number of audio frame blocks in system memory to skip (from the base address) when reading or writing samples. Multichannel streams therefore require one DMA context per channel.

Audio data samples are always read and written as 32-bit values, either integer or float, as specified in the `floatConvert` flag of the [SHAPE\_DMA\_CONTEXT](/reference/audio/shapedmacontext/structs/shape_dma_context) structure. Note that the direction of the DMA (read or write) is specified in the DMA command, not in the DMA context. This helps reduce the amount of data bandwidth. The DMA engine has no signal processing, but can perform float-to-integer conversion (or integer-to-float). This allows the application CPU to process data samples in floating-point format.

To calculate the size of a DMA buffer, use the following formula:

```cpp theme={null}
fullBufferSizeInBytes = 128 * 4 * numChannels * numFrames  
```

The read and write pointers are incremented as follows:

```cpp theme={null}
readPointer = (readPointer + 1) % numFrames 

writePointer = (writePointer + 1) % numFrames  
```

Addresses within the audio buffer are calculated as follows:

```cpp theme={null}
readAddress = audioBuffer + (128 * 4 * ((readPointer * numChannels) + channel))   

writeAddress = audioBuffer + (128 * 4 * ((writePointer * numChannels) + channel))  
```

## Requirements

**Header:** shapedmacontext.h

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

## See also

[ShapeDmaContext](/reference/audio/shapedmacontext/shapedmacontext_members)


## Related topics

- [ShapeDmaContext](/reference/audio/shapedmacontext/shapedmacontext_members.md)
- [SetShapeDmaNumChannels](/reference/audio/shapedmacontext/functions/setshapedmanumchannels.md)
- [GetShapeDmaNumFrames](/reference/audio/shapedmacontext/functions/getshapedmanumframes.md)
- [SHAPE_DMA_CONTEXT](/reference/audio/shapedmacontext/structs/shape_dma_context.md)
- [GetShapeDmaNumChannels](/reference/audio/shapedmacontext/functions/getshapedmanumchannels.md)