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

[アーティクル]
03/14/2023

呼び出し元がデータパケットを書き込むことができるレンダリングエンドポイントバッファー内の次の使用可能な領域へのポインターを取得します。

構文

HRESULT GetBuffer(
  [in]  UINT32 NumFramesRequested,
  [out] BYTE   **ppData
);

パラメーター

[in] NumFramesRequested

呼び出し元がバッファー内の要求された領域に書き込む予定のデータパケット内のオーディオフレームの数。呼び出しが成功した場合、 *ppData が指すバッファー領域のサイズは 、NumFramesRequested で指定されたサイズと一致します。

[out] ppData

メソッドが、呼び出し元がデータパケットを書き込むバッファー領域の開始アドレスを書き込むポインター変数へのポインター。

戻り値

メソッドが成功した場合は、S_OK を返します。失敗した場合、次の表に示す値が含まれますが、これに限定されません。

リターンコード	説明
AUDCLNT_E_BUFFER_ERROR	GetBuffer はデータバッファーの取得に失敗し、*ppData は NULL を指しています。詳細については、「解説」を参照してください。
AUDCLNT_E_BUFFER_TOO_LARGE	NumFramesRequested 値が、使用可能なバッファー領域 (バッファーサイズからパディングサイズを引いた値) を超えています。
AUDCLNT_E_BUFFER_SIZE_ERROR	ストリームは排他モードであり、イベントドリブンバッファリングを使用しますが、クライアントはバッファーのサイズではないパケットを取得しようとしました。
AUDCLNT_E_OUT_OF_ORDER	以前の IAudioRenderClient::GetBuffer 呼び出しはまだ有効です。
AUDCLNT_E_DEVICE_INVALIDATED	オーディオエンドポイントデバイスが取り外されているか、オーディオハードウェアまたは関連するハードウェアリソースが再構成、無効、削除、またはその他の方法で使用できなくなります。
AUDCLNT_E_BUFFER_OPERATION_PENDING	ストリームのリセットが進行中のため、バッファーにアクセスできません。
AUDCLNT_E_SERVICE_NOT_RUNNING	Windows オーディオサービスが実行されていません。
E_POINTER	パラメーター ppData は NULL です。

注釈

呼び出し元は、バッファー内の使用可能な領域の量以下のパケットサイズを要求できます (イベントドリブンバッファリングを使用する排他モードストリームの場合を除きます)。詳細については、「 IAudioClient::Initialize」を参照してください。使用可能な領域は、単にバッファーサイズから、再生するために既にキューに登録されているバッファー内のデータの量を差し引いた値です。呼び出し元がバッファー内の使用可能な領域を超える NumFramesRequested 値を指定した場合、呼び出しは失敗し、エラーコード AUDCLNT_E_BUFFER_TOO_LARGEを返します。

クライアントは、オーディオストリームでグリッチが発生しないように、バッファーに十分な量のデータを書き込む必要があります。バッファリングの要件の詳細については、「 IAudioClient::Initialize」を参照してください。

GetBuffer を呼び出してデータパケットを取得した後、クライアントはパケットにレンダリングデータを入力し、IAudioRenderClient::ReleaseBuffer メソッドを呼び出してオーディオエンジンにパケットを発行します。

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

0 以外のパケットサイズの場合、クライアントは GetBuffer と ReleaseBuffer を交互に呼び出す必要があります。各 GetBuffer 呼び出しの後に、対応する ReleaseBuffer 呼び出しが続く必要があります。クライアントが GetBuffer を 呼び出してデータパケットを取得した後、クライアントは ReleaseBuffer を呼び出して前のパケットを解放するまで、次のデータパケットを取得できません。 GetBuffer または ReleaseBuffer への 2 つ以上の連続する呼び出しは許可されず、エラーコード AUDCLNT_E_OUT_OF_ORDERで失敗します。

呼び出しの正しい順序を確認するには、 GetBuffer 呼び出しとそれに対応する ReleaseBuffer 呼び出しが同じスレッドで発生する必要があります。

オーディオフレームのサイズは、クライアントが IAudioClient::GetMixFormat メソッドを呼び出して取得する WAVEFORMATEX 構造体の nBlockAlign メンバーによって指定されます。

呼び出し元が NumFramesRequested = 0 を設定した場合、メソッドは状態コード S_OKを返しますが、 ppData パラメーターが指す変数には書き込まれません。

クライアントは、バッファーを取得する 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 メソッドを呼び出すコード例については、次のトピックを参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows Vista [デスクトップアプリのみ \| UWP アプリ]
サポートされている最小のサーバー	Windows Server 2008 [デスクトップアプリ \| UWP アプリ]
対象プラットフォーム	Windows
ヘッダー	audioclient.h