Share via

IAudioRenderClient::GetBuffer

  • Article
Previous Next

IAudioRenderClient::GetBuffer

The GetBuffer method retrieves a pointer to the next available space in the rendering endpoint buffer into which the caller can write a data packet.

HRESULT GetBuffer(
  UINT32  NumFramesRequested,
  BYTE  **ppData
);

Parameters

NumFramesRequested

[in]  The number of audio frames in the data packet that the caller plans to write to the requested space in the buffer. If the call succeeds, the size of the buffer area pointed to by *ppData matches the size specified in NumFramesRequested.

ppData

[out]  Pointer to a pointer variable into which the method writes the starting address of the buffer area into which the caller will write the data packet.

Return Value

If the method succeeds, it returns S_OK. If it fails, possible return codes include, but are not limited to, the values shown in the following table.

Return code Description
AUDCLNT_E_BUFFER_TOO_LARGE The NumFramesRequested value exceeds the available buffer space (buffer size minus padding size).
AUDCLNT_E_BUFFER_SIZE_ERROR The stream is exclusive mode and uses event-driven buffering, but the client attempted to get a packet that was not the size of the buffer.
AUDCLNT_E_OUT_OF_ORDER A previous IAudioRenderClient::GetBuffer call is still in effect.
AUDCLNT_E_DEVICE_INVALIDATED The audio endpoint device has been unplugged, or the audio hardware or associated hardware resources have been reconfigured, disabled, removed, or otherwise made unavailable for use.
AUDCLNT_E_BUFFER_OPERATION_PENDING Buffer cannot be accessed because a stream reset is in progress.
AUDCLNT_E_SERVICE_NOT_RUNNING The Windows audio service is not running.
E_POINTER Parameter ppData is NULL.

Remarks

The caller can request a packet size that is less than or equal to the amount of available space in the buffer (except in the case of an exclusive-mode stream that uses event-driven buffering; for more information, see IAudioClient::Initialize). The available space is simply the buffer size minus the amount of data in the buffer that is already queued up to be played. If the caller specifies a NumFramesRequested value that exceeds the available space in the buffer, the call fails and returns error code AUDCLNT_E_BUFFER_TOO_LARGE.

The client is responsible for writing a sufficient amount of data to the buffer to prevent glitches from occurring in the audio stream. For more information about buffering requirements, see IAudioClient::Initialize.

After obtaining a data packet by calling GetBuffer, the client fills the packet with rendering data and issues the packet to the audio engine by calling the IAudioRenderClient::ReleaseBuffer method.

The client must call ReleaseBuffer after a GetBuffer call that successfully obtains a packet of any size other than 0. The client has the option of calling or not calling ReleaseBuffer to release a packet of size 0.

For nonzero packet sizes, the client must alternate calls to GetBuffer and ReleaseBuffer. Each GetBuffer call must be followed by a corresponding ReleaseBuffer call. After the client has called GetBuffer to acquire a data packet, the client cannot acquire the next data packet until it has called ReleaseBuffer to release the previous packet. Two or more consecutive calls either to GetBuffer or to ReleaseBuffer are not permitted and will fail with error code AUDCLNT_E_OUT_OF_ORDER.

To ensure the correct ordering of calls, a GetBuffer call and its corresponding ReleaseBuffer call must occur in the same thread.

The size of an audio frame is specified by the nBlockAlign member of the WAVEFORMATEX structure that the client obtains by calling the IAudioClient::GetMixFormat method.

If the caller sets NumFramesRequested = 0, the method returns status code S_OK but does not write to the variable that the ppData parameter points to.

Clients should avoid excessive delays between the GetBuffer call that acquires a buffer and the ReleaseBuffer call that releases the buffer. The implementation of the audio engine assumes that the GetBuffer call and the corresponding ReleaseBuffer call occur within the same buffer-processing period. Clients that delay releasing a buffer for more than one period risk losing sample data.

For code examples that call the GetBuffer method, see the following topics:

Requirements

Client: Windows Vista

Header: Include Audioclient.h.

See Also

Previous Next