EVT_ACX_STREAM_SET_RENDER_PACKET callback function (acxstreams.h)

Article
08/06/2024

The EvtAcxStreamSetRenderPacket event tells the driver which packet was just released by the client.

If there are no glitches, this packet should be (CurrentRenderPacket + 1), where CurrentRenderPacket is the packet the driver is currently streaming from. The driver should continue to increase the CurrentRenderPacket as packets are rendered instead of changing its CurrentRenderPacket to match this value. The property will include the packet index (0-based) and, if appropriate, an EOS flag with the byte offset of the end of the stream in the current packet.

Syntax

EVT_ACX_STREAM_SET_RENDER_PACKET EvtAcxStreamSetRenderPacket;

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

Parameters

Stream

An ACXSTREAM object represents an audio stream created by a circuit. For more information, see ACX - Summary of ACX Objects.

Packet

The number of the packet written by the OS to the WaveRT buffer. Depending on the values provided by the driver to AcxRtStreamNotifyPacketComplete, the Packet number may skip values.

Flags

Flags can be 0 or KSSTREAM_HEADER_OPTIONSF_ENDOFSTREAM = 0x200, indicating the Packet is the last packet in the stream, and EosPacketLength is a valid length in bytes for the packet. For more information see OptionsFlags in KSSTREAM_HEADER structure (ks.h).

EosPacketLength

The length of the EOS packet if KSSTREAM_HEADER_OPTIONSF_ENDOFSTREAM = 0x200 is specified in Flags. Zero is a valid value. If KSSTREAM_HEADER_OPTIONSF_ENDOFSTREAM is not specified in Flags, this parameter should be ignored. The EosPacketLength is measured in bytes.

Return value

Returns STATUS_SUCCESS if the call was successful. Otherwise, it returns an appropriate error code. For more information, see Using NTSTATUS Values.

STATUS_DATA_LATE_ERROR – The driver returns this error if the OS passes a packet number that has already transferred or is currently transferring. In this case, a glitch condition has occurred. The driver may optionally use some of the data from the packet or continue playing out the data previously written to this packet number.

STATUS_DATA_OVERRUN – The driver returns this error if the OS passes a packet number that is higher than can be stored in the WaveRT buffer. In this case, a glitch condition has occurred. The driver may optionally ignore the data in the packet.

STATUS_INVALID_DEVICE_STATE – The driver returns this error if the OS calls this routine after previously setting the KSSTREAM_HEADER_OPTIONSF_ENDOFSTREAM flag.

STATUS_INVALID_PARAMETER – The driver returns this error if it finds any other parameter invalid, aside from the specific cases for other error status. This includes any Flag values not specifically defined above.

Remarks

After the OS calls this routine, the driver may optionally use the provided information to optimize the hardware transfer. For example, the driver might optimize DMA transfers, or program hardware to stop transfer at the end of the specified packet in case the OS does not call this routine again to inform the driver of another packet. This can mitigate audible effects of underflow, for example introducing an audible gap rather than repeating a circular buffer. The driver however is still obligated to increase its internal packet counter and signal notification events at a nominal real time rate.

Depending on hardware capabilities, if the KSSTREAM_HEADER_OPTIONSF_ENDOFSTREAM flag is specified, the driver may silence-fill a portion of the WaveRT buffer that follows the EOS packet in case the hardware transfers data beyond the EOS position.

The client starts by pre-rolling a buffer. When the client calls ReleaseBuffer, this will translate to a call in AudioKSE that will call into the ACX layer, which will call EvtAcxStreamSetRenderPacket on the active ACXSTREAM. The property will include the packet index (0-based) and, if appropriate, an EOS flag with the byte offset of the end of the stream in the current packet.   

Example

Example usage is shown below.

    //
    // 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 requirements

Minimum ACX version: 1.0

For more information about ACX versions, see ACX version overview.

Requirements

Requirement	Value
Header	acxstreams.h
IRQL	PASSIVE_LEVEL

Share via