IDirectMusicSynthSink

IDirectMusicSynthSink インターフェイスは現在ではほぼ廃止されており、DirectX 8 より前のバージョンの DirectMusic でのみサポートされます。

Init メソッドは、シンスシンク (synth-sink) オブジェクトを初期化します。

呼び出しが成功した場合、Init は S_OK を返します。それ以外の場合は、該当するエラーコードを返します。

IDirectMusicSynth::SetSynthSink の呼び出しによってシンセサイザーがシンスシンクに接続されると、シンセサイザーはシンスシンクの Init メソッドを呼び出します。

循環参照を避けるため、IDirectMusicSynthSink は IDirectMusicSynth シンセオブジェクトの参照カウントを増やしません。代わりに、IDirectMusicSynth オブジェクトが常に親であり、使用を終えたときには常に IDirectMusicSynthSink オブジェクトを解放するという規則に従います。

接続後、シンスシンクは IDirectMusicSynthSink::Activate の呼び出しによってアクティブ化する必要があります。この時点でシンスシンクは wave バッファーの生成を開始し、IDirectMusicSynth::Render を呼び出してそれらをシンセサイザーに渡します。

pSynth パラメーターは、COM オブジェクトの参照カウントの規約に従います。

詳細については、Synthesizers and Wave Sinks を参照してください。また、Microsoft Windows SDK ドキュメントの IDirectMusic インターフェイスの説明も参照してください。

SetMasterClock メソッドは、DirectMusic の他の部分との同期に必要となるマスタータイムソースをシンスシンクに提供します。

呼び出しが成功した場合、SetMasterClock は S_OK を返します。それ以外の場合は、該当するエラーコードを返します。次の表に、返される可能性のあるステータスコードの一部を示します。

シンスシンクは、ストリーミング wave を DirectMusic の他の部分と同期させるためのマスタークロックを受け取るまで機能できません。

マスタータイムとサンプルタイムは異なるクリスタル (発振子) で駆動されている可能性があるため、両者はずれていくことがあります。シンスシンクは、位相同期ループ (PLL) を用いて、現在のサンプルタイムの認識をマスタータイムにロックできます。

マスタークロックは、IDirectMusicSynth::GetLatencyClock の呼び出しによってシンスシンクから取得されるレイテンシークロックとは異なります。マスタークロックがタイムベースを提供するのに対し、レイテンシークロックは wave ストリームへのノートのレンダリングの進行状況を追跡するだけです。これにより、アプリケーションは IDirectMusicSynth::PlayBuffer メソッドを使用して再生用メッセージを送信できる最も早い時刻を知ることができます。レイテンシークロックはマスタークロックと厳密に同期している必要があるため、その単位は相対的なものです。

レイテンシークロックの時刻とマスタークロックの時刻を比較することで、シンセサイザーのレイテンシーを測定できます。なお、レイテンシークロックには、シンセサイザーのミキシングのバースト的な性質を反映したジッターが生じます (IDirectMusicSynth::Render の呼び出しごとにバッファー長の分だけ前方にジャンプします)。これに対して、マスタークロックは滑らかに増加します。

pClock パラメーターは、COM オブジェクトの参照カウントの規約に従います。

GetLatencyClock メソッドは、出力オーディオストリームの進行状況を測定するレイテンシークロックを取得します。

呼び出しが成功した場合、GetLatencyClock は S_OK を返します。それ以外の場合は、該当するエラーコードを返します。次の表に、返される可能性のあるステータスコードの一部を示します。

レイテンシー用の IReferenceClock は、その IReferenceClock::GetTime メソッドが呼び出されるたびに、現在のレンダリング時刻を返します。この時刻は常に、IDirectMusicSynthSink::SetMasterClock を使用してシンスシンクに設定されたマスタークロックによって確立された時刻からの相対値です。レイテンシー時刻は、DirectMusic のパフォーマンス層が、次にノートの再生を開始できる時刻を判別するために使用します。

ppClock パラメーターは、COM オブジェクトの参照カウントの規約に従います。

レイテンシークロックの詳細については、Synthesizer Latency を参照してください。また、Microsoft Windows SDK ドキュメントの IReferenceClock および IDirectMusic インターフェイスの説明も参照してください。

Activate メソッドは、シンセサイザーシンクをアクティブ化または非アクティブ化します。

