3D sound source object More...

Inherits CriDisposable.

Classes
struct	Config
	Structure for 3D sound source configuration More...

Public Member Functions
	CriAtomEx3dSource (bool enableVoicePriorityDecay=false, uint randomPositionListMaxLength=0)
	Creates a 3D sound source object More...

override void	Dispose ()
	Discards a 3D sound source object More...

void	Update ()
	Updates the 3D sound source More...

void	ResetParameters ()
	Initializes 3D sound source parameters More...

void	SetPosition (float x, float y, float z)
	Sets the position of the 3D sound source More...

void	SetVelocity (float x, float y, float z)
	Sets the velocity of the 3D sound source More...

void	SetOrientation (Vector3 front, Vector3 top)
	Sets the orientation of the 3D sound source More...

void	SetConeOrientation (float x, float y, float z)
	Sets the orientation of the sound cone of the 3D sound source More...

void	SetConeParameter (float insideAngle, float outsideAngle, float outsideVolume)
	Sets the sound cone parameters of the 3D sound source More...

void	SetMinMaxDistance (float minDistance, float maxDistance)
	Sets the minimum/maximum distances of the 3D sound source More...

void	SetInteriorPanField (float sourceRadius, float interiorDistance)
	Sets the interior Panning boundary distance of the 3D sound source More...

void	SetDopplerFactor (float dopplerFactor)
	Sets the Doppler coefficient of the 3D sound source More...

void	SetVolume (float volume)
	Sets the volume of the 3D sound source More...

void	SetMaxAngleAisacDelta (float maxDelta)
	Sets the maximum amount of change in angle AISAC control value More...

void	SetAttenuationDistanceSetting (bool flag)
	Sets the distance attenuation More...

bool	GetAttenuationDistanceSetting ()
	Gets distance attenuation settings More...

void	SetRandomPositionConfig (CriAtomEx.Randomize3dConfig?config)
	Settings related to position randomization of 3D sound sources More...

void	SetRandomPositionList (Vector3[] positionList)
	Sets the list of coordinates to be used to randomize the position of a 3D sound source More...

void	Set3dRegion (CriAtomEx3dRegion region3d)
	Sets the 3D region More...

void	SetListenerBasedElevationAngleAisacControlId (ushort aisacControlId)
	Sets the listener reference elevation AISAC control setting ID More...

void	SetSourceBasedElevationAngleAisacControlId (ushort aisacControlId)
	Sets the sound source reference azimuth AISAC control ID More...

void	SetDistanceAisacControlId (ushort aisacControlId)
	Sets the Distance AISAC Control ID More...

bool	IsDestroyable ()
	Check if the 3D sound source can be discarded More...

CriAtomEx.NativeVector	GetPosition ()
	Getting the position of the 3D sound source More...

Detailed Description

3D sound source object

Description:: An object for handling the 3D sound source.
Used for 3D Positioning.

You set the parameters and position information of the 3D sound source through the 3D sound source object.

Constructor & Destructor Documentation

CriAtomEx3dSource	(	bool	enableVoicePriorityDecay = `false`,
		uint	randomPositionListMaxLength = `0`
	)

inline

Creates a 3D sound source object

Parameters

enableVoicePriorityDecay	Enables voice priority attenuation according to the distance
randomPositionListMaxLength	Gets the maximum number of elements that can be in the coordinates list used for position randomization of a 3D sound source

Description:: Create a 3D sound source object based on the config for creating a 3D sound source object.

Note:: The library must be initialized before calling this function.

Member Function Documentation

override void Dispose ( )

inline

Discards a 3D sound source object

Description:: Discards a 3D source object.
When this function is called, all the resources allocated in the DLL when creating the 3D sound source object are released.
If there are any sounds being played by an AtomExPlayer with the 3D sound source object set, either stop those sounds or discard the AtomExPlayer before calling this function.

void Update ( )

inline

Updates the 3D sound source

Description:: Updates the 3D sound source using the parameters set to the 3D sound source.
This function updates all the parameters set to the 3D sound source.
It is more efficient to change multiple parameters before performing update than to update using this function each time a parameter is changed.

