KSPROPSETID_Synth

项目
02/26/2024

KSPROPSETID_Synth 属性集包含对合成器节点 (KSNODETYPE_SYNTHESIZER) 配置的全局属性。

此集中的属性项由 KSPROPERTY_SYNTH 枚举值指定，如标头文件 Dmusprop.h 中定义。

使用情况摘要表

系统使用 KSPROPERTY_SYNTH_CAPS 属性来确定合成器的功能。

获取	设置	目标	属性描述符类型	属性值类型
是	否	固定	KSNODEPROPERTY	SYNTHCAPS

属性值（操作数据）是 SYNTHCAPS 类型的结构，指定合成器的功能。这些功能包括：

可用示例内存量
通道组最大数目
语音最大数目
音频通道最大数目
渲染效果

有关详细信息，请参阅 SYNTHCAPS。

返回值

KSPROPERTY_SYNTH_CAPS 属性请求返回 STATUS_SUCCESS，以指示已成功完成。否则，请求将返回适当的错误状态代码。

有关合成器功能的详细信息，请参阅 Microsoft Windows SDK 文档中的 IDirectMusicPort::GetCaps 方法和 DMUS_PORTCAPS 结构。

使用情况摘要表

KSPROPERTY_SYNTH_CHANNELGROUPS 属性由系统用来设置或获取 PIN 实例上的活动通道组数。通道组在每个 PIN 实例上从 0 开始编号。

获取	设置	目标	属性描述符类型	属性值类型
是	是	固定	KSNODEPROPERTY	ULONG

属性值（操作数据）的类型为 ULONG，并指定 PIN 支持的通道组数。如果 PIN 支持 n 个通道组，则 PIN 上的通道组编号为 0 到 n-1。

返回值

KSPROPERTY_SYNTH_CAPS 属性请求返回 STATUS_SUCCESS，以指示已成功完成。否则，请求将返回适当的错误状态代码。下表显示了一些可能的故障代码。

状态代码	含义
STATUS_BUFFER_TOO_SMALL	缓冲区太小，无法完成操作。
STATUS_UNSUCCESSFUL	操作未成功完成。

有关通道组的详细信息，请参阅 Microsoft Windows SDK 文档中 IDirectMusicPort::GetNumChannelGroups 和 IDirectMusicPort::SetNumChannelGroups 方法的说明。

使用情况摘要表

KSPROPERTY_SYNTH_LATENCYCLOCK 属性用于查询流的当前延迟时钟时间的微型端口驱动程序，该时间始终晚于主时钟时间。

获取	设置	目标	属性描述符类型	属性值类型
是	否	固定	KSNODEPROPERTY	ULONGLONG

属性值（操作数据）的类型为 ULONGLONG，表示合成器当前的延迟时间。此时间是相对于主时钟指定的，并以 100 纳秒为单位表示。

返回值

KSPROPERTY_SYNTH_LATENCYCLOCK 属性请求返回 STATUS_SUCCESS，以指示已成功完成。否则，请求将返回适当的错误状态代码。下表显示了一些可能的故障代码。

状态代码	含义
STATUS_BUFFER_TOO_SMALL	缓冲区太小，无法完成操作。
STATUS_UNSUCCESSFUL	操作未成功完成。
STATUS_INVALID_DEVICE_REQUEST	该操作对此设备无效。

延迟时钟通常用于在多个设备之间同步音频输出流。

KSPROPERTY_SYNTH_LATENCYCLOCK get 请求应返回与当前主时钟时间相等的延迟时钟时间，以及流通过的音频筛选器的最小保证延迟。计划早于当前延迟时钟时间播放的音频数据的应用程序程序可能会延迟播放数据。

要详细了解延迟时钟，请参阅以下内容：

延迟时钟中 KSPROPERTY_SYNTH_LATENCYCLOCK 属性的讨论。
Microsoft Windows SDK 文档中 IDirectMusicPort::GetLatencyClock 和 IReferenceClock::GetTime 方法的说明。

使用情况摘要表

KSPROPERTY_SYNTH_PORTPARAMETERS 属性用于获取 DirectMusic port 的配置参数，这是发送或接收音乐数据的设备的 DirectMusic 术语。（在 KS 术语中，DirectMusic 端口与 DMus 端口驱动程序不对应。它对应于 DirectMusic 筛选器上的呈现或捕获引脚。）

获取	设置	目标	属性描述符类型	属性值类型
是	否	固定	KSNODEPROPERTY + SYNTH_PORTPARAMS	SYNTH_PORTPARAMS

属性描述符（实例数据）由 KSNODEPROPERTY 结构组成，该结构紧跟 SYNTH_PORTPARAMS 结构。在发送属性请求之前，客户端通过将请求的参数值写入 SYNTH_PORTPARAMS 结构来指定其请求的参数值。

属性值（操作数据）也是 SYNTH_PORTPARAMS 类型。微型端口驱动程序使用实际用于配置端口的参数值加载此结构。

返回值

