[−][src]Function fermium::audio::SDL_LoadWAV_RW

pub unsafe extern "C" fn SDL_LoadWAV_RW(
    src: *mut SDL_RWops, 
    freesrc: c_int, 
    spec: *mut SDL_AudioSpec, 
    audio_buf: *mut *mut u8, 
    audio_len: *mut u32
) -> *mut SDL_AudioSpec

Load the audio data of a WAVE file into memory

Loading a WAVE file requires src, spec, audio_buf, and audio_len to be valid pointers. The entire data portion of the file is then loaded into memory and decoded if necessary.

If freesrc is non-zero, the data source gets automatically closed and freed before the function returns.

Supported are RIFF WAVE files with the formats PCM (8, 16, 24, and 32 bits), IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits), and A-law and µ-law (8 bits). Other formats are currently unsupported and cause an error.

If this function succeeds, the pointer returned by it is equal to spec and the pointer to the audio data allocated by the function is written to audio_buf and its length in bytes to audio_len. The SDL_AudioSpec members freq, channels, and format are set to the values of the audio data in the buffer. The samples member is set to a sane default and all others are set to zero.

It's necessary to use SDL_FreeWAV to free the audio data returned in audio_buf when it is no longer used.

Because of the under-specification of the Waveform format, there are many problematic files in the wild that cause issues with strict decoders. To provide compatibility with these files, this decoder is lenient in regards to the truncation of the file, the fact chunk, and the size of the RIFF chunk. The hints SDL_HINT_WAVE_RIFF_CHUNK_SIZE, SDL_HINT_WAVE_TRUNCATION, and SDL_HINT_WAVE_FACT_CHUNK can be used to tune the behavior of the loading process.

Any file that is invalid (due to truncation, corruption, or wrong values in the headers), too big, or unsupported causes an error. Additionally, any critical I/O error from the data source will terminate the loading process with an error. The function returns NULL on error and in all cases (with the exception of src being NULL), an appropriate error message will be set.

It is required that the data source supports seeking.

Example:

SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...);
  • src The data source with the WAVE data
  • freesrc A integer value that makes the function close the data source if non-zero
  • spec A pointer filled with the audio format of the audio data
  • audio_buf A pointer filled with the audio data allocated by the function
  • audio_len A pointer filled with the length of the audio data buffer in bytes

Return: NULL on error, or non-NULL on success.