IAudioCaptureClient::GetBuffer メソッド (audioclient.h)

キャプチャ エンドポイント バッファー内の次に使用可能なデータ パケットへのポインターを取得します。

構文

HRESULT GetBuffer(
  [out] BYTE   **ppData,
  [out] UINT32 *pNumFramesToRead,
  [out] DWORD  *pdwFlags,
  [out] UINT64 *pu64DevicePosition,
  [out] UINT64 *pu64QPCPosition
);

パラメーター

[out] ppData

クライアントが読み取るために使用できる次のデータ パケットの開始アドレスをメソッドが書き込むポインター変数へのポインター。

[out] pNumFramesToRead

メソッドがフレーム数 (データ パケットで使用可能なオーディオ フレームの数) を書き込む UINT32 変数へのポインター。 クライアントは、データ パケット全体を読み取るか、まったく読み取らてはなりません。

[out] pdwFlags

メソッドがバッファー状態フラグを書き込む DWORD 変数へのポインター。 メソッドは、次の 1 つ以上の _AUDCLNT_BUFFERFLAGS 列挙値の 0 またはビットごとの OR の組み合わせを書き込みます。

AUDCLNT_BUFFERFLAGS_SILENT

AUDCLNT_BUFFERFLAGS_DATA_DISCONTINUITY

AUDCLNT_BUFFERFLAGS_TIMESTAMP_ERROR

[out] pu64DevicePosition

メソッドがデータ パケット内の最初のオーディオ フレームのデバイス位置を書き込む UINT64 変数へのポインター。 デバイスの位置は、ストリームの先頭からのオーディオ フレームの数として表されます。 クライアントがデバイスの位置を必要としない場合、このパラメーターは NULL にすることができます 。 詳細については、「解説」を参照してください。

[out] pu64QPCPosition

オーディオ エンドポイント デバイスがデータ パケット内の最初のオーディオ フレームのデバイス位置を記録した時点で、メソッドがパフォーマンス カウンターの値を書き込む UINT64 変数へのポインター。 メソッドは、カウンター値を *pu64QPCPosition に書き込む前に 100 ナノ秒単位に変換します。クライアントがパフォーマンス カウンター値を必要としない場合、このパラメーターは NULL にすることができます。 詳細については、「解説」を参照してください。

戻り値

次の表に示す値には、可能なリターン コードが含まれますが、これらに限定されません。

注釈

このメソッドは、キャプチャ エンドポイント バッファーから次のデータ パケットを取得します。 特定の時点で、バッファーには、読み取る準備ができている 0 個、1 つ以上のパケットが含まれる場合があります。 通常、キャプチャ エンドポイント バッファーからデータを読み取るバッファー処理スレッドは、スレッドが実行されるたびに使用可能なすべてのパケットを読み取ります。

オーディオ キャプチャ ストリームの処理中に、クライアント アプリケーションは GetBuffer メソッドと IAudioCaptureClient::ReleaseBuffer メソッドを交互に呼び出します。 クライアントは、 GetBuffer 呼び出しごとに 1 つ以上のデータ パケットを読み取ることができます。 GetBuffer の各呼び出しの後、クライアントは ReleaseBuffer を呼び出してパケットを解放する必要があります。その後、クライアントは GetBuffer を再度呼び出して次のパケットを取得できます。

GetBuffer または ReleaseBuffer への 2 つ以上の連続する呼び出しは許可されず、エラー コード AUDCLNT_E_OUT_OF_ORDERで失敗します。 呼び出しの正しい順序を確認するには、 GetBuffer 呼び出しとそれに対応する ReleaseBuffer 呼び出しが同じスレッドで発生する必要があります。

GetBuffer 呼び出しのたびに、呼び出し元はパケット全体を取得するか、いずれも取得しない必要があります。 パケットを読み取る前に、呼び出し元はパケット サイズ (pNumFramesToRead パラメーターで使用可能) をチェックして、パケット全体を格納するのに十分なスペースがあることを確認できます。

ReleaseBuffer 呼び出しのたびに、呼び出し元はバッファーから読み取ったオーディオ フレームの数を報告します。 この数値は、(0 以外の) パケット サイズまたは 0 のいずれかである必要があります。 数値が 0 の場合、次の GetBuffer 呼び出しでは、前の GetBuffer 呼び出しと同じパケットを呼び出し元に表示します。