如果微型端口驱动程序成功配置 DirectMusic 端口与调用方指定的端口完全一样，则将返回 STATUS_SUCCES 代码。否则，将返回相应的错误代码。下表指示一些可能的错误状态代码。

状态代码	含义
STATUS_NOT_ALL_ASSIGNED	操作成功，但微型端口驱动程序必须修改调用方在属性值中标记为有效的一个或多个参数值。
STATUS_UNSUCCESSFUL	操作未成功完成。

这是最难处理的 DirectMusic 属性项。虽然此属性仅支持获取请求，但 Get 请求也会设置端口参数。端口将 SYNTH_PORTPARAMS 结构作为属性请求的属性描述符传递。属性值缓冲区附带属性请求，但由于这是一个 Get 请求，因此缓冲区仅用于从微型端口驱动程序检索信息。

微型端口驱动程序首先将属性描述符中的 SYNTH_PORTPARAMS structure 结构复制到属性值缓冲区。接下来，检查是否能够支持调用方请求的（标记为有效）所有参数值。如果微型端口驱动程序无法支持一个或多个请求的参数值，则会覆盖（在属性值缓冲区中的 SYNTH_PORTPARAMS 结构中）这些特定参数的请求值以及它可支持的值。

如果微型端口驱动程序对调用方 SYNTH_PORTPARAMS 没有更改，则调用方会返回一个属性值，该值与调用方最初发送到微型端口驱动程序的属性描述符中的参数完全匹配。

按照约定，驱动程序还会填充 SYNTH_PORTPARAMS 的 dwValidParams 成员中未设置相应位的参数的值。这允许调用方查看用于这些参数的微型端口驱动程序的默认值。微型端口驱动程序输出用于生成波形接口设备的实际参数值。

微型端口驱动程序的 KSPROPERTY_SYNTH_PORTPARAMETERS 处理程序准备好正确处理采样率更改的请求。

使用情况摘要表

KSPROPERTY_SYNTH_RUNNINGSTATS 属性用于查询微型端口驱动程序，以获取合成器的性能统计信息。

获取	设置	目标	属性描述符类型	属性值类型
是	否	固定	KSNODEPROPERTY	SYNTH_STATS

属性值（操作数据）是 SYNTH_STATS 类型的结构。微型端口驱动程序的属性处理程序将以下统计信息写入此结构：

播放语音的平均数量
CPU 使用率
丢失的注释数
可用内存量
峰值音量级别

返回值

KSPROPERTY_SYNTH_RUNNINGSTATS 属性请求返回 STATUS_SUCCESS，以指示已成功完成。否则，请求将返回适当的错误状态代码。下表显示了一些可能的错误代码。

状态代码	含义
STATUS_BUFFER_TOO_SMALL	缓冲区太小，无法完成操作。
STATUS_UNSUCCESSFUL	操作未成功完成。
STATUS_INVALID_DEVICE_REQUEST	该操作对此设备无效。

合成器的性能统计信息在设备保持 KSSTATE_RUN 状态时会持续更新。每次设备进入这种状态时，都会重置统计信息，从而将峰值音量和丢失音符数量等累积值清零。

有关详细信息，请参阅 Microsoft Windows SDK 文档中 IDirectMusicPort::GetRunningStats 方法和 DMUS_SYNTHSTATS 结构的说明。

使用情况摘要表

KSPROPERTY_SYNTH_VOICEPRIORITY 属性指定当微型端口驱动程序需要从其语音缓存中提升语音时，MIDI 合成器中特定语音应具有哪些优先级。

获取	设置	目标	属性描述符类型	属性值类型
是	是	固定	KSNODEPROPERTY + SYNTHVOICEPRIORITY_INSTANCE	DWORD

属性描述符（实例数据）由 KSNODEPROPERTY 结构组成，紧接着是 SYNTHVOICEPRIORITY_INSTANCE 结构，该结构指定语音的通道组（16 个 MIDI 通道的集合）和通道编号（在组中）。

属性值（操作数据）是指定优先级的 DWORD。客户端使用 KSPROPERTY_SYNTH_VOICEPRIORITY set 属性请求将语音的新优先级发送到微型端口驱动程序，并使用 KSPROPERTY_SYNTH_VOICEPRIORITY get 属性请求从微型端口驱动程序检索语音的当前优先级。

语音优先级

标头文件 Dmusprop.h 中定义了以下通道组优先级：

  DAUD_CRITICAL_VOICE_PRIORITY
  DAUD_HIGH_VOICE_PRIORITY
  DAUD_STANDARD_VOICE_PRIORITY
  DAUD_LOW_VOICE_PRIORITY
  DAUD_PERSIST_VOICE_PRIORITY

上述列表按照优先级最高的顺序排列，优先级最低的顺序排列在列表的顶部。这些优先级与通道优先级偏移进行 OR 运算，以得到通道组内每个通道的语音优先级。由此产生的优先级在 get 和 set 属性请求中传递。

与通道优先级偏移量相比，前面的通道组优先级值较大。结果是，更改通道组优先级会提高或降低整个通道组相对于其他通道组的优先级，而不会更改通道组中通道的相对优先级。

