音频空间化器 SDK

音频空间化器 SDK 提供了控件来更改应用程序从音频源 将场景中的音频剪辑播放到音频监听器或通过混音器播放的组件。更多信息
请参阅术语表进入周围的空间。它是原生音频插件SDK的扩展。

音频源的内置平移是一种简单的空间化形式。它获取源并根据左右耳之间的距离和角度来调节左右耳贡献的增益音频监听器（Audio Listener） 一个组件，其作用类似于麦克风，从场景中的音频源接收声音并输出到计算机扬声器。更多信息
请参阅术语表和音频源。这为水平面上的玩家提供了简单的方向提示。

Unity Audio Spatializer SDK 和示例实现

为了提供对音频空间化工作的灵活性和支持，Unity 提供了一个开放的接口，即 Audio Spatializer SDK，作为 Native Audio Plugin SDK 之上的扩展。您可以将 Unity 中的标准平移器替换为更高级的平移器，并允许它访问有关计算所需的源和侦听器的重要元数据。

有关本机空间化器音频插件的示例，请参阅 Unity 本机音频插件 SDK。该插件仅支持直接的头部相关传递函数 （HRTF），仅用于示例目的。

您可以使用插件中包含的简单混响将音频数据从空间化器插件路由到混响插件。HRTF 过滤基于 KEMAR 数据集的修改版本。有关 KEMAR 数据集的更多信息，请参阅麻省理工学院媒体实验室的文档和测量文件。

如果您想探索从人类受试者获得的数据集，请参阅 IRCAM 的数据集。

初始化 Unity 音频空间设置器

Unity 在音频源解码音频数据后直接应用空间化效果。这将生成音频数据流，其中每个源都有自己单独的效果实例。Unity 仅处理来自该源的音频及其相应的效果实例。

要使插件能够作为空间化器运行，您需要在效果的描述位字段中设置一个标志：

definition.flags |= UnityAudioEffectDefinitionFlags_IsSpatializer;

如果您将UnityAudioEffectDefinitionFlags_IsSpatializer标志，Unity 会在插件扫描阶段将插件识别为空间化器。当 Unity 创建插件的实例时，它会分配UnityAudioSpatializerData结构spatializerdata成员UnityAudioEffectState结构。

要在项目中使用空间器，请在项目设置中选择它（菜单：编辑>项目设置>音频）：

然后，在检查器一个 Unity 窗口，显示有关当前选定游戏对象、资产或项目设置的信息，允许您检查和编辑值。更多信息
请参阅术语表窗口中，启用 Spatialize：

您还可以通过 C# 脚本启用音频源的空间化器，使用AudioSource.spatialize财产。

在具有大量声音的应用程序中，您可能只想在附近的声音上启用空间化器，并在远处的声音上使用传统的平移，以减少混合线程上空间化器效果的 CPU 负载。

如果您希望 Unity 将空间数据传递给非空间化器的混音器插件，您可以在描述位字段中使用以下标志：

definition.flags |= UnityAudioEffectDefinitionFlags_NeedsSpatializerData;

如果插件使用UnityAudioEffectDefinitionFlags_NeedsSpatializerData标志，插件接收UnityAudioSpatializerData结构，但只有listenermatrix字段有效。有关 UnityAudioSpatializerData 的详细信息，请参阅空间设置器效果元数据部分。

要阻止 Unity 代表空间化器插件应用距离衰减，请使用以下标志：

definition.flags |= UnityAudioEffectDefinitionFlags_AppliesDistanceAttenuation;

这UnityAudioEffectDefinitionFlags_AppliesDistanceAttenuation标志向 Unity 指示空间化器处理距离衰减的应用。有关距离衰减的更多信息，请参阅衰减曲线和可听性部分。

空间设置器效果元数据

与其他 Unity 不同音频效果可以修改混音器组件输出的任何效果，例如过滤声音的频率范围或应用混响。更多信息
请参阅术语表在混合声音上运行时，Unity 会在音频源解码音频数据后直接应用空间化器。空间化器效果的每个实例都有自己的实例UnityAudioSpatializerData，主要与有关音频源的数据相关联。

struct UnityAudioSpatializerData
{
    float listenermatrix[16];   // Matrix that transforms sourcepos into the local space of the listener
    float sourcematrix[16];     // Transform matrix of the Audio Source
    float spatialblend;         // Distance-controlled spatial blend
    float reverbzonemix;        // Reverb zone mix level parameter (and curve) on 
                                // the Audio Source
    float spread;               // Spread parameter of the Audio Source (0..360 degrees)
    float stereopan;            // Stereo panning parameter of the Audio Source (-1: fully left, 1: fully right)
                                // The spatializer plugin may override the distance attenuation to
                                // influence the voice prioritization (leave this callback as NULL 
                                // to use the built-in Audio Source attenuation curve)
    UnityAudioEffect_DistanceAttenuationCallback distanceattenuationcallback;
    float minDistance;          // The minimum distance of the Audio Source. 
                                // This value may be useful for determining when to apply near-field effects. 
    float maxDistance;          // The maximum distance of the Audio Source, or the 
                                // distance where the audio becomes inaudible to the listener. 
    
};

该结构包含与检查器中“音频源”组件的属性相对应的字段：“空间混合”、“混响区域混合”、“扩散”、“立体声声相”、“最小距离”和“最大距离”。

