Positional channel configuration
Configure positional channels for spatial audio in 3D environments.
Read time 2 minutesLast updated 8 months 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 message to the Vivox SDK.
vx_req_session_set_3d_positionPositional 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 . Successful responses from this request are ignored.
vx_req_session_set_3d_positionTo 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 to .
vx_req_session_set_3d_position.req_disposition_typereq_disposition_no_reply_required