Note:: This function runs independently of the parameter update in the AtomExPlayer ( CriWare.CriAtomExPlayer::UpdateAll , CriAtomExPlayer::Update ).
When you change the parameter of the 3D sound source, perform the update process using this function.

Example:

： // 音源の作成 CriAtomEx3dSource source = new CriAtomEx3dSource(); ： // 音源の位置を設定 source.SetPosition(0.0f, 0.0f, 1.0f);

// 音源の速度を設定 source.SetVelocity(1.0f, 0.0f, 0.0f);

// 注意）この時点では音源の位置や速度はまだ変更されていません。

// 変更の適用 source.Update(); ：

void ResetParameters ( )

inline

Initializes 3D sound source parameters

Description:: Clears the parameters set to the 3D sound source and restores the initial values.

Note:: To actually apply the cleared parameters, you need to call the CriWare.CriAtomEx3dSource::Update function.

See also: CriAtomEx3dSource::Update

void SetPosition	(	float	x,
		float	y,
		float	z
	)

inline

Sets the position of the 3D sound source

Parameters

x	X coordinate
y	Y coordinate
z	Z coordinate

Description:: Sets the position of the 3D sound source.
The position is used for calculating the distance attenuation and localization.
The position is specified as a 3D vector.
The unit of the position is determined by the distance factor of the 3D listener (set using the CriWare.CriAtomEx3dListener::SetDistanceFactor function).
The default is (0.0f, 0.0f, 0.0f).
Since the position cannot be set on the data, the value set using this function is always used.

Note:: To actually apply the set parameters, you need to call the CriWare.CriAtomEx3dSource::Update function.

See also: CriAtomEx3dSource::Update

void SetVelocity	(	float	x,
		float	y,
		float	z
	)

inline

Sets the velocity of the 3D sound source

Parameters

x	Velocity along X axis
y	Velocity along Y axis
z	Velocity along Z axis

Description:: Sets the velocity of the 3D sound source.
The velocity is used to calculate the Doppler effect.
The velocity is specified as a 3D vector.
The unit of velocity is the distance traveled per second.
The unit of the distance is determined by the distance factor of the 3D listener (set using the CriWare.CriAtomEx3dListener::SetDistanceFactor function). The default is (0.0f, 0.0f, 0.0f).
Since the velocity cannot be set on the data, the value set using this function is always used.

Note:: To actually apply the set parameters, you need to call the CriWare.CriAtomEx3dSource::Update function.

See also: CriAtomEx3dSource::Update

void SetOrientation	(	Vector3	front,
		Vector3	top
	)

inline

Sets the orientation of the 3D sound source

Parameters

front	Forward vector
top	Upper vector

Description:

Sets the orientation of the 3D sound source.
The orientation is determined by a sound cone.
The sound cone represents the direction in which the sound is emitted from the sound source. It is used to express the directivity of the sound.
The orientation of the sound cone is specified by a 3D vector. The orientation vector is then normalized and used by the library internally.
Since the direction of the sound cone cannot be set on the data side, calling this function is necessary to set the orientation.
The default values are as follows.

Forward vector: (0.0f, 0.0f, 1.0f)
Upper vector: (0.0f, 1.0f, 0.0f)

Note:: If you set the orientation of the sound cone, the upper vector is ignored and only the forward vector is used.
Also, if you are using Ambisonics playback, Ambisonics will rotate according to the orientation specified by this function and the orientation of the listener.

Note:: You must call the CriWare.CriAtomEx3dSource::Update function to actually apply the parameters you have set.
Please note that sound cones cannot be applied to Ambisonics.

See also: CriAtomEx3dSource::SetConeParameter, CriAtomEx3dSource::Update

void SetConeOrientation	(	float	x,
		float	y,
		float	z
	)

inline

Sets the orientation of the sound cone of the 3D sound source

Deprecated:: 削除予定の非推奨APIです。 CriWare.CriAtomEx3dSource.SetOrientation(Vector3, Vector3) の使用を検討してください。

Parameters

x	Value in X direction
y	Value in Y direction
z	Value in Z direction

