CRIWARE Unity Plugin Manual  Last Updated: 2025-05-08
类 | Public 成员函数 | 所有成员列表
CriAtomEx3dSource类 参考
CRI Atom Native Wrapper

3D声源对象 更多...

继承自 CriDisposable .

类

struct  Config
 3D音源配置结构体 更多...
 

Public 成员函数

 CriAtomEx3dSource (bool enableVoicePriorityDecay=false, uint randomPositionListMaxLength=0)
 创建3D声源对象 更多...
 
override void Dispose ()
 丢弃3D声源对象 更多...
 
void Update ()
 更新3D声源 更多...
 
void ResetParameters ()
 3D声源参数初始化 更多...
 
void SetPosition (float x, float y, float z)
 设置3D声源位置 更多...
 
void SetVelocity (float x, float y, float z)
 设置3D声源速度 更多...
 
void SetOrientation (Vector3 front, Vector3 top)
 设置3D声源方向 更多...
 
void SetConeOrientation (float x, float y, float z)
 设置3D声源的声锥方向 更多...
 
void SetConeParameter (float insideAngle, float outsideAngle, float outsideVolume)
 设置3D声源的声锥参数 更多...
 
void SetMinMaxDistance (float minDistance, float maxDistance)
 设置3D声源最小距离／最大距离 更多...
 
void SetInteriorPanField (float sourceRadius, float interiorDistance)
 设置3D声源的内部Panning边界距离 更多...
 
void SetDopplerFactor (float dopplerFactor)
 设置3D声源的多普勒系数 更多...
 
void SetVolume (float volume)
 设置3D声源的音量 更多...
 
void SetMaxAngleAisacDelta (float maxDelta)
 设置角度AISAC控制器值的最大变化量 更多...
 
void SetAttenuationDistanceSetting (bool flag)
 设置距离衰减 更多...
 
bool GetAttenuationDistanceSetting ()
 设置获取距离衰减 更多...
 
void SetRandomPositionConfig (CriAtomEx.Randomize3dConfig?config)
 3D声源的位置随机化的设置 更多...
 
void SetRandomPositionList (Vector3[] positionList)
 3D声源位置随机化中的位置坐标列表设置 更多...
 
void Set3dRegion (CriAtomEx3dRegion region3d)
 设置3D区域 更多...
 
void SetListenerBasedElevationAngleAisacControlId (ushort aisacControlId)
 设置收听者基准仰俯角AISAC控制器ID 更多...
 
void SetSourceBasedElevationAngleAisacControlId (ushort aisacControlId)
 设置声源基准方位角AISAC控制器ID 更多...
 
void SetDistanceAisacControlId (ushort aisacControlId)
 设置距离AISAC控制器ID 更多...
 
bool IsDestroyable ()
 检查是否可以销毁3D声源 更多...
 
CriAtomEx.NativeVector GetPosition ()
 3D声源位置的获取 更多...
 

详细描述

3D声源对象

说明:
是用于操作3D声源的对象。
用于3D定位功能。

3D声源参数、位置信息设置等通过3D声源对象执行。

构造及析构函数说明

CriAtomEx3dSource ( bool  enableVoicePriorityDecay = false,
uint  randomPositionListMaxLength = 0 
)
inline

创建3D声源对象

参数
enableVoicePriorityDecay启用根据距离判断的Voice优先级衰减
randomPositionListMaxLength用于3D声源位置随机化的坐标列表的最大元素数
说明:
基于3D声源对象创建用配置，创建3D声源对象。
注意:
执行本函数前，需要事先对程序库进行初始化。

成员函数说明

override void Dispose ( )
inline

丢弃3D声源对象

说明:
丢弃3D声源对象。
一旦执行了本函数，创建3D声源对象时，在DLL内取得的资源将全部被释放。
如果有用设置了3D声源对象的AtomExPlayer播放的音频时， 在执行本函数前，请停止这些音频，或丢弃该AtomExPlayer。
void Update ( )
inline

更新3D声源

