KSPROPERTY_RTAUDIO_BUFFER

The KSPROPERTY_RTAUDIO_BUFFER property specifies a driver-allocated cyclic buffer for audio data.

The following table summarizes the features of this property.

Usage Summary Table

Get	Set	Target	Property descriptor type	Property value type
Yes	No	Pin	KSRTAUDIO_BUFFER_PROPERTY	KSRTAUDIO_BUFFER

The property descriptor (instance data) consists of a KSRTAUDIO_BUFFER_PROPERTY structure that contains a KSPROPERTY structure along with other members. The client writes its requested buffer size into the structure. If the client does not have to work with a specific base address, it must specify the base address as NULL.

The property value (operation data) is a structure of type KSRTAUDIO_BUFFER. The driver fills this structure with the actual buffer size, base address, and memory barrier flag for the cyclic buffer that it has allocated.

Return Value

A KSPROPERTY_RTAUDIO_BUFFER property request returns STATUS_SUCCESS to indicate that it has completed successfully. Otherwise, the request returns an appropriate failure status code. The following table shows some of the possible failure status codes.

Status code	Meaning
STATUS_UNSUCCESSFUL	A cyclic buffer with the specified combination of buffer attributes cannot be allocated.
STATUS_INSUFFICIENT_RESOURCES	Memory for the buffer cannot be allocated.
STATUS_DEVICE_NOT_READY	The device is not ready

Remarks

The base address is the virtual memory address at the start of the cyclic buffer. The client can directly access the buffer at this address. The buffer is contiguous in virtual memory. The decision whether to make the buffer contiguous in physical memory is left up to the driver.

The client should set the base address in the property descriptor to NULL. The driver sets the base address in the property value to the virtual address of the allocated audio buffer.

Typically, audio hardware requires the audio buffer either to begin and end on sample boundaries or meet other types of hardware-dependent alignment constraints. If sufficient memory is available, the actual size of the buffer is the requested size rounded (up or down) to the nearest sample or other hardware-constrained boundary. The actual size must be at least the requested size; otherwise, the Audio Session API (WASAPI) audio engine won't use the buffer, and stream creation will fail.

If a KSPROPERTY_RTAUDIO_BUFFER property request is successful, the property value, which is a structure of type KSRTAUDIO_BUFFER, contains the address and size of the driver-allocated buffer.

Closing the pin automatically frees the buffer that was allocated through this property.

If you want event notifications, you must call KSPROPERTY_RTAUDIO_BUFFER_WITH_NOTIFICATION instead of KSPROPERTY_RTAUDIO_BUFFER.

Requirements

Version	Available in Windows Vista and later Windows operating systems.
Header	Ksmedia.h

See also

KSRTAUDIO_BUFFER

KSRTAUDIO_BUFFER_PROPERTY

KSPROPERTY_RTAUDIO_BUFFER_WITH_NOTIFICATION