IAudioCaptureClient::ReleaseBuffer
| Previous | Next |
IAudioCaptureClient::ReleaseBuffer
The ReleaseBuffer method releases the buffer.
HRESULT ReleaseBuffer( UINT32 NumFramesRead );
Parameters
NumFramesRead
[in] The number of audio frames that the client read from the capture buffer. This parameter must be either equal to the number of frames in the previously acquired data packet or 0.
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_INVALID_SIZE | The NumFramesRead parameter is set to a value other than the data packet size or 0. |
| AUDCLNT_E_OUT_OF_ORDER | This call was not preceded by a corresponding IAudioCaptureClient::GetBuffer call. |
| 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_SERVICE_NOT_RUNNING | The Windows audio service is not running. |
Remarks
The client should call this method when it finishes reading a data packet that it obtained previously by calling the IAudioCaptureClient::GetBuffer method.
The data in the packet that the client obtained from a GetBuffer call is guaranteed to remain valid until the client calls ReleaseBuffer to release the packet.
Between each GetBuffer call and its corresponding ReleaseBuffer call, the client must either read the entire data packet or none of it. If the client reads the entire packet following the GetBuffer call, then it should call ReleaseBuffer with NumFramesRead set to the total number of frames in the data packet. In this case, the next call to GetBuffer will produce a new data packet. If the client reads none of the data from the packet following the call to GetBuffer, then it should call ReleaseBuffer with NumFramesRead set to 0. In this case, the next GetBuffer call will produce the same data packet as in the previous GetBuffer call.
If the client calls ReleaseBuffer with NumFramesRead set to any value other than the packet size or 0, then the call fails and returns error code AUDCLNT_E_INVALID_SIZE.
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 a code example that calls the ReleaseBuffer method, see Capturing a Stream.
Requirements
Client: Windows Vista
Header: Include Audioclient.h.
See Also
| Previous | Next |