Retrieves a pointer to the next available space in the rendering endpoint buffer into which the caller can write a data packet.
public:
HRESULT GetBuffer(
UINT32 NumFramesRequested,
BYTE **ppData
)
NumFramesRequested
Type: UINT32
[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
Type: BYTE **
[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.
Type: HRESULT
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_ERROR | GetBuffer failed to retrieve a data buffer and *ppData points to NULL. For more information, see Remarks. |
| AUDCLNT_E_BUFFER_TOO_LARGE | The NumFramesRequested value exceeds the available buffer space (buffer size minus padding size). |
| AUDCLNT_E_BUFFER_SIZE_ERROR | This error is not used on Xbox One. |
| 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 audio service is not running. |
| E_POINTER | Parameter ppData is NULL. |
Refer to WASAPI error codes.
The caller can request a packet size that is less than or equal to the amount of available space in the buffer. 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.
If GetBuffer returns AUDCLNT_E_BUFFER_ERROR, the thread consuming the audio samples must wait for the next processing pass. The client might benefit from keeping a count of the failed GetBuffer calls. If GetBuffer returns this error repeatedly, the client can start a new processing loop after shutting down the current client by calling IAudioClient::Stop, IAudioClient::Reset, and releasing the audio client.
Header: Declared in audioclient.h.
Library: Use mmdevapi.lib.