说明:
使用3D声源中设置的参数，更新3D声源。
本函数对3D声源中设置的所有参数进行更新。
建议用户可以在更改了多个参数后一起用本函数进行更新处理， 而不是在更改单个参数后每次都进行更新处理，可以提高效率。
注意:
本函数与AtomExPlayer的参数更新（ CriWare.CriAtomExPlayer::UpdateAll , CriAtomExPlayer::Update ） 是分开单独动作的。
如果更改了3D声源的参数，请用本函数进行更新处理。
例:

： // 音源の作成 CriAtomEx3dSource source = new CriAtomEx3dSource(); ： // 音源の位置を設定 source.SetPosition(0.0f, 0.0f, 1.0f);

// 音源の速度を設定 source.SetVelocity(1.0f, 0.0f, 0.0f);

// 注意）この時点では音源の位置や速度はまだ変更されていません。

// 変更の適用 source.Update(); ：

void ResetParameters ( )
inline

3D声源参数初始化

说明:
清除3D声源中设置的参数，恢复为初始值。
注意:
要实际适用已清除的参数时，需要调用 CriWare.CriAtomEx3dSource::Update 函数。
参见
CriAtomEx3dSource::Update
void SetPosition ( float  x,
float  y,
float  z 
)
inline

设置3D声源位置

参数
xX坐标
yY坐标
zZ坐标
说明:
设置3D声源位置。
位置用于距离衰减和定位计算。
位置以3维向量进行指定。
位置的单位是多少取决于3D收听者的距离计数 （通过 CriWare.CriAtomEx3dListener::SetDistanceFactor 函数进行设置）。
预设值是(0.0f, 0.0f, 0.0f)。
由于无法在数据侧设置位置，因此会始终使用本函数的设置值。
注意:
要实际适用所设置的参数时，需要调用 CriWare.CriAtomEx3dSource::Update 函数。
参见
CriAtomEx3dSource::Update
void SetVelocity ( float  x,
float  y,
float  z 
)
inline

设置3D声源速度

参数
xX轴方向的速度
yY轴方向的速度
zZ轴方向的速度
说明:
设置3D声源速度。
速度用于计算多普勒效应。
速度以3维向量进行指定。
速度的单位是每1秒的移动距离。
距离的单位是多少取决于3D收听者的距离计数 （通过 CriWare.CriAtomEx3dListener::SetDistanceFactor 函数进行设置）。 预设值是(0.0f, 0.0f, 0.0f)。
由于无法在数据侧设置速度，因此会始终使用本函数的设置值。
注意:
要实际适用所设置的参数时，需要调用 CriWare.CriAtomEx3dSource::Update 函数。
参见
CriAtomEx3dSource::Update
void SetOrientation ( Vector3  front,
Vector3  top 
)
inline

设置3D声源方向

参数
front前方向量
top上方向量
说明:
设置3D声源的方向。
通过此功能设置的方向设置音锥的方向。
音锥代表了从声源发出声音的方向，用于表现声音的方向性。
音锥的方向由3D向量指定。设置的方向向量会被归一化并在库内部使用。
由于无法在数据侧设置音锥的方向，因此始终使用此函数的设置值。
预设值如下。
  • 前方向量：（0.0f，0.0f，1.0f）
  • 上方向量：（0.0f，1.0f，0.0f）
备注:
如果设置音锥的方向，则忽略上方向量，仅使用前方向量。
另外，如果您使用Ambisonics播放，则Ambisonics将根据此功能指定的方向和收听者的方向旋转。
注意:
您必须调用 CriWare.CriAtomEx3dSource::Update 函数才能实际应用您设置的参数。
注意音锥不能应用于Ambisonics。
参见
CriAtomEx3dSource::SetConeParameter, CriAtomEx3dSource::Update
void SetConeOrientation ( float  x,
float  y,
float  z 
)
inline

设置3D声源的声锥方向

