KSPROPERTY_RTAUDIO_POSITIONREGISTER
The KSPROPERTY_RTAUDIO_POSITIONREGISTER property maps the position register of an audio device for a particular stream into a virtual memory location that the client can access.
The following table summarizes the features of this property.
Usage Summary Table
| Get | Set | Target | Property descriptor type | Property value type |
|---|---|---|---|---|
Yes |
No |
Pin |
The property descriptor (instance data) is a KSRTAUDIO_HWREGISTER_PROPERTY structure, which contains a KSPROPERTY structure. Before sending the request, the client loads the structure with values that indicate the preferred base address for the register.
The property value (operation data) is a KSRTAUDIO_HWREGISTER structure into which the property handler writes the virtual address to which it has mapped the hardware position register. The client can directly read the register from this address. The KSRTAUDIO_HWREGISTER structure also specifies the rate at which the position register increments itself.
Return Value
A KSPROPERTY_RTAUDIO_POSITIONREGISTER property request returns STATUS_SUCCESS to indicate that it has completed successfully. Otherwise, the request returns an appropriate failure status code.
Remarks
Typically, audio applications must monitor the current position of an audio stream. This position is specified as a byte offset from the beginning of the stream:
In the case of a rendering stream, the stream's position is the byte offset of the audio frame that is currently playing through the digital-to-analog converters (DACs).
In the case of a capture stream, the stream's position is the byte offset of the audio frame that is currently being recorded through the analog-to-digital converters (ADCs).
Some audio devices contain position registers that increment continually while the stream is running. For an audio device that incorporates all digital and analog functions into a single chip, the position register typically indicates the current stream position directly.
However, for a chipset that divides digital and analog functions into separate bus-controller and codec chips, the position register is typically located in the bus-controller chip and indicates the following:
In the case of a rendering stream, the position register indicates the byte offset of the last audio frame that the bus controller wrote to the codec.
In the case of a capture stream, the position register indicates the byte offset of the last audio frame that the bus controller read from the codec.
In both cases, the position register value does not include the delay through the codec. If the client has determined the codec delay, it can add this delay to the position register value to estimate the true stream position (at the DACs or ADCs). For a CodecDelay value that specifies the worst-case delay through the codec, you can query the KSPROPERTY_RTAUDIO_HWLATENCY property.
If successful, a KSPROPERTY_RTAUDIO_POSITIONREGISTER property request maps the position register to a virtual memory address that is accessible to the client from either user-mode or kernel-mode, as specified by the client. Thereafter, the client reads from this address to obtain the current value of the position register.
The property request fails if the audio hardware does not support a position register that can be mapped to a virtual address. In this case, the client must determine the position from the KSPROPERTY_AUDIO_POSITION property.
The mapping of the position register is destroyed when the pin closes. The client can map the register only once in the lifetime of an opened pin, and any subsequent call to remap the position register for the pin fails.
It is typically faster to read the position register than it is to send a KSPROPERTY_AUDIO_POSITION request, which requires transitions between user-mode and kernel-mode for user-mode clients.
Requirements
Version |
Available in Windows Vista and later Windows operating systems. |
Header |
Ksmedia.h |
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for