呼び出しが成功した場合、Activate は S_OK を返します。それ以外の場合は、該当するエラーコードを返します。次の表に、返される可能性のあるステータスコードの一部を示します。

シンセサイザー自体に対して、オーディオデバイスの有効化または無効化を指示できます。これを受けてシンセサイザーは、オーディオデバイスを管理するシンスシンクを呼び出します。これにより、アプリケーションはリソースの使用を管理できます。音楽を再生していないときにシンクを非アクティブ化すれば、wave 出力デバイスを他のアプリケーションのために解放できます。

詳細については、Microsoft Windows SDK ドキュメントの IDirectMusic インターフェイスの説明を参照してください。

SampleToRefTime メソッドは、サンプルタイムをリファレンスタイムに変換します。

呼び出しが成功した場合、SampleToRefTime は S_OK を返します。それ以外の場合は、該当するエラーコードを返します。

SampleToRefTime メソッドは、サンプルタイムをリファレンスタイムに変換します。サンプルタイムはレンダリングされたサンプル数で表され、リファレンスタイムは 100 ナノ秒単位で計測されます。

シンスシンクは、マスタークロック (IDirectMusicSynthSink::SetMasterClock の呼び出しで設定) とオーディオストリームとの間のタイミング関係を管理します。

詳細については、Synthesizer Timing のリファレンスタイムとサンプルタイムの説明を参照してください。

RefTimeToSample メソッドは、リファレンスタイムをサンプルタイムに変換します。

呼び出しが成功した場合、RefTimeToSample は S_OK を返します。それ以外の場合は、該当するエラーコードを返します。

RefTimeToSample メソッドは、リファレンスタイムをサンプルタイムに変換します。このメソッドは入力パラメーターとしてリファレンスタイムを受け取り、対応するサンプルタイムを出力します。

リファレンスタイムからのサンプルタイムの計算は、サンプリング周波数に依存します。たとえば、出力バッファーが 44.2 kHz 形式である場合、サンプルタイム 44,200 はリファレンスタイムの 1 秒に相当します。

シンスシンクは、マスタークロック (IDirectMusicSynthSink::SetMasterClock の呼び出しで設定) とオーディオストリームとの間のタイミング関係を管理します。

詳細については、Synthesizer Timing のリファレンスタイムとサンプルタイムの説明を参照してください。

SetDirectSound メソッドは、シンセサイザーシンクを既存の DirectSound オブジェクトおよび DirectSound バッファーに接続します。

呼び出しが成功した場合、SetDirectSound は S_OK を返します。それ以外の場合は、該当するエラーコードを返します。次の表に、返される可能性のあるステータスコードの一部を示します。

pDirectSound パラメーターは、IDirectMusicPort::SetDirectSound から受け取った IDirectSound インスタンスを指し、NULL ではありません。

pDirectSoundBuffer が NULL の場合、IDirectSound のプライマリバッファーは、必要に応じてシンクのサンプルレートおよびチャンネル情報 (IDirectMusicSynth::GetFormat から取得) をサポートするようにアップグレードされます。

IDirectSoundBuffer は、シンセサイザーから取得した形式に一致する形式を持つセカンダリストリーミングバッファーである必要があります。pDirectSoundBuffer が NULL の場合は、適切な IDirectSoundBuffer インスタンスが内部的に作成されます。

シンクがアクティブ化された後は、IDirectSound インスタンスも IDirectSoundBuffer インスタンスも変更できません。

pDirectSound および pDirectSoundBuffer パラメーターは、COM オブジェクトの参照カウントの規約に従います。

詳細については、Microsoft Windows SDK ドキュメントの IDirectSound、IDirectSoundBuffer、IDirectMusicPort インターフェイスの説明を参照してください。

GetDesiredBufferSize メソッドは、シンセサイザーが推奨するバッファーサイズをサンプル単位で取得します。

呼び出しが成功した場合、GetDesiredBufferSize は S_OK を返します。それ以外の場合は、該当するエラーコードを返します。次の表に、返される可能性のあるステータスコードの一部を示します。

GetDesiredBufferSize メソッドは、シンセの現在の形式に基づいて、希望するバッファーサイズを返します。IDirectMusicSynthSink::SetDirectSound に渡す DirectSound バッファーは、少なくともこのサイズがないと無効になる可能性があります。

詳細については、Microsoft Windows SDK ドキュメントの IDirectMusicPort インターフェイスの説明を参照してください。