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

# GetShapeDmaPeakMagnitude

> GetShapeDmaPeakMagnitude

# GetShapeDmaPeakMagnitude

获取峰值幅度。

## Syntax

```cpp theme={null}
float GetShapeDmaPeakMagnitude(  
         const SHAPE_DMA_CONTEXT* context  
)  
```

### Parameters

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

指向 [SHAPE\_DMA\_CONTEXT](/reference/audio/shapedmacontext/structs/shape_dma_context) 结构的指针。

### Return value

Type: float

峰值幅度。

## Remarks

在游戏的音频引擎中,管理动态余量可能非常困难。因此,每个 [SHAPE](/build/console-features/audio/overviews/shape-overview) 块都会维护与信号余量和增益相关的状态。除采样率转换器 (SRC) 块外,每个块都会记录处理期间是否发生了内部饱和。

除了内部饱和标志外,每个硬件块还维护两个 4 位数,用以表示该硬件块输出的幅度。幅度的计算方法是:确定该音频帧期间的峰值输出,然后对该峰值的绝对值进行前导零计数。其中一个 4 位数用于维护持久峰值幅度;另一个则由硬件在每个音频帧时重置。

除了监视每个单独硬件块的峰值幅度外,还会维护混合缓冲区的峰值幅度。当硬件块的输出被累加到混合缓冲区时,峰值幅度按同样方式计算(前导零计数)。每个硬件块的状态另外维护一对 4 位峰值幅度值。这些值表示该硬件块的输出被累加到混合缓冲区后,该混合缓冲区的峰值幅度。其中一个 4 位数表示持续、持久的峰值幅度;另一个每个音频帧都会更新。虽然实际上表示的是混合缓冲区状态,但这些峰值幅度值仍保存在 SHAPE 块的上下文中。

峰值幅度按下表进行编码。

| 二进制值            | 说明                                                                                                                                   |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| 0B0000          | 饱和:用于产生输出的计算值超出了 24 位有符号范围,已被替换为最接近的极值。具体来说,大于 8,388,607 (0x7F\_FFFF) 的值被替换为 8,388,607;小于 -8,388,608 (0x80\_0000) 的值被替换为 -8,388,608。 |
| 0B0001          | 峰值的绝对值大于 MAX >> 1 (0x3F\_FFFF)。                                                                                                      |
| 0B0010          | 峰值的绝对值大于 MAX >> 2 (0x1F\_FFFF)。                                                                                                      |
| 0B0011          | 峰值的绝对值大于 MAX >> 3。                                                                                                                   |
| 0B0100          | 峰值的绝对值大于 MAX >> 4。                                                                                                                   |
| 0B0101          | 峰值的绝对值大于 MAX >> 5。                                                                                                                   |
| 0B0110 到 0B1101 | 与上述说明类似,即峰值的绝对值大于 MAX >> 6 到 13 的情形。                                                                                                 |
| 0B1110          | 峰值的绝对值大于 MAX >> 14。                                                                                                                  |
| 0B1111          | 峰值的绝对值小于或等于 MAX >> 14。                                                                                                               |

除了细粒度增益设置外,为帮助管理余量并避免溢出和饱和,还可以在将硬件块的输出累加到输出混合缓冲区之前对其执行 0 到 7 位的右移。这在每个 SHAPE 硬件块的上下文中指定。

## Requirements

**头文件:** shapedmacontext.h

**支持的平台:** XBOX One 系列主机和 XBOX Series 主机

## See also

[SHAPE 概述](/build/console-features/audio/overviews/shape-overview)\
[ShapeDmaContext](/reference/audio/shapedmacontext/shapedmacontext_members)


## Related topics

- [ShapeDmaContext](/zh-CN/reference/audio/shapedmacontext/shapedmacontext_members.md)
- [GetShapeDmaMixBufferPeakMagnitude](/zh-CN/reference/audio/shapedmacontext/functions/getshapedmamixbufferpeakmagnitude.md)
- [GetShapeEqCompPeakMagnitude](/zh-CN/reference/audio/shapeeqcompcontext/functions/getshapeeqcomppeakmagnitude.md)
- [GetShapeFiltVolPeakMagnitude](/zh-CN/reference/audio/shapefiltvolcontext/functions/getshapefiltvolpeakmagnitude.md)
- [GetShapeEqCompMixBufferPeakMagnitude](/zh-CN/reference/audio/shapeeqcompcontext/functions/getshapeeqcompmixbufferpeakmagnitude.md)