#pragma section-numbers off
#pragma disable-camelcase

= SDL_ConvertAudio =
Use this function to convert audio data to a desired audio format.

<<TableOfContents()>>

== Syntax ==
{{{#!highlight cpp
int SDL_ConvertAudio(SDL_AudioCVT* cvt)
}}}

== Function Parameters ==
||'''cvt'''||an [[SDL_AudioCVT]] structure that was previously set up; see [[#Remarks|Remarks]] for details||

== Return Value ==

Returns 0 if the conversion was completed successfully or a negative error code on failure; call [[SDL_GetError]]() for more information.

== Code Examples ==
{{{#!highlight cpp
// Change 1024 stereo sample frames at 48000Hz from Float32 to Int16.
SDL_AudioCVT cvt;
SDL_BuildAudioCVT(&cvt, AUDIO_F32, 2, 48000, AUDIO_S16, 2, 48000);
SDL_assert(cvt.needed); // obviously, this one is always needed.
cvt.len = 1024 * 2 * 4;  // 1024 stereo float32 sample frames.
cvt.buf = (Uint8 *) SDL_malloc(cvt.len * cvt.len_mult);
// read your float32 data into cvt.buf here.
SDL_ConvertAudio(&cvt);
// cvt.buf has cvt.len_cvt bytes of converted data now.
}}}

== Remarks ==
This function does the actual audio data conversion, after the application has called [[SDL_BuildAudioCVT]]() to prepare the conversion information and then filled in the buffer details.

Once the application has initialized the '''cvt''' structure using [[SDL_BuildAudioCVT]](), allocated an audio buffer and filled it with audio data in the source format, this function will convert the buffer, in-place, to the desired format.

The data conversion may go through several passes; any given pass may possibly temporarily increase the size of the data. For example, SDL might expand 16-bit data to 32 bits before resampling to a lower frequency, shrinking the data size after having grown it briefly. Since the supplied buffer will be both the source and destination, converting as necessary in-place, the application must allocate a buffer that will fully contain the data during its largest conversion pass. After [[SDL_BuildAudioCVT]]() returns, the application should set the '''cvt''' structure's '''len''' field to the size, in bytes, of the source data, and allocate a buffer that is '''len''' * '''len_mult''' bytes long for the '''buf''' field.

The source data should be copied into this buffer before the call to [[SDL_ConvertAudio]](). Upon successful return, this buffer will contain the converted audio, and the '''cvt''' structure's '''len_cvt''' field will be the size of the converted data, in bytes. Any bytes in the buffer past '''len_cvt''' are undefined once this function returns.

== Related Functions ==
 .[[SDL_BuildAudioCVT]]

----
[[CategoryAPI]], [[CategoryAudio]]