各 GetBuffer 呼び出しの後、パケット内のデータは、次の ReleaseBuffer 呼び出しによってバッファーが解放されるまで有効なままになります。

クライアントは、0 以外の任意のサイズのパケットを正常に取得する GetBuffer 呼び出しの後に ReleaseBuffer を呼び出す必要があります。 クライアントには、サイズ 0 のパケットを解放するために ReleaseBuffer を呼び出すか呼び出さないかのオプションがあります。

メソッドは、 pu64DevicePosition 出力パラメーターと pu64QPCPosition 出力パラメーターを使用して、デバイスの位置とパフォーマンス カウンター を 出力します。 これらの値は、データ パケット内の最初のオーディオ フレームのタイム スタンプを提供します。 pdwFlags 出力パラメーターを使用して、 メソッドは、報告されたデバイスの位置が有効かどうかを示します。

メソッドが *pu64DevicePosition に書き込むデバイスの位置は、スピーカー (レンダリング ストリームの場合) またはマイク (キャプチャ ストリームの場合) を介して現在再生されているオーディオ フレームのストリーム相対位置です。 位置は、ストリームの先頭からのフレーム数として表されます。 オーディオ ストリーム内のフレームのサイズは、ストリーム形式を指定する WAVEFORMATEX (または WAVEFORMATEXTENSIBLE) 構造体の nBlockAlign メンバーによって指定されます。 オーディオ フレームのサイズ (バイト単位) は、ストリーム内のチャネルの数にチャネルあたりのサンプル サイズを掛けた値と等しくなります。 たとえば、16 ビット サンプルを含むステレオ (2 チャネル) ストリームの場合、フレーム サイズは 4 バイトです。

GetBuffer が *pu64QPCPosition に書き込むパフォーマンス カウンター値は、QueryPerformanceCounter 関数から取得された生のカウンター値ではありません。 t が生カウンター値で、f が QueryPerformanceFrequency 関数から取得された頻度の場合、GetBuffer はパフォーマンス カウンター値を次のように計算します。

*pu64QPCPosition = 10,000,000^。T/F

結果は 100 ナノ秒単位で表されます。 QueryPerformanceCounter と QueryPerformanceFrequency の詳細については、Windows SDK のドキュメントを参照してください。

現在使用できる新しいパケットがない場合、メソッドは *pNumFramesToRead = 0 を設定し、状態コード AUDCLNT_S_BUFFER_EMPTYを返します。 この場合、 メソッドは、ppData、pu64DevicePosition、および pu64QPCPosition パラメーターによって指される変数に書き込まれません。

クライアントは、パケットを取得する GetBuffer 呼び出しと、パケットを 解放する ReleaseBuffer 呼び出しの間の過度の遅延を回避する必要があります。 オーディオ エンジンの実装では、 GetBuffer 呼び出しと対応する ReleaseBuffer 呼び出しが同じバッファー処理期間内に発生することを前提としています。 パケットのリリースを複数の期間遅延するクライアントは、サンプル データを失うリスクがあります。

Windows 7 以降では、 GetBuffer は、排他的モードでエンドポイント バッファーを使用するオーディオ クライアントの AUDCLNT_E_BUFFER_ERROR エラー コードを返すことができます。 このエラーは、データ パケットが使用できなかった (*ppData が NULL を受け取った) ため、データ バッファーが取得されなかったことを示します。

GetBuffer が AUDCLNT_E_BUFFER_ERRORを返す場合、オーディオ サンプルを使用するスレッドは、次の処理パスを待機する必要があります。 クライアントは、失敗した GetBuffer 呼び出しの数を保持することでメリットが得られる場合があります。 GetBuffer がこのエラーを繰り返し返し返す場合、クライアントは IAudioClient::Stop、IAudioClient::Reset を呼び出し、オーディオ クライアントを解放することで、現在のクライアントをシャットダウンした後に新しい処理ループを開始できます。

例

GetBuffer メソッドを呼び出すコード例については、「Streamのキャプチャ」を参照してください。

要件

こちらもご覧ください

IAudioCaptureClient インターフェイス

IAudioCaptureClient::ReleaseBuffer

IAudioClient::GetMixFormat

IAudioClock::GetPosition