这UnityAudioSpatializerData结构包含音频监听器和音频源的完整 4x4 转换矩阵。侦听器矩阵是反转的，以便您可以将两个矩阵相乘以获得相对方向向量。侦听矩阵始终是正交矩阵，因此您可以快速计算逆矩阵。

Unity 的音频系统仅以立体声信号的形式提供原始源声音。即使源是单声道或多声道，信号也是立体声的，并且 Unity 根据需要使用上混或下混音。

矩阵约定

这sourcematrix字段包含音频源变换矩阵的副本。对于游戏对象Unity 场景中的基本对象，可以表示角色、道具、风景、相机、航路点等。游戏对象的功能由附加到它的组件定义。更多信息
请参阅术语表不旋转的矩阵，矩阵是一个平移矩阵，其中位置编码在元素 12、13 和 14 中。

这listenermatrix字段包含 AudioListener 的转换矩阵的倒数。

你可以确定从 AudioListener 到 音频源的方向向量，如下所示，其中 L 是listenermatrixS 是sourcematrix:

float dir_x = L[0] * S[12] + L[4] * S[13] + L[ 8] * S[14] + L[12];
float dir_y = L[1] * S[12] + L[5] * S[13] + L[ 9] * S[14] + L[13];
float dir_z = L[2] * S[12] + L[6] * S[13] + L[10] * S[14] + L[14];

（L[12]， L[13]， L[14]） 中的位置实际上是您在 Unity 的 Inspector 窗口中看到的负值相机在场景中创建特定视点图像的组件。输出要么绘制到屏幕上，要么作为纹理捕获。更多信息
请参阅术语表矩阵。如果摄像机也旋转了，您还必须先撤消旋转的效果。要反转变换-旋转矩阵，请转置 L 的左上角 3x3 旋转矩阵，并计算位置，如下所示：

float listenerpos_x = -(L[0] * L[12] + L[ 1] * L[13] + L[ 2] * L[14]);
float listenerpos_y = -(L[4] * L[12] + L[ 5] * L[13] + L[ 6] * L[14]);
float listenerpos_z = -(L[8] * L[12] + L[ 9] * L[13] + L[10] * L[14]);

有关音频空间器插件代码中的示例，请参阅Plugin_Spatializer.cpp文件中的第 215 行。

衰减曲线和可听性

除非您指定UnityAudioEffectDefinitionFlags_AppliesDistanceAttenuation标志，如初始化 Unity 音频空间化器部分中所述，Unity 音频系统仍控制距离衰减。Unity 在声音进入空间化阶段之前对声音应用距离衰减，并允许音频系统了解源的大致可听性。音频系统使用近似可听性来根据重要性动态虚拟声音，以匹配用户定义的最大真实声音限制。

Unity 不会从实际的信号电平测量中检索可听性信息，而是使用从距离控制的衰减曲线、Volume 属性和混音器应用的衰减中读取的值的组合。

你可以直接覆盖衰减曲线，也可以使用音频源曲线计算的值作为修改的基础。要覆盖或修改该值，请使用UnityAudioSpatializerData结构如下图所示：

typedef UNITY_AUDIODSP_RESULT (UNITY_AUDIODSP_CALLBACK* UnityAudioEffect_DistanceAttenuationCallback)(
    UnityAudioEffectState* state,
    float distanceIn,
    float attenuationIn,
    float* attenuationOut);

您还可以使用简单的自定义对数曲线，如下所示：

UNITY_AUDIODSP_RESULT UNITY_AUDIODSP_CALLBACK SimpleLogAttenuation(
    UnityAudioEffectState* state,
    float distanceIn,
    float attenuationIn,
    float* attenuationOut)
{
    const float rollOffScale = 1.0f; // Similar to the one in the Audio Project Settings
    *attenuationOut = 1.0f / max(1.0f, rollOffScale * distanceIn);
    return UNITY_AUDIODSP_OK;
}

使用 Unity API 中的 C# 脚本

音频源上有两种方法允许设置空间化器效果并从中获取参数：SetSpatializerFloat和GetSpatializerFloat.这些方法的工作方式类似于SetFloatParameter和GetFloatParameter通用原生音频插件接口中的方法。然而SetSpatializerFloat和GetSpatializerFloat为它们必须设置或读取的参数取索引，而SetFloatParameter和GetFloatParameter按名称引用参数。

布尔属性AudioSource.spatializer链接到 Unity 的 Inspector 窗口中音频源的 Spatialize 选项。该属性控制 Unity 如何根据音频中的所选插件实例化和解除分配空间化器效果项目设置广泛的设置集合，允许您配置物理、音频、网络、图形、输入和项目的许多其他区域的行为方式。更多信息
请参阅术语表.

如果空间化效果的实例化非常占用资源，则就项目中的内存或其他资源而言，从预设的“池”中分配空间化效果可能会很有效，这样 Unity 就不需要在每次需要使用它时都创建空间化器的新实例。如果您保持 Unity 插件界面绑定非常轻量级并动态分配音频效果，则可以避免项目中的丢帧或其他性能问题。

示例插件的已知限制

由于采用快速卷积算法，快速移动会导致一些拉链伪影，您可以通过使用重叠保存卷积或交叉淡入淡出缓冲区来消除这些伪影。

该代码也不支持倾斜侦听器的头部，无论侦听器是直接连接到玩家角色，还是位于其他地方的摄像机。