.\" 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_mixer's wiki page for Mix_SetDistance:
.\"   https://wiki.libsdl.org/SDL_mixer/Mix_SetDistance
.\" Generated with SDL/build-scripts/wikiheaders.pl
.\"  revision 3~git20240319~12fb85e+ds-1
.\" 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%20Mix_SetDistance
.\" SDL_mixer can be found at https://libsdl.org/projects/SDL_mixer
.de URL
\$2 \(laURL: \$1 \(ra\$3
..
.if \n[.g] .mso www.tmac
.TH Mix_SetDistance 3 "SDL_mixer 3.0.0" "SDL_mixer" "SDL_mixer3 FUNCTIONS"
.SH NAME
Mix_SetDistance \- Set the "distance" of a channel\[char46]
.SH SYNOPSIS
.nf
.B #include \(dqSDL3_mixer/SDL_mixer.h\(dq
.PP
.BI "int Mix_SetDistance(int channel, Uint8 distance);
.fi
.SH DESCRIPTION

.BR distance
is an integer from 0 to 255 that specifies the location of the
sound in relation to the listener\[char46] Distance 0 is overlapping the listener,
and 255 is as far away as possible\[char46] A distance of 255 does not guarantee
silence; in such a case, you might want to try changing the chunk's volume,
or just cull the sample from the mixing process with

.BR Mix_HaltChannel
()\[char46] For efficiency, the precision of this
effect may be limited (distances 1 through 7 might all produce the same
effect, 8 through 15 are equal, etc)\[char46] (distance) is an integer between 0
and 255 that specifies the space between the sound and the listener\[char46] The
larger the number, the further away the sound is\[char46] Setting the distance to 0
unregisters this effect, since the data would be unchanged\[char46] If you need
more precise positional audio, consider using OpenAL for spatialized
effects instead of SDL_mixer\[char46] This is only meant to be a basic effect for
simple "3D" games\[char46]

Setting the channel to 
.BR MIX_CHANNEL_POST
 registers this
as a posteffect, and the distance attenuation will be done to the final
mixed stream before passing it on to the audio device\[char46]

This uses the 
.BR Mix_RegisterEffect
() API internally\[char46]

Note that unlike most SDL and SDL_mixer functions, this function returns
zero if there's an error, not on success\[char46] We apologize for the API design
inconsistency here\[char46]

.SH FUNCTION PARAMETERS
.TP
.I channel
The mixer channel to attenuate, or 
.BR MIX_CHANNEL_POST
\[char46]
.TP
.I distance
distance; 0 is the listener, 255 is maxiumum distance away\[char46]
.SH RETURN VALUE
Returns zero if error (no such channel or

.BR Mix_RegisterEffect
() fails), nonzero if position
effect is enabled\[char46] Error messages can be retrieved from

.BR Mix_GetError
()\[char46]

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