Description:: Sets the orientation of the sound cone of the 3D sound source.
The sound cone represents the direction in which sound is emitted from a sound source and is used to express the directionality of the sound.
The orientation of the sound cone is specified using a 3D vector.
The orientation vector that is set is normalized inside the library before being used.
The default is (0.0f, 0.0f, -1.0f).
As you cannot set the orientation of the sound cone on the data, the setting in this function is always used.

Note:: To actually apply the set parameters, you need to call the CriWare.CriAtomEx3dSource::Update function.

See also: CriAtomEx3dSource::SetConeParameter, CriAtomEx3dSource::Update

void SetConeParameter	(	float	insideAngle,
		float	outsideAngle,
		float	outsideVolume
	)

inline

Sets the sound cone parameters of the 3D sound source

Parameters

insideAngle	Sound cone inside angle
outsideAngle	Sound cone outside angle
outsideVolume	Sound cone outside volume

Description:

Sets the sound cone parameters of the 3D sound source.
The sound cone represents the direction in which sound is emitted from a sound source and is used to express the directionality of the sound.
The sound cone consists of inner cone and outer cone. The inside angle represents the angle of the inner cone, the outside angle represents the angle of the outer cone, and the outside volume represents the volume beyond the outer cone angle.
At angles smaller than the inner cone angle, no attenuation is applied by the cone. In the direction between the inner and outer cones, the sound is gradually attenuated to the outside volume.
The inside and outside angles are specified within the range of 0.0f to 360.0f.
The outside volume is specifies as a scale factor for the amplitude within the range of 0.0f to 1.0f (the unit is not decibel).
The default values when initializing the library are as follows, and no attenuation is applied by the cone.

Inside angle: 360.0f
Outside angle: 360.0f
Outside volume: 0.0f

If this function is called when the sound cone parameters are set on the data, the following settings are applied:

Inside angle: Addition
Outside angle: Addition
Outside volume: Multiplication .

Note:: To actually apply the set parameters, you need to call the CriWare.CriAtomEx3dSource::Update function.

See also: CriAtomEx3dSource::Update

void SetMinMaxDistance	(	float	minDistance,
		float	maxDistance
	)

inline

Sets the minimum/maximum distances of the 3D sound source

Parameters

minDistance	Minimum distance
maxDistance	Maximum distance

Description:

Sets the minimum/maximum distances of the 3D sound source.
The minimum distance represents the distance at which the volume cannot be increased any further.
The maximum distance is the distance with the lowest volume.
The unit of the distance is determined by the distance factor of the 3D listener (set using the CriWare.CriAtomEx3dListener::SetDistanceFactor function).
The default values when the library is initialized are as follows:

Minimum distance: 0.0f
Maximum distance: 0.0f

When this function is called when the minimum/maximum distances are set on the data, the values on the data are overridden (ignored).

Note:: To actually apply the set parameters, you need to call the CriWare.CriAtomEx3dSource::Update function.

See also: CriAtomEx3dSource::Update

void SetInteriorPanField	(	float	sourceRadius,
		float	interiorDistance
	)

inline

Sets the interior Panning boundary distance of the 3D sound source

Parameters

sourceRadius	3D sound source radius
interiorDistance	Interior distance

Description:: Sets the interior Panning boundary distance of the 3D sound source.
The radius of the 3D sound source is the radius when the 3D sound source is considered as a sphere.
Interior distance is the distance from the radius of the 3D sound source to which the interior Panning is applied.
Within the radius of the 3D sound source, interior Panning is applied, but since the interior distance is treated as 0.0, the sound is played back from all speakers at the same volume.
Within the interior distance, interior Panning is applied.
Outside the interior distance, interior Panning is not applied and the sound is played from 1 or 2 speakers closest to the sound source position.
By default, the 3D sound source radius is set to 0.0f, and interior distance is set to 0.0f (depending on the minimum distance of the 3D sound source).

Note:: To actually apply the set parameters, you need to call the CriWare.CriAtomEx3dSource::Update function.

See also: CriAtomEx3dSource::Update, CriAtomEx3dSource::SetMinMaxDistance

void SetDopplerFactor ( float dopplerFactor )

inline

Sets the Doppler coefficient of the 3D sound source

Parameters

dopplerFactor Doppler coefficient

