IAudioClock::GetPosition メソッド (audioclient.h)

  • [アーティクル]

GetPosition メソッドは、現在のデバイス位置を取得します。

構文

HRESULT GetPosition(
  [out] UINT64 *pu64Position,
  [out] UINT64 *pu64QPCPosition
);

パラメーター

[out] pu64Position

メソッドがデバイスの位置を書き込む UINT64 変数へのポインター。 デバイスの位置は、ストリームの先頭からストリーム内の現在位置までのオフセットです。 ただし、このオフセットが表される単位は未定義です。デバイスの位置の値は、 IAudioClock::GetFrequency メソッドによって報告される頻度に関連してのみ意味します。 詳細については、「解説」を参照してください。

[out] pu64QPCPosition

GetPosition 呼び出しに応答してオーディオ エンドポイント デバイスがデバイスの位置 (*pu64Position) を読み取った時点で、メソッドがパフォーマンス カウンターの値を書き込む UINT64 変数へのポインター。 メソッドは、カウンター値を *pu64QPCPosition に書き込む前に、100 ナノ秒の時間単位に変換します。 クライアントがパフォーマンス カウンター値を必要としない場合、このパラメーターは NULL にすることができます。

戻り値

メソッドが成功し、位置の正確な読み取りを取得すると、S_OKが返されます。 メソッドが成功したが、呼び出しの継続時間が位置の読み取りの精度を損なうのに十分な長さである場合、メソッドはS_FALSEを返します。 エラーが発生した場合、次の表に示す値が、可能なリターン コードに含まれますが、これらに限定されません。

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

注釈

ストリームの現在の再生またはレコード位置に基づいてクロックを公開する必要があるクライアントをレンダリングまたはキャプチャすると、このメソッドを使用してそのクロックを派生させることができます。

このメソッドは、次の 2 つの相関ストリーム位置値を取得します。

  • デバイスの位置。 クライアントは、出力パラメーター pu64Position を使用してデバイスの位置を取得します。 これは、現在スピーカーを介して再生されている (レンダリング ストリームの場合)、またはマイク (キャプチャ ストリームの場合) を介して記録されているサンプルのストリーム位置です。
  • パフォーマンス カウンター。 クライアントは、出力パラメーター pu64QPCPosition を使用してパフォーマンス カウンターを取得します。 これは、オーディオ エンドポイント デバイスがストリーム位置 (*pu64Position) を記録した時点で QueryPerformanceCounter 関数を呼び出すことによって取得されたメソッドのカウンター値です。 GetPosition は、カウンター値を 100 ナノ秒の時間単位に変換します。
デバイスの位置は、 IAudioClock::GetFrequency メソッドによって報告されるデバイスの頻度と組み合わされない限り、意味がありません。 理由は、異なるストリームのデバイス位置が表されるユニットは、ストリームが共有モードで開かれたか排他モードで開かれたかなどの要因によって異なる可能性があるためです。 ただし、GetFrequency から得られる周波数 f は、常にデバイス位置 p のものと互換性のある単位で表されます。 したがって、ストリーム相対オフセットを秒単位で常に p/f として計算できます。

デバイスの位置は、ストリーム相対オフセットです。 つまり、ストリームの先頭からのオフセットとして指定されます。 デバイスの位置は、ストリーム全体を含み、最初から最後まで連続する理想的なバッファーへのオフセットと考えることができます。

GetPosition 呼び出し時のデバイスの位置とパフォーマンス カウンターを指定すると、クライアントは QueryPerformanceCounter を呼び出して現在のパフォーマンス カウンターを取得し、元のデバイス位置が記録されてからカウンターがどの程度進んだかに基づいてデバイスの位置を推定することで、少し後でデバイスの位置をよりタイムリーに見積もることができます。 クライアントは QueryPerformanceFrequency 関数を呼び出して、カウンターをインクリメントするクロックの頻度を決定できます。 QueryPerformanceCounter から取得した生カウンター値と、GetPosition によって *pu64QPCPosition に書き込まれた値を比較する前に、生カウンター値を次のように 100 ナノ秒の時間単位に変換します。

  1. 生のカウンター値に 10,000,000 を乗算します。
  2. QueryPerformanceFrequency から取得したカウンター頻度で結果を除算します。
QueryPerformanceCounter と QueryPerformanceFrequency の詳細については、Windows SDK のドキュメントを参照してください。

新しいストリームの作成直後に、デバイスの位置は 0 になります。 IAudioClient::Start メソッドの呼び出しの後、デバイスの位置は均一なレートでインクリメントされます。 IAudioClient::Stop メソッドはデバイスの位置を固定し、後続の Start 呼び出しでは、Stop 呼び出し時にその値からインクリメントを再開するデバイスの位置が発生します。 ストリームの停止中にのみ発生する IAudioClient::Reset の呼び出しは、デバイスの位置を 0 にリセットします。

新しいまたはリセットされたレンダリング ストリームが最初に実行を開始すると、オーディオ データがエンドポイント バッファーからレンダリング エンドポイント デバイスに伝達されるまで、デバイスの位置が数ミリ秒間 0 のままになることがあります。 デバイスを介してデータの再生が開始されると、デバイスの位置が 0 から 0 以外の値に変わります。

連続するデバイスの読み取り値は単調に増加しています。 デバイスの位置は、2 つの連続する読み取りの間で変更されない可能性がありますが、デバイスの位置が 1 つの読み取りから次の読み取りに減少することはありません。

pu64Position パラメーターは有効な NULL 以外のポインターである必要があります。または、 メソッドは失敗し、エラー コードE_POINTERを返します。

位置の測定は、断続的で優先度の高いイベントによって遅延する場合があります。 これらのイベントは、オーディオとは無関係な場合があります。 排他モード ストリームの場合、メソッドが成功したが、呼び出しの継続時間が報告された位置の精度を損なうのに十分な長さである場合、メソッドはS_OKの代わりにS_FALSEを返すことができます。 この場合、呼び出し元はメソッドを再度呼び出して、(戻り値S_OKで示されているように) より正確な位置を取得しようとします。 ただし、呼び出し元は、メソッドが一貫してS_FALSEを返す場合に、無限ループでこのテストを実行しないようにする必要があります。

要件

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

こちらもご覧ください

IAudioClient::Reset

IAudioClient::Start

IAudioClient::Stop

IAudioClock インターフェイス

IAudioClock::GetFrequency