KSPROPSETID_Synth

發行項
06/15/2023

屬性 KSPROPSETID_Synth 集包含合成節點組態的全域屬性， (KSNODETYPE_SYNTHESIZER) 。

這個集合中的屬性專案是由KSPROPERTY_SYNTH列舉值所指定，如標頭檔 Dmusprop.h 中所定義。

使用量摘要資料表

系統會使用 KSPROPERTY_SYNTH_CAPS 屬性來判斷合成器的功能。

Get	集合	目標	屬性描述項類型	屬性值類型
是	否	Pin	KSNODEPROPERTY	SYNTHCAPS

(作業資料) 屬性值是 SYNTHCAPS 類型的結構，並指定合成器的功能。這些功能包括：

可用的範例記憶體數量
通道群組數目上限
語音數目上限
音訊通道數目上限
轉譯效果

如需詳細資訊，請參閱 SYNTHCAPS。

傳回值

KSPROPERTY_SYNTH_CAPS屬性要求會傳回STATUS_SUCCESS，表示它已順利完成。否則，要求會傳回適當的錯誤狀態碼。

如需合成器功能的詳細資訊，請參閱Microsoft Windows SDK檔中的IDirectMusicPort：：GetCaps方法和DMUS_PORTCAPS結構。

使用量摘要資料表

系統會使用KSPROPERTY_SYNTH_CHANNELGROUPS屬性來設定或取得針腳實例上的使用中通道群組數目。每個針腳實例上的通道群組編號都是從零開始。

Get	集合	目標	屬性描述項類型	屬性值類型
是	是	Pin	KSNODEPROPERTY	ULONG

(作業資料) 屬性值為 ULONG 類型，並指定針腳支援的通道群組數目。如果針腳支援 n 個通道群組，則針腳上的通道群組會從 0 編號為 n-1。

傳回值

KSPROPERTY_SYNTH_CAPS屬性要求會傳回STATUS_SUCCESS，表示它已順利完成。否則，要求會傳回適當的錯誤狀態碼。下表顯示一些可能的失敗碼。

狀態碼	意義
STATUS_BUFFER_TOO_SMALL	緩衝區太小而無法完成作業。
STATUS_UNSUCCESSFUL	作業未順利完成。

如需通道群組的詳細資訊，請參閱Microsoft Windows SDK檔中的 IDirectMusicPort：：GetNumChannelGroups和IDirectMusicPort：：SetNumChannelGroups方法的描述。

使用量摘要資料表

KSPROPERTY_SYNTH_LATENCYCLOCK 屬性是用來查詢迷你埠驅動程式的資料流程目前延遲時鐘時間，這一律大於主時鐘時間。

Get	集合	目標	屬性描述項類型	屬性值類型
是	否	Pin	KSNODEPROPERTY	ULONGLONG

(作業資料) 的屬性值為 ULONGLONG 類型，並代表合成器的目前延遲時間。這個時間是指定相對於主時鐘，並以 100 奈秒單位表示。

傳回值

KSPROPERTY_SYNTH_LATENCYCLOCK屬性要求會傳回STATUS_SUCCESS，表示它已順利完成。否則，要求會傳回適當的錯誤狀態碼。下表顯示一些可能的失敗碼。

狀態碼	意義
STATUS_BUFFER_TOO_SMALL	緩衝區太小而無法完成作業。
STATUS_UNSUCCESSFUL	作業未順利完成。
STATUS_INVALID_DEVICE_REQUEST	此裝置的作業無效。

延遲時鐘通常用來同步處理多個裝置之間的音訊輸出資料流程。

KSPROPERTY_SYNTH_LATENCYCLOCK get-property 要求應該傳回與目前主時鐘時間相等的延遲時鐘時間，以及資料流程通過之音訊篩選器的最小保證延遲。排程比目前延遲時鐘時間時間早播放音訊資料的應用程式程式，可能會延遲播放資料。

如需延遲時鐘的詳細資訊，請參閱下列內容：

