IMiniportWaveCyclicStream::GetPosition メソッド (portcls.h)

[アーティクル]
03/05/2024

メソッドは GetPosition 、ストリームの現在位置を取得します。

構文

NTSTATUS GetPosition(
  [out] PULONG Position
);

パラメーター

[out] Position

位置値の出力ポインター。このパラメーターは、メソッドがストリームの現在のバイト位置を書き込む呼び出し元によって割り当てられた変数を指します。

戻り値

GetPosition は、呼び出しが成功した場合にSTATUS_SUCCESSを返します。それ以外の場合、メソッドは適切なエラーコードを返します。

注釈

GetPosition は、ストリームの現在の再生位置またはレコード位置を報告します。位置は、DMA バッファーの先頭からのバイトオフセットとして表され、DAC または ADC で現在データのバイト位置のミニポートドライバーの最適な推定値を表します。

ストリームの初期化直後の位置は 0 です。 KSSTATE_STOP状態に遷移すると ( KSSTATE を参照)、位置が 0 にリセットされます。 KSSTATE_RUNからKSSTATE_PAUSEまたはKSSTATE_ACQUIREへの切り替えによってストリームが停止すると、位置がフリーズします。ストリームが KSSTATE_PAUSE から切り替わるか、KSSTATE_RUNに戻KSSTATE_ACQUIREすると、フリーズが解除されます。

GetPosition は、サイクリックバッファーへのオフセットとして位置を指定します。位置が循環バッファーの末尾に達すると、バッファーの先頭に折り返されます。そのため、位置がバッファーサイズを超えることはありません。

呼び出しによって GetPosition 取得されるオフセット値は、次のいずれかであることに注意してください。

レンダーストリームの場合、 GetPosition メソッドは再生位置を取得します。これは、DAC を介して現在再生され、スピーカージャックを介して送信されているサンプルのバイトオフセットです。
キャプチャストリームの場合、 GetPosition メソッドは、マイクジャックを介して受信し、ADC によってキャプチャされる最新のサンプルのバイトオフセットであるレコード位置を取得します。

オーディオデバイスの DMA エンジンが現在オーディオバッファーから読み取ったり、オーディオバッファーに書き込んだりしているサンプルのオフセットではありません。

一部のオーディオハードウェアには、各 DAC または ADC で現在サンプルのバイトオフセットを追跡するための位置レジスタが含まれています。この場合 GetPosition 、メソッドは適切なストリームの位置レジスタの内容を取得するだけです。その他のオーディオハードウェアは、DMA ポインターをオーディオバッファーにドライバーを提供することしかできません。この場合 GetPosition 、メソッドは、現在の DMA 位置とデバイス内部のバッファリング遅延に基づいて DAC または ADC のバイトオフセットの最適な見積もりを提供する必要があります。

再生ストリームまたはキャプチャストリームの一部を内部的にバッファーするオーディオハードウェアでは、正確な位置の読み取りが困難になる場合があります。この場合、ドライバーは可能な限り正確に現在の位置を推定する必要があります。たとえば、オーディオデバイスが再生ストリームを内部バッファーにプリフェッチする場合、ドライバーは、再生位置を適切に推定するためにバッファーサイズとタイミング情報の両方を考慮する必要がある場合があります。

WaveCyclic ポートドライバーは、 KSPROPERTY_AUDIO_POSITIONのプロパティハンドラーを実装します。このプロパティハンドラーは、メソッドを GetPosition 呼び出して、ミニポートドライバーから現在の再生位置またはレコード位置を取得します。詳細については、「 Audio Position プロパティ」を参照してください。