Description:: Set the Doppler coefficient of the 3D sound source.
The Doppler coefficient specifies the scale factor for exaggerating the Doppler effect calculated when the sound velocity of 340m/s.
For example, if you specify 2.0f, the pitch is multiplied by 2 if the velocity of the sound is 340m/s.
If you specify 0.0f, the Doppler effect is disabled.
The default value when the library is initialized is 0.0f.
When this function is called when the Doppler coefficient is set on the data, the value on the data is overridden (ignored).

Note:: To actually apply the set parameters, you need to call the CriWare.CriAtomEx3dSource::Update function.

See also: CriAtomEx3dSource::Update

void SetVolume ( float volume )

inline

Sets the volume of the 3D sound source

Parameters

volume Volume

Description:: Sets the volume of the 3D sound source.
The volume of the 3D sound source affects only the volume related to localization (L,R,SL,SR), and does not affect the output level of LFE or the center.
For the volume value, specify a real value in the range of 0.0f to 1.0f.
The volume value is a scale factor for the amplitude of the sound data (the unit is not decibel).
For example, if you specify 1.0f, the original sound is played at its unmodified volume.
If you specify 0.5f, the sound is played at the volume by halving the amplitude (-6dB) of the original waveform.
If you specify 0.0f, the sound is muted (silent).
The default value when the library is initialized is 1.0f.
When this function is called when the volume of the 3D sound source is set on the data, the value on the data is multiplied by this value.

Note:: To actually apply the set parameters, you need to call the CriWare.CriAtomEx3dSource::Update function.

See also: CriAtomEx3dSource::Update

void SetMaxAngleAisacDelta ( float maxDelta )

inline

Sets the maximum amount of change in angle AISAC control value

Parameters

maxDelta Maximum amount of change in angle AISAC control value

Description:: Sets the maximum amount of change when the AISAC control value is changed by the angle AISAC.
By changing the maximum amount of change to a lower value, the change of the AISAC control value by angle AISAC can be made smooth even if the relative angle between the sound source and the listener changes abruptly.
For example, if (0.5f / 30.0f) is set, the change takes place over 30 frames when the angle changes from 0° to 180°.
The default value is 1.0f (no limit).
Since this parameter cannot be set on the data, the value set using this function is always used.

Note:: To actually apply the set parameters, you need to call the CriWare.CriAtomEx3dSource::Update function.
The maximum amount of change set by this function is applied only to the change of the angle AISAC control value calculated based on the localization angle. It does not affect the localization angle itself.

See also: CriAtomEx3dSource::Update

void SetAttenuationDistanceSetting ( bool flag )

inline

Sets the distance attenuation

Parameters

flag	Whether to enable the distance attenuation (True: enable, False: disable)

Description:: Sets whether to enable or disable the volume variation by distance attenuation.
The default is True (enabled).

Note:: To actually apply the set parameters, you need to call the CriWare.CriAtomEx3dSource::Update function.

See also: CriAtomEx3dSource::Update, CriAtomEx3dSource::GetAttenuationDistanceSetting

bool GetAttenuationDistanceSetting ( )

inline

Gets distance attenuation settings

Returns: Distance attenuation setting (True: enable, False: disable)

Description:: Gets whether the volume variation by distance attenuation is enabled or disabled.
The default is True (enabled).

See also: CriAtomEx3dSource::SetAttenuationDistanceSetting

void SetRandomPositionConfig ( CriAtomEx.Randomize3dConfig? config )

inline

Settings related to position randomization of 3D sound sources

Parameters

config Config structure (nullable) used to randomize the positions of the 3D sound sources.

Description:: Assigns the randomized position to the 3D sound source handle. Once this function is executed, the position of the voice will change randomly according to the original position information and settings.

Note:: You can clear the settings by specifying null for the argument config.

Note:: You must call the CriWare.CriAtomEx3dSource::Update function to actually apply the parameters you have set.
This function does not affect the audio currently being played.
The new parameters will be applied from the next audio playback.

See also: CriAtomEx::Randomize3dConfig

void SetRandomPositionList ( Vector3[] positionList )

inline

Sets the list of coordinates to be used to randomize the position of a 3D sound source

