by Gabriel Maldonado
gabriel@musicaverticale.net
http://csounds.com/maldonado
This documentation is partially based on Microsoft DirectX ® SDK manual and Creative Labs EAX 2.0 ® SDK manual. All respective copyright reserved
3D AUDIO SOURCE OUTPUT AND INITALIZATION
Init3dAudio isourcenummax
InitEAX
Out3d asig, ksourcenum
DESCRIPTION
3D audio source output and initialization
INITIALIZATION
isourcenummax - number of 3D audio sources to initialize (max. 32)
PERFORMANCE
asig - audio input signal
ksourcenum - 3D audio source number
Init3dAudio must be located in the header section of the orchestra, externally to the intruments. It sets the number of 3D sources available in the orchestra (max. 32), initializes the 3d audio support and creates the listener and source objects. Without placing this opcode in the header section, it is not possible to use any 3D audio opcode. IMPORTANT: When using 3d audio, nchnls must be set to 1 (at least in present version).
If 3D audio is NOT supported in hardware by your audio card, it is not recommended to use it, because realtime performance with DirectCsound will be seriously lowered. Furthermore, in emulated mode the sound quality is very bad (since DirectSound3D emulation translates the output to eight-bit samples, at a sampling-rate of 22'050 automatically).
InitEAX opcode has no arguments. It enables EAX 2.0 operations with the related opcodes. Notice that, at present time (october 1999), EAX 2.0 is available only with SoundBlaster Live! and SoundBlaster Live! value audio cards. I've heard that Diamond Monster Sound MX300 will support EAX 2.0 soon. However Creative says that EAX is an open standard approved by IASIG (Interactive Audio Special Interest Group) and will be supported by most audio card manufacturers in the near future.
InitEAX must be placed in the header section of the orchestra, after the line containing Init3dAudio opcode. It is not allowed to use InitEAX if Init3dAudio has not been previously called. Don't use any EAX-related opcode if InitEAX is not present in the header section of the orchestra. Also, don't use any EAX-related opcodes if EAX 2.0 is not supported by your platform (otherwise DirectCsound will crash).
Out3d represent a 3D source. It is similar to out opcode: it sends audio samples to one of the 3d audio accumulating output buffers created at the beginning of performance by the Init3dAudio opcode. It collects the output of all active instruments referring to the same source number, before the sound stream is processed by the DirectSound3D API routines. There can be any number of Out3ds referring to the same 3D source number in an instrument, and the output of different instruments can be patched to the same 3D source. Each 3D source can be considered as a continuosly-movable virtual speaker which can be placed anywhere in the aural space.
The first 3D source is number 0, the second sound source is number 1 etc. The maximum number one can assign to a sound source is isourcenummax - 1.
Out3d is similar to the out opcode. koutnum argument indicates the number of 3D source.
The names of 3D opcodes contain uppercase characters. Notice that uppercases are significant.
Out3d can be used only in realtime sessions, since no output will be written to a file.
It is still possible to use out opocode, however consider that its output will seem to originate from the center of the listener's head.
Setting DirectSound3D Listener properties
DsListenerPosition_i ix, iy, iz
DsListenerPosition kx, ky, kz
DsListenerOrientation_i ixfront, iyfront, izfront, ixtop, iytop,
iztop
DsListenerOrientation kxfront, kyfront, kzfront, kxtop, kytop,
kztop
DsListenerRolloffFactor_i irolloff
DsListenerRolloffFactor krolloff
DsListenerDistanceFactor_i idistancefactor
DsListenerDistanceFactor kdistancefactor
DsListenerSetAll_i iPositionx, iPositiony, iPositionz, iOrientFrontx, iOrientFronty, iOrientFrontz, iOrientTopx, iOrientTopy, iOrientTopz, iRolloffFactor, iDistanceFactor
DsListenerSetAll kPositionx, kPositiony, kPositionz, kOrientFrontx, kOrientFronty, kOrientFrontz, kOrientTopx, kOrientTopy, kOrientTopz, kRolloffFactor, kDistanceFactor
DESCRIPTION
Set the listener properties, such as position, orientation, rolloff factor and distance factor.
INITIALIZATION and PERFORMANCE
x, y, z - coordinates of listener position, expressed in meters by default (this unit of measure can be changed. See DsListenerDistanceFactor).
xfront, yfront, zfront - coordinates of listener front vector
xtop, ytop, ztop - coordinates of listener top vector
rolloff - amount of attenuation that is applied to sounds, based on the listener's distance from the sound source. Range: 0 to 10
distancefactor - scales listener's distance from sound sources.
Positionx, Positiony, Positionz, OrientFrontx, OrientFronty, OrientFrontz, OrientTopx, OrientTopy, OrientTopz, RolloffFactor, DistanceFactor - DirectSound3D listener batch parameters
DsListenerPosition sets the position of the listener in 3D aural space. Every 3D sound source and 3D listener has a position. As one would expect, the position of a 3D sound source or listener represents its location in 3D space. Listener position can be changed continuously at k-rate. Default listener position has coordinates 0,0,0.
DsListenerOrientation sets the orientation of the listener in the 3D aural space. Listener orientation is defined by the relationship between two vectors that share an origin: the top and front vectors. The top vector originates from the center of the listener's head and points straight up through the top of the head. The front vector also originates from the center of the listener's head, but it points at a right angle to the top vector, forward through the listener's face. Listener orientation can be changed continuously at k-rate. By default, the front vector is 0, 0, 1.0, and the top vector is 0, 1.0, 0
DsListenerRolloffFactor sets the amount of attenuation that is applied to sounds, based on the listener's distance from the sound source. DsListenerRolloffFactor can apply to a sound up to 10 times the rolloff experienced in the real world by setting a rolloff factor. The rolloff factor can range from 0 to 10. A value of 0 means no rolloff is applied to a sound. Every other value represents a multiple of the rolloff experienced in the real world. In other words, a value of 1 means the rolloff experienced in the real world is applied to the sound; a value of 2 means two times the rolloff experienced in the real world, and so on. Default rolloff factor is 1.0
Normally ,3D DirectSound3D API uses meters as the default unit of distance measurements. If your application does not use meters, it can set a distance factor. To set a distance factor for an application that uses feet, for example, call the DsListenerDistanceFactor opcode, specifying .30480006096 as the distancefactor parameter (this value is the number of meters in a foot). The default value is 1.0, meaning that one distance unit corresponds to 1 meter. At the default value, a position vector of 3.0, 7.2, -20.9 means that the object is 3.0 m right, 7.2 m above, and 20.9 m behind the origin. If the distance factor were changed to 2.0, the same position vector would mean that the object is 6.0 m right, 14.4 m above, and 41.8 m behind the origin.
DsListenerSetAll sets all DirectSound listener properties at once.
Setting DirectSound3D Sound Sources properties
DsMode_i imode, isourcenum
DsMode kmode, isourcenum
DsPosition_i ix, iy, iz, isourcenum
DsPosition kx, ky, kz, isourcenum
DsMinDistance_i imindistance, isourcenum
DsMinDistance kmindistance, isourcenum
DsMaxDistance_i imaxdistance, isourcenum
DsMaxDistance kmaxdistance, isourcenum
DsConeAngles_i insideconeangle, ioutsideconeangle,
isourcenum
DsConeAngles kinsideconeangle, koutsideconeangle, isourcenum
DsConeOrientation_i ixo, iyo, izo, isourcenum
DsConeOrientation kxo, kyo, kzo, isourcenum
DsConeOutsideVolume_i ivolume, isourcenum
DsConeOutsideVolume kvolume, isourcenum
DsSetAll_i iMode, iPositionx, iPositiony, iPositionz, iMinDistance, iMaxDistance, iInsideConeAngle, iOutsideConeAngle, iConeOrientx, iConeOrienty, iConeOrientz, iConeOutsideVolume, isourcenum
DsSetAll kMode, kPositionx, kPositiony, kPositionz, kMinDistance, kMaxDistance, kInsideConeAngle, kOutsideConeAngle, kConeOrientx, kConeOrienty, kConeOrientz, kConeOutsideVolume, isourcenum
DESCRIPTION
Set the sound-sources properties, such as position, minimum and maximum distance, cone angles, cone orientation and cone outside volume for each individual 3D sound source. Different sound sources can be set each one with different parameter values.
INITIALIZATION and PERFORMANCE
isourcenum - 3D audio source number
mode - operation mode for 3D sound processing. Must be set to one of the following values: 0=normal; 1=head-relative; 2= disabled.
x, y, z - coordinates of the 3D sound source position, expressed in meters by default (this unit of measure can be changed. See DsListenerDistanceFactor).
mindistance, maxdistance - minimum and maximum distance values.
insideconeangle, outsideconeangle - inside outside sound cone
angles.
xo, yo, zo - coordinates of the cone orientation vector
volume - volume of outside cone.
kMode, kPositionx, kPositiony, kPositionz, kMinDistance, kMaxDistance, kInsideConeAngle, kOutsideConeAngle, kConeOrientx, kConeOrienty, kConeOrientz, kConeOutsideVolume - DirectSound3D sound-source batch parameters
----------
DsMode sets the operation mode for 3D sound processing. Sound sources have three processing modes: normal, head-relative, and disabled. Normal processing mode is the default mode. In the head-relative mode, sound parameters (position, velocity, and orientation) are relative to the listener's parameters. In this mode, the absolute parameters of the sound are updated automatically as the listener's parameters change, so that the relative parameters remain constant. In the disabled mode, 3D sound processing is disabled and the sound seems to originate from the center of the listener's head.
DsPosition sets the position of one of the sound sources in 3D aural space. Every 3D sound source has a position. As one would expect, the position of a 3D sound source represents its location in 3D space. Source position can be changed continuously at k-rate. Default position has coordinates 0,0,0.
DsMinDistance and DsMaxDistance allow to specify minimum and maximum distance values for a 3D sound source. The minimum distance is the distance at which the sound does not get louder. Conversely, the maximum distance is the distance at which the sound no longer attenuates. For more information about the relationship between these values, see Minimum and Maximum Distances.
A 3D sound source has two sound cones: an inside cone and an outside cone. It is possible to set and retrieve the cone angles, maximum and minimum distances, and position and orientation of a source's sound projection cones by using DsConeAngles, DsConeOrientation and DsConeOutsideVolume opcodes. For more information about the behavior and characteristics of sound projection cones, see Sound Cones.
DsConeAngles sets the inside and outside cone angles. By default, cone angles are 360 degrees, meaning the object projects sound at the same volume in all directions. A smaller value means that the object projects sound at a lower volume outside the defined cone. The outside cone angle must always be equal to or greater than the inside cone angle.
DsConeOutsideVolume sets outside cone volume. The outside cone volume represents the additional volume attenuation of the sound when the listener is outside the sound source cone. This factor is expressed in hundredths of decibels. By default the outside volume is zero, meaning the sound cone will have no perceptible effect until this parameter is changed. Keep in mind that an audible outside cone volume is still subject to attenuation, due to distance from the sound source. When the listener is within the sound cone, the normal sound source volume is used. When the listener is outside the sound cone, the cone outside volume is applied as well, making the actual volume the sum of the two. Near the boundary of the cone, the volume fades smoothly between the two levels to avoid perceptual artifacts.
DsSetAll sets all DirectSound properties of a 3D sound source at once.
Setting EAX 2.0 Listener properties
EaxListenerEnvironment_i iparm
EaxListenerEnvironment kparm
EaxListenerEnvSize_i iparm
EaxListenerEnvSize kparm
EaxListenerEnvDiffusion_i iparm
EaxListenerEnvDiffusion kparm
EaxListenerRoom_i iparm
EaxListenerRoom kparm
EaxListenerRoomHF_i iparm
EaxListenerRoomHF kparm
EaxListenerDecayTime_i iparm
EaxListenerDecayTime kparm
EaxListenerDecayTimeHfRatio_i iparm
EaxListenerDecayTimeHfRatio kparm
EaxListenerReflections_i iparm
EaxListenerReflections kparm
EaxListenerReflectionsDelay_i iparm
EaxListenerReflectionsDelay kparm
EaxListenerReverb_i iparm
EaxListenerReverb kparm
EaxListenerReverbDelay_i iparm
EaxListenerReverbDelay kparm
EaxListenerRoomRolloff_i iparm
EaxListenerRoomRolloff kparm
EaxListenerAirAbsorption_i iparm
EaxListenerAirAbsorption kparm
EaxListenerFlags_i idecaitimescale, ireflectionsscale,
ireflectionsdelayscale, ireverbscale, ireverbdelayscale, idecayhflimit
EaxListenerFlags kdecaitimescale, kreflectionsscale,
kreflectionsdelayscale, kreverbscale, kreverbdelayscale, kdecayhflimit
EaxListenerAll_i iEnvironment, iEnvironmentSize, iEnvironmentDiffusion, iRoom, iRoomHF, iDecayTime, iDecayHFRatio, iReflections, iReflectionsDelay, iReverb, iReverbDelay, iRoomRolloffFactor, iAirAbsorptionHF
EaxListenerAll kEnvironment, kEnvironmentSize, kEnvironmentDiffusion, kRoom, kRoomHF, kDecayTime, kDecayHFRatio, kReflections, kReflectionsDelay, kReverb, kReverbDelay, kRoomRolloffFactor, kAirAbsorptionHF
DESCRIPTION
Set the EAX 2.0 Listener properties.
INITIALIZATION and PERFORMANCE
iparm, kparm - EAX Listener opcode parameter (its meaning varies according
to each opcode). See below.
decaitimescale, reflectionsscale, reflectionsdelayscale, reverbscale,
reverbdelayscale, decayhflimit - EAX Listener flags (can be set to 0
or 1).
Environment, EnvironmentSize, EnvironmentDiffusion, Room, RoomHF, DecayTime, DecayHFRatio, Reflections, ReflectionsDelay, Reverb, ReverbDelay, RoomRolloffFactor, AirAbsorptionHF - EAX listener batch parameters
--------------------
The listener-related opcodes allow to set the EAX listener properties. EAX Listener properties mainly deal with enviromental reverb parameters.
For an overview table of all listener properties, click here.
EaxListenerEnvironment sets the environment-model preset number.
Value range: 0 to 25.
Default value: 0.
For detailed information about this property
click here.
EaxListenerEnvSize sets the apparent size of the surrounding
“room.”
Value range: 1.0 to 100.0 meters
Default value: 7.5 meters
For detailed information about this property
click here.
EaxListenerEnvDiffusion controls the echo density in the reverberation
decay.
Value range: 0.0 to 1.0
For detailed information about this property
click here.
EaxListenerRoom sets the maximum amount of reflections and reverberation
added to the sound mix in the listener.
Value range: -10000 to 0 hundredths of a dB
For detailed information about this property
click here.
EaxListenerRoomHF modifies reflected sound by attenuating it at high
frequencies.
Value range: -10000 to 0 hundredths of a dB
For detailed information about this property
click here.
EaxListenerDecayTime sets the reverberation decay time.
Value range: 0.1 to 20.0 seconds
For detailed information about this property
click here.
EaxListenerDecayTimeHfRatio sets the spectral quality of the Decay
Time parameter.
Value range: 0.1 to 20.0
For detailed information about this property
click here.
EaxListenerReflections controls the overall amount of initial reflections
relative to the Room property.
Value range: -10000 to 1000 hundredths of a dB
For detailed information about this property
click here.
EaxListenerReflectionsDelay sets the amount of delay between the arrival
time of the direct path from the source to the first reflection from the
source.
Value range: 0.0 to 0.3 seconds
For detailed information about this property
click here.
EaxListenerReverb controls the overall amount of later reverberation
relative to the Room property.
Value range: -10000 to 2000
For detailed information about this property
click here.
EaxListenerReverbDelay defines the begin time of the late reverberation
relative to the time of the initial reflection (the first of the early
reflections).
Value range: 0.0 to 0.1 seconds
For detailed information about this property
click here.
EaxListenerRoomRolloff attenuates the reflected sound (containing
both reflections and reverberation) according to source-listener distance.
Value range: 0.0 to 10.0
For detailed information about this property
click here.
EaxListenerAirAbsorption controls the distance-dependent attenuation
at high frequencies caused by the propagation medium.
Value range: -100.0 to 0.0 hundredths of a dB per meter
For detailed information about this property
click here.
EaxListenerFlags sets the listener flags.
Value range: 0 or 1 (false or true) for each argument
For detailed information about this property
click here.
EaxListenerAll sets all EAX listener properties (except for EAX listener flags) at once.
Setting EAX 2.0 Sound Sources properties
EaxSourceDirect_i iparm, isourcenum
EaxSourceDirect kparm, isourcenum
EaxSourceDirectHF_i iparm, isourcenum
EaxSourceDirectHF kparm, isourcenum
EaxSourceRoom_i iparm, isourcenum
EaxSourceRoom kparm, isourcenum
EaxSourceRoomHF_i iparm, isourcenum
EaxSourceRoomHF kparm, isourcenum
EaxSourceObstruction_i iparm, isourcenum
EaxSourceObstruction kparm, isourcenum
EaxSourceObstructionRatio_i iparm,
isourcenum
EaxSourceObstructionRatio kparm, isourcenum
EaxSourceOcclusion_i iparm, isourcenum
EaxSourceOcclusion kparm, isourcenum
EaxSourceOcclusionRatio_i iparm, isourcenum
EaxSourceOcclusionRatio kparm, isourcenum
EaxSourceOcclusionRoomRatio_i iparm,
isourcenum
EaxSourceOcclusionRoomRatio kparm, isourcenum
EaxSourceRoomRolloff_i iparm, isourcenum
EaxSourceRoomRolloff kparm, isourcenum
EaxSourceAirAbsorption_i iparm, isourcenum
EaxSourceAirAbsorption kparm, isourcenum
EaxSourceOutsideVolumeHF_i iparm,
isourcenum
EaxSourceOutsideVolumeHF kparm, isourcenum
EaxSourceFlags_i iDIRECTHFAUTO, iROOMAUTO, iROOMHFAUTO
EaxSourceFlags kDIRECTHFAUTO, kROOMAUTO, kROOMHFAUTO
EaxSourceAll_i iDirect, iDirectHF, iRoom, iRoomHF, iObstruction, iObstructionLFRatio, iOcclusion, iOcclusionLFRatio, iOcclusionRoomRatio, iRoomRolloffFactor, iAirAbsorptionFactor, iOutsideVolumeHF, isourcenum
EaxsourceAll kDirect, kDirectHF, kRoom, kRoomHF, kObstruction, kObstructionLFRatio, kOcclusion, kOcclusionLFRatio, kOcclusionRoomRatio, kRoomRolloffFactor, kAirAbsorptionFactor, kOutsideVolumeHF, isourcenum
DESCRIPTION
Set the EAX 2.0 properties of each individual 3D sound source. Different sound sources can be configured each one with different EAX parameters.
INITIALIZATION and PERFORMANCE
isourcenum - 3D audio source number
iparm, kparm - EAX source opcode parameter (its meaning varies according
to each opcode). See below.
DIRECTHFAUTO, ROOMAUTO, ROOMHFAUTO - 3D sound source flags
Direct, DirectHF, Room, RoomHF, Obstruction, ObstructionLFRatio, Occlusion, OcclusionLFRatio, OcclusionRoomRatio, RoomRolloffFactor, AirAbsorptionFactor, OutsideVolumeHF - EAX sound-source batch parameters
EaxSourceDirect applies a relative correction to this sound source’s
direct-path intensity.
Value range: -10000 to 1000 hundredths of a dB
For detailed information about this property
click here.
EaxSourceDirectHF applies a relative correction to the high-frequency
component of the sound source’s direct-path intensity.
Value range: -10000 to 0 hundredths of a dB
For detailed information about this property
click here.
EaxSourceRoom is the volume control for reflected sound (early reflections
and reverberation).
Value range: -10000 to 1000 hundredths of a dB
For detailed information about this property
click here.
EaxSourceRoomHF controls a low-pass filter that applies to the reflected
sound added to this source.
Value range: -10000 to 0 hundredths of a dB
For detailed information about this property
click here.
EaxSourceObstruction specifies the amount of obstruction muffling
to apply to a sound source’s direct-path sound.
Value range -10000 to 0 hundredths of a dB
For detailed information about this property
click here.
EaxSourceObstructionRatio specifies the obstruction attenuation at
low frequencies relative to the attenuation at high frequencies.
Value range: 0.0 to 1.0
For detailed information about this property
click here.
EaxSourceOcclusion specifies the amount of occlusion muffling to apply
to a sound source’s direct sound and to its reflected sound.
Value range: -10000 to 0 hundredths of a dB
For detailed information about this property
click here.
EaxSourceOcclusionRatio specifies the occlusion attenuation at low
frequencies relative to the attenuation at high frequencies.
Value range: 0.0 to 1.0
For detailed information about this property
click here.
EaxSourceOcclusionRoomRatio specifies the additional amount of occlusion
attenuation to be applied to reflected sound (early reflections and
reverberation).
Value range: 0.0 to 10.0
For detailed information about this property
click here.
EaxSourceRoomRolloff attenuates the reflected sound (early reflections
and reverberation) according to source-listener distance.
Value range: 0.0 to 10.0
For detailed information about this property
click here.
EaxSourceAirAbsorption controls the distance-dependent attenuation
at high frequencies caused by the propagation medium.
Value range: 0.0 to 10.0
For detailed information about this property
click here.
EaxSourceOutsideVolumeHF
Value range: -10000 to 0 hundredths of a dB
For detailed information about this property
click here.
EaxSourceFlags sets the flags of a sound source.
Value range: 0 or 1 (false or true) for each argument
For detailed information about this property
click here.
EaxSourceAll sets all properties of a 3D sound source at once (except for flags) .
DirectSound3D and EAX 2.0 property deferred settings
DsEaxSetDeferredFlag iflag
DsCommitDeferredSettings_i
DsCommitDeferredSettings
DESCRIPTION
Set DirectSound3D and EAX deferred flag and commits deferred property updating.
INITIALIZATION
iflag - activates or deactivates deferred settings (1=deferred; 0=immediate)
Every change to a 3D listener parameter requires a recalculation of the 3D positional filter parameters. Therefore, in order to get maximum efficiency, it is possible to defer parameter changes by using DsEaxSetDeferredFlag opcode, setting iflag=1. When all settings are complete, a call of DsCommitDeferredSettings will actually update all the parameters that were changed in the meanwhile. This applies both to DirectSound3D opcodes and to EAX opcodes.
Any deferred settings are overwritten if you call the same setting with iflag set to 0 (immediate) before calling DsCommitDeferredSettings. That is, if you set the listener position to (1,2,3) by using the deferred flag and then set the listener position to (4,5,6) with the immediate flag, the position will be (4,5,6). Then, if you call DsCommitDeferredSettings opocode, the position will still be (4,5,6).
These opcodes allow to set a 3D sound buffer's parameters individually or in batches. To set individual values, your application can use the applicable IDirectSound3DBuffer interface method. However, applications often must set or retrieve all the values that describe the buffer at once. An application can perform a batch parameter manipulation in a single call by using the IDirectSound3DBuffer::GetAllParameters and IDirectSound3DBuffer::SetAllParameters methods.
Click here for more infomation about deferred settings.