FmodChannelControl#
继承： RefCounted < Object
Channel 和 ChannelGroup 的通用控制基类 （参见 FmodChannel ） （参见 FmodChannelGroup ）
FmodChannelControl 封装 FMOD::ChannelControl 的共享能力，为 FmodChannel 和 FmodChannelGroup 提供播放控制、音量、3D 空间化、声像矩阵、滤波、DSP 链和样本精确调度等功能。
描述#
FmodChannelControl 为 FmodChannel 和 FmodChannelGroup 提供播放、音量、空间化、DSP 链和调度操作。通过 FmodSystem 获取已绑定句柄的通道或组；直接实例化基类不会创建 FMOD 句柄。
属性#
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
方法#
信号#
callback_received(type: int)
收到 FMOD 回调时发出， type 表示回调事件类型。可连接此信号以接收播放结束等通道事件。
属性说明#
bool paused = true
为 true 时暂停通道播放。
float pitch = 1.0
相对音高和播放速率
float volume_db = 0.0
音量，单位为分贝
bool volume_ramp = false
音量变化是否使用平滑斜坡
bool mute = false
静音状态
PackedVector3Array 3d_custom_rolloff = PackedVector3Array()
void set_3d_custom_rolloff(3d_custom_rolloff: PackedVector3Array)
PackedVector3Array get_3d_custom_rolloff() const
自定义 3D 距离衰减曲线
自定义 3D 距离衰减曲线 （参见 PackedVector3Array ）
float 3d_doppler_level = 1.0
多普勒效果缩放量
float 3d_level = 1.0
Controls 3d level.
float 3d_min_distance = 1.0
3D 距离衰减的最小距离
float 3d_max_distance = 100000.0
3D 距离衰减的最大距离
float 3d_spread = 0.0
Controls 3d spread.
float gain = 1.0
内置低通/距离滤波使用的干信号增益
方法说明#
bool channel_control_is_valid() const
封装保存了非空 ChannelControl 指针时返回 true 。此方法不会验证底层句柄，也不会检查通道是否仍在播放。
bool channel_control_is_null() const
封装没有 ChannelControl 指针时返回 true 。已经停止的通道仍可能保存非空指针。
bool is_playing() const
返回该 Channel 或 ChannelGroup 当前是否正在播放。
void stop()
停止当前通道，或停止当前组及其嵌套组中的所有通道。停止后的 Channel 句柄失效；ChannelGroup 仍可用于后续播放。
void set_paused(paused: bool)
设置暂停状态。 true 会暂停播放， false 会恢复播放。
bool get_paused() const
返回当前暂停状态。
void set_mode(mode: FmodMode)
设置支持的播放模式标志，包括循环和 2D/3D 空间化。标志见 FmodSystem.FmodMode ；声音创建标志应在创建声音时传入。
FmodMode get_mode() const
返回当前播放模式标志。 （参见 FmodMode ）
void set_pitch(pitch: float)
设置相对音高和播放速率。 1.0 为原始音高， 2.0 为两倍速， 0.5 为半速。
1.0：正常播放速度小于 1.0：播放变慢、音高降低
大于 1.0：播放变快、音高升高
float get_pitch() const
返回当前相对音高和播放速率。
float get_audibility() const
返回综合音量、静音、3D 衰减和父级混音后的最终可听度。
void set_volume_db(volume: float)
设置音量，单位为分贝。
0.0 dB：单位增益，保持原音量负值：衰减，降低音量
正值：放大，提高音量
常用范围为 -80 dB 到 +24 dB。
float get_volume_db() const
返回当前音量，单位为分贝。
void set_volume_ramp(volume_ramp: bool)
设置音量变化是否使用 FMOD 的平滑斜坡。启用后可减少突然变更音量时的爆音。
bool get_volume_ramp() const
返回音量变化是否使用平滑斜坡。
void set_mute(mute: bool)
设置静音状态。
bool get_mute() const
返回当前静音状态。
void set_3d_attributes(pos: Vector3, vel: Vector3)
设置 3D 位置和速度，用于平移、距离衰减和多普勒计算。
pos：世界空间位置vel：用于计算多普勒效果的速度
Dictionary get_3d_attributes() const
返回 3D 属性字典，包含 pos 和 vel 。
pos：当前位置，类型为 Vector3vel：当前速度，类型为 Vector3
void set_3d_cone_orientation(orientation: Vector3)
设置 3D 声音锥体方向，用于方向性遮挡和衰减。
此向量应归一化，并指向音源朝向。
Vector3 get_3d_cone_orientation() const
返回当前 3D 声音锥体方向。
void set_3d_cone_settings(inside_cone_angle: float, outside_cone_angle: float, outside_volume_db: float)
设置方向性 3D 声音锥体的内角、外角和外部音量衰减。
inside_cone_angle：保持最大音量的锥角，单位为度，范围为 0 到 360outside_cone_angle：外部锥角，单位为度，范围为 0 到 360outside_volume_db：锥外音量，单位为 dB
Dictionary get_3d_cone_settings() const
返回锥体设置字典，包含 inside_cone_angle 、 outside_cone_angle 和 outside_volume_db 。
inside_cone_angle：内部锥角，单位为度outside_cone_angle：外部锥角，单位为度outside_volume_db：锥外音量，单位为 dB
void set_3d_custom_rolloff(3d_custom_rolloff: PackedVector3Array)
设置自定义 3D 距离衰减曲线。通常需要配合 FMOD_MODE_3D_CUSTOMROLLOFF 使用。
每个点使用 Vector3 表示，其中 x 为距离，y 为音量，z 不使用。
PackedVector3Array get_3d_custom_rolloff() const
返回当前自定义 3D 距离衰减曲线。
void set_3d_distance_filter(custom: bool, custom_level: float, center_freq: float)
设置 3D 距离滤波器覆盖值，用于随距离改变低通/高通滤波表现。
custom：是否启用自定义滤波设置custom_level：启用自定义设置时的滤波电平center_freq：距离滤波器的中心频率
Dictionary get_3d_distance_filter() const
返回距离滤波器设置字典，包含 custom 、 custom_level 和 center_freq 。
custom：是否已启用自定义滤波custom_level：自定义滤波电平center_freq：中心频率
void set_3d_doppler_level(level: float)
设置多普勒效果缩放量。该功能主要用于 Channel。
值越大，速度造成的音高变化越明显。
float get_3d_doppler_level() const
返回多普勒效果缩放量。
void set_3d_level(level: float)
设置 3D 平移与 2D 平移之间的混合比例。
0.0 表示完全使用 2D 声像，1.0 表示完全使用 3D 空间化。
float get_3d_level() const
返回 3D 平移与 2D 平移之间的混合比例。
void set_3d_min_distance(min_distance: float)
设置 3D 距离衰减开始前的最小距离。
该距离以内保持完整音量。
float get_3d_min_distance() const
返回 3D 距离衰减的最小距离。
void set_3d_max_distance(max_distance: float)
设置 3D 距离衰减的最大距离。
超过该距离后，音量保持在最低电平。
float get_3d_max_distance() const
返回 3D 距离衰减的最大距离。
void set_3d_occlusion(direct_occlusion: float, reverb_occlusion: float)
设置直接声和混响路径的遮挡衰减因子，范围通常为 0.0 到 1.0 。
direct_occlusion：0.0 为无遮挡，1.0 为完全遮挡reverb_occlusion：0.0 为无遮挡，1.0 为完全遮挡
Dictionary get_3d_occlusion() const
返回遮挡字典，包含 direct_occlusion 和 reverb_occlusion 。
direct_occlusion：直达声遮挡，范围为 0.0 到 1.0reverb_occlusion：混响声遮挡，范围为 0.0 到 1.0
void set_3d_spread(angle: float)
设置 3D 声音在扬声器空间中的扩散角度。
值越大，立体声声场中的声音越分散。
float get_3d_spread() const
返回 3D 声音扩散角度。
void set_pan(pan: float)
设置左右声像。 -1.0 为左， 0.0 为中间， 1.0 为右。
-1.0：完全偏左0.0：居中（默认值）1.0：完全偏右
中间值表示相应的中间声像位置。
void set_mix_levels_input(levels: PackedFloat32Array)
为多声道输入信号的每个输入通道设置电平。该功能主要用于 Channel。
用于逐声道控制音量。
void set_mix_levels_output(front_left: float, front_right: float, center: float, lfe: float, surround_left: float, surround_right: float, back_left: float, back_right: float)
为每个输出扬声器设置音量电平。
用于自定义路由到指定扬声器输出。
void set_mix_matrix(matrix: PackedFloat32Array, outchannels: int, inchannels: int, inchannel_hop: int = 0)
通道数必须在 1 到 32 之间。 inchannel_hop 必须为 0 ，或介于 inchannels 和 32 之间。输入必须包含所有有效元素，最后一行末尾可省略填充。无效尺寸、步长和过短数组会在调用 FMOD 前被拒绝。
设置自定义混音矩阵，将输入通道（列）映射到输出扬声器通道（行）。
矩阵按行优先顺序排列。 inchannel_hop 为 0 时，每行视为包含 inchannels 个元素。
Dictionary get_mix_matrix() const
返回当前混音矩阵字典，包含 matrix （矩阵数据）、 outchannels （输出声道数）、 inchannels （输入声道数）和 inchannel_hop （输入声道步长）。
void set_reverb_properties(instance: int, wet: float)
设置指定全局混响实例的发送电平。
float get_reverb_properties(instance: int) const
返回指定全局混响实例的发送电平。
void set_low_pass_gain(gain: float)
设置内置低通/距离滤波应用时干信号的增益。
float get_low_pass_gain() const
返回内置低通/距离滤波应用时干信号的增益。
void add_dsp(index: int, dsp: FmodDSP)
在 DSP 链指定索引处插入一个 DSP 单元。
void remove_dsp(dsp: FmodDSP)
从 DSP 链中移除指定 DSP 单元。
int get_num_dsps() const
返回 DSP 链中的 DSP 单元数量。
FmodDSP get_dsp(index: int) const
返回 DSP 链中指定索引处的 DSP 单元；索引无效时返回 null 。
void set_dsp_index(dsp: FmodDSP, index: int)
设置指定 DSP 单元在 DSP 链中的索引。
int get_dsp_index(dsp: FmodDSP) const
返回指定 DSP 单元在 DSP 链中的索引。
Dictionary get_dsp_clock() const
返回当前 DSP 时钟信息，通常包含当前时钟和父级时钟。 （参见 Dictionary ）
"dsp_lock"（int）：当前通道的 DSP 时钟。"parent_clock"（int）：父 ChannelGroup 的当前 DSP 时钟。
这些时钟值用于采样级精度的播放调度。
void set_delay(start: int, end: int, stop_channels: bool = true)
设置相对于父 ChannelGroup DSP 时钟的样本精确开始和停止时间。
start：开始播放时的 DSP 时钟值，0 表示立即播放。end：停止播放时的 DSP 时钟值，0 表示持续播放到手动停止。stop_channels：为true时，到达结束时间即停止通道。
Dictionary get_delay() const
返回样本精确延迟设置，包含开始、结束时钟和停止行为。 （参见 Dictionary ）
"start"（int）：开始播放时的 DSP 时钟值。"end"（int）：停止播放时的 DSP 时钟值。"stop_channels"（bool）：到达结束时间时是否停止通道。
void add_fade_point(dspclock: int, volume: float)
在指定 DSP 时钟处添加一个音量淡变点。
void set_fade_point_ramp(dspclock: int, volume: float)
添加从当前音量到指定 DSP 时钟音量的淡变斜坡。 （参见 add_fade_point() ）
void remove_fade_points(start: int, end: int)
移除两个 DSP 时钟值之间的所有淡变点。
Dictionary get_fade_points() const
返回包含 num_points （int）、 point_dspclocks （PackedInt64Array）和 point_volumes （PackedFloat32Array）的字典。两个数组的相同索引分别给出淡变点的时钟和线性音量；失败时返回空字典。
void set_callback()
安装封装的 FMOD 通道事件回调，通知会延迟到 Godot 执行。 FmodChannel 发出 FmodChannel.ended 等专用信号；基类实现发出 callback_received 。
void clear_callback()
移除 set_callback() 安装的 FMOD 回调，停止该句柄的基类和派生类通道事件通知。