The ReleaseBuffer method releases the buffer space acquired in the previous call to the IAudioRenderClient::GetBuffer method.
public:
HRESULT ReleaseBuffer(
UINT32 NumFramesWritten,
DWORD dwFlags
)
NumFramesWritten
Type: UINT32
[in]
The number of audio frames written by the client to the data packet. The value of this parameter must be less than or equal to the size of the data packet, as specified in the NumFramesRequested parameter passed to the IAudioRenderClient::GetBuffer method.
dwFlags
Type: DWORD
[in]
The buffer-configuration flags. The caller can set this parameter either to 0 or to the following _AUDCLNT_BUFFERFLAGS enumeration value (a flag bit):
AUDCLNT_BUFFERFLAGS_SILENT
If this flag bit is set, the audio engine treats the data packet as though it contains silence regardless of the data values contained in the packet. This flag eliminates the need for the client to explicitly write silence data to the rendering buffer.
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_INVALID_SIZE | The NumFramesWritten value exceeds the NumFramesRequested value specified in the previous IAudioRenderClient::GetBuffer call. |
| AUDCLNT_E_BUFFER_SIZE_ERROR | This error code is not used on Xbox One. |
| AUDCLNT_E_OUT_OF_ORDER | This call was not preceded by a corresponding call to IAudioRenderClient::GetBuffer. |
| 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 audio service is not running. |
| E_INVALIDARG | Parameter dwFlags is not a valid value. |
Refer to WASAPI error codes.
The client must release the same number of frames that it requested in the preceding call to the IAudioRenderClient::GetBuffer method. The single exception to this rule is that the client can always call ReleaseBuffer to release 0 frames.
This behavior provides a convenient means for the client to “release” a previously requested packet of length 0. In this case, the call to ReleaseBuffer is optional. After calling GetBuffer to obtain a packet of length 0, the client has the option of not calling ReleaseBuffer before calling GetBuffer again.
In addition, if the preceding GetBuffer call obtained a packet of nonzero size, calling ReleaseBuffer with NumFramesRequested set to 0 will succeed. The meaning of the call is that the client wrote no data to the packet before releasing it. Thus, the method treats the portion of the buffer represented by the packet as unused and will make this portion of the buffer available again to the client in the next GetBuffer call.
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 ReleaseBuffer method, see the following topic:
Header: Declared in audioclient.h.
Library: Use mmdevapi.lib.