弃用:
削除予定の非推奨APIです。 CriWare.CriAtomEx3dSource.SetOrientation(Vector3, Vector3) の使用を検討してください。
参数
xX方向的值
yY方向的值
zZ方向的值
说明:
设置3D声源的声锥方向。
声锥表示声音从声源发生的方向，用于表现声音的方向性。
声锥方向以3维向量进行指定。
所设置的向量将会在程序库中经过标准化后进行使用。
预设值是(0.0f, 0.0f, -1.0f)。
由于无法在数据侧设置声锥方向，因此会始终使用本函数的设置值。
注意:
要实际适用所设置的参数时，需要调用 CriWare.CriAtomEx3dSource::Update 函数。
参见
CriAtomEx3dSource::SetConeParameter, CriAtomEx3dSource::Update
void SetConeParameter ( float  insideAngle,
float  outsideAngle,
float  outsideVolume 
)
inline

设置3D声源的声锥参数

参数
insideAngle声锥的内角
outsideAngle声锥的外角
outsideVolume声锥的外音量
说明:
设置3D声源的声锥参数。
声锥表示声音从声源发生的方向，用于表现声音的方向性。
声锥由内锥和外锥组成。内角表示内锥的角度， 外角表示外锥的角度，外音量表示外锥角度以上 方向的音量。
在比内锥角度更小的角度方向下，不会受到声锥的衰减。 在内锥和外锥之间的方向下，会逐渐衰减至外音量。
内角和外角以度来指定0.0f～360.0f。
外音量以对振幅的倍率来指定0.0f～1.0f（单位不是分贝）。
程序库初始化时的预设值如下，不会执行声锥衰减。
  • 内角：360.0f
  • 外角：360.0f
  • 外音量：0.0f
如数据侧设置了声锥参数，则调用本函数后，会如下进行适用。
  • 内角：加算
  • 外角：加算
  • 外音量：乘积 .
注意:
要实际适用所设置的参数时，需要调用 CriWare.CriAtomEx3dSource::Update 函数。
参见
CriAtomEx3dSource::Update
void SetMinMaxDistance ( float  minDistance,
float  maxDistance 
)
inline

设置3D声源最小距离／最大距离

参数
minDistance最小距离
maxDistance最大距离
说明:
设置3D声源最小距离／最大距离。
最小距离表示以上音量无法继续增加的距离。
最大距离表示达到最小音量的距离。
距离的单位是多少取决于3D收听者的距离计数 （通过 CriWare.CriAtomEx3dListener::SetDistanceFactor 函数进行设置）。
程序库初始化时的预设值如下。
  • 最小距离：0.0f
  • 最大距离：0.0f
如数据侧设置了最小距离／最大距离，则在调用本函数后， 将覆盖（忽略）数据侧的值并进行适用。
注意:
要实际适用所设置的参数时，需要调用 CriWare.CriAtomEx3dSource::Update 函数。
参见
CriAtomEx3dSource::Update
void SetInteriorPanField ( float  sourceRadius,
float  interiorDistance 
)
inline

设置3D声源的内部Panning边界距离

参数
sourceRadius3D声源的半径
interiorDistance内部距离
说明:
设置3D声源的内部Panning边界距离设置。
3D声源的半径是指以3D声源为球体时的半径。
内部距离是指适用内部Panning的3D声源的半径的距离。
在3D声源半径内，会适用内部Panning，但内部距离会作为0.0处理， 因此可以从所有扬声器以相同的音量播放音频。
在内部距离内，将会适用内部Panning。
在内部距离外，将不会适用内部Panning，将会从距离声源位置最近的一个， 或两个扬声器播放音频。
预设值是3D声源的半径 0.0f、内部距离 0.0f(取决于3D声源的最小距离)。
注意:
要实际适用所设置的参数时，需要调用 CriWare.CriAtomEx3dSource::Update 函数。
参见
CriAtomEx3dSource::Update, CriAtomEx3dSource::SetMinMaxDistance
void SetDopplerFactor ( float  dopplerFactor)
inline

设置3D声源的多普勒系数

