KSPROPSETID_Synth_Dls

KSPROPSETID_Synth_Dls プロパティ セットには、DLS サンプルとインストゥルメントを MIDI シンセサイザーにダウンロードするために使用されるプロパティが含まれます。 これらは、DirectMusic フィルターの DirectMusic ピン上のシンセ ノード (KSNODETYPE_SYNTHESIZER) のプロパティです (「MIDI および DirectMusic フィルター」を参照)。

このセクションでは、DLS データを含むメモリの「チャンク」をダウンロードおよびアンロードする方法に関連するこれらのプロパティの動作について説明します。 ダウンロードしたインストルメントおよびウェーブ データ チャンクの実際の形式は、Microsoft Windows SDK ドキュメントの低レベル DLS ディスカッションで指定されています。

DLS は、ピンが存在していればいつでもダウンロードとアンロードができます。 DirectMusic イベントとは異なり、タイムスタンプが設定されていないため、できるだけ早く処理する必要があります。

このセクションでは、DLS リソース、または単にリソースという用語は、DLS インストルメント チャンクまたは DLS ウェーブ チャンクを指します。 システムは、すべての DLS リソースの参照カウントを適切に維持しています。

• クライアントがウェーブを参照する最後のインストルメントをアンロードすると、システムはウェーブをアンロードする呼び出しを自動的に生成します。

• 逆にシステムは、クライアントがウェーブを参照する最後のインストゥルメントをアンロードするまで、ウェーブをアンロードする呼び出しを延期します。

このセット内のプロパティ項目は、ヘッダー ファイル Dmusprop.h で定義されている KSPROPERTY_SYNTH_DLS リストが指定します。

用法の要点テーブル

KSPROPERTY_SYNTH_DLS_APPEND プロパティは、クライアントがシンセサイザーにダウンロードする各バッファーの DLS データに追加する予約ストレージ領域の量を指定します。

Yammer の入手	設定	移行先	プロパティ記述子の種類	プロパティ値の種類
はい	いいえ	ピン留めする	KSNODEPROPERTY	ULONG

プロパティ値 (操作データ) は ULONG 型であり、ダウンロードされた各 DLS データ バッファーの末尾でミニポート ドライバーが独自の使用のために予約する必要があるバイト数を指定します。 次に、クライアントは、ダウンロードされたデータの終了後に要求されたバイト数を格納するのに十分な大きさの各ダウンロード バッファーを割り当てます。

戻り値

KSPROPERTY_SYNTH_DLS_APPEND プロパティ要求は、正常に完了したことを示すために STATUS_SUCCESS を返します。 それ以外の場合、要求は適切なエラー状態コードを返します。 次の表に、考えられるエラー コードの一部を示します。

状態コード	意味
STATUS_UNSUCCESSFUL	操作が正常に完了しませんでした。

これらの追加バイトは、配置要件に追加の埋め込みを必要とするドライバー、またはサンプル補間を簡略化するためにサンプルの開始をレプリケートすることを目的としています。

用法の要点テーブル

KSPROPERTY_SYNTH_DLS_COMPACT プロパティは、シンセサイザーに対して、空きサンプル メモリの最大チャンクを使用できるようにするための要求です。

Yammer の入手	設定	移行先	プロパティ記述子の種類	プロパティ値の種類
いいえ	はい	ピン留めする	KSNODEPROPERTY	なし

このプロパティに関連付けられているプロパティ値 (操作データ) はありません。

戻り値

KSPROPERTY_SYNTH_DLS_COMPACT プロパティ要求は、正常に完了したことを示すために STATUS_SUCCESS を返します。 それ以外の場合、要求は適切なエラー状態コードを返します。 次の表に、考えられるエラー コードの一部を示します。

状態コード	意味
STATUS_UNSUCCESSFUL	操作が正常に完了しませんでした。

このプロパティのハンドラーの実装では、再生を中断しないでください。

詳細については、Microsoft Windows SDK ドキュメントの IDirectMusicPort::Compact メソッドに関する説明を参照してください。

用法の要点テーブル

KSPROPERTY_SYNTH_DLS_DOWNLOAD プロパティは、DLS データをシンセサイザーにダウンロードするために使用されます。

Yammer の入手	設定	移行先	プロパティ記述子の種類	プロパティ値の種類
はい	いいえ	ピン留めする	KSNODEPROPERTY + SYNTH_BUFFER	SYNTHDOWNLOAD

プロパティ記述子 (インスタンス データ) は、ダウンロードする DLS データ バッファーの場所とサイズを指定する SYNTH_BUFFER 構造体が直後に続く KSNODEPROPERTY 構造体で構成されます。

プロパティ値 (操作データ) は SYNTHDOWNLOAD 構造体です。 ミニポート ドライバーは、この構造体で次の情報を返します。

• ダウンロードした DLS データを一意に識別するためにミニポート ドライバーが生成するハンドル。 このクライアントは、このハンドルを保存し、後でそれを使用してデータをアンロードする必要があります (「KSPROPERTY_SYNTH_DLS_UNLOAD」を参照)。

• プロパティ要求の完了後に、クライアントが DLS データを含むバッファーを解放できるかどうかを示すブール値。 ミニポート ドライバーが DLS データの独自のコピーを作成した場合、クライアントはバッファーを解放できます。 それ以外の場合で、ミニポート ドライバーがクライアントの元の DLS データ バッファーを使用し続ける場合は、ミニポート ドライバーが DLS データをアンロードするまで、クライアントはバッファーを解放するべきではありません。

戻り値

KSPROPERTY_SYNTH_DLS_DOWNLOAD プロパティ要求は、正常に完了したことを示すために STATUS_SUCCESS を返します。 それ以外の場合、要求は適切なエラー状態コードを返します。 次の表に、考えられるエラー コードの一部を示します。

状態コード	意味
STATUS_BUFFER_TOO_SMALL	バッファーが小さすぎて操作を完了できませんでした。
STATUS_UNSUCCESSFUL	操作が正常に完了しませんでした。
STATUS_NO_MEMORY	この要求を完了するために使用できるメモリはありません。

詳細については、Microsoft Windows SDK ドキュメントの IDirectMusicPort::DownloadInstrument メソッドに関する議論を参照してください。

例

KSPROPERTY_SYNTH_DLS_DOWNLOAD プロパティ要求は、ユーザー メモリ アドレスを持つ DLS ダウンロード データの場所を指定します。 ミニポート ドライバーは、アクセスを試行する前に、DLS データを含むユーザー メモリをプローブしてロックする必要があります。 次のサンプル コードで、その方法を示します。

  NTSTATUS Status = STATUS_UNSUCCESSFUL;
  PSYNTH_BUFFER pDlsBuffer = (PSYNTH_BUFFER)pRequest->Instance;
  PMDL pMdl = IoAllocateMdl(pDlsBuffer->BufferAddress, pDlsBuffer->BufferSize,
                            FALSE, FALSE, NULL);
  if (pMdl)
  {
      __try
      {
          MmProbeAndLockPages(pMdl, KernelMode, IoReadAccess);
          PVOID pvUserData = MmGetSystemAddressForMdlSafe(pMdl, NormalPagePriority);
 
         // do something with the data here
      }
      __except (EXCEPTION_EXECUTE_HANDLER)
      {
          Status = GetExceptionCode();
      }
 
      MmUnlockPages(pMdl);
      IoFreeMdl(pMdl);
  }
  else
  {
      Status = STATUS_NO_MEMORY;
  }

用法の要点テーブル

KSPROPERTY_SYNTH_DLS_UNLOAD プロパティは、以前にダウンロードした DLS データ リソースをアンロードします。

Yammer の入手	設定	移行先	プロパティ記述子の種類	プロパティ値の種類
いいえ	はい	ピン留めする	KSNODEPROPERTY	HANDLE

プロパティ値 (操作データ) は HANDLE 型であり、解放されるダウンロード済み DLS データ リソースのハンドルが含まれています。 これは、ミニポート ドライバーが 以前の KSPROPERTY_SYNTH_DLS_DOWNLOADget-property 要求にある DLS データを識別するために、生成したハンドルです。

戻り値

KSPROPERTY_SYNTH_DLS_UNLOAD プロパティ要求は、正常に完了したことを示すために STATUS_SUCCESS を返します。 それ以外の場合、要求は適切なエラー状態コードを返します。 次の表に、考えられるエラー コードの一部を示します。

状態コード	意味
STATUS_BUFFER_TOO_SMALL	バッファーが小さすぎて操作を完了できませんでした。
STATUS_UNSUCCESSFUL	操作が正常に完了しませんでした。
STATUS_PENDING	操作は後で完了します。

ミニポート ドライバーは、DLS データを使用するノートが再生されていないとすぐに DLS データをアンロードする必要があります。 シンセサイザーが、KSPROPERTY_SYNTH_DLS_UNLOAD set-property 要求の時点で DLS データ リソースに関連付けられているメモリを解放できない場合は、非同期プロパティ補完を使用して、後で要求を完了できます。

DLS データ リソースをアンロードした後、シンセサイザーがリソースを使用するノートオン イベントを受信した場合、ミニポート ドライバーは、新しい DLS データ リソースが中間でダウンロードされていない限り、イベントを無視する必要があります。

詳細については、Microsoft Windows SDK ドキュメントの IDirectMusicPort::UnloadInstrument メソッドに関する議論を参照してください。

用法の要点テーブル

KSPROPERTY_SYNTH_DLS_WAVEFORMAT プロパティは、シンセサイザーの出力ウェーブ形式をクエリするために使用されます。

Yammer の入手	設定	移行先	プロパティ記述子の種類	プロパティ値の種類
はい	いいえ	ピン留めする	KSNODEPROPERTY	WAVEFORMATEX

プロパティ値 (演算データ) は WAVEFORMATEX 型で、シンセサイザーの出力ストリームのウェーブ形式を指定します。

戻り値

KSPROPERTY_SYNTH_DLS_WAVEFORMAT プロパティ要求は、正常に完了したことを示すために STATUS_SUCCESS を返します。 それ以外の場合、要求は適切なエラー状態コードを返します。 次の表に、考えられるエラー コードの一部を示します。

状態コード	意味
STATUS_BUFFER_TOO_SMALL	バッファーが小さすぎて操作を完了できませんでした。

sizeof (WAVEFORMATEX) バイトのプロパティ値バッファーは、すべてのウェーブ形式に対して十分な大きさではない可能性があります。 たとえば、マルチチャネル形式では、sizeof(WAVEFORMATEXTENSIBLE) バイトのバッファーが必要です。 プロパティ要求が STATUS_BUFFER_TOO_SMALL の状態コードを返す場合、クライアントはミニポート ドライバーが出力するプロパティ値のサイズをチェックし、大きなバッファーを割り当ててから、2 番目の要求を送信できます。

詳細については、Microsoft Windows SDK ドキュメントの IDirectMusicPort::GetFormat メソッドに関する説明を参照してください。