延遲時鐘中KSPROPERTY_SYNTH_LATENCYCLOCK屬性的討論。
Microsoft Windows SDK檔中IDirectMusicPort：：GetLatencyClock和IReferenceClock：：GetTime方法的描述。

使用量摘要資料表

KSPROPERTY_SYNTH_PORTPARAMETERS 屬性可用來取得 DirectMusic 埠的組態參數，這是傳送或接收音樂資料之裝置的 DirectMusic 字詞。 (在 KS 術語中，DirectMusic 埠不會對應至 DMus 埠驅動程式。它會對應至 DirectMusic filter 上的轉譯或擷取釘選。)

Get	集合	目標	屬性描述項類型	屬性值類型
是	否	Pin	KSNODEPROPERTY + SYNTH_PORTPARAMS	SYNTH_PORTPARAMS

屬性描述項 (實例資料) 是由緊接著SYNTH_PORTPARAMS結構的 KSNODEPROPERTY 結構所組成。傳送屬性要求之前，用戶端會將其寫入至SYNTH_PORTPARAMS結構，以指定其要求的參數值。

(作業資料) 屬性值也是類型SYNTH_PORTPARAMS。迷你埠驅動程式會使用實際用來設定埠的參數值載入此結構。

傳回值

如果迷你埠驅動程式成功設定 DirectMusic 埠與呼叫端所指定完全相同，則會傳回STATUS_SUCCESS程式碼。否則，它會傳回適當的錯誤碼。下表指出一些可能的錯誤狀態碼。

狀態碼	意義
STATUS_NOT_ALL_ASSIGNED	作業成功，但迷你埠驅動程式必須修改呼叫端在屬性值中標示為有效的一或多個參數值。
STATUS_UNSUCCESSFUL	作業未順利完成。

這是要處理的最複雜 DirectMusic 屬性專案。雖然這個屬性只支援 get 要求，但 get 要求也會設定埠參數。埠會將SYNTH_PORTPARAMS結構當做屬性要求的屬性描述項傳遞。屬性值緩衝區伴隨屬性要求，但因為這是取得要求，所以緩衝區只會用來從迷你埠驅動程式擷取資訊。

迷你埠驅動程式應該先將SYNTH_PORTPARAMS結構從屬性描述項複製到屬性值緩衝區。接下來，它應該檢查它是否能夠支援呼叫端要求的所有參數值， (標示為有效的) 。如果迷你埠驅動程式無法支援一或多個要求的參數值，它應該覆寫屬性值緩衝區中SYNTH_PORTPARAMS結構中的 (，) 這些特定參數的要求值，並加上可支援的值。

如果迷你埠驅動程式不會對呼叫端的SYNTH_PORTPARAMS進行任何變更，則呼叫端應該會傳回屬性值，其與呼叫端原本傳送至迷你埠驅動程式的屬性描述元中的參數完全相符。

根據慣例，驅動程式也會針對未在 SYNTH_PORTPARAMS 的 dwValidParams 成員中設定對應位的參數填入值。這可讓呼叫端查看用於這些參數之迷你埠驅動程式的預設值。迷你埠驅動程式會輸出用來建置波浪介面裝置的實際參數值。

迷你埠驅動程式的KSPROPERTY_SYNTH_PORTPARAMETERS處理常式應該準備好正確處理取樣率變更的要求。

使用量摘要資料表

KSPROPERTY_SYNTH_RUNNINGSTATS 屬性可用來查詢迷你埠驅動程式，以取得合成器的效能統計資料。

Get	集合	目標	屬性描述項類型	屬性值類型
是	否	Pin	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 合成器中特定語音的優先順序。

Get	集合	目標	屬性描述項類型	屬性值類型
是	是	Pin	KSNODEPROPERTY + SYNTHVOICEPRIORITY_INSTANCE	DWORD