参数
dopplerFactor多普勒系数
说明:
设置3D声源的多普勒系数。
多普勒系数是针对将音速作为340m/s计算所得的多普勒效应， 指定用于夸张表现的倍率。
例如，如果指定2.0f，则会在将音速作为340m/s计算所得的音高乘以2倍后进行适用。
如果指定0.0f，则多普勒效应更改为无效。
程序库初始化时的预设值是0.0f。
如数据侧设置了多普勒系数，则在调用本函数后， 将覆盖（忽略）数据侧的值并进行适用。
注意:
要实际适用所设置的参数时，需要调用 CriWare.CriAtomEx3dSource::Update 函数。
参见
CriAtomEx3dSource::Update
void SetVolume ( float  volume)
inline

设置3D声源的音量

参数
volume音量
说明:
设置3D声源的音量。
3D声源的音量仅会影响定位相关的音量（L,R,SL,SR）， 不会影响LFE或向中心的输出Level。
音量值是在0.0f～1.0f的范围内指定实数值。
音量值是针对音频数据的振幅的倍率（单位不是分贝）。
例如，指定为1.0f时，将按照原有的音量输出原音。
指定为0.5f时，将会以等同于原音波形一半振幅的音量（-6dB） 来输出音频。
指定为0.0f时，音频将被静音（更改为无音状态）。
程序库初始化时的预设值是1.0f。
如数据侧设置了3D声源的音量，则在调用本函数后， 将与数据侧的值进行乘积后进行适用。
注意:
要实际适用所设置的参数时，需要调用 CriWare.CriAtomEx3dSource::Update 函数。
参见
CriAtomEx3dSource::Update
void SetMaxAngleAisacDelta ( float  maxDelta)
inline

设置角度AISAC控制器值的最大变化量

参数
maxDelta角度AISAC控制器值的最大变化量
说明:
设置根据角度AISAC更改AISAC控制器值时的最大变化量。
如果将最大变化量设置为较低的值，即使在声源和收听者间的相对角度急剧变化时， 也能够让由角度AISAC引起的AISAC控制器值的变化变得平滑。
例如，设置为(0.5f / 30.0f)时，如果角度从0度变化为180度， 则会更改为乘以30帧的变化量。
预设值是1.0f（无限制）。
由于无法在数据侧设置本参数，因此会始终使用本函数的设置值。
注意:
要实际适用所设置的参数时， 需要调用 CriWare.CriAtomEx3dSource::Update 函数。
用本函数设置的最大变化量仅会适用于按照定位角度计算出的 角度AISAC控制器值的变化。定位角度本身不会受到影响。
参见
CriAtomEx3dSource::Update
void SetAttenuationDistanceSetting ( bool  flag)
inline

设置距离衰减

参数
flag是否将距离衰减设为有效(True: 有效，False: 无效)
说明:
设置是否将距离衰减的音量变动设为有效。
预设值是 True （有效）。
注意:
要实际适用所设置的参数时，需要调用 CriWare.CriAtomEx3dSource::Update 函数。
参见
CriAtomEx3dSource::Update, CriAtomEx3dSource::GetAttenuationDistanceSetting
bool GetAttenuationDistanceSetting ( )
inline

设置获取距离衰减

返回
距离衰减设置(True: 有效，False: 无效)
说明:
获取距离衰减的音量变动是否有效。
预设值是 True （有效）。
参见
CriAtomEx3dSource::SetAttenuationDistanceSetting
void SetRandomPositionConfig ( CriAtomEx.Randomize3dConfig?  config)
inline

3D声源的位置随机化的设置

参数
config用于随机化3D声源位置的配置结构体（可为空）
说明:
设置3D声源句柄的位置随机化。
执行此函数时，声音的位置会在播放时根据原始位置信息和设定值随机变化。
备注:
您可以通过为参数config指定null来取消设置。
注意:
您必须调用 CriWare.CriAtomEx3dSource::Update 函数才能实际应用您设置的参数。
此功能不会对正在播放的音频应用任何参数。
这些参数将应用于下一次播放的音频中。
参见
CriAtomEx::Randomize3dConfig
void SetRandomPositionList ( Vector3[]  positionList)
inline

3D声源位置随机化中的位置坐标列表设置

