Miles Sound System SDK 7.2a

AIL_set_sample_3D_position

The function AIL_set_sample_3D_position sets a sample's current position in 3D space.

void AIL_set_sample_3D_position(
  HSAMPLE S,
  F32 X,
  F32 Y,
  F32 Z
);

In Parameters

S: specifies the 3D sample.
X: specifies the X coordinate (usually imagined as left to right - left is negative, right is positive).
Y: specifies the Y coordinate (usually imagined as down to up - down is negative, up is positive).
Z: specifies the Z coordinate (usually imagined as back to front - back is negative, front is positive).

Discussion

Assigning a 3D position to an HSAMPLE allows MSS to determine its channel levels automatically by performing distance and directionality calculations based on the relative positions of the HSAMPLE and its HDIGDRIVER (also known as the listener) in 3D space. Positions in 3D space are specified in left-handed coordinates (+X = right, +Y = up, +Z = front) by means of the AIL_set_sample_3D_position and AIL_set_listener_3D_position functions.

Even after you call AIL_set_sample_3D_position on an HSAMPLE, the sample's channel-level scale factors may still be specified by the application, if desired, with the AIL_set_sample_channel_levels function. The 3D positioner will continue to multiply its own set of scale factors with the default channel-level scalars until the HSAMPLE is released and reallocated, or reinitialized with a call to AIL_init_sample, AIL_set_sample_info, AIL_set_sample_file, or AIL_set_named_sample_file. Any of these actions will disable 3D positioning on an HSAMPLE when the MSS software mixer is in use.

Once an HSAMPLE has been placed under 3D control, a number of additional MSS API functions can be applied to the HSAMPLE. AIL_set_sample_3D_distances determines how distance-based attenuation is applied to the sound, while the AIL_set_sample_3D_cone and AIL_set_sample_3D_orientation functions give the sound a directional falloff characteristic. AIL_set_sample_3D_velocity applies Doppler shift to the sound. Similar functions apply to the listener object associated with the HDIGDRIVER. When the MSS software mixer is in use, none of the functions whose name contains '_3D_' affect HSAMPLES that have not been assigned a 3D position.

You should carefully review the How do I use multi-channel sound output in Miles? FAQ before using this function.

Example files that use this function: examms.cpp

Group: Digital Audio Services
Related Functions: AIL_calculate_3D_channel_levels, AIL_init_sample, AIL_sample_3D_position, AIL_sample_3D_velocity, AIL_set_listener_3D_position, AIL_set_named_sample_file, AIL_set_sample_3D_cone, AIL_set_sample_3D_distances, AIL_set_sample_3D_orientation, AIL_set_sample_3D_position, AIL_set_sample_3D_velocity, AIL_set_sample_3D_velocity_vector, AIL_set_sample_channel_levels, AIL_set_sample_file, AIL_set_sample_info, AIL_update_sample_3D_position
Related Basic Types: F32, HSAMPLE, MILES_OPEN_DIGITAL_FLAGS, void
Related FAQs: How do I play a 3D digital sound?, How do I use multi-channel sound output in Miles?, What's the best way to port my older Miles application to MSS 7?