Parameters

positionList Position coordinates list

Description:: Specifies a list of possible coordinates.
When the randomization of the 3D sound source's position is enabled, the coordinates will be randomly picked from that list.

Note:: This parameter is referenced only when CriWare.CriAtomEx::Randomize3dCalcType::List
is set as the calculation method for the coordinates.
If any other calculation method is set, this parameter will be ignored.

Note:: You must call the CriWare.CriAtomEx3dSource::Update function to actually apply the parameters you have set.
The area passed to this function will no longer be referenced after the execution of the
CriWare.CriAtomEx3dSource::SetRandomPositionList function is completed.
Instead, the list of the coordinates will be saved internally.
Therefore, setting a list whose length exceeds
CriWare.CriAtomEx3dSource::Config::randomPositionListMaxLength will result in an error.

See also: CriAtomEx::Randomize3dConfig, CriAtomEx3dSource::Config

void Set3dRegion ( CriAtomEx3dRegion region3d )

inline

Sets the 3D region

Description:: Set the 3D regions to the 3D sound source.

Note:: If the regions set to the 3D sound source and 3D listener set to the same ExPlayer are different,
and if there is no 3D Transceiver that has the same region as the 3D sound source, the sound is muted.
To actually apply the set parameters, you need to call the CriWare.CriAtomEx3dSource::Update function.

See also: CriAtomEx3dRegion::Create, CriAtomEx3dSource::Update

void SetListenerBasedElevationAngleAisacControlId ( ushort aisacControlId )

inline

Sets the listener reference elevation AISAC control setting ID

Parameters

aisacControlId Listener reference elevation AISAC control ID

Description:: Specifies the AISAC control ID linked to the elevation of the sound source seen from the listener.
The listener reference elevation AISAC control ID set on the data is overridden by this function.

Note:: To actually apply the set parameters, you need to call the CriWare.CriAtomEx3dSource::Update function.

See also: CriAtomEx3dSource::Update

void SetSourceBasedElevationAngleAisacControlId ( ushort aisacControlId )

inline

Sets the sound source reference azimuth AISAC control ID

Parameters

aisacControlId Sound source reference azimuth AISAC control ID

Description:: Specifies the AISAC control ID linked to the azimuth of the listener as seen from the sound source.
The sound source reference azimuth AISAC control ID set on the data is overridden by this function.

Note:: To actually apply the set parameters, you need to call the CriWare.CriAtomEx3dSource::Update function.

See also: CriAtomEx3dSource::Update

void SetDistanceAisacControlId ( ushort aisacControlId )

inline

Sets the Distance AISAC Control ID

Parameters

aisacControlId Sound source reference azimuth AISAC control ID

Description:: Specifies the AISAC control ID to be linked to the distance attenuation between the minimum and maximum distances.
If an AISAC control ID is set with this function, the default distance attenuation is disabled.
The distance AISAC control ID set on the data side is overridden by this function.

Note:: To actually apply parameter changes, it is necessary to call the CriAtomEx3dSource.Update function.
When this function is executed, any previous changes due to the AISAC control ID set to the 3D sound source will be invalidated,
while the parameters changes previously applied to the audio being played will stay unchanged.
Therefore, it is recommended to execute this function when no audio associated with the specified 3D sound source is being played.

See also: CriAtomEx3dSource::Update

bool IsDestroyable ( )

inline

Check if the 3D sound source can be discarded

Returns: Status of 3D sound source (true = can be discarded, false = cannot be discarded)

Description:: Checks if a 3D Source can be destroyed.
Calling the Dispose function will fail to destroy a 3D Source if it is attached to an AtomExPlayer still playing audio.
In this case, you will need to either destroy all AtomExPlayers that have this 3D Source attached, or attach a different 3D Source to them in order to destroy the 3D Source.

See also: Dispose, CriAtomExPlayer.Set3dSource

CriAtomEx.NativeVector GetPosition ( )

inline

Getting the position of the 3D sound source

Description:: Gets the position of the 3D sound source.
The position is returned as a 3D vector.

The documentation for this class was generated from the following file:

CriAtomEx3dSource.cs

Classes

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation