KSPROPSETID_Synth_Dls

[アーティクル]
03/15/2024

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 メソッドに関する説明を参照してください。

次の方法で共有

KSPROPSETID_Synth_Dls

用法の要点テーブル

戻り値

用法の要点テーブル

戻り値

用法の要点テーブル

戻り値

用法の要点テーブル

戻り値

用法の要点テーブル

戻り値

フィードバック

その他のリソース