Documentation

Support

Vivox Core SDK

Vivox Core SDK

Positional channel configuration

Configure positional channels for spatial audio in 3D environments.
Read time 1 minuteLast updated a day ago
If a game has joined a positional channel, it must frequently update the Vivox SDK with the position and orientation of the user in the 3D space that is associated with that channel. The client does this by sending a 
vx_req_session_set_3d_position
message to the Vivox SDK. Positional channels use a right-hand coordinate system. When the player avatar is standing facing directly forward, the following criteria applies:
  • The positive X-axis is to the avatar's right.
  • The positive Y-axis runs from the avatar's feet upward through their head.
  • The positive Z-axis runs from the avatar's chest out through their back.
When a player joins a positional channel, the player avatar is placed at a null position until they move to a position. You can set the position of the avatar's mouth independently of the avatar's ears. These are respectively referred to as the speaker position and the listener position, and they share coordinates in most scenarios. Because the positions are independent, this allows for effects like an "audio zoom," where a character who is using something like a shotgun microphone could be configured to hear voice as though they were closer to the target, but they are still only speaking to those immediately around them. In addition to position, the listener can also have its orientation set to accurately render audio panning. However, the speaker cannot have its orientation set; spoken voices are treated as omni-directional audio “point sources” and are unaffected by the speaker’s orientation. After you set up and join a positional channel with any configured 3D properties, you then report your actor's position and orientation to the Vivox SDK. The following code displays an example of how to set a user's position in a positional channel: 
. . .vx_req_session_set_3d_position *req;vx_req_session_set_3d_position_create(&req);req->session_handle = vx_strdup("mychannel");req->req_disposition_type = req_disposition_no_reply_required;req->speaker_position[0] = 10;req->speaker_position[1] = 0;req->speaker_position[2] = 0;req->listener_position[0] = 10;req->listener_position[1] = 0;req->listener_position[2] = 0;req->listener_at_orientation[0] = 0;req->listener_at_orientation[1] = 0;req->listener_at_orientation[2] = -1;req->listener_up_orientation[0] = 0;req->listener_up_orientation[1] = 1;req->listener_up_orientation[2] = 0;vx_issue_request3(&req->base, &request_count);. . .
The most frequently issued request is 
vx_req_session_set_3d_position
. Successful responses from this request are ignored. To save processing time in your game, and because responses with errors are still returned, to prevent the Vivox SDK from returning successful responses to this request, set the 
vx_req_session_set_3d_position.req_disposition_type
to 
req_disposition_no_reply_required
.