17 lines
13 KiB
HTML
17 lines
13 KiB
HTML
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>3D Sound</title><link rel="stylesheet" href="ts3doc.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.74.0"><link rel="home" href="index.html" title="TeamSpeak 3 Client SDK Developer Manual"><link rel="up" href="index.html" title="TeamSpeak 3 Client SDK Developer Manual"><link rel="prev" href="ar01s19.html" title="Playing wave files"><link rel="next" href="ar01s21.html" title="Query available servers, channels and clients"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><img id="logo" src="images/logo.png"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">3D Sound</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s19.html"><img src="images/prev.png" alt="Prev"></a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s21.html"><img src="images/next.png" alt="Next"></a></td></tr></table><hr></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sound3d"></a>3D Sound</h2></div></div></div><p>TeamSpeak 3 supports 3D sound to assign each speaker a unique position in 3D space. Provided are functions to modify the 3D position, velocity and orientation of own and foreign clients.</p><a class="indexterm" name="idm44835434168688"></a><p>Generally the struct <span class="structname">TS3_VECTOR</span> describes a vector in 3D space:</p><a class="indexterm" name="idm44835434167264"></a><pre class="programlisting">typedef struct {
|
||
float x; /* X coordinate in 3D space. */
|
||
float y; /* Y coordinate in 3D space. */
|
||
float z; /* Z coordinate in 3D space. */
|
||
} TS3_VECTOR;</pre><p>To set the position, velocity and orientation of the own client in 3D space, call:
|
||
</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">unsigned int <b class="fsfunc">ts3client_systemset3DListenerAttributes</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">position</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">forward</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">up</var><code>)</code>;</td><td> </td></tr></table><div class="paramdef-list"><code>uint64 <var class="pdparam">serverConnectionHandlerID</var></code>;<br><code>const TS3_VECTOR* <var class="pdparam">position</var></code>;<br><code>const TS3_VECTOR* <var class="pdparam">forward</var></code>;<br><code>const TS3_VECTOR* <var class="pdparam">up</var></code>;</div><div class="funcprototype-spacer"> </div></div><p>
|
||
<a class="indexterm" name="idm44835434161200"></a></p><div class="itemizedlist"><ul type="disc"><li><p><em class="parameter"><code>serverConnectionHandlerID</code></em></p><p>ID of the server connection handler on which the 3D sound listener attributes are to be set.</p></li><li><p><em class="parameter"><code>position</code></em></p><p>3D position of the own client.</p><p>If passing NULL, the parameter is ignored and the value not updated.</p></li><li><p><em class="parameter"><code>forward</code></em></p><p>Forward orientation of the listener. The vector must be of unit length and perpendicular to the up vector.</p><p>If passing NULL, the parameter is ignored and the value not updated.</p></li><li><p><em class="parameter"><code>up</code></em></p><p>Upward orientation of the listener. The vector must be of unit length and perpendicular to the forward vector.</p><p>If passing NULL, the parameter is ignored and the value not updated.</p></li></ul></div><p>Returns <em class="structfield"><code>ERROR_ok</code></em> on success, otherwise an error code as defined in <code class="filename">public_errors.h</code>.</p><div class="literallayout"><p><br>
|
||
</p></div><p>To adjust 3D sound system settings use:
|
||
</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">unsigned int <b class="fsfunc">ts3client_systemset3DSettings</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">distanceFactor</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">rolloffScale</var><code>)</code>;</td><td> </td></tr></table><div class="paramdef-list"><code>uint64 <var class="pdparam">serverConnectionHandlerID</var></code>;<br><code>float <var class="pdparam">distanceFactor</var></code>;<br><code>float <var class="pdparam">rolloffScale</var></code>;</div><div class="funcprototype-spacer"> </div></div><p>
|
||
<a class="indexterm" name="idm44835434145936"></a></p><div class="itemizedlist"><ul type="disc"><li><p><em class="parameter"><code>serverConnectionHandlerID</code></em></p><p>ID of the server connection handler on which the 3D sound system settings are to be adjusted.</p></li><li><p><em class="parameter"><code>distanceFactor</code></em></p><p>Relative distance factor. Default is 1.0 = 1 meter</p></li><li><p><em class="parameter"><code>rolloffScale</code></em></p><p>Scaling factor for 3D sound rolloff. Defines how fast sound volume will attenuate. As higher the value, as faster the sound is toned with increasing distance.</p></li></ul></div><p>Returns <em class="structfield"><code>ERROR_ok</code></em> on success, otherwise an error code as defined in <code class="filename">public_errors.h</code>.</p><div class="literallayout"><p><br>
|
||
</p></div><p>To adjust a clients position and velocity in 3D space, call:
|
||
</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">unsigned int <b class="fsfunc">ts3client_channelset3DAttributes</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">clientID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">position</var><code>)</code>;</td><td> </td></tr></table><div class="paramdef-list"><code>uint64 <var class="pdparam">serverConnectionHandlerID</var></code>;<br><code>anyID <var class="pdparam">clientID</var></code>;<br><code>const TS3_VECTOR* <var class="pdparam">position</var></code>;</div><div class="funcprototype-spacer"> </div></div><p>
|
||
<a class="indexterm" name="idm44835434133664"></a></p><div class="itemizedlist"><ul type="disc"><li><p><em class="parameter"><code>serverConnectionHandlerID</code></em></p><p>ID of the server connection handler on which the 3D sound channel attributes are to be adjusted.</p></li><li><p><em class="parameter"><code>clientID</code></em></p><p>ID of the client to adjust.</p></li><li><p><em class="parameter"><code>position</code></em></p><p>Vector specifying the position of the given client in 3D space.</p></li></ul></div><p>Returns <em class="structfield"><code>ERROR_ok</code></em> on success, otherwise an error code as defined in <code class="filename">public_errors.h</code>.</p><div class="literallayout"><p><br>
|
||
</p></div><p>The following event is called to calculate volume attenuation for distance in 3D positioning of clients.</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">onCustom3dRolloffCalculationClientEvent</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">clientID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">distance</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">volume</var><code>)</code>;</td><td> </td></tr></table><div class="paramdef-list"><code>uint64 <var class="pdparam">serverConnectionHandlerID</var></code>;<br><code>anyID <var class="pdparam">clientID</var></code>;<br><code>float <var class="pdparam">distance</var></code>;<br><code>float* <var class="pdparam">volume</var></code>;</div><div class="funcprototype-spacer"> </div></div><a class="indexterm" name="idm44835434120624"></a><div class="itemizedlist"><ul type="disc"><li><p><em class="parameter"><code>serverConnectionHandlerID</code></em></p><p>ID of the server connection handler on which the volume attenuation calculation occured.</p></li><li><p><em class="parameter"><code>clientID</code></em></p><p>ID of the client which is being 3D positioned.</p></li><li><p><em class="parameter"><code>distance</code></em></p><p>The distance between the listener and the client.</p></li><li><p><em class="parameter"><code>volume</code></em></p><p>The volume which the Client Lib calculated. This can be changed in this callback.</p></li></ul></div><div class="literallayout"><p><br>
|
||
</p></div><p>The following event is called to calculate volume attenuation for distance in 3D positioning of a wave file that was opened previously with <a class="link" href="ar01s19.html" title="Playing wave files"><code class="function">ts3client_playWaveFileHandle</code></a>.</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">onCustom3dRolloffCalculationWaveEvent</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">waveHandle</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">distance</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">volume</var><code>)</code>;</td><td> </td></tr></table><div class="paramdef-list"><code>uint64 <var class="pdparam">serverConnectionHandlerID</var></code>;<br><code>uint64 <var class="pdparam">waveHandle</var></code>;<br><code>float <var class="pdparam">distance</var></code>;<br><code>float* <var class="pdparam">volume</var></code>;</div><div class="funcprototype-spacer"> </div></div><a class="indexterm" name="idm44835434106624"></a><div class="itemizedlist"><ul type="disc"><li><p><em class="parameter"><code>serverConnectionHandlerID</code></em></p><p>ID of the server connection handler on which the volume attenuation calculation occured.</p></li><li><p><em class="parameter"><code>waveHandle</code></em></p><p>Handle for the playing wave file, returned by <code class="function">ts3client_playWaveFileHandle</code>.</p></li><li><p><em class="parameter"><code>distance</code></em></p><p>The distance between the listener and the client.</p></li><li><p><em class="parameter"><code>volume</code></em></p><p>The volume which the Client Lib calculated. This can be changed in this callback.</p></li></ul></div><div class="literallayout"><p><br>
|
||
</p></div><p>This method is used to 3D position a wave file that was opened previously with <a class="link" href="ar01s19.html" title="Playing wave files"><code class="function">ts3client_playWaveFileHandle</code></a>.</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">unsigned int <b class="fsfunc">ts3client_set3DWaveAttributes</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">waveHandle</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">position</var><code>)</code>;</td><td> </td></tr></table><div class="paramdef-list"><code>uint64 <var class="pdparam">serverConnectionHandlerID</var></code>;<br><code>uint64 <var class="pdparam">waveHandle</var></code>;<br><code>const TS3_VECTOR* <var class="pdparam">position</var></code>;</div><div class="funcprototype-spacer"> </div></div><a class="indexterm" name="idm44835434092960"></a><div class="itemizedlist"><ul type="disc"><li><p><em class="parameter"><code>serverConnectionHandlerID</code></em></p><p>ID of the server connection handler on which the volume attenuation calculation occured.</p></li><li><p><em class="parameter"><code>waveHandle</code></em></p><p>Handle for the playing wave file, returned by <code class="function">ts3client_playWaveFileHandle</code>.</p></li><li><p><em class="parameter"><code>position</code></em></p><p>The 3D position of the sound.</p></li><li><p><em class="parameter"><code>volume</code></em></p><p>The volume which the Client Lib calculated. This can be changed in this callback.</p></li></ul></div><p>Returns <em class="structfield"><code>ERROR_ok</code></em> on success, otherwise an error code as defined in <code class="filename">public_errors.h</code>.</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ar01s19.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ar01s21.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Playing wave files </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Query available servers, channels and clients</td></tr></table></div></body></html>
|