IAudioRenderClient::GetBuffer メソッド (audioclient.h)
呼び出し元がデータ パケットを書き込むことができるレンダリング エンドポイント バッファー内の次の使用可能な領域へのポインターを取得します。
構文
HRESULT GetBuffer(
[in] UINT32 NumFramesRequested,
[out] BYTE **ppData
);
パラメーター
[in] NumFramesRequested
呼び出し元がバッファー内の要求された領域に書き込む予定のデータ パケット内のオーディオ フレームの数。 呼び出しが成功した場合、 *ppData が指すバッファー領域のサイズは 、NumFramesRequested で指定されたサイズと一致します。
[out] ppData
メソッドが、呼び出し元がデータ パケットを書き込むバッファー領域の開始アドレスを書き込むポインター変数へのポインター。
戻り値
メソッドが成功した場合は、S_OK を返します。 失敗した場合、次の表に示す値が含まれますが、これに限定されません。
| リターン コード | 説明 |
|---|---|
|
GetBuffer はデータ バッファーの取得に失敗し、*ppData は NULL を指しています。 詳細については、「解説」を参照してください。 |
|
NumFramesRequested 値が、使用可能なバッファー領域 (バッファー サイズからパディング サイズを引いた値) を超えています。 |
|
ストリームは排他モードであり、イベント ドリブン バッファリングを使用しますが、クライアントはバッファーのサイズではないパケットを取得しようとしました。 |
|
以前の IAudioRenderClient::GetBuffer 呼び出しはまだ有効です。 |
|
オーディオ エンドポイント デバイスが取り外されているか、オーディオ ハードウェアまたは関連するハードウェア リソースが再構成、無効、削除、またはその他の方法で使用できなくなります。 |
|
ストリームのリセットが進行中のため、バッファーにアクセスできません。 |
|
Windows オーディオ サービスが実行されていません。 |
|
パラメーター 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 |