MIX_LoadAudioNoCopy(3)

📦
version 3.2.4 · 2 versions
, in fedora 44

💖 MIX_LoadAudioNoCopy(3) 💖

okay bestie so this is a page out of the SDL_mixer3 FUNCTIONS manual, and honestly? it's giving efficiency queen. let's get into it 🫶

✨ NAME ✨

MIX_LoadAudioNoCopy — loads audio for playback straight out of a memory buffer, and does NOT make a copy. no copy. none. zero. she said "your buffer, your problem" 💅

🌸 SYNOPSIS 🌸

#include <SDL3_mixer/SDL_mixer.h>

MIX_Audio * MIX_LoadAudioNoCopy(MIX_Mixer *mixer, const void *data, size_t datalen, bool free_when_done);

🦋 DESCRIPTION 🦋

so when you load audio the normal way with most of the other LoadAudio functions, the data gets cached fully in RAM in its original data format, and then it's decoded on-demand. this function does most of that same work, but instead it uses a buffer of memory that the app provides — and it does not make a copy of it. periodt.

⚠️ this buffer must live for the ENTIRE time the returned MIX_Audio lives, because the mixer will go back and poke at that buffer whenever it needs to mix more data. if your buffer evaporates, that's on you bestie 😭

this function exists to maximize efficiency: if the data is already sitting in memory and can stay there, why copy it? the data can be in any supported audio file format (WAV, MP3, etc.) and it'll be decoded on the fly while mixing.

unlike MIX_LoadAudio(), there is no predecode option here — and that's on purpose, because this whole function is optimizing for data that's already in memory and plans to live there for a significant amount of time. since predecoding would only need the file format data once, upfront, you could just wrap it in SDL_CreateIOFromConstMem() and hand that to MIX_LoadAudio_IO(). iykyk 🤷♀️

MIX_Audio objects can be shared between multiple mixers, which is iconic of them. the mixer parameter just suggests the most likely mixer to use this audio with, in case some optimization might get applied — but it is not required, and you can totally pass a NULL mixer. no pressure, no drama.

if free_when_done is true, SDL_mixer will call SDL_free(data) when the returned MIX_Audio is eventually destroyed. this is useful when the data isn't static, but was instead loaded elsewhere for this specific MIX_Audio — you just wanna dodge that extra copy 🎀

and heads up: since audio format info gets pulled from the file format metadata, this function is not useful for raw PCM data. for that, use MIX_LoadRawAudioNoCopy() instead, which offers an SDL_AudioSpec. different function, different vibe, okurrr.

once a MIX_Audio is created, you can assign it to a MIX_Track with MIX_SetTrackAudio(), or just play it with no management at all using MIX_PlayAudio(). main character energy fr fr 👑

and when you're done with a MIX_Audio, free it with MIX_DestroyAudio(). clean up after yourself, we love a responsible legend 🧚

💜 FUNCTION PARAMETERS 💜

  • mixer — a mixer this audio is intended to be used with. may be NULL. it's a suggestion, not a rule 💫
  • data — the buffer where the audio data lives. your memory, your rules.
  • datalen — the size, in bytes, of the buffer.
  • free_when_done — if true, data will be handed over to SDL_free() when the MIX_Audio is destroyed. she'll take it from here 🫡

⭐ RETURN VALUE ⭐

returns an audio object that you can use to make sound on a mixer 🎶 ...or NULL on failure. if you get NULL, call SDL_GetError() for more info — she'll tell you what went wrong, no cap.

🌈 THREAD SAFETY 🌈

it is safe to call this function from any thread. go wild, multitask, slay across cores 💅

🎀 AVAILABILITY 🎀

this function has been available since SDL_mixer 3.0.0. an icon since day one 👑

👀 SEE ALSO 👀

and that's the whole page bestie!! this one's straight out of the SDL_mixer docs, version SDL_mixer 3.2.4 — so if you're holding a copy, that's the release it rode in on. now go forth and not copy your buffers 💖✨🦋💅

📦 where this page comes from