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

[アーティクル]
02/23/2024

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 ナノ秒の時間単位に変換します。

生のカウンター値に 10,000,000 を乗算します。
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

こちらもご覧ください

IAudioClock::GetFrequency

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

構文

パラメーター

戻り値

注釈

要件

こちらもご覧ください

フィードバック

フィードバック

その他のリソース