IAudioClient::GetCurrentPadding メソッド (audioclient.h)

  • [アーティクル]

GetCurrentPadding メソッドは、エンドポイント バッファー内のパディングのフレーム数を取得します。

構文

HRESULT GetCurrentPadding(
  [out] UINT32 *pNumPaddingFrames
);

パラメーター

[out] pNumPaddingFrames

メソッドがフレーム数 (バッファー内のパディングのオーディオ フレームの数) を書き込む UINT32 変数へのポインター。

戻り値

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

リターン コード 説明
AUDCLNT_E_NOT_INITIALIZED
 オーディオ ストリームが正常に初期化されていません。
AUDCLNT_E_DEVICE_INVALIDATED
 オーディオ エンドポイント デバイスが取り外されているか、オーディオ ハードウェアまたは関連するハードウェア リソースが再構成、無効、削除、またはその他の方法で使用できなくなります。
AUDCLNT_E_SERVICE_NOT_RUNNING
 Windows オーディオ サービスが実行されていません。
E_POINTER
 パラメーター pNumPaddingFrames が NULL です。

注釈

このメソッドでは、 IAudioClient インターフェイスを事前に初期化する必要があります。 クライアントが IAudioClient::Initialize メソッドを正常に呼び出してオーディオ ストリームを初期化するまで、このメソッドの呼び出しはすべてエラー AUDCLNT_E_NOT_INITIALIZEDで失敗します。

このメソッドは、エンドポイント バッファーに現在含まれている有効な未読データの量を示すパディング値を取得します。 レンダリング アプリケーションでは、埋め込み値を使用して、オーディオ エンジンがまだバッファーから読み取っていない以前に書き込まれたデータを上書きすることなく、エンドポイント バッファーに安全に書き込むことができる新しいデータの量を決定できます。 キャプチャ アプリケーションでは、埋め込み値を使用して、オーディオ エンジンがまだ有効なデータを書き込んでいないバッファーの領域から無効なデータを読み取ることなく、エンドポイント バッファーから安全に読み取ることができる新しいデータの量を決定できます。

埋め込み値は、オーディオ フレームの数として表されます。 オーディオ フレームのサイズは、クライアントが IAudioClient::Initialize メソッドに渡した WAVEFORMATEX (または WAVEFORMATEXTENSIBLE) 構造体の nBlockAlign メンバーによって指定されます。 オーディオ フレームのサイズ (バイト単位) は、ストリーム内のチャネルの数にチャネルあたりのサンプル サイズを掛けた値と等しくなります。 たとえば、16 ビット サンプルを含むステレオ (2 チャネル) ストリームの場合、フレーム サイズは 4 バイトです。

共有モードのレンダリング ストリームの場合、 GetCurrentPadding によって報告される埋め込み値は、エンドポイント バッファーで再生するためにキューに入れられたオーディオ フレームの数を指定します。 エンドポイント バッファーに書き込む前に、クライアントはバッファーの長さからパディング値を減算することで、バッファー内の使用可能な領域の量を計算できます。 IAudioRenderClient::GetBuffer メソッドの後続の呼び出しが成功するように、クライアントはバッファー内の使用可能な領域を超えないパケット長を要求する必要があります。 バッファーの長さを取得するには、 IAudioClient::GetBufferSize メソッドを 呼び出します。

共有モードキャプチャ ストリームの場合、 GetCurrentPadding によって報告されるパディング値は、エンドポイント バッファー内の次のパケットで使用可能なキャプチャ データのフレーム数を指定します。 特定の時点で、キャプチャ データの 0 個、1 つ以上のパケットが、クライアントがバッファーから読み取る準備が整う可能性があります。 現在使用可能なパケットがない場合、メソッドはパディング値 0 を報告します。 GetCurrentPadding 呼び出しの後、IAudioCaptureClient::GetBuffer メソッド呼び出しは、GetCurrentPadding によって報告されたパディング値と正確に等しい長さのパケットを取得します。 GetBuffer を呼び出すたびに、パケット全体が取得されます。 パケットには常に、オーディオ フレームの整数が含まれます。

共有モードキャプチャ ストリームの場合、 GetCurrentPadding の 呼び出しは 、IAudioCaptureClient::GetNextPacketSize メソッドの呼び出しと同じです。 つまり、 GetCurrentPadding によって報告されるパディング値は、 GetNextPacketSize によって報告されるパケット長と等しくなります。

AUDCLNT_STREAMFLAGS_EVENTCALLBACK フラグを使用して初期化された排他モードレンダリングまたはキャプチャ ストリームの場合、通常、クライアントは GetCurrentPadding によって報告されるパディング値に使用されません。 代わりに、クライアントは各処理パスの間にバッファー全体にアクセスします。 バッファーが処理に使用できるようになるたびに、オーディオ エンジンはクライアントのイベント ハンドルに通知することでクライアントに通知します。 このフラグの詳細については、「 IAudioClient::Initialize」を参照してください。

AUDCLNT_STREAMFLAGS_EVENTCALLBACK フラグで初期化されていない排他モードレンダリングまたはキャプチャ ストリームの場合、クライアントは GetCurrentPadding から取得したパディング値を、共有モード ストリームに対して前述したのと同様の方法で使用できます。 詳細は以下の通り。

最初に、排他モードのレンダリング ストリームの場合、埋め込み値は、エンドポイント バッファーで再生するためにキューに入れられたオーディオ フレームの数を指定します。 前と同様に、クライアントはバッファーの長さからパディング値を減算することで、バッファー内の使用可能な領域の量を計算できます。

次に、排他モード キャプチャ ストリームの場合、 GetCurrentPadding によって報告されるパディング値は、次のパケットの現在の長さを指定します。 ただし、このパディング値はパケット長のスナップショットであり、クライアントが IAudioCaptureClient::GetBuffer メソッドを呼び出す前に増加する可能性があります。 したがって、GetBuffer によって取得されるパケットの長さは、少なくとも GetBuffer 呼び出しの前に GetCurrentPadding 呼び出しによって報告される埋め込み値よりも大きくなる可能性があります。 これに対し、共有モード キャプチャ ストリームの場合、 GetBuffer から取得されたパケットの長さは、常に、前の GetCurrentPadding 呼び出しによって報告されたパディング値と等しくなります。

GetCurrentPadding メソッドを呼び出すコード例については、「Streamのレンダリング」を参照してください。

要件

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

こちらもご覧ください

IAudioCaptureClient::GetBuffer

IAudioCaptureClient::GetNextPacketSize

IAudioClient インターフェイス

IAudioClient::Initialize

IAudioRenderClient::GetBuffer