.\" This manpage content is licensed under Creative Commons
.\"  Attribution 4.0 International (CC BY 4.0)
.\"   https://creativecommons.org/licenses/by/4.0/
.\" This manpage was generated from SDL's wiki page for SDL_SetAudioStreamGetCallback:
.\"   https://wiki.libsdl.org/SDL_SetAudioStreamGetCallback
.\" Generated with SDL/build-scripts/wikiheaders.pl
.\"  revision SDL-3.1.0
.\" Please report issues in this manpage's content at:
.\"   https://github.com/libsdl-org/sdlwiki/issues/new
.\" Please report issues in the generation of this manpage from the wiki at:
.\"   https://github.com/libsdl-org/SDL/issues/new?title=Misgenerated%20manpage%20for%20SDL_SetAudioStreamGetCallback
.\" SDL can be found at https://libsdl.org/
.de URL
\$2 \(laURL: \$1 \(ra\$3
..
.if \n[.g] .mso www.tmac
.TH SDL_SetAudioStreamGetCallback 3 "SDL 3.1.0" "SDL" "SDL3 FUNCTIONS"
.SH NAME
SDL_SetAudioStreamGetCallback \- Set a callback that runs when data is requested from an audio stream\[char46]
.SH SYNOPSIS
.nf
.B #include \(dqSDL3/SDL.h\(dq
.PP
.BI "int SDL_SetAudioStreamGetCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata);
.fi
.SH DESCRIPTION
This callback is called _before_ data is obtained from the stream, giving
the callback the chance to add more on-demand\[char46]

The callback can (optionally) call

.BR SDL_PutAudioStreamData
() to add more audio to the
stream during this call; if needed, the request that triggered this
callback will obtain the new data immediately\[char46]

The callback's
.BR approx_request
argument is roughly how many bytes of
_unconverted_ data (in the stream's input format) is needed by the caller,
although this may overestimate a little for safety\[char46] This takes into account
how much is already in the stream and only asks for any extra necessary to
resolve the request, which means the callback may be asked for zero bytes,
and a different amount on each call\[char46]

The callback is not required to supply exact amounts; it is allowed to
supply too much or too little or none at all\[char46] The caller will get what's
available, up to the amount they requested, regardless of this callback's
outcome\[char46]

Clearing or flushing an audio stream does not call this callback\[char46]

This function obtains the stream's lock, which means any existing callback
(get or put) in progress will finish running before setting the new
callback\[char46]

Setting a NULL function turns off the callback\[char46]

.SH FUNCTION PARAMETERS
.TP
.I stream
the audio stream to set the new callback on\[char46]
.TP
.I callback
the new callback function to call when data is added to the stream\[char46]
.TP
.I userdata
an opaque pointer provided to the callback for its own personal use\[char46]
.SH RETURN VALUE
Returns 0 on success, -1 on error\[char46] This only fails if
.BR stream
is NULL\[char46]

.SH THREAD SAFETY
It is safe to call this function from any thread\[char46]

.SH AVAILABILITY
This function is available since SDL 3\[char46]0\[char46]0\[char46]

.SH SEE ALSO
.BR SDL_SetAudioStreamPutCallback (3)