屬性描述項 (實例資料) 是由緊接SYNTHVOICEPRIORITY_INSTANCE結構的 KSNODEPROPERTY 結構所組成，該結構會指定 (組 16 MIDI 通道) 和群組) 內的通道號碼 (。

) 作業資料 (屬性值是指定優先順序的 DWORD。用戶端會使用 KSPROPERTY_SYNTH_VOICEPRIORITY set-property 要求，將語音的新優先順序傳送至迷你埠驅動程式，並使用 KSPROPERTY_SYNTH_VOICEPRIORITY get-property 要求，從迷你埠驅動程式擷取語音的目前優先順序。

語音優先順序

下列通道群組優先順序定義于標頭檔 Dmusprop.h：

  DAUD_CRITICAL_VOICE_PRIORITY
  DAUD_HIGH_VOICE_PRIORITY
  DAUD_STANDARD_VOICE_PRIORITY
  DAUD_LOW_VOICE_PRIORITY
  DAUD_PERSIST_VOICE_PRIORITY

上述清單會以清單頂端的最高優先順序和底部的最低優先順序來排序。這些優先順序是 ORed，具有通道優先順序位移，以到達通道群組內每個通道的語音優先順序。產生的優先順序會傳入 get- 和 set-property 要求中。

相較于通道優先順序位移，上述通道群組優先順序值很大。結果是變更通道群組優先順序會提高或降低整個通道群組相對於其他通道群組的優先順序，而不改變通道群組內通道的相對優先順序。

預設優先順序

建立合成器迷你埠驅動程式時，它會為其每個語音指派預設優先順序。預設值的定義如下：

根據預設，優先順序會跨通道群組相等。例如，這表示通道群組 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 也會以位 ORing 每個位移與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 屬性會取得或設定合成器裝置的音量層級。

Get	集合	目標	屬性描述元類型	屬性值類型
是	是	Pin	KSPROPERTY	LONG

(作業資料) 的屬性值為 LONG 類型，並指定合成器裝置的磁片區層級。磁片區設定是以 1/100 秒的分貝為單位來指定。迷你埠驅動程式應該變更其磁片區或報告其磁片區，視要求是要取得或設定屬性而定。

傳回值

KSPROPERTY_SYNTH_VOLUME屬性要求會傳回STATUS_SUCCESS，表示它已順利完成。否則，要求會傳回適當的錯誤狀態碼。下表顯示一些可能的錯誤碼。

狀態碼	意義
STATUS_BUFFER_TOO_SMALL	緩衝區太小而無法完成作業。
STATUS_UNSUCCESSFUL	作業未順利完成。

使用量摘要表格

KSPROPERTY_SYNTH_VOLUMEBOOST 屬性會指定合成器裝置音量提升的數量。

Get	集合	目標	屬性描述元類型	屬性值類型
是	是	Pin	KSNODEPROPERTY	LONG

(作業資料) 的屬性值為 LONG 類型，並指定混合階段之後要提升音訊訊號的程度。這是在完成所有語音表達和混合之後，要新增至合成器最終輸出的音量。音量提升數量是以 1/100 秒的分貝指定。此值可以是正數或負數。

傳回值

KSPROPERTY_SYNTH_VOLUMEBOOST屬性要求會傳回STATUS_SUCCESS，表示它已順利完成。否則，要求會傳回適當的錯誤狀態碼。下表顯示一些可能的錯誤碼。

狀態碼	意義
STATUS_BUFFER_TOO_SMALL	緩衝區太小而無法完成作業。
STATUS_UNSUCCESSFUL	作業未順利完成。

不應該將其他提升新增至輸出。合成器應遵循嚴格的 DLS 層級 1 慣例來表達。

這個屬性用來將合成器的音量與其他音訊輸出相等，因此應該在所有裝置上以一致的方式解譯提升數量。

共用方式為

KSPROPSETID_Synth

使用量摘要資料表

傳回值

使用量摘要資料表

傳回值

使用量摘要資料表

傳回值

使用量摘要資料表

傳回值

使用量摘要資料表

傳回值

使用量摘要資料表

預設優先順序

傳回值

使用量摘要表格

傳回值

使用量摘要表格

傳回值

意見反應

其他資源