默认优先级

创建合成器微型端口驱动程序时，它会为其每个语音分配默认优先级。默认值定义如下：

默认情况下，通道组之间的优先级相等。这意味着，通道组 1 上的通道 5 与通道组 2 上的通道 5 具有相同的优先级。
根据 DLS 级别 1 规范，通道 10（MIDI 打击乐通道）具有最高优先级，其次是 1 到 9 和 11 到 16。

标头文件 Dmusprop.h 定义以下优先级偏移量：

  DAUD_CHAN10_VOICE_PRIORITY_OFFSET
  DAUD_CHAN1_VOICE_PRIORITY_OFFSET
  DAUD_CHAN2_VOICE_PRIORITY_OFFSET
  DAUD_CHAN3_VOICE_PRIORITY_OFFSET
  DAUD_CHAN4_VOICE_PRIORITY_OFFSET
  DAUD_CHAN5_VOICE_PRIORITY_OFFSET
  DAUD_CHAN6_VOICE_PRIORITY_OFFSET
  DAUD_CHAN7_VOICE_PRIORITY_OFFSET
  DAUD_CHAN8_VOICE_PRIORITY_OFFSET
  DAUD_CHAN9_VOICE_PRIORITY_OFFSET
  DAUD_CHAN11_VOICE_PRIORITY_OFFSET
  DAUD_CHAN12_VOICE_PRIORITY_OFFSET
  DAUD_CHAN13_VOICE_PRIORITY_OFFSET
  DAUD_CHAN14_VOICE_PRIORITY_OFFSET
  DAUD_CHAN15_VOICE_PRIORITY_OFFSET
  DAUD_CHAN16_VOICE_PRIORITY_OFFSET

前面的偏移列表以最高优先级排列在列表的顶部。标头文件 Dmusprop.h 还通过按位 OR 对每个通道组中的通道的默认优先级定义 DAUD_STANDARD_VOICE_PRIORITY。例如，以下定义为每个通道组中的通道 1 提供默认优先级：

  #define DAUD_CHAN1_DEF_VOICE_PRIORITY \
    (DAUD_STANDARD_VOICE_PRIORITY | DAUD_CHAN1_VOICE_PRIORITY_OFFSET)

返回值

KSPROPERTY_SYNTH_VOICEPRIORITY 属性请求返回 STATUS_SUCCESS，以指示已成功完成。否则，请求将返回适当的错误状态代码。下表显示了一些可能的错误代码。

状态代码	含义
STATUS_BUFFER_TOO_SMALL	缓冲区太小，无法完成操作。
STATUS_UNSUCCESSFUL	操作未成功完成。

有关语音优先级的详细信息，请参阅 Microsoft Windows SDK 文档中 IDirectMusicPort::GetChannelPriority 和 IDirectMusicPort::SetChannelPriority 方法的说明。

使用情况摘要表

KSPROPERTY_SYNTH_VOLUME 属性获取或设置合成器设备的音量级别。

获取	设置	目标	属性描述符类型	属性值类型
是	是	固定	KSPROPERTY	LONG

属性值（操作数据）的类型为 LONG，指定合成器设备的音量级别。音量设置以 1/100 分贝为单位指定。微型端口驱动程序更改其音量或报告其音量，具体取决于请求是获取属性还是设置属性。

返回值

KSPROPERTY_SYNTH_VOLUME 属性请求返回 STATUS_SUCCESS，以指示已成功完成。否则，请求将返回适当的错误状态代码。下表显示了一些可能的错误代码。

状态代码	含义
STATUS_BUFFER_TOO_SMALL	缓冲区太小，无法完成操作。
STATUS_UNSUCCESSFUL	操作未成功完成。

使用情况摘要表

The KSPROPERTY_SYNTH_VOLUMEBOOST 属性指定合成器设备音量提升的量。

获取	设置	目标	属性描述符类型	属性值类型
是	是	固定	KSNODEPROPERTY	LONG

属性值（操作数据）的类型为 LONG，指定在混合阶段之后提升音频信号的量。这是在完成所有语音发音和混音后，添加到合成器最终输出的音量。音量提升量以 1/100 分贝为单位指定。此值可以是正数也可以是负数。

返回值

KSPROPERTY_SYNTH_VOLUMEBOOST 属性请求返回 STATUS_SUCCESS，以指示已成功完成。否则，请求将返回适当的错误状态代码。下表显示了一些可能的错误代码。

状态代码	含义
STATUS_BUFFER_TOO_SMALL	缓冲区太小，无法完成操作。
STATUS_UNSUCCESSFUL	操作未成功完成。

输出中不应添加其他提升。合成器应该严格遵循 DLS 1 级的发音惯例。

通过

KSPROPSETID_Synth

使用情况摘要表

返回值

使用情况摘要表

返回值

使用情况摘要表

返回值

使用情况摘要表

返回值

使用情况摘要表

返回值

使用情况摘要表

默认优先级

返回值

使用情况摘要表

返回值

使用情况摘要表

返回值

反馈

其他资源