EVT_ACX_STREAM_SET_RENDER_PACKET コールバック関数 (acxstreams.h)

  • [アーティクル]

EvtAcxStreamSetRenderPacket イベントは、クライアントによって解放されたパケットをドライバーに通知します。

障害がない場合、このパケットは (CurrentRenderPacket + 1) にする必要があります。CurrentRenderPacket は、ドライバーが現在ストリーミングしているパケットです。 この値に一致するように CurrentRenderPacket を変更するのではなく、パケットがレンダリングされるため、ドライバーは引き続き CurrentRenderPacket を増やす必要があります。 このプロパティには、パケット インデックス (0 ベース) と、必要に応じて、現在のパケット内のストリームの末尾のバイト オフセットを含む EOS フラグが含まれます。

構文

EVT_ACX_STREAM_SET_RENDER_PACKET EvtAcxStreamSetRenderPacket;

NTSTATUS EvtAcxStreamSetRenderPacket(
  ACXSTREAM Stream,
  ULONG Packet,
  ULONG Flags,
  ULONG EosPacketLength
)
{...}

パラメーター

Stream

ACXSTREAM オブジェクトは、回線によって作成されたオーディオ ストリームを表します。 詳細については、ACX - ACX オブジェクトの概要を参照してください。

Packet

OS によって WaveRT バッファーに書き込まれたパケットの数。 AcxRtStreamNotifyPacketCompleteを するためにドライバーによって提供される値に応じて、パケット番号は値をスキップすることがあります。

Flags

フラグは 0 または KSSTREAM_HEADER_OPTIONSF_ENDOFSTREAM = 0x200で、パケットがストリームの最後のパケットであることを示し、EosPacketLength はパケットの有効な長さ (バイト単位) です。 詳細については、「KSSTREAM_HEADER 構造体 (ks.h)の OptionsFlags を参照してください。

EosPacketLength

フラグで KSSTREAM_HEADER_OPTIONSF_ENDOFSTREAM = 0x200 が指定されている場合の EOS パケットの長さ。 ゼロは有効な値です。 フラグで KSSTREAM_HEADER_OPTIONSF_ENDOFSTREAM が指定されていない場合、このパラメーターは無視する必要があります。 EosPacketLength はバイト単位で測定されます。

戻り値

呼び出しが成功した場合に STATUS_SUCCESS を返します。 それ以外の場合は、適切なエラー コードが返されます。 詳細については、NTSTATUS 値の使用に関する を参照してください。

STATUS_DATA_LATE_ERROR – OS が既に転送済みまたは現在転送中のパケット番号を渡した場合、ドライバーはこのエラーを返します。 この場合、グリッチ状態が発生しました。 必要に応じて、ドライバーは、パケットからのデータの一部を使用するか、このパケット番号に書き込まれたデータの再生を続行できます。

STATUS_DATA_OVERRUN – ドライバーは、OS が WaveRT バッファーに格納できるよりも大きいパケット番号を渡した場合に、このエラーを返します。 この場合、グリッチ状態が発生しました。 ドライバーは、必要に応じてパケット内のデータを無視できます。

STATUS_INVALID_DEVICE_STATE – 以前に KSSTREAM_HEADER_OPTIONSF_ENDOFSTREAM フラグを設定した後に OS がこのルーチンを呼び出した場合、ドライバーはこのエラーを返します。

STATUS_INVALID_PARAMETER – ドライバーは、他のエラー状態の特定のケースを除いて、無効な他のパラメーターが見つかると、このエラーを返します。 これには、上記で特に定義されていないフラグ値が含まれます。

備考

OS がこのルーチンを呼び出した後、ドライバーは必要に応じて提供された情報を使用してハードウェア転送を最適化できます。 たとえば、ドライバーは DMA 転送を最適化したり、OS が別のパケットをドライバーに通知するためにこのルーチンを再度呼び出さない場合に、指定されたパケットの最後に転送を停止するようにハードウェアをプログラムする場合があります。 これにより、循環バッファーを繰り返すのではなく、可聴ギャップを導入するなど、アンダーフローの可聴効果を軽減できます。 ただし、ドライバーは、内部パケット カウンターを増やし、通知イベントをわずかなリアルタイム レートで通知する義務を引き続き負います。

ハードウェアの機能によっては、KSSTREAM_HEADER_OPTIONSF_ENDOFSTREAM フラグが指定されている場合、ハードウェアが EOS 位置を超えてデータを転送する場合に備えて、ドライバーは EOS パケットに続く WaveRT バッファーの一部を無音にする場合があります。

クライアントは、まずバッファーを事前にローリングします。 クライアントが ReleaseBuffer を呼び出すと、これは、アクティブな ACXSTREAM で EvtAcxStreamSetRenderPacket を呼び出す ACX レイヤーを呼び出す AudioKSE の呼び出しに変換されます。 このプロパティには、パケット インデックス (0 ベース) と、必要に応じて、現在のパケット内のストリームの末尾のバイト オフセットを含む EOS フラグが含まれます。   

例

使用例を次に示します。

    //
    // Init RT streaming callbacks.
    //
    ACX_RT_STREAM_CALLBACKS rtCallbacks;
    ACX_RT_STREAM_CALLBACKS_INIT(&rtCallbacks);

    rtCallbacks.EvtAcxStreamSetRenderPacket = EvtStreamSetRenderPacket;

    status = AcxStreamInitAssignAcxRtStreamCallbacks(StreamInit, &rtCallbacks);

#pragma code_seg("PAGE")
NTSTATUS
EvtStreamSetRenderPacket(
    _In_ ACXSTREAM Stream,
    _In_ ULONG     Packet,
    _In_ ULONG     Flags,
    _In_ ULONG     EosPacketLength
    )
{
    PSTREAM_CONTEXT ctx;
    NTSTATUS        status = STATUS_SUCCESS;

    PAGED_CODE();

    ctx = GetStreamContext(Stream);

    currentPacket = (ULONG)InterlockedCompareExchange((LONG*)&ctx->m_CurrentPacket, -1, -1);

    if (Packet <= currentPacket)
    {
        status = STATUS_DATA_LATE_ERROR;
    }
    else if (Packet > currentPacket + 1)
    {
        status = STATUS_DATA_OVERRUN;
    }

    return status;
}

ACX の要件

最小 ACX バージョン: 1.0

ACX バージョンの詳細については、ACX バージョンの概要参照してください。

必要条件

要件 価値
ヘッダー acxstreams.h
IRQL PASSIVE_LEVEL

関連項目

  • acxstreams.h ヘッダー を する