参数
positionList位置坐标列表
说明:
指定位置坐标列表的数组。
启用3D声源位置的随机化后，将从指定数组的坐标中随机确定坐标。
备注:
仅当设置 CriWare.CriAtomEx::Randomize3dCalcType::List 为位置坐标的计算方法时，才会引用该参数。
如果设置了其他计算方法，则该参数将被忽略。
注意:
您必须调用 CriWare.CriAtomEx3dSource::Update 函数才能实际应用您设置的参数。
CriWare.CriAtomEx3dSource::SetRandomPositionList 函数执行完成后，将不会从内部引用传参给此函数的内存空间，
而是将其保存在内部保留的位置坐标列表中。
因此，设置长度超过 CriWare.CriAtomEx3dSource::Config::randomPositionListMaxLength 的列表将导致错误。
参见
CriAtomEx::Randomize3dConfig, CriAtomEx3dSource::Config
void Set3dRegion ( CriAtomEx3dRegion  region3d)
inline

设置3D区域

说明:
针对3D声源，设置3D区域。
注意:
如果同一个ExPlayer中设置的3D声源和3D收听者设置的区域不同，
并且没有与3D声源相同区域设置的3D收发器时，音频会被静音。
要实际适用所设置的参数时，需要调用 CriWare.CriAtomEx3dSource::Update 函数。
参见
CriAtomEx3dRegion::Create, CriAtomEx3dSource::Update
void SetListenerBasedElevationAngleAisacControlId ( ushort  aisacControlId)
inline

设置收听者基准仰俯角AISAC控制器ID

参数
aisacControlId收听者基准仰俯角AISAC控制器ID
说明:
指定与从收听者看到的声源仰俯角联动的AISAC控制器ID。
通过本函数，数据侧设置的收听者基准仰俯角AISAC控制器ID将被覆盖并进行适用。。
注意:
要实际适用所设置的参数时，需要调用 CriWare.CriAtomEx3dSource::Update 函数。
参见
CriAtomEx3dSource::Update
void SetSourceBasedElevationAngleAisacControlId ( ushort  aisacControlId)
inline

设置声源基准方位角AISAC控制器ID

参数
aisacControlId声源基准方位角AISAC控制器ID
说明:
指定从声源一侧看到的收听者的方位角联动的AISAC控制器ID。
数据侧设置的声源基准方位角AISAC控制器ID将通过本函数被覆盖适用。
注意:
要实际适用所设置的参数时，需要调用 CriWare.CriAtomEx3dSource::Update 函数。
参见
CriAtomEx3dSource::Update
void SetDistanceAisacControlId ( ushort  aisacControlId)
inline

设置距离AISAC控制器ID

参数
aisacControlId声源基准方位角AISAC控制器ID
说明:
指定与最小距离和最大距离之间的距离衰减相关的AISAC控制器ID。
当本函数设置了AISAC控制器ID，预设的距离衰减就会被禁用。
在数据侧设置的距离AISAC控制器ID被本函数覆盖。
注意:
为了实际应用参数设置，需要调用 CriAtomEx3dSource.Update 函数。
执行本函数时，由于先前为3D声源设置的AISAC控制器ID值的变化而引起的参数变化将被禁用，
而先前应用于已经播放的音频的参数将继续被应用。
建议在指定3D声源相关的音频未被播放的状态下执行本函数。
参见
CriAtomEx3dSource::Update
bool IsDestroyable ( )
inline

检查是否可以销毁3D声源

返回
3D声源状态（true = 可以销毁、false = 不可销毁）
说明:
检查 3D Source 是否可以被销毁。
如果挂载了 3D Source 的 AtomExPlayer 上有音频在播放，调用Dispose函数将无法销毁它。
这种情况下，要销毁此3D Source，需要首先销毁所有挂载了此 3D Source 的 AtomExPlayer，或者对其设置另一个 3D Source 。
参见
Dispose, CriAtomExPlayer.Set3dSource
CriAtomEx.NativeVector GetPosition ( )
inline

3D声源位置的获取

说明:
获取3D声源的位置。
位置以3D向量形式获取。
该类的文档由以下文件生成: