XCEngine/docs/api/XCEngine/Audio/HRTF/HRTF.md

HRTF

命名空间: XCEngine::Audio

类型: class

头文件: XCEngine/Audio/HRTF.h

描述: 一个简化的双耳空间化处理器，根据声源与监听器相对方向对立体声样本做基础方位处理。

角色概述

HRTF 试图提供比简单左右声像更进一步的空间听感处理。它不是 IAudioEffect 派生类，而是一个独立的空间处理器，要求调用方显式传入：

• sourcePosition
• listenerPosition
• listenerRotation

从设计方向上，它对应的是商业引擎里空间化模块的雏形。

当前实现行为

1. 处理流程是“方向计算 + 简化双耳处理”

ProcessAudio() 当前会：

1. 根据源和监听器关系计算 azimuth / elevation
2. 计算 ITD 和 ILD
3. 如果开启 HRTF，则执行 ApplyHRTF()
4. 否则退回到 ApplySimplePanning()

2. 当前真正生效的是简化方向增益与延迟线

从源码看，当前 HRTF 路径主要依赖：

• 方位角带来的左右增益差
• 一个固定长度的左右延迟线
• interauralLevelDifference 对一侧增益的衰减

这使它更像“轻量双耳近似”，而不是完整的 HRTF 卷积系统。

3. 退化路径是简单声像

当 m_hrtfEnabled == false 时，会退化成简单左右声像分配。这提供了一个比完整 HRTF 更轻的回退模式。

当前参数里哪些真的生效

已确认直接影响处理的参数

• enabled
• hrtfEnabled
• speedOfSound
• qualityLevel 说明: 当前主要体现在参数保存与质量档位范围约束，不代表已经实现多档卷积质量策略。

当前主要是存值或接线不完整的参数

• crossFeed
• dopplerEnabled
• m_prevSourcePosition
• m_prevListenerPosition
• m_prevDopplerShift

这些字段和开关已经存在，但在当前处理路径里没有看到完整消费逻辑。

当前实现限制

• ComputePinnaEffect() 当前定义了但没有接入处理主路径。
• ComputeITD() 会计算 interauralTimeDelay，但 ApplyHRTF() 没有按该值动态调整读取偏移，延迟线处理仍然非常简化。
• dopplerEnabled 当前没有真正参与 Doppler 计算。
• 只对 channels >= 2 的输入做有意义处理。
• 没有看到该类型的直接单元测试。

设计理解

对当前版本最准确的理解方式是：它已经比单纯的 pan 多一步空间方向近似，但距离完整商用双耳空间化系统还有明显差距。文档因此不会把它写成“完整 HRTF 渲染器”。

相关方法

• Constructor
• Destructor
• ProcessAudio
• SetEnabled
• IsEnabled
• SetHRTFEnabled
• IsHRTFEnabled
• SetQualityLevel
• GetQualityLevel
• SetCrossFeed
• GetCrossFeed
• SetDopplerShiftEnabled
• IsDopplerShiftEnabled
• SetSpeedOfSound
• GetSpeedOfSound

相关文档

• 当前模块
• AudioListenerComponent
• AudioSourceComponent
• API 总索引