CriAtomEx3d API

Data Structures
struct	CriAtomExVectorTag
	3D vector structure More...
struct	CriAtomEx3dSourceConfigTag
	Configuration structure used to create a 3D sound source. More...
struct	CriAtomEx3dSourceListConfigTag
	Configuration structure used to create a 3D sound source list. More...
struct	CriAtomEx3dListenerConfigTag
	Configuration structure used to create a 3D listener. More...
struct	CriAtomEx3dRegionConfigTag
	Config structure for creating 3D region handle. More...
struct	CriAtomEx3dTransceiverConfigTag
	Config structure for creating 3D Transceiver handle. More...
struct	CriAtomEx3dSourceRandomPositionConfigTag
	Configuration structure for randomizing 3D sound source position. More...
struct	CriAtomEx3dSourceRandomPositionResultInfoDetailTag
	Details of position coordinate results when randomizing 3D sound source position. More...

Macros
#define	CRIATOMEX3DSOURCE_MAX_RANDOM_POSITION_CALCULATION_PARAMETERS   (3)
	Maximum number of parameters for various calculation methods in randomizing 3D sound sources. More...
#define	criAtomEx3dSource_SetDefaultConfig(p_config)
	Assign the default values to the configuration structure used to create a 3D sound source. More...
#define	criAtomEx3dSourceList_SetDefaultConfig(p_config)
	Assign the default values to the configuration structure used to create a 3D sound sources list. More...
#define	criAtomEx3dListener_SetDefaultConfig(p_config)
	Assign the default values to the configuration structure used to create a 3D listener. More...
#define	criAtomEx3dRegion_SetDefaultConfig(p_config)
	Assign the default values to the configuration structure used to create a 3D Region. More...
#define	criAtomEx3dTransceiver_SetDefaultConfig(p_config)
	Assign the default values to the configuration structure used to create a 3D Transceiver. More...
#define	criAtomEx3dSource_SetDefaultConfigForRandomPosition(p_config)
	Set default values in config structure for randomizing 3D sound source position. More...
#define	criAtomEx3dSource_SetMinMaxDistance(ex_3d_source, min_attenuation_distance, max_attenuation_distance)    criAtomEx3dSource_SetMinMaxAttenuationDistance((ex_3d_source), (min_attenuation_distance), (max_attenuation_distance))
	Set min and max values of the attenuation distance of a 3D source. More...
#define	criAtomEx3dSource_ChangeDefaultMinMaxDistance(min_attenuation_distance, max_attenuation_distance)    criAtomEx3dSource_ChangeDefaultMinMaxAttenuationDistance((min_attenuation_distance), (max_attenuation_distance))
	Change the default values of max and min of attenuation distance of a 3D source. More...

Typedefs
typedef struct CriAtomExVectorTag	CriAtomExVector
	3D vector structure More...
typedef struct CriAtomEx3dSourceConfigTag	CriAtomEx3dSourceConfig
	Configuration structure used to create a 3D sound source. More...
typedef struct CriAtomEx3dSourceListConfigTag	CriAtomEx3dSourceListConfig
	Configuration structure used to create a 3D sound source list. More...
typedef struct CriAtomEx3dListenerConfigTag	CriAtomEx3dListenerConfig
	Configuration structure used to create a 3D listener. More...
typedef CriAtomEx3dSourceObj *	CriAtomEx3dSourceHn
	3D sound source handle More...
typedef CriAtomEx3dSourceListObj *	CriAtomEx3dSourceListHn
	3D sound source handle list More...
typedef CriAtomEx3dListenerObj *	CriAtomEx3dListenerHn
	3D listener handle More...
typedef struct CriAtomEx3dRegionConfigTag	CriAtomEx3dRegionConfig
	Config structure for creating 3D region handle. More...
typedef CriAtomEx3dRegionObj *	CriAtomEx3dRegionHn
	3D region handle More...
typedef struct CriAtomEx3dTransceiverConfigTag	CriAtomEx3dTransceiverConfig
	Config structure for creating 3D Transceiver handle. More...
typedef CriAtomEx3dTransceiverObj *	CriAtomEx3dTransceiverHn
	3D Transceiver handle More...
typedef enum CriAtomEx3dSourceRandomPositionCalculationTypeTag	CriAtomEx3dSourceRandomPositionCalculationType
	How to calculate position coordinates when randomizing the position of a 3D sound source. More...
typedef struct CriAtomEx3dSourceRandomPositionConfigTag	CriAtomEx3dSourceRandomPositionConfig
	Configuration structure for randomizing 3D sound source position. More...
typedef struct CriAtomEx3dSourceRandomPositionResultInfoDetailTag	CriAtomEx3dSourceRandomPositionResultInfoDetail
	Details of position coordinate results when randomizing 3D sound source position. More...
typedef void(*	CriAtomEx3dSourceRandomPositionCalculationCbFunc) (void *obj, const CriAtomEx3dSourceHn ex_3d_source, CriAtomExVector *result_pos)
	Callback function type for calculating position coordinates when randomizing the position of a 3D sound source. More...
typedef void(*	CriAtomEx3dSourceRandomPositionResultCbFunc) (void *obj, const CriAtomEx3dSourceRandomPositionResultInfoDetail *result_info)
	Position coordinate result callback function type for randomizing the position of a 3D sound source. More...

Enumerations
enum	CriAtomEx3dSourceRandomPositionCalculationTypeTag {   CRIATOMEX3DSOURCE_RANDOM_POSITION_CALCULATION_TYPE_NONE = -1 , CRIATOMEX3DSOURCE_RANDOM_POSITION_CALCULATION_TYPE_RECTANGLE = 0 , CRIATOMEX3DSOURCE_RANDOM_POSITION_CALCULATION_TYPE_CUBOID , CRIATOMEX3DSOURCE_RANDOM_POSITION_CALCULATION_TYPE_CIRCLE ,   CRIATOMEX3DSOURCE_RANDOM_POSITION_CALCULATION_TYPE_CYLINDER , CRIATOMEX3DSOURCE_RANDOM_POSITION_CALCULATION_TYPE_SPHERE , CRIATOMEX3DSOURCE_RANDOM_POSITION_CALCULATION_TYPE_CALLBACK , CRIATOMEX3DSOURCE_RANDOM_POSITION_CALCULATION_TYPE_LIST ,   CRIATOMEX3DSOURCE_RANDOM_POSITION_CALCULATION_TYPE_ENUM_SIZE_IS_4BYTES = 0x7FFFFFFF }
	How to calculate position coordinates when randomizing the position of a 3D sound source. More...

Functions
CriSint32	criAtomEx3dSource_CalculateWorkSize (const CriAtomEx3dSourceConfig *config)
	Calculate the size of the work buffer required to create a 3D sound source. More...
CriAtomEx3dSourceHn	criAtomEx3dSource_Create (const CriAtomEx3dSourceConfig *config, void *work, CriSint32 work_size)
	Create a 3D sound source. More...
void	criAtomEx3dSource_Destroy (CriAtomEx3dSourceHn ex_3d_source)
	Destroy a 3D sound source. More...
void	criAtomEx3dSource_Update (CriAtomEx3dSourceHn ex_3d_source)
	Update a 3D sound source. More...
void	criAtomEx3dSource_ResetParameters (CriAtomEx3dSourceHn ex_3d_source)
	Reset the 3D sound source parameters. More...
void	criAtomEx3dSource_SetPosition (CriAtomEx3dSourceHn ex_3d_source, const CriAtomExVector *position)
	Set the position of a 3D sound source. More...
CriAtomExVector	criAtomEx3dSource_GetPosition (CriAtomEx3dSourceHn ex_3d_source)
	Get the 3D sound source position. More...
void	criAtomEx3dSource_SetVelocity (CriAtomEx3dSourceHn ex_3d_source, const CriAtomExVector *velocity)
	Set the velocity of a 3D sound source. More...
void	criAtomEx3dSource_SetOrientation (CriAtomEx3dSourceHn ex_3d_source, const CriAtomExVector *front, const CriAtomExVector *top)
	Setting the direction of 3D sound source. More...
void	criAtomEx3dSource_SetConeParameter (CriAtomEx3dSourceHn ex_3d_source, CriFloat32 inside_angle, CriFloat32 outside_angle, CriFloat32 outside_volume)
	Set the parameters of the sound cone of a 3D sound source. More...
void	criAtomEx3dSource_ChangeDefaultConeParameter (CriFloat32 inside_angle, CriFloat32 outside_angle, CriFloat32 outside_volume)
	Change the default values of the sound cone parameters a 3D sound source. More...
void	criAtomEx3dSource_SetMinMaxAttenuationDistance (CriAtomEx3dSourceHn ex_3d_source, CriFloat32 min_attenuation_distance, CriFloat32 max_attenuation_distance)
	Set the minimum and maximum attenuation distances of a 3D sound source. More...
void	criAtomEx3dSource_ChangeDefaultMinMaxAttenuationDistance (CriFloat32 min_attenuation_distance, CriFloat32 max_attenuation_distance)
	Change the default values of the minimum and maximum attenuation distances of a 3D sound source. More...
void	criAtomEx3dSource_SetInteriorPanField (CriAtomEx3dSourceHn ex_3d_source, CriFloat32 source_radius, CriFloat32 interior_distance)
	Set the interior panning boundaries of a 3D sound source. More...
void	criAtomEx3dSource_ChangeDefaultInteriorPanField (CriFloat32 source_radius, CriFloat32 interior_distance)
	Change the default value of the interior panning boundaries of a 3D sound source. More...
void	criAtomEx3dSource_SetDopplerFactor (CriAtomEx3dSourceHn ex_3d_source, CriFloat32 doppler_factor)
	Set the Doppler factor for a 3D sound source. More...
void	criAtomEx3dSource_ChangeDefaultDopplerFactor (CriFloat32 doppler_factor)
	Change the default Doppler factor for a 3D sound source. More...
void	criAtomEx3dSource_SetVolume (CriAtomEx3dSourceHn ex_3d_source, CriFloat32 volume)
	Set the volume of a 3D sound source. More...
void	criAtomEx3dSource_ChangeDefaultVolume (CriFloat32 volume)
	Change the default volume of a 3D sound source. More...
void	criAtomEx3dSource_SetMaxAngleAisacDelta (CriAtomEx3dSourceHn ex_3d_source, CriFloat32 max_delta)
	Set the maximum variation of the angle AISAC control valu. More...
void	criAtomEx3dSource_SetDistanceAisacControlId (CriAtomEx3dSourceHn ex_3d_source, CriAtomExAisacControlId aisac_control_id)
	Set the distance AISAC control ID. More...
void	criAtomEx3dSource_SetListenerBasedAzimuthAngleAisacControlId (CriAtomEx3dSourceHn ex_3d_source, CriAtomExAisacControlId aisac_control_id)
	Set the listener reference angle AISAC control ID. More...
void	criAtomEx3dSource_SetListenerBasedElevationAngleAisacControlId (CriAtomEx3dSourceHn ex_3d_source, CriAtomExAisacControlId aisac_control_id)
	Set the sound listener reference elevation AISAC control ID. More...
void	criAtomEx3dSource_SetSourceBasedAzimuthAngleAisacControlId (CriAtomEx3dSourceHn ex_3d_source, CriAtomExAisacControlId aisac_control_id)
	Set the source reference angle AISAC control ID. More...
void	criAtomEx3dSource_SetSourceBasedElevationAngleAisacControlId (CriAtomEx3dSourceHn ex_3d_source, CriAtomExAisacControlId aisac_control_id)
	Set the sound source reference elevation AISAC control ID. More...
void	criAtomEx3dSource_Set3dRegionHn (CriAtomEx3dSourceHn ex_3d_source, CriAtomEx3dRegionHn ex_3d_region)
	Set 3D region handle for 3D source handle. More...
void	criAtomEx3dSource_SetRandomPositionConfig (CriAtomEx3dSourceHn ex_3d_source, const CriAtomEx3dSourceRandomPositionConfig *config)
	Setting position randomization for 3D sound sources. More...
void	criAtomEx3dSource_SetRandomPositionCalculationCallback (CriAtomEx3dSourceHn ex_3d_source, CriAtomEx3dSourceRandomPositionCalculationCbFunc func, void *obj)
	Registration of a callback function for calculating position coordinates when randomizing the position of a 3D sound source. More...
void	criAtomEx3dSource_SetRandomPositionList (CriAtomEx3dSourceHn ex_3d_source, const CriAtomExVector *position_list, CriUint32 length)
	Setting a list of position coordinates for randomizing the position of 3D sound sources. More...
void	criAtomEx3dSource_SetRandomPositionResultCallback (CriAtomEx3dSourceHn ex_3d_source, CriAtomEx3dSourceRandomPositionResultCbFunc func, void *obj)
	Registering a callback function for the position coordinate result when randomizing the position of a 3D sound source. More...
CriSint32	criAtomEx3dSourceList_CalculateWorkSize (const CriAtomEx3dSourceListConfig *config)
	Calculate the size of the work area necessary to create the 3D sound source handle list. More...
CriAtomEx3dSourceListHn	criAtomEx3dSourceList_Create (const CriAtomEx3dSourceListConfig *config, void *work, CriSint32 work_size)
	Create a 3D sound source handle list. More...
void	criAtomEx3dSourceList_Destroy (CriAtomEx3dSourceListHn ex_3d_source_list)
	Discard a 3D sound source handle list. More...
void	criAtomEx3dSourceList_Add (CriAtomEx3dSourceListHn ex_3d_source_list, CriAtomEx3dSourceHn ex_3d_source)
	Add a 3D sound source handle to a 3D sound source handle list. More...
void	criAtomEx3dSourceList_Remove (CriAtomEx3dSourceListHn ex_3d_source_list, CriAtomEx3dSourceHn ex_3d_source)
	Delete a 3D sound source handle from 3D sound source handle list. More...
void	criAtomEx3dSourceList_RemoveAll (CriAtomEx3dSourceListHn ex_3d_source_list)
	Delete all the 3D sound source handles from a 3D sound source handle list. More...
CriSint32	criAtomEx3dListener_CalculateWorkSize (const CriAtomEx3dListenerConfig *config)
	Calculate the size of the work buffer required to create a 3D listener. More...
CriAtomEx3dListenerHn	criAtomEx3dListener_Create (const CriAtomEx3dListenerConfig *config, void *work, CriSint32 work_size)
	Create a 3D listener handle. More...
void	criAtomEx3dListener_Destroy (CriAtomEx3dListenerHn ex_3d_listener)
	Destroy a 3D listener. More...
void	criAtomEx3dListener_Update (CriAtomEx3dListenerHn ex_3d_listener)
	Update a 3D listener. More...
void	criAtomEx3dListener_ResetParameters (CriAtomEx3dListenerHn ex_3d_listener)
	Reset the 3D listener parameters. More...
void	criAtomEx3dListener_SetPosition (CriAtomEx3dListenerHn ex_3d_listener, const CriAtomExVector *position)
	Set the position of a 3D listener. More...
CriAtomExVector	criAtomEx3dListener_GetPosition (CriAtomEx3dListenerHn ex_3d_listener)
	Get 3D position of listener. More...
void	criAtomEx3dListener_SetVelocity (CriAtomEx3dListenerHn ex_3d_listener, const CriAtomExVector *velocity)
	Set the velocity of a 3D listener. More...
void	criAtomEx3dListener_SetOrientation (CriAtomEx3dListenerHn ex_3d_listener, const CriAtomExVector *front, const CriAtomExVector *top)
	Set the orientation of the 3D listener. More...
void	criAtomEx3dListener_SetDopplerMultiplier (CriAtomEx3dListenerHn ex_3d_listener, CriFloat32 doppler_multiplier)
	Set the Doppler multiplier for the 3D listener. More...
void	criAtomEx3dListener_SetFocusPoint (CriAtomEx3dListenerHn ex_3d_listener, const CriAtomExVector *focus_point)
	Set the focus point of the 3D listener. More...
void	criAtomEx3dListener_SetDistanceFocusLevel (CriAtomEx3dListenerHn ex_3d_listener, CriFloat32 distance_focus_level)
	Set the focus level of the distance sensor. More...
void	criAtomEx3dListener_SetDirectionFocusLevel (CriAtomEx3dListenerHn ex_3d_listener, CriFloat32 direction_focus_level)
	Set the focus level of the direction sensor. More...
void	criAtomEx3dListener_GetFocusPoint (CriAtomEx3dListenerHn ex_3d_listener, CriAtomExVector *focus_point)
	Getting the 3D listener's attention point. More...
CriFloat32	criAtomEx3dListener_GetDistanceFocusLevel (CriAtomEx3dListenerHn ex_3d_listener)
	Get the focus level of the distance sensor. More...
CriFloat32	criAtomEx3dListener_GetDirectionFocusLevel (CriAtomEx3dListenerHn ex_3d_listener)
	Get focus level of direction sensor. More...
void	criAtomEx_EnableCalculationAisacControlFrom3dPosition (CriBool flag)
	When the pan type is Pan 3D, sets whether to reflect the distance attenuation AISAC and angle AISAC control values to the sound source. More...
CriBool	criAtomEx_IsEnableCalculationAisacControlFrom3dPosition (void)
	Gets whether distance attenuation AISAC and angle AISAC control values are reflected in the sound source when pan type is pan 3D. More...
void	criAtomEx3dListener_Set3dRegionHn (CriAtomEx3dListenerHn ex_3d_listener, CriAtomEx3dRegionHn ex_3d_region)
	Set 3D region handle for 3D listener handle. More...
CriSint32	criAtomEx3dRegion_CalculateWorkSize (const CriAtomEx3dRegionConfig *config)
	Calculation of the work area size required to create a 3D region handle. More...
CriAtomEx3dRegionHn	criAtomEx3dRegion_Create (const CriAtomEx3dRegionConfig *config, void *work, CriSint32 work_size)
	Create 3D region handle. More...
void	criAtomEx3dRegion_Destroy (CriAtomEx3dRegionHn ex_3d_region)
	Discard 3D region handle. More...
CriSint32	criAtomEx3dTransceiver_CalculateWorkSize (const CriAtomEx3dTransceiverConfig *config)
	Calculating the work area size required to create a 3D transceiver handle. More...
CriAtomEx3dTransceiverHn	criAtomEx3dTransceiver_Create (const CriAtomEx3dTransceiverConfig *config, void *work, CriSint32 work_size)
	Create 3D Transceiver handle. More...
void	criAtomEx3dTransceiver_Destroy (CriAtomEx3dTransceiverHn ex_3d_transceiver)
	Discard 3D Transceiver handle. More...
void	criAtomEx3dTransceiver_Update (CriAtomEx3dTransceiverHn ex_3d_transceiver)
	3D Transceiver Update More...
void	criAtomEx3dTransceiver_SetInputPosition (CriAtomEx3dTransceiverHn ex_3d_transceiver, const CriAtomExVector *position)
	Setting the position of the 3D transceiver input. More...
void	criAtomEx3dTransceiver_SetOutputPosition (CriAtomEx3dTransceiverHn ex_3d_transceiver, const CriAtomExVector *position)
	Setting the position of the 3D transceiver output. More...
void	criAtomEx3dTransceiver_SetInputOrientation (CriAtomEx3dTransceiverHn ex_3d_transceiver, const CriAtomExVector *front, const CriAtomExVector *top)
	Setting the orientation of the 3D transceiver input. More...
void	criAtomEx3dTransceiver_SetOutputOrientation (CriAtomEx3dTransceiverHn ex_3d_transceiver, const CriAtomExVector *front, const CriAtomExVector *top)
	Setting the orientation of the 3D transceiver output. More...
void	criAtomEx3dTransceiver_SetOutputConeParameter (CriAtomEx3dTransceiverHn ex_3d_transceiver, CriFloat32 inside_angle, CriFloat32 outside_angle, CriFloat32 outside_volume)
	Setting sound cone parameters for 3D transceiver output. More...
void	criAtomEx3dTransceiver_SetOutputMinMaxAttenuationDistance (CriAtomEx3dTransceiverHn ex_3d_transceiver, CriFloat32 min_attenuation_distance, CriFloat32 max_attenuation_distance)
	Set minimum/maximum distance for 3D transceiver. More...
void	criAtomEx3dTransceiver_SetOutputInteriorPanField (CriAtomEx3dTransceiverHn ex_3d_transceiver, CriFloat32 transceiver_radius, CriFloat32 interior_distance)
	Set Interior Panning Boundary Distance for 3D Transceiver Output. More...
void	criAtomEx3dTransceiver_SetInputCrossFadeField (CriAtomEx3dTransceiverHn ex_3d_transceiver, CriFloat32 direct_audio_radius, CriFloat32 crossfade_distance)
	Set Crossfade Boundary Distance for 3D Transceiver Input. More...
void	criAtomEx3dTransceiver_SetOutputVolume (CriAtomEx3dTransceiverHn ex_3d_transceiver, CriFloat32 volume)
	Setting the volume of the 3D transceiver output. More...
void	criAtomEx3dTransceiver_AttachAisac (CriAtomEx3dTransceiverHn ex_3d_transceiver, const CriChar8 *global_aisac_name)
	Attach AISAC to 3D transceiver. More...
void	criAtomEx3dTransceiver_DetachAisac (CriAtomEx3dTransceiverHn ex_3d_transceiver, const CriChar8 *global_aisac_name)
	Detach AISAC from 3D transceiver. More...
void	criAtomEx3dTransceiver_SetMaxAngleAisacDelta (CriAtomEx3dTransceiverHn ex_3d_transceiver, CriFloat32 max_delta)
	Setting of maximum change amount of angle AISAC control value. More...
void	criAtomEx3dTransceiver_SetDistanceAisacControlId (CriAtomEx3dTransceiverHn ex_3d_transceiver, CriAtomExAisacControlId aisac_control_id)
	Set the distance AISAC control ID. More...
void	criAtomEx3dTransceiver_SetListenerBasedAzimuthAngleAisacControlId (CriAtomEx3dTransceiverHn ex_3d_transceiver, CriAtomExAisacControlId aisac_control_id)
	Setting listener reference azimuth AISAC control ID. More...
void	criAtomEx3dTransceiver_SetListenerBasedElevationAngleAisacControlId (CriAtomEx3dTransceiverHn ex_3d_transceiver, CriAtomExAisacControlId aisac_control_id)
	Listener standard elevation/depression angle AISAC control ID setting. More...
void	criAtomEx3dTransceiver_SetTransceiverOutputBasedAzimuthAngleAisacControlId (CriAtomEx3dTransceiverHn ex_3d_transceiver, CriAtomExAisacControlId aisac_control_id)
	3D transceiver output reference azimuth AISAC control ID setting More...
void	criAtomEx3dTransceiver_SetTransceiverOutputBasedElevationAngleAisacControlId (CriAtomEx3dTransceiverHn ex_3d_transceiver, CriAtomExAisacControlId aisac_control_id)
	3D transceiver output reference elevation angle AISAC control ID setting More...
void	criAtomEx3dTransceiver_Set3dRegionHn (CriAtomEx3dTransceiverHn ex_3d_transceiver, CriAtomEx3dRegionHn ex_3d_region)
	Setting the 3D region handle for the 3D transceiver handle. More...

Detailed Description

Macro Definition Documentation

CRIATOMEX3DSOURCE_MAX_RANDOM_POSITION_CALCULATION_PARAMETERS

#define CRIATOMEX3DSOURCE_MAX_RANDOM_POSITION_CALCULATION_PARAMETERS   (3)

Maximum number of parameters for various calculation methods in randomizing 3D sound sources.

Description:

The maximum number of elements in the CriAtomEx3dSourceRandomPositionConfig::calculation_parameters array.

See also

CriAtomEx3dSourceRandomPositionConfig

criAtomEx3dSource_SetDefaultConfig

#define criAtomEx3dSource_SetDefaultConfig

(

p_config

)

Value:

{\
    (p_config)->enable_voice_priority_decay = CRI_FALSE;\
    (p_config)->random_position_list_max_length = 0;\
}

Assign the default values to the configuration structure used to create a 3D sound source.

Parameters

[out]

p_config

pointer to the configuration structure used to create a 3D sound source

Description:

Assigns the default values to the configuration structure ( CriAtomEx3dSourceConfig ) used to create a 3D sound source.

See also

CriAtomEx3dSourceConfig

criAtomEx3dSourceList_SetDefaultConfig

#define criAtomEx3dSourceList_SetDefaultConfig

(

p_config

)

Value:

{\
    (p_config)->reserved = 0;\
}

Assign the default values to the configuration structure used to create a 3D sound sources list.

Parameters

[out]

p_config

pointer to the configuration structure used to create a 3D sound sources list

Description:

Assigns the default values to the configuration structure ( CriAtomEx3dSourceListConfig ) used to create a 3D sound sources list.

See also

CriAtomEx3dSourceListConfig

criAtomEx3dListener_SetDefaultConfig

#define criAtomEx3dListener_SetDefaultConfig

(

p_config

)

Value:

{\
    (p_config)->reserved = 0;\
}

Assign the default values to the configuration structure used to create a 3D listener.

Parameters

[out]

p_config

pointer to the configuration structure used to create a 3D listener

Description:

Assigns the default values to the configuration structure ( CriAtomEx3dListenerConfig ) used to create a 3D listener.

See also

CriAtomEx3dListenerConfig

criAtomEx3dRegion_SetDefaultConfig

#define criAtomEx3dRegion_SetDefaultConfig

(

p_config

)

Value:

{\
    (p_config)->reserved = 0;\
}

Assign the default values to the configuration structure used to create a 3D Region.

Parameters

[out]

p_config

pointer to the configuration structure used to create a 3D Region

Description:

Assigns the default values to the configuration structure ( CriAtomEx3dRegionConfig ) used to create a 3D Region.

See also

CriAtomEx3dRegionConfig

criAtomEx3dTransceiver_SetDefaultConfig

#define criAtomEx3dTransceiver_SetDefaultConfig

(

p_config

)

Value:

{\
    (p_config)->reserved = 0;\
}

Assign the default values to the configuration structure used to create a 3D Transceiver.

Parameters

[out]

p_config

pointer to the configuration structure used to create a 3D Transceiver

Description:

Assigns the default values to the configuration structure ( CriAtomEx3dTransceiverConfig ) used to create a 3D Transceiver.

See also

CriAtomEx3dTransceiverConfig

criAtomEx3dSource_SetDefaultConfigForRandomPosition

#define criAtomEx3dSource_SetDefaultConfigForRandomPosition

(

p_config

)

Value:

{\
    (p_config)->follows_original_source = CRI_FALSE;\
    (p_config)->calculation_type = CRIATOMEX3DSOURCE_RANDOM_POSITION_CALCULATION_TYPE_RECTANGLE;\
    (p_config)->calculation_parameters[0] = 1.0f;\
    (p_config)->calculation_parameters[1] = 1.0f;\
    (p_config)->calculation_parameters[2] = 0.0f;\
}

Set default values in config structure for randomizing 3D sound source position.

Parameters

[out]

p_config

A pointer to a configuration structure for randomizing the position of the 3D sound source.

Description:

Sets the default values for the configuration structure ( CriAtomEx3dSourceRandomPositionConfig ) related to randomization of the 3D sound source position.

See also

CriAtomEx3dSourceRandomPositionConfig

criAtomEx3dSource_SetMinMaxDistance

#define criAtomEx3dSource_SetMinMaxDistance	(		ex_3d_source,
			min_attenuation_distance,
			max_attenuation_distance
	)		criAtomEx3dSource_SetMinMaxAttenuationDistance((ex_3d_source), (min_attenuation_distance), (max_attenuation_distance))

Set min and max values of the attenuation distance of a 3D source.

Parameters

[in]	ex_3d_source	3D sound source handle
[in]	min_attenuation_distance	minimum attenuation distance
[in]	max_attenuation_distance	maximum attenuation distance

Description:

Sets the minimum and maximum attenuation distances for a 3D sound source.
The minimum distance represents the distance below which the volume is maximum. The maximum distance represents the distance at which the minimum volume is reached.
The default values at the initialization of the library are as follows:

• Minimum distance: 0.0f
• Maximum distance: 0.0f

The default values can be changed by calling the criAtomEx3dSource_ChangeDefaultMinMaxDistance function.
If the minimum and maximum distances are set on the data side (i.e. in the tool), they are overwritten (ignored) when this function is called.

Attention

To actually apply the specified values, you have to call the criAtomEx3dSource_Update function.

See also

criAtomEx3dSource_Update, criAtomEx3dSource_ChangeDefaultMinMaxAttenuationDistance]

criAtomEx3dSource_ChangeDefaultMinMaxDistance

#define criAtomEx3dSource_ChangeDefaultMinMaxDistance	(		min_attenuation_distance,
			max_attenuation_distance
	)		criAtomEx3dSource_ChangeDefaultMinMaxAttenuationDistance((min_attenuation_distance), (max_attenuation_distance))

Change the default values of max and min of attenuation distance of a 3D source.

Parameters

[in]	min_attenuation_distance	minimum attenuation distance
[in]	max_attenuation_distance	maximum attenuation distance

Description:

Changes the default values for the minimum and maximum attenuation distances of a 3D sound source.
After calling this function, the new default values for minimum and maximum distance attenuation are applied each time a new 3D sound source is created.

Attention

If the relevant parameters were not set in the tool, the default values are used implicitly.
Therefore, if you change the default values, the parameters may be different from the ones intended.
Note that in the following cases, parmeters will not be affected by this function:

• Min/max attenuation distance is set to something else than 0 by default in the tool's properties.
• The data is built for in-game preview.

See also

criAtomEx3dSource_SetMinMaxAttenuationDistance

Typedef Documentation

CriAtomExVector

typedef struct CriAtomExVectorTag CriAtomExVector

3D vector structure

Description:

Structure used to handle three-dimensional vectors.

See also

CriAtomEx3dListener, CriAtomEx3dSource

CriAtomEx3dSourceConfig

typedef struct CriAtomEx3dSourceConfigTag CriAtomEx3dSourceConfig

Configuration structure used to create a 3D sound source.

Description:

Structure used to create a 3D sound source.
While no parameters can be specified at this time, some may be added in the future. Therefore, when using this structure, it is recommended to use the criAtomEx3dSource_SetDefaultConfig macro to initialize it.

See also

criAtomEx3dSource_SetDefaultConfig, criAtomEx3dSource_CalculateWorkSize, criAtomEx3dSource_Create

CriAtomEx3dSourceListConfig

typedef struct CriAtomEx3dSourceListConfigTag CriAtomEx3dSourceListConfig

Configuration structure used to create a 3D sound source list.

Description:

Structure used to create a 3D sound source list.
While no parameters can be specified at this time, some may be added in the future. Therefore, when using this structure, it is recommended to call the criAtomEx3dSourceList_SetDefaultConfig macro to initialize it.

See also

criAtomEx3dSourceList_SetDefaultConfig, criAtomEx3dSourceList_CalculateWorkSize, criAtomEx3dSourceList_Create

CriAtomEx3dListenerConfig

typedef struct CriAtomEx3dListenerConfigTag CriAtomEx3dListenerConfig

Configuration structure used to create a 3D listener.

Description:

Structure used to create a 3D listener.
While no parameters can be specified at this time, some may be added in the future. Therefore, when using this structure, it is recommended to use the criAtomEx3dListener_SetDefaultConfig macro to initialize it.

See also

criAtomEx3dListener_SetDefaultConfig, criAtomEx3dListener_CalculateWorkSize, criAtomEx3dListener_Create

CriAtomEx3dSourceHn

typedef CriAtomEx3dSourceObj* CriAtomEx3dSourceHn

3D sound source handle

Description:

Handle for a 3D sound source.
It is used by the 3D positioning functions.

The parameters and position of a 3D sound source are set through this type of handle.

See also

criAtomEx3dSource_Create

CriAtomEx3dSourceListHn

typedef CriAtomEx3dSourceListObj* CriAtomEx3dSourceListHn

3D sound source handle list

Description:

Handle list for a 3D sound source.
It is used by the 3D positioning functions.

See also

criAtomEx3dSourceList_Create

CriAtomEx3dListenerHn

typedef CriAtomEx3dListenerObj* CriAtomEx3dListenerHn

3D listener handle

Description:

Handle for a 3D listener.
It is used by the 3D positioning functions.

The parameters and position of a 3D listener are set through this type of handle.

See also

criAtomEx3dListener_Create

CriAtomEx3dRegionConfig

typedef struct CriAtomEx3dRegionConfigTag CriAtomEx3dRegionConfig

Config structure for creating 3D region handle.

Description:

A structure used to create 3D region handles.
Currently, there are no parameters that can be specified, but parameters may be added in the future. Therefore, when using this structure, be sure to initialize the structure by using the criAtomEx3dRegion_SetDefaultConfig macro.

See also

criAtomEx3dRegion_SetDefaultConfig, criAtomEx3dRegion_CalculateWorkSize, criAtomEx3dRegion_Create

CriAtomEx3dRegionHn

typedef CriAtomEx3dRegionObj* CriAtomEx3dRegionHn

3D region handle

Description:

Handle for a 3D region.
Used for 3D transceiver function.

See also

criAtomEx3dRegion_Create

CriAtomEx3dTransceiverConfig

typedef struct CriAtomEx3dTransceiverConfigTag CriAtomEx3dTransceiverConfig

Config structure for creating 3D Transceiver handle.

Description:

A structure used to create 3D Transceiver handles.
Currently, there are no parameters that can be specified, but parameters may be added in the future. Therefore, when using this structure, be sure to initialize the structure by using the criAtomEx3dTransceiver_SetDefaultConfig macro.

See also

criAtomEx3dTransceiver_SetDefaultConfig, criAtomEx3dTransceiver_CalculateWorkSize, criAtomEx3dTransceiver_Create

CriAtomEx3dTransceiverHn

typedef CriAtomEx3dTransceiverObj* CriAtomEx3dTransceiverHn

3D Transceiver handle

Description:

Handle for a 3D Transceiver.
Used for 3D transceiver function.
3D Transceiver parameters, location settings, etc., are performed via 3D Transceiver handle.

See also

criAtomEx3dTransceiver_Create

CriAtomEx3dSourceRandomPositionCalculationType

typedef enum CriAtomEx3dSourceRandomPositionCalculationTypeTag CriAtomEx3dSourceRandomPositionCalculationType

How to calculate position coordinates when randomizing the position of a 3D sound source.

Description:

This defines how to calculate the position coordinates when randomizing the position of a 3D sound source.

See also

CriAtomEx3dSourceRandomPositionConfig

CriAtomEx3dSourceRandomPositionConfig

typedef struct CriAtomEx3dSourceRandomPositionConfigTag CriAtomEx3dSourceRandomPositionConfig

Configuration structure for randomizing 3D sound source position.

Description:

A structure that contains settings related to randomizing the position of 3D sound sources.

Attention

Since the number of members may increase in the future, if you do not use the criAtomEx3dSource_SetDefaultConfigForRandomPosition macro, be sure to clear the structure to zero before using it.
(Be careful not to put undefined values into the structure members.)

See also

criAtomEx3dSource_SetRandomPositionConfig, criAtomEx3dSource_SetDefaultConfigForRandomPosition

CriAtomEx3dSourceRandomPositionResultInfoDetail

typedef struct CriAtomEx3dSourceRandomPositionResultInfoDetailTag CriAtomEx3dSourceRandomPositionResultInfoDetail

Details of position coordinate results when randomizing 3D sound source position.

Description:

This is a structure that notifies detailed information about the playback when the position coordinate result of randomizing the position of a 3D sound source is output.
It is passed as an argument to the position coordinate result callback function of randomizing the position of a 3D sound source.

See also

CriAtomEx3dSourceRandomPositionResultCbFunc

CriAtomEx3dSourceRandomPositionCalculationCbFunc

typedef void( * CriAtomEx3dSourceRandomPositionCalculationCbFunc) (void *obj, const CriAtomEx3dSourceHn ex_3d_source, CriAtomExVector *result_pos)

Callback function type for calculating position coordinates when randomizing the position of a 3D sound source.

Parameters

[in]	obj	User-specified objects
[in]	ex_3d_source	Handle of the original 3D sound source
[out]	result_pos	Processing result position

Description:

This is the type of the callback function for calculating position coordinates when randomizing a 3D sound source.
You can register a callback function by executing the criAtomEx3dSource_SetRandomPositionCalculationCallback function.
This callback function is called when calculating the position coordinates for randomizing the position of the 3D sound source.
Please use this when you want to determine the position coordinates on the application side.

Attention

Please note that if you block processing within this callback function for a long period of time, problems such as sound dropouts may occur.

This callback function will be called only when CRIATOMEX3DSOURCE_RANDOM_POSITION_CALCULATION_TYPE_CALLBACK is specified in the CriAtomEx3dSourceRandomPositionConfig structure.

See also

CriAtomEx3dSourceRandomPositionConfig, criAtomEx3dSource_SetRandomPositionCalculationCallback

CriAtomEx3dSourceRandomPositionResultCbFunc

typedef void( * CriAtomEx3dSourceRandomPositionResultCbFunc) (void *obj, const CriAtomEx3dSourceRandomPositionResultInfoDetail *result_info)

Position coordinate result callback function type for randomizing the position of a 3D sound source.

Parameters

[in]	obj	User-specified objects
[in]	result_info	Location coordinate result details

Description:

This is the type of the position coordinate result callback function when randomizing the position of a 3D sound source.
You can register a callback function by executing the criAtomEx3dSource_SetRandomPositionResultCallback function.
This callback function is called after the position coordinates of the 3D sound source are calculated if randomization of the 3D sound source position is enabled.
Please use this if you want to obtain randomized position coordinate information on the application side.

Remarks:

If the setting to track the original 3D sound source is enabled, this callback function will be executed according to changes in the position of the original 3D sound source.

Attention

Please note that if you block processing within this callback function for a long period of time, problems such as sound dropouts may occur.

See also

criAtomEx3dSource_SetRandomPositionResultCallback, CriAtomEx3dSourceRandomPositionResultInfoDetail

Enumeration Type Documentation

CriAtomEx3dSourceRandomPositionCalculationTypeTag

enum CriAtomEx3dSourceRandomPositionCalculationTypeTag

How to calculate position coordinates when randomizing the position of a 3D sound source.

Description:

This defines how to calculate the position coordinates when randomizing the position of a 3D sound source.

See also

CriAtomEx3dSourceRandomPositionConfig

Enumerator
CRIATOMEX3DSOURCE_RANDOM_POSITION_CALCULATION_TYPE_NONE	No settings. Description: Coordinate calculation processing is not performed. Attention This definition is for informational purposes only. Therefore, if you specify this setting value in the CriAtomEx3dSourceRandomPositionConfig structure and execute the criAtomEx3dSource_SetRandomPositionConfig function, an error will occur.
CRIATOMEX3DSOURCE_RANDOM_POSITION_CALCULATION_TYPE_RECTANGLE	Rectangle. Description: xz Calculates coordinates within a rectangle on a plane.
CRIATOMEX3DSOURCE_RANDOM_POSITION_CALCULATION_TYPE_CUBOID	Rectangular. Description: xyz Calculates coordinates within a rectangular prism in space.
CRIATOMEX3DSOURCE_RANDOM_POSITION_CALCULATION_TYPE_CIRCLE	Circle. Description: xz Calculates coordinates within a circle on a plane.
CRIATOMEX3DSOURCE_RANDOM_POSITION_CALCULATION_TYPE_CYLINDER	Cylinder. Description: xyz Calculates coordinates within a cylinder in space.
CRIATOMEX3DSOURCE_RANDOM_POSITION_CALCULATION_TYPE_SPHERE	Sphere. Description: xyz Calculates coordinates within a sphere in space.
CRIATOMEX3DSOURCE_RANDOM_POSITION_CALCULATION_TYPE_CALLBACK	Callback. Description: Determine the coordinates in a user-defined callback function. Remarks: A separate callback function that calculates coordinates must be registered. See also CriAtomEx3dSourceRandomPositionCalculationCbFunc, criAtomEx3dSource_SetRandomPositionCalculationCallback
CRIATOMEX3DSOURCE_RANDOM_POSITION_CALCULATION_TYPE_LIST	Coordinate List. Description: The coordinates are determined based on a predefined coordinate list. Remarks: A separate coordinate list setting is required. See also criAtomEx3dSource_SetRandomPositionList

Function Documentation

criAtomEx3dSource_CalculateWorkSize()

CriSint32 criAtomEx3dSource_CalculateWorkSize

(

const CriAtomEx3dSourceConfig *

config

)

Calculate the size of the work buffer required to create a 3D sound source.

Parameters

[in]

config

pointer to the configuration structure used to create a 3D sound source

Returns

CriSint32 work buffer size

Return values

>=	0 successfully completed
-1	error occurred

Description:

Calculates the size of the work buffer required to create a 3D sound source.
If you create a 3D sound source without having registered a user-allocator, a memory buffer having the size returned by this function must be passed to criAtomEx3dSource_Create .

The size of the work buffer needed to create a 3D sound source depends on the value of the parameters in the configuration structure ( CriAtomEx3dSourceConfig ).

When NULL is specified for the structure, the default settings (the same than the ones set by the criAtomEx3dSource_SetDefaultConfig macro) are used to calculate the size of the work buffer.
If this function fails to calculate the size of the work buffer, it will return -1.
To know the reason of the failure, refer to the error callback message.
message.

Remarks:

The information in the config argument is referenced only within the function.
Since it will not be referenced after the function exits, it is okay to free the config area after the function is executed.

See also

criAtomEx3dSource_Create, CriAtomEx3dSourceConfig

criAtomEx3dSource_Create()

CriAtomEx3dSourceHn criAtomEx3dSource_Create	(	const CriAtomEx3dSourceConfig *	config,
		void *	work,
		CriSint32	work_size
	)

Create a 3D sound source.

Parameters

[in]	config	pointer to the configuration structure used to create a 3D sound source
[in]	work	pointer to the work buffer
[in]	work_size	size of the work buffer

Returns

CriAtomEx3dSourceHn 3D sound source handle

Description:

Creates a 3D sound source based on the value of the parameters of the configuration structure.
When this function creates a 3D sound source successfully, it returns a handle.
When creating a 3D sound source, you must pass a work buffer.
The size of that buffer is calculated by calling the criAtomEx3dSource_CalculateWorkSize function.
(If a user-allocator has already been registered by using the criAtomEx_SetUserAllocator macro, you do not need to pass the work buffer.)

Attention

You must initialize the library before executing this function.

See also

criAtomEx3dSource_CalculateWorkSize, criAtomEx3dSource_Destroy

criAtomEx3dSource_Destroy()

void criAtomEx3dSource_Destroy

(

CriAtomEx3dSourceHn

ex_3d_source

)

Destroy a 3D sound source.

Parameters

[in]

ex_3d_source

3D sound source handle

Description:

Destroys a 3D sound source.
All resources allocated when you created the 3D sound source are released when you execute this function.
Also, the 3D sound source handle specified as an argument is disabled.
If any sounds are being played back on an AtomEx player to which this 3D sound source handle has been assigned, you must first stop these sounds or destroy the AtomEx player, then only execute this function.

See also

criAtomEx3dSource_Create

criAtomEx3dSource_Update()

void criAtomEx3dSource_Update

(

CriAtomEx3dSourceHn

ex_3d_source

)

Update a 3D sound source.

Parameters

[in]

ex_3d_source

3D sound source handle

Description:

Updates a 3D sound source with the parameters previously specified with other functions.
This function updates all the parameters specified for the 3D sound source at once.
Updating the 3D sound source with this function every time you change a single parameter is inefficient. You should update it after changing all the parameters you need to change.

Example:

CriAtomExVector pos;
CriAtomExVector vel;
 
// Set position
pos.x = 0.0f
pos.y = 0.0f
pos.z = 1.0f
criAtomEx3dSource_SetPosition(source, &pos);
// Set velocity
vel.x = 1.0f
vel.y = 0.0f
vel.z = 0.0f
criAtomEx3dSource_SetVelocity(source, &vel);
 
// Update source parameters
criAtomEx3dSource_Update(source);

Attention

This function works independently from the parameter update functions ( criAtomExPlayer_UpdateAll and criAtomExPlayer_Update). Whenever you change the parameters of a 3D sound source, use this function to update them.

criAtomEx3dSource_ResetParameters()

void criAtomEx3dSource_ResetParameters

(

CriAtomEx3dSourceHn

ex_3d_source

)

Reset the 3D sound source parameters.

Parameters

[in]

ex_3d_source

3D sound source handle

Description:

Clears the parameters set for the 3D sound source and restores them to their initial values.

Attention

To actually apply the cleared parameters, the user must call the criAtomEx3dSource_Update function.

See also

criAtomEx3dSource_Update

criAtomEx3dSource_SetPosition()

void criAtomEx3dSource_SetPosition	(	CriAtomEx3dSourceHn	ex_3d_source,
		const CriAtomExVector *	position
	)

Set the position of a 3D sound source.

Parameters

[in]	ex_3d_source	3D sound source handle
[in]	position	position vector

Description:

Sets the position of the 3D sound source.
The position is used to calculate the distance attenuation and the localization .
Specify the position as a 3D vector.
The default value is (0.0f, 0.0f, 0.0f).
The value set by this function is always used because the position cannot be set on the data side.

Attention

To actually apply the specified values, you have to call the criAtomEx3dSource_Update function.

See also

criAtomEx3dSource_Update

criAtomEx3dSource_GetPosition()

CriAtomExVector criAtomEx3dSource_GetPosition

(

CriAtomEx3dSourceHn

ex_3d_source

)

Get the 3D sound source position.

Parameters

[in]

ex_3d_source

3D sound source handle

Description:

Get the position of the 3D sound source.
Position is acquired with 3 dimensional vector.

criAtomEx3dSource_SetVelocity()

void criAtomEx3dSource_SetVelocity	(	CriAtomEx3dSourceHn	ex_3d_source,
		const CriAtomExVector *	velocity
	)

Set the velocity of a 3D sound source.

Parameters

[in]	ex_3d_source	3D sound source handle
[in]	velocity	velocity vector

Description:

Sets the velocity of the 3D sound source.
The velocity is used to calculate the Doppler effect.
Specify the velocity as a 3D vector. The velocity corresponds to the distance traveled per second.
The default value is (0.0f, 0.0f, 0.0f).
The value set in this function is always used, because the velocity cannot be set on the data side.

Attention

To actually apply the specified values, you hve to call the criAtomEx3dSource_Update function.

See also

criAtomEx3dSource_Update

criAtomEx3dSource_SetOrientation()

void criAtomEx3dSource_SetOrientation	(	CriAtomEx3dSourceHn	ex_3d_source,
		const CriAtomExVector *	front,
		const CriAtomExVector *	top
	)

Setting the direction of 3D sound source.

Parameters

[in]	ex_3d_source	3D sound source handle
[in]	front	Forward vector
[in]	top	Up vector

Description:

Sets the orientation of the specified 3D sound source.
The direction set by this function will be set as the direction of the sound cone.
The sound cone represents the direction from which sound emanates from a sound source and is used to describe the directionality of sound.
The direction of the sound cone is specified as a three-dimensional vector. The set direction vector is normalized and used within the library.
Since the direction of the sound cone cannot be set on the data side, the value set by this function is always used.
The default values are as follows:

• Forward vector : (0.0f, 0.0f, 1.0f)
• Up vector : (0.0f, 1.0f, 0.0f)

Remarks:

When setting the sound cone orientation, the up vector is ignored and only the forward vector is used.
Also, if you are using Ambisonics playback, the Ambisonics will rotate according to the orientation specified by this function and the orientation of the listener.

Attention

To actually apply the specified values, you have to call the criAtomEx3dSource_Update function.
It is not possible to apply a sound cone to Ambiosnics.

See also

criAtomEx3dSource_SetConeParameter, criAtomEx3dSource_Update

criAtomEx3dSource_SetConeParameter()

void criAtomEx3dSource_SetConeParameter	(	CriAtomEx3dSourceHn	ex_3d_source,
		CriFloat32	inside_angle,
		CriFloat32	outside_angle,
		CriFloat32	outside_volume
	)

Set the parameters of the sound cone of a 3D sound source.

Parameters

[in]	ex_3d_source	3D sound source handle
[in]	inside_angle	inside angle of the sound cone
[in]	outside_angle	outside angle of the sound cone
[in]	outside_volume	outside volume of the sound cone

Description:

Sets the parameters of the sound cone of the 3D sound source.
A sound cone represents the orientation of the sounds generated from a sound source, and is used to represent the directivity of sounds.
A sound cone consists of inside and outside cones. insideAngle indicates the angle of the inside cone, and outsideAngle indicates the angle of the outside cone. outsideVolume indicates the volume at an angle that is greater than or equal to the angle of the outside cone.
When the sound source angle is smaller than the angle of the inside cone, no attenuation occurs due to the cone. At an angle between the inside and outside cones, the volume gradually decreases towards the outside volume.
For the inside and outside angles, specify a degree from 0.0f to 360.0f.
The outside volume is specified as a scaling factor between 0.0f and 1.0f (the unit is not decibel).
The default values at the initialization of the library are as follow (no attenuation occurs due to the cone).

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

The default values can be changed by calling the criAtomEx3dSource_ChangeDefaultConeParameter function.
If the sound cone parameters are set on the data side, the parameters are evaluated as follows when this function is called.

• Inside angle: Addition
• Outside angle: Addition
• Outside volume: Multiplication

Attention

To actually apply the specified parameters, call the criAtomEx3dSource_Update function.

See also

criAtomEx3dSource_Update, criAtomEx3dSource_ChangeDefaultConeParameter

criAtomEx3dSource_ChangeDefaultConeParameter()

void criAtomEx3dSource_ChangeDefaultConeParameter	(	CriFloat32	inside_angle,
		CriFloat32	outside_angle,
		CriFloat32	outside_volume
	)

Change the default values of the sound cone parameters a 3D sound source.

Parameters

[in]	inside_angle	inside angle of the sound cone
[in]	outside_angle	outside angle of the sound cone
[in]	outside_volume	outside volume of the sound cone

Description:

Changes the default values for the sound cone parameters of a 3D sound source.
If you change the default value by this function, the initial value of the sound cone parameter of the 3D sound source handle ( CriAtomEx3dSourceHn ) to be created later becomes the value set by this function.
For default values at library initialization, see criAtomEx3dSource_SetConeParameter function.

Attention

For this parameter, the default value is implicitly applied for "not changed by tool" (default state) data.
Therefore, if you change the default value with this function, it may be different from the intended parameter when editing with the tool.
However, data built for in-game preview is not affected by this function.

See also

criAtomEx3dSource_SetConeParameter

criAtomEx3dSource_SetMinMaxAttenuationDistance()

void criAtomEx3dSource_SetMinMaxAttenuationDistance	(	CriAtomEx3dSourceHn	ex_3d_source,
		CriFloat32	min_attenuation_distance,
		CriFloat32	max_attenuation_distance
	)

Set the minimum and maximum attenuation distances of a 3D sound source.

Parameters

[in]	ex_3d_source	3D sound source handle
[in]	min_attenuation_distance	minimum distance
[in]	max_attenuation_distance	maximum distance

Description:

Sets the minimum and maximum attenuation distances for a 3D sound source.
The minimum distance represents the distance below which the volume is maximum. The maximum distance represents the distance at which the minimum volume is reached.
The default values at the initialization of the library are as follows:

• Minimum distance: 0.0f
• Maximum distance: 0.0f

The default values can be changed by calling the criAtomEx3dSource_ChangeDefaultMinMaxAttenuationDistance function.
If the parameter is set on the data side (i.e. in the tool), the values of the data are overwritten (ignored) when this function is called.

Attention

To actually apply the specified values, you have to call the criAtomEx3dSource_Update function.

See also

criAtomEx3dSource_Update, criAtomEx3dSource_ChangeDefaultMinMaxAttenuationDistance

criAtomEx3dSource_ChangeDefaultMinMaxAttenuationDistance()

void criAtomEx3dSource_ChangeDefaultMinMaxAttenuationDistance	(	CriFloat32	min_attenuation_distance,
		CriFloat32	max_attenuation_distance
	)

Change the default values of the minimum and maximum attenuation distances of a 3D sound source.

Parameters

[in]	min_attenuation_distance	minimum distance
[in]	max_attenuation_distance	maximum distance

Description:

Changes the default values for the minimum and maximum attenuation distances.
If you change the default value by using this function, the initial values of the sound cone parameters of the 3D sound source handle ( CriAtomEx3dSourceHn ) to be created later become the value set by this function.
For default values at library initialization, see criAtomEx3dSource_SetMinMaxAttenuationDistance function.

Attention

If the relevant parameters were not set in the tool, the default values are used implicitly.
Therefore, if you change the default values, the parameters may be different from the ones intended.
However, in the following cases the data is not affected by this function.

• Initial value of minimum distance / maximum distance is set to other than 0.0 in tool properties
• The Cue Sheets are built for in-game preview

See also

criAtomEx3dSource_SetMinMaxAttenuationDistance

criAtomEx3dSource_SetInteriorPanField()

void criAtomEx3dSource_SetInteriorPanField	(	CriAtomEx3dSourceHn	ex_3d_source,
		CriFloat32	source_radius,
		CriFloat32	interior_distance
	)

Set the interior panning boundaries of a 3D sound source.

Parameters

[in]	ex_3d_source	3D sound source handle
[in]	source_radius	Radius of 3D sound source
[in]	interior_distance	Interior distance

Description:

Sets the interior panning boundaries of a 3D sound source.
The radius of the 3D sound source corresponds to the sound source being considered as a sphere.
The interior distance is the distance from the radius of the 3D sound source applied to the interior panning.
Interior panning is applied within the radius of the 3D sound source, but since the interior distance is treated as 0.0, sound is played at the same volume from all the speakers.
Within the interior distance, interior panning is applied.
Outside the interior distance, interior panning is not applied, and audio is played from the one or two speakers closest to the sound source location.
The default values at library initialization are as follows.

• Radius of 3D sound source : 0.0f
• Interior distance : 0.0f (Depends on minimum distance of 3D sound source)

The default value can be changed with the criAtomEx3dSource_ChangeDefaultInteriorPanField function.
Since this parameter can not currently be set in the tool, the value set with this function is always used.

Attention

In order to actually apply these parameters, you need to call the criAtomEx3dSource_Update function.

See also

criAtomEx3dSource_Update, criAtomEx3dSource_ChangeDefaultInteriorPanField

criAtomEx3dSource_ChangeDefaultInteriorPanField()

void criAtomEx3dSource_ChangeDefaultInteriorPanField	(	CriFloat32	source_radius,
		CriFloat32	interior_distance
	)

Change the default value of the interior panning boundaries of a 3D sound source.

Parameters

[in]	source_radius	Radius of 3D sound source
[in]	interior_distance	Interior distance

Description:

Change the default values for the interior panning boundaries of a 3D sound source.
If you change the default value with this function, the initial interior panning boundary values of any 3D sound source handle ( CriAtomEx3dSourceHn ) created later will be the values you passed.
For default values at library initialization, see criAtomEx3dSource_SetInteriorPanField function.

See also

criAtomEx3dSource_SetInteriorPanField

criAtomEx3dSource_SetDopplerFactor()

void criAtomEx3dSource_SetDopplerFactor	(	CriAtomEx3dSourceHn	ex_3d_source,
		CriFloat32	doppler_factor
	)

Set the Doppler factor for a 3D sound source.

Parameters

[in]	ex_3d_source	3D sound source handle
[in]	doppler_factor	Doppler factor

Description:

Sets the Doppler factor for a 3D sound source.
The Doppler factor is a scale factor to exaggerate the Doppler effect, which is calculated based on a sound velocity of 340 m/s.
For example, if you specify 2.0f, the pitch that is calculated based on a sound velocity of 340 m/s is doubled.
If you specify 0.0f, the Doppler effect is disabled.
The default value at the initialization of the library is 0.0f.
The default value can be changed using the criAtomEx3dSource_ChangeDefaultDopplerFactor function.
If a Doppler factor is set on the data side, the value in the data is overwritten (ignored) when this function is called.

Attention

To actually apply the specified value, you have to call the criAtomEx3dSource_Update function.

See also

criAtomEx3dSource_Update, criAtomEx3dSource_ChangeDefaultDopplerFactor

criAtomEx3dSource_ChangeDefaultDopplerFactor()

void criAtomEx3dSource_ChangeDefaultDopplerFactor

(

CriFloat32

doppler_factor

)

Change the default Doppler factor for a 3D sound source.

Parameters

[in]

doppler_factor

Doppler factor

Description:

Changes the default value of the Doppler factor for a 3D sound source.
If you change the default value by this function, the initial value of the doppler factor of the 3D sound source handle ( CriAtomEx3dSourceHn ) to be created later becomes the value set by this function.
For default values at library initialization, see criAtomEx3dSource_SetDopplerFactor function.

Attention

When the relevant parameter is not set in the tool, the default value is used implicitly.
Therefore, if you change the default value, the parameter may be different than what was intended.
However, data built for in-game preview is not affected by this function.

See also

criAtomEx3dSource_SetDopplerFactor

criAtomEx3dSource_SetVolume()

void criAtomEx3dSource_SetVolume	(	CriAtomEx3dSourceHn	ex_3d_source,
		CriFloat32	volume
	)

Set the volume of a 3D sound source.

Parameters

[in]	ex_3d_source	3D sound source handle
[in]	volume	volume

Description:

Sets the volume of the 3D sound source.
The volume of the 3D sound source affects only the volumes (L, R, SL, and SR) related to sound localization. It does not affect the output levels of the LFE or the center speaker.
Specify a real number of 0.0f to 1.0f for the volume value.
The volume is a scaling factor for the amplitude of the sound data (the unit is not decibel).
For example, if you specify 1.0f, the volume of the original sound is maintained.
If you specify 0.5f, the amplitude of the original sound is halved (i.e. the volume is -6 dB).
If you specify 0.0f, the sound is muted (silent).
The default value at the initialization of the library is 1.0f.
The default value can be changed with the criAtomEx3dSource_ChangeDefaultVolume function. If the volume of the 3D sound source is set on the data side and this function is called, the result of the multiplication between the volume from the data and the volume passed to the function will be applied.

Attention

To actually apply the specified value, you have to call the criAtomEx3dSource_Update function.

See also

criAtomEx3dSource_Update, criAtomEx3dSource_ChangeDefaultVolume

criAtomEx3dSource_ChangeDefaultVolume()

void criAtomEx3dSource_ChangeDefaultVolume

(

CriFloat32

volume

)

Change the default volume of a 3D sound source.

Parameters

[in]

volume

volume

Description:

Changes the default volume of a 3D sound source.
If you change the default value by this function, the initial value of the volume of the 3D sound source handle ( CriAtomEx3dSourceHn ) to be created later becomes the value set by this function.
For default values at library initialization, see criAtomEx3dSource_SetConeParameter function.

Attention

When the relevant parameter is not set in the tool, the default value is used implicitly.
Therefore, if you change the default value, the parameter may be different than what was intended.
However, data built for in-game preview is not affected by this function.

See also

criAtomEx3dSource_SetVolume

criAtomEx3dSource_SetMaxAngleAisacDelta()

void criAtomEx3dSource_SetMaxAngleAisacDelta	(	CriAtomEx3dSourceHn	ex_3d_source,
		CriFloat32	max_delta
	)

Set the maximum variation of the angle AISAC control valu.

Parameters

[in]

ex_3d_source

3D sound source handle

Returns

max_delta maximum variation of the angle AISAC control value

Description:

Sets the maximum variation when the AISAC control value is changed by the angle AISAC.
When the maximum variation is set to a small value, the angle AISAC changes the AISAC control value smoothly, even if the relative angle between the sound source and the listener is changed sharply.
For example, if you set (0.5f / 30.0f), 30 frames are used to change the angle from 0 degrees to 180 degrees.
The default value is 1.0f (no restriction).
The value set by this function is always used, because this parameter cannot be set on the data side.

Attention

To apply the specified value, you have to call the criAtomEx3dSource_Update function.
The maximum variation set by this function is applied only to the change in the angle AISAC control value that is calculated based on the localization angle. It does not affect the localization angle itself.

See also

criAtomEx3dSource_Update

criAtomEx3dSource_SetDistanceAisacControlId()

void criAtomEx3dSource_SetDistanceAisacControlId	(	CriAtomEx3dSourceHn	ex_3d_source,
		CriAtomExAisacControlId	aisac_control_id
	)

Set the distance AISAC control ID.

Parameters

[in]	ex_3d_source	3D sound source handle
[in]	aisac_control_id	Distance AISAC control ID

Description:

Specify the AISAC control ID linked with the distance attenuation between the minimum and maximum distances.
The default distance attenuation will be disabled if you set the AISAC control ID in this function.
The distance AISAC control ID set on the data side (i.e. in AtomCraft) is overwritten by this function.

Attention

In order to actually apply this parameter, you need to call the criAtomEx3dSource_Update function.
The control value for the AISAC control ID specified by this function takes priority over the control value set in the player using any of the following functions.

• criAtomExPlayer_SetAisacControlById function
  
• criAtomExPlayer_SetAisacControlByName function
  If you change the AISAC control ID for a 3D sound source that is playing, the final control value for the control ID before the change will continue to be applied.
  As a result, two parameters, one before the change and one after the change, are applied, and the intended output is not obtained.
  It is recommended to run this function while the audio associated with the specified 3D sound source is not being played.
  

See also

criAtomEx3dSource_Update

criAtomEx3dSource_SetListenerBasedAzimuthAngleAisacControlId()

void criAtomEx3dSource_SetListenerBasedAzimuthAngleAisacControlId	(	CriAtomEx3dSourceHn	ex_3d_source,
		CriAtomExAisacControlId	aisac_control_id
	)

Set the listener reference angle AISAC control ID.

Parameters

[in]	ex_3d_source	3D sound source handle
[in]	aisac_control_id	Listener reference angle AISAC control ID

Description:

Specify the AISAC control ID linked with the angle of the sound source seen from the listener.
The listener reference angle AISAC control ID set on the data side (i.e. in AtomCraft) is overwritten by this function.

Attention

In order to actually apply this parameter, you need to call the criAtomEx3dSource_Update function.
The control value for the AISAC control ID specified by this function takes priority over the control value set in the player using any of the following functions.

• criAtomExPlayer_SetAisacControlById function
  
• criAtomExPlayer_SetAisacControlByName function
  If you change the AISAC control ID for a 3D sound source that is playing, the final control value for the control ID before the change will continue to be applied.
  As a result, two parameters, one before the change and one after the change, are applied, and the intended output is not obtained.
  It is recommended to run this function while the audio associated with the specified 3D sound source is not being played.
  

See also

criAtomEx3dSource_Update

criAtomEx3dSource_SetListenerBasedElevationAngleAisacControlId()

void criAtomEx3dSource_SetListenerBasedElevationAngleAisacControlId	(	CriAtomEx3dSourceHn	ex_3d_source,
		CriAtomExAisacControlId	aisac_control_id
	)

Set the sound listener reference elevation AISAC control ID.

Parameters

[in]	ex_3d_source	3D sound source handle
[in]	aisac_control_id	Elevation AISAC control ID based on sound source

Description:

Specify the AISAC control ID linked with the elevation of the listener as seen from the sound listener.
The sound listener reference elevation AISAC control ID set on the data side (i.e. in AtomCraft) is overwritten by this function.

Attention

In order to actually apply this parameter, you need to call the criAtomEx3dSource_Update function.
The control value for the AISAC control ID specified by this function takes priority over the control value set in the player using any of the following functions.

• criAtomExPlayer_SetAisacControlById function
  
• criAtomExPlayer_SetAisacControlByName function
  If you change the AISAC control ID for a 3D sound source that is playing, the final control value for the control ID before the change will continue to be applied.
  As a result, two parameters, one before the change and one after the change, are applied, and the intended output is not obtained.
  It is recommended to run this function while the audio associated with the specified 3D sound source is not being played.
  

See also

criAtomEx3dSource_Update

criAtomEx3dSource_SetSourceBasedAzimuthAngleAisacControlId()

void criAtomEx3dSource_SetSourceBasedAzimuthAngleAisacControlId	(	CriAtomEx3dSourceHn	ex_3d_source,
		CriAtomExAisacControlId	aisac_control_id
	)

Set the source reference angle AISAC control ID.

Parameters

[in]	ex_3d_source	3D sound source handle
[in]	aisac_control_id	Source reference angle AISAC control ID

Description:

Specify the AISAC control ID linked with the angle of the sound source seen from the source.
The source reference angle AISAC control ID set on the data side (i.e. in AtomCraft) is overwritten by this function.

Attention

In order to actually apply this parameter, you need to call the criAtomEx3dSource_Update function.
The control value for the AISAC control ID specified by this function takes priority over the control value set in the player using any of the following functions.

• criAtomExPlayer_SetAisacControlById function
  
• criAtomExPlayer_SetAisacControlByName function
  If you change the AISAC control ID for a 3D sound source that is playing, the final control value for the control ID before the change will continue to be applied.
  As a result, two parameters, one before the change and one after the change, are applied, and the intended output is not obtained.
  It is recommended to run this function while the audio associated with the specified 3D sound source is not being played.
  

See also

criAtomEx3dSource_Update

criAtomEx3dSource_SetSourceBasedElevationAngleAisacControlId()

void criAtomEx3dSource_SetSourceBasedElevationAngleAisacControlId	(	CriAtomEx3dSourceHn	ex_3d_source,
		CriAtomExAisacControlId	aisac_control_id
	)

Set the sound source reference elevation AISAC control ID.

Parameters

[in]	ex_3d_source	3D sound source handle
[in]	aisac_control_id	Elevation AISAC control ID based on sound source

Description:

Specify the AISAC control ID linked with the elevation of the listener as seen from the sound source.
The sound source reference elevation AISAC control ID set on the data side (i.e. in AtomCraft) is overwritten by this function.

Attention

In order to actually apply this parameter, you need to call the criAtomEx3dSource_Update function.
The control value for the AISAC control ID specified by this function takes priority over the control value set in the player using any of the following functions.

• criAtomExPlayer_SetAisacControlById function
  
• criAtomExPlayer_SetAisacControlByName function
  If you change the AISAC control ID for a 3D sound source that is playing, the final control value for the control ID before the change will continue to be applied.
  As a result, two parameters, one before the change and one after the change, are applied, and the intended output is not obtained.
  It is recommended to run this function while the audio associated with the specified 3D sound source is not being played.
  

See also

criAtomEx3dSource_Update

criAtomEx3dSource_Set3dRegionHn()

void criAtomEx3dSource_Set3dRegionHn	(	CriAtomEx3dSourceHn	ex_3d_source,
		CriAtomEx3dRegionHn	ex_3d_region
	)

Set 3D region handle for 3D source handle.

Description:

Set the 3D region handle for the 3D source handle.

Attention

The 3D sound source set to the same ExPlayer and the region set to the 3D listener are different, and if there is no 3D transceiver that has the same region as the 3D source, the audio will be muted.
To actually apply the set parameters, you need to call the criAtomEx3dSource_Update function.

See also

criAtomEx3dRegion_Create, criAtomEx3dSource_Update

criAtomEx3dSource_SetRandomPositionConfig()

void criAtomEx3dSource_SetRandomPositionConfig	(	CriAtomEx3dSourceHn	ex_3d_source,
		const CriAtomEx3dSourceRandomPositionConfig *	config
	)

Setting position randomization for 3D sound sources.

Parameters

[in]	ex_3d_source	3D Sound Source Handle
[in]	config	A pointer to a config structure for randomizing the 3D sound source position.

Description:

Sets position randomization for the 3D sound source handle. When this function is executed, the audio position will change randomly during playback according to the original position information and the set value.

Remarks:

You can cancel the setting by specifying NULL for the second argument, config.

Attention

To actually apply the set parameters, you must call the criAtomEx3dSource_Update function.

This function does not apply parameters to the audio currently being played.
They will be applied from the next audio played.

See also

CriAtomEx3dSourceRandomPositionConfig

criAtomEx3dSource_SetRandomPositionCalculationCallback()

void criAtomEx3dSource_SetRandomPositionCalculationCallback	(	CriAtomEx3dSourceHn	ex_3d_source,
		CriAtomEx3dSourceRandomPositionCalculationCbFunc	func,
		void *	obj
	)

Registration of a callback function for calculating position coordinates when randomizing the position of a 3D sound source.

Parameters

[in]	ex_3d_source	3D Sound Source Handle
[in]	func	Callback function for calculating position coordinates in 3D sound source randomization
[in]	obj	User-specified objects

Description:

For 3D sound sources, register a callback function for calculating position coordinates when randomizing the position of the 3D sound source.
If randomization of the 3D sound source position is enabled, the registered callback function will be executed when the coordinates are calculated.

Remarks:

The specified callback function will be executed when calculating coordinates only if CRIATOMEX3DSOURCE_RANDOM_POSITION_CALCULATION_TYPE_CALLBACK is set for the calculation_type variable of CriAtomEx3dSourceRandomPositionConfig, which is a configuration structure for randomizing the position of the 3D sound source.

Attention

The criAtomEx3dSource_Update function must be called to apply the callback registration.

If you execute an API that does not take into account interrupts to server processing, an error or deadlock may occur.
Generally, you should not use any Atom Library APIs within your callback functions.
Please note that if you block processing within this callback function for a long period of time, problems such as sound dropouts may occur.

Only one callback function can be registered for each 3D sound source handle.
If you perform the registration operation multiple times, the callback function that has already been registered will be overwritten by the callback function registered later.

You can unregister a registered function by specifying NULL for func.

See also

CriAtomEx3dSourceRandomPositionCalculationCbFunc, CriAtomEx3dSourceRandomPositionConfig

criAtomEx3dSource_SetRandomPositionList()

void criAtomEx3dSource_SetRandomPositionList	(	CriAtomEx3dSourceHn	ex_3d_source,
		const CriAtomExVector *	position_list,
		CriUint32	length
	)

Setting a list of position coordinates for randomizing the position of 3D sound sources.

Parameters

[in]	ex_3d_source	3D Sound Source Handle
[in]	position_list	Position coordinate list
[in]	length	The number of elements in the list

Description:

Specifies the array of position coordinates list.
If randomization of the 3D sound source position is enabled, the coordinates will be determined randomly from the coordinates of the specified array.

Remarks:

This parameter is referenced only when CRIATOMEX3DSOURCE_RANDOM_POSITION_CALCULATION_TYPE_LIST is set as the method for calculating position coordinates.
If any other calculation method is set, this parameter will be ignored.

Attention

To actually apply the set parameters, you must call the criAtomEx3dSource_Update function.

The area set in this function will not be referenced internally after the execution of the criAtomEx3dSource_SetRandomPositionList function is complete.
Instead, it stores them in an internally allocated list of position coordinates.
Therefore, setting a value greater than CriAtomEx3dSourceConfig::random_position_list_max_length will result in an error.

See also

CriAtomEx3dSourceRandomPositionConfig, CriAtomEx3dSourceConfig

criAtomEx3dSource_SetRandomPositionResultCallback()

void criAtomEx3dSource_SetRandomPositionResultCallback	(	CriAtomEx3dSourceHn	ex_3d_source,
		CriAtomEx3dSourceRandomPositionResultCbFunc	func,
		void *	obj
	)

Registering a callback function for the position coordinate result when randomizing the position of a 3D sound source.

Parameters

[in]	ex_3d_source	3D Sound Source Handle
[in]	func	Position coordinate result callback function for 3D sound source randomization
[in]	obj	User-specified objects

Description:

Registers a callback function for the position coordinate result of randomizing the position of a 3D sound source.
If randomization of the 3D sound source position is enabled, the registered callback function will be executed after the coordinate calculation is performed.

Remarks:

If the tracking setting is enabled, this callback function will be executed according to the movement of the original source.

Attention

The criAtomEx3dSource_Update function must be called to apply the callback registration.

If you execute an API that does not take into account interrupts to server processing, an error or deadlock may occur.
Generally, you should not use any Atom Library APIs within your callback functions.
Please note that if you block processing within this callback function for a long period of time, problems such as sound dropouts may occur.

Only one callback function can be registered.
If you perform the registration operation multiple times, the callback function that has already been registered will be overwritten by the callback function registered later.

You can unregister a registered function by specifying NULL for func.

See also

CriAtomEx3dSourceRandomPositionResultCbFunc

criAtomEx3dSourceList_CalculateWorkSize()

CriSint32 criAtomEx3dSourceList_CalculateWorkSize

(

const CriAtomEx3dSourceListConfig *

config

)

Calculate the size of the work area necessary to create the 3D sound source handle list.

Parameters

[in]

config

Pointer to the configuration structure for the creation of the 3D sound source handle list

Returns

CriSint32 Work size the creation of the 3D sound source handle list creation

Return values

>=	0 Successfully completed
-1	Error occurred

Description:

Get the size of the work area required to create a 3D sound source handle list.
When creating a 3D sound source handle list without having registered an allocator, it is necessary to call the criAtomEx3dSourceList_Create function with the right size for the work area.

The size of the work memory required to create the 3D sound source handle list varies depending on the contents of the 3D sound source handle list creation configuration structure ( CriAtomEx3dSourceListConfig ).

When NULL is specified as an argument, the work area size is calculated from the default settings. ( criAtomEx3dSourceList_SetDefaultConfig )
If the work area size calculation fails, the return value is -1.
The reason why the work area size calculation failed can be confirmed with the error call back message.

Remarks:

The information passed in the argument "config" is only referenced within this function.
Therefore it is safe to release the "config" area after executing the function.

See also

criAtomEx3dSourceList_Create, CriAtomEx3dSourceListConfig

criAtomEx3dSourceList_Create()

CriAtomEx3dSourceListHn criAtomEx3dSourceList_Create	(	const CriAtomEx3dSourceListConfig *	config,
		void *	work,
		CriSint32	work_size
	)

Create a 3D sound source handle list.

Parameters

[in]	config	Pointer to the configuration structure for the creation of a 3D sound source handle list
[in]	work	Pointer to the work area for the creation of a 3D sound source handle list
[in]	work_size	Work size for the creation of a 3D sound source handle list

Returns

CriAtomEx3dSourceListHn 3D sound source handle list

Description:

Creates a 3D sound source handle list creation based on the configuration structure.
After successful creation, the 3D sound source handle list is returned.
When creating a 3D sound source handle list, it is necessary to pass memory as a work area.
Calculate the required memory size with the criAtomEx3dSourceList_CalculateWorkSize function.
(If you have registered an allocator using the criAtomEx_SetUserAllocator macro, you do not need to specify a work area for this function.)

Attention

Before executing this function, it is necessary to initialize the library.

See also

criAtomEx3dSourceList_CalculateWorkSize, criAtomEx3dSourceList_Destroy

criAtomEx3dSourceList_Destroy()

void criAtomEx3dSourceList_Destroy

(

CriAtomEx3dSourceListHn

ex_3d_source_list

)

Discard a 3D sound source handle list.

Parameters

[in]

ex_3d_source_list

3D sound source handle list

Description:

Discards a 3D sound source handle list.
When this function is executed, all the resources secured when creating a 3D sound source handle list are released.
Also, the 3D sound source handle list specified as an argument becomes invalid.
If there is sound being played by the AtomEx player who uses the 3D sound source handle list, stop these sounds or discard the AtomEx player before executing this function.

Remarks:

If this function is executed when a 3D sound source handle has been added to the 3D sound source handle list, the added 3D sound source handle will be automatically deleted from the 3D sound source handle list.

See also

criAtomEx3dSourceList_Create

criAtomEx3dSourceList_Add()

void criAtomEx3dSourceList_Add	(	CriAtomEx3dSourceListHn	ex_3d_source_list,
		CriAtomEx3dSourceHn	ex_3d_source
	)

Add a 3D sound source handle to a 3D sound source handle list.

Parameters

[in]	ex_3d_source_list	3D sound source handle list
[in]	ex_3d_source	3D sound source handle

Description:

Adds a 3D sound source handle to a 3D sound source handle list.
The added AtomEx player is associated with the 3D sound source handle list, and multi-positioning playback becomes possible.
To delete the added 3D sound source handle from the 3D sound source handle list, call criAtomEx3dSourceList_Remove function or criAtomEx3dSourceList_RemoveAll function.

Remarks:

A 3D sound source handle that satisfies the following conditions can not be added to the 3D sound source handle list.

• Already assigned to the AtomEx player
• Already added to another 3D sound source handle list
  This function can be used on the 3D sound source handle list attached to the AtomEx player currently playing.
  

Attention

This function is a function that returns completion.
When this function is executed, the Atom library processing will be blocked for a while.
If it happens during sound playback, problems such as interruption of sound may occur, so please call this function when your application can tolerate load fluctuation, such as a scene change.

See also

criAtomEx3dSourceList_Remove, criAtomEx3dSourceList_RemoveAll

criAtomEx3dSourceList_Remove()

void criAtomEx3dSourceList_Remove	(	CriAtomEx3dSourceListHn	ex_3d_source_list,
		CriAtomEx3dSourceHn	ex_3d_source
	)

Delete a 3D sound source handle from 3D sound source handle list.

Parameters

[in]	ex_3d_source_list	3D sound source handle list
[in]	ex_3d_source	3D sound source handle

Description:

Delete the specified 3D sound source handle from the 3D sound source handle list.
If you want to delete all 3D sound source handles from a 3D sound source handle list, please call criAtomEx3dSourceList_Remove function.
If you want to add a 3D sound source handle to a 3D sound source handle list, call criAtomEx3dSourceList_Add function.

Remarks:

This function can be used on the 3D sound source handle list attached to the AtomEx player currently playing.

Attention

This function is a function that returns completion.
When this function is executed, the Atom library processing will be blocked for a while.
If it happens during sound playback, problems such as interruption of sound may occur, so please call this function when your application can tolerate load fluctuation, such as a scene change.

See also

criAtomEx3dSourceList_RemoveAll

criAtomEx3dSourceList_RemoveAll()

void criAtomEx3dSourceList_RemoveAll

(

CriAtomEx3dSourceListHn

ex_3d_source_list

)

Delete all the 3D sound source handles from a 3D sound source handle list.

Parameters

[in]

ex_3d_source_list

3D sound source handle list

Description:

Deletes all the 3D sound source handles from a 3D sound source handle list.
If you want to delete a specific 3D sound source handle from the 3D sound source handle list, call the criAtomEx3dSourceList_Remove function.
If you want to add a 3D sound source handle to the 3D sound source handle list, call criAtomEx3dSourceList_Add function.

Remarks:

This function can be used on the 3D sound source handle list attached to the AtomEx player currently playing.

Attention

This function is a function that returns completion.
When this function is executed, the Atom library processing will be blocked for a while.
If it happens during sound playback, problems such as interruption of sound may occur, so please call this function when your application can tolerate load fluctuation, such as a scene change.

See also

criAtomEx3dSourceList_Remove

criAtomEx3dListener_CalculateWorkSize()

CriSint32 criAtomEx3dListener_CalculateWorkSize

(

const CriAtomEx3dListenerConfig *

config

)

Calculate the size of the work buffer required to create a 3D listener.

Parameters

[in]

config

pointer to the configuration structure used to create a 3D listener

Returns

CriSint32 size of the work buffer to create a 3D listener

Return values

>=	0 Successfully completed
-1	Error occurred

Description:

Calculates the size of the work buffer required to create a 3D listener.
If you create a 3D listener without having registered a user-allocator, a memory buffer having the size returned by this function must be passed to criAtomEx3dListener_Create.

The size of the work buffer needed to create a 3D listener depends on the value of the parameters in the configuration structure ( CriAtomEx3dListenerConfig ).

When NULL is specified for the structure, the default settings (the same than the ones set by the criAtomEx3dListener_SetDefaultConfig macro) are used to calculate the size of the work buffer.
If this function fails to calculate the size of the work buffer, it will return -1.
To know the reason of the failure, refer to the error callback message.

Remarks:

The information in the configuration structure is only used during the initialization and is not referenced after that. Therefore, it is safe to release it once the function has returned.

See also

criAtomEx3dListener_Create, CriAtomEx3dListenerConfig

criAtomEx3dListener_Create()

CriAtomEx3dListenerHn criAtomEx3dListener_Create	(	const CriAtomEx3dListenerConfig *	config,
		void *	work,
		CriSint32	work_size
	)

Create a 3D listener handle.

Parameters

[in]	config	pointer to the configuration structure used to create a 3D listener
[in]	work	pointer to the work buffer
[in]	work_size	size of the work buffer

Returns

CriAtomEx3dListenerHn 3D listener handle

Description:

Creates a 3D listener based on the value of the parameters of the configuration structure.
When this function creates a 3D listener successfully, it returns a handle.
When creating a 3D listener, you must pass a work buffer.
The size of that buffer is calculated by calling the criAtomEx3dListener_CalculateWorkSize function.
(If a user-allocator has already been registered by using the criAtomEx_SetUserAllocator macro, you do not need to pass the work buffer.)

Attention

You must initialize the library before executing this function.

See also

criAtomEx3dListener_CalculateWorkSize, criAtomEx3dListener_Destroy

criAtomEx3dListener_Destroy()

void criAtomEx3dListener_Destroy

(

CriAtomEx3dListenerHn

ex_3d_listener

)

Destroy a 3D listener.

Parameters

[in]

ex_3d_listener

3D listener handle

Description:

Destroys a 3D listener.
All resources allocated when you created the 3D listener are released when you execute this function.
Also, the 3D listener handle specified as an argument is disabled.
If any sounds are being played back on an AtomEx player to which this 3D listener handle has been assigned, you must first stop these sounds or destroy the AtomEx player, then only execute this function.

See also

criAtomEx3dListener_Create

criAtomEx3dListener_Update()

void criAtomEx3dListener_Update

(

CriAtomEx3dListenerHn

ex_3d_listener

)

Update a 3D listener.

Parameters

[in]

ex_3d_listener

3D listener handle

Description:

Updates a 3D listener with the parameters previously specified with other functions.
This function updates all the parameters specified for the 3D listener at once.
Updating the 3D listener with this function every time you change a single parameter is inefficient. You should update it after changing all the parameters you need to change.

Example:

CriAtomExVector pos;
CriAtomExVector vel;
 
// Set position
pos.x = 0.0f
pos.y = 0.0f
pos.z = 1.0f
criAtomEx3dListener_SetPosition(source, &pos);
// Set velocity
vel.x = 1.0f
vel.y = 0.0f
vel.z = 0.0f
criAtomEx3dListener_SetVelocity(source, &vel);
 
// Update source parameters
criAtomEx3dListener_Update(source);

Attention

This function works independently from the parameter update functions ( criAtomExPlayer_UpdateAll and criAtomExPlayer_Update). Whenever you change the parameters of a 3D listener, use this function to update them.

criAtomEx3dListener_ResetParameters()

void criAtomEx3dListener_ResetParameters

(

CriAtomEx3dListenerHn

ex_3d_listener

)

Reset the 3D listener parameters.

Parameters

[in]

ex_3d_listener

3D listener handle

Description:

Clears the parameters set for the 3D listener and restores them to their initial values.

Attention

To actually apply the cleared parameters, the user must call the criAtomEx3dListener_Update function.

See also

criAtomEx3dListener_Update

criAtomEx3dListener_SetPosition()

void criAtomEx3dListener_SetPosition	(	CriAtomEx3dListenerHn	ex_3d_listener,
		const CriAtomExVector *	position
	)

Set the position of a 3D listener.

Parameters

[in]	ex_3d_listener	3D listener handle
[in]	position	position vector

Description:

Sets the position of the 3D listener.
The position is used to calculate the distance attenuation and the localization .
Specify the position as a 3D vector.
The default value is (0.0f, 0.0f, 0.0f).
The value set by this function is always used because the position cannot be set on the data side.

Attention

To actually apply the specified values, you have to call the criAtomEx3dListener_Update function.

See also

criAtomEx3dListener_Update

criAtomEx3dListener_GetPosition()

CriAtomExVector criAtomEx3dListener_GetPosition

(

CriAtomEx3dListenerHn

ex_3d_listener

)

Get 3D position of listener.

Parameters

[in]

ex_3d_listener

3D listener handle

Description:

Gets the position of the 3D listener.
Position is acquired with 3 dimensional vector.

criAtomEx3dListener_SetVelocity()

void criAtomEx3dListener_SetVelocity	(	CriAtomEx3dListenerHn	ex_3d_listener,
		const CriAtomExVector *	velocity
	)

Set the velocity of a 3D listener.

Parameters

[in]	ex_3d_listener	3D listener handle
[in]	velocity	velocity vector

Description:

Sets the velocity of a 3D listener.
The velocity is used to calculate the Doppler effect.
Specify the velocity as a 3D vector. The velocity corresponds to the distance traveled per second.
The default value is (0.0f, 0.0f, 0.0f).
The value set in this function is always used, because the velocity cannot be set on the data side.

Attention

To actually apply the specified values, you hve to call the criAtomEx3dListener_Update function.

See also

criAtomEx3dListener_Update

criAtomEx3dListener_SetOrientation()

void criAtomEx3dListener_SetOrientation	(	CriAtomEx3dListenerHn	ex_3d_listener,
		const CriAtomExVector *	front,
		const CriAtomExVector *	top
	)

Set the orientation of the 3D listener.

Parameters

[in]	ex_3d_listener	3D listener handle
[in]	front	front orientation vector
[in]	top	top orientation vector

Description:

Sets the orientation of the 3D listener using front and top orientation vectors.
The orientation is specified by 3D vectors. They are used after being normalized within the library. The default values are as follows.

• Front orientation vector (0.0f, 0.0f, 1.0f)
• Top orientation vector (0.0f, 1.0f, 0.0f)

The value set in this function is always used, because the orientation cannot be set on the data side.

Attention

To actually apply the specified values, you hve to call the criAtomEx3dListener_Update function.

See also

criAtomEx3dListener_Update

criAtomEx3dListener_SetDopplerMultiplier()

void criAtomEx3dListener_SetDopplerMultiplier	(	CriAtomEx3dListenerHn	ex_3d_listener,
		CriFloat32	doppler_multiplier
	)

Set the Doppler multiplier for the 3D listener.

Parameters

[in]	ex_3d_listener	3D listener handle
[in]	doppler_multiplier	Doppler multiplier

Description:

Set the Doppler multiplier of 3D listener. This scaling factor is used to calculate the Doppler effect.
For example, if you specify 10.0 f for doppler_multiplier, the Doppler effect will be 10 times normal.
Specify a value of 0.0 f or more for doppler_multiplier. The default value is 1.0f.
Since the listener's Doppler multiplier can not be set on the data side, the setting value of this function is always used.

Attention

To actually apply the specified parameter, call the criAtomEx3dListener_Update function.

See also

criAtomEx3dListener_Update

criAtomEx3dListener_SetFocusPoint()

void criAtomEx3dListener_SetFocusPoint	(	CriAtomEx3dListenerHn	ex_3d_listener,
		const CriAtomExVector *	focus_point
	)

Set the focus point of the 3D listener.

Parameters

[in]	ex_3d_listener	3D listener handle
[in]	focus_point	focus point vector

Description:

Sets the focus point of a 3D listener.
When performing 3D positioning, setting a focus point connects the listener position and the focus point with a straight line along which the microphone can be moved.
For example, you can easily represent and adjust objective and subjective situations by setting a focus point on the main character while keeping the listener and the camera sychronized.
Note that the microphone that can be moved between the listener position and focus point differs from real-world microphones in that its distance sensor (for distance attenuation calculation) and direction sensor (for localization calculation) are independent.
By operating the sensors separately, you can achieve effects such as setting the focus on the main character and performing distance attenuation based on the character position, or performing localization calculation based on the camera position to match localization with the view point on the screen.
The default value is (0.0f, 0.0f, 0.0f). When the focus levels of the distance sensor and direction sensor are not set, there is no need to set a focus point. In that case, all 3D positioning calculations are performed based on the listener position as usual.

Attention

To actually apply the specified parameter, call the criAtomEx3dListener_Update function.

See also

criAtomEx3dListener_Update, criAtomEx3dListener_SetDistanceFocusLevel, criAtomEx3dListener_SetDirectionFocusLevel

criAtomEx3dListener_SetDistanceFocusLevel()

void criAtomEx3dListener_SetDistanceFocusLevel	(	CriAtomEx3dListenerHn	ex_3d_listener,
		CriFloat32	distance_focus_level
	)

Set the focus level of the distance sensor.

Parameters

[in]	ex_3d_listener	3D listener handle
[in]	distance_focus_level	focus level of the distance sensor

Description:

Sets the focus level of the distance sensor.
The distance sensor represents the reference position used to calculate the distance attenuation for the 3D positioning. It can be considered as a microphone that only detects the effect of the distance attenuation and ignores localization.
The focus level represents how close the sensor (microphone) can be brought to the focus point. The sensor (microphone) can be moved along the line connecting the listener position and the focus point, with 0.0f and 1.0f corresponding to the listener position and the focus point, respectively.
For example, when the focus level of the distance sensor is set to 1.0f and the focus level of the direction sensor is set to 0.0f, the distance attenuation is applied based on the focus point, and the localization is determined based on the listener position.
The default value is 0.0f. When the focus levels of the distance and direction sensors are not set, all 3D positioning calculations are performed based on the listener position as usual.

Attention

To actually apply the specified parameter, call the criAtomEx3dListener_Update function.

See also

criAtomEx3dListener_Update, criAtomEx3dListener_SetFocusPoint, criAtomEx3dListener_SetDirectionFocusLevel

criAtomEx3dListener_SetDirectionFocusLevel()

void criAtomEx3dListener_SetDirectionFocusLevel	(	CriAtomEx3dListenerHn	ex_3d_listener,
		CriFloat32	direction_focus_level
	)

Set the focus level of the direction sensor.

Parameters

[in]	ex_3d_listener	3D listener handle
[in]	direction_focus_level	focus level of the direction sensor

Description:

Sets the focus level of the direction sensor.
The direction sensor represents the reference position used to calculate the localization for the 3D positioning. It can be considered as a microphone that only detects localization and ignores distance attenuation.
For the orientation of the direction sensor, the orientation of the listener is used (set by the criAtomEx3dListener_SetOrientation function).
The focus level represents how close the sensor (microphone) can be brought to the focus point. The sensor (microphone) can be moved along the line connecting the listener position and the focus point, with 0.0f and 1.0f corresponding to the listener position and the focus point, respectively.
For example, when the focus level of the distance sensor is set to 1.0f and the focus level of the direction sensor is set to 0.0f, the distance attenuation is applied based on the focus point, and the localization is determined based on the listener position.
The default value is 0.0f. When the focus levels of the distance and direction sensors are not set, all 3D positioning calculations are performed based on the listener position as usual.

Attention

To actually apply the specified parameter, call the criAtomEx3dListener_Update function.

See also

criAtomEx3dListener_Update, criAtomEx3dListener_SetFocusPoint, criAtomEx3dListener_SetDistanceFocusLevel

criAtomEx3dListener_GetFocusPoint()

void criAtomEx3dListener_GetFocusPoint	(	CriAtomEx3dListenerHn	ex_3d_listener,
		CriAtomExVector *	focus_point
	)

Getting the 3D listener's attention point.

Parameters

[in]	ex_3d_listener	3D listener handle
[out]	focus_point	Attention point vector

Description:

Gets the 3D listener's focus point.
The default value is (0.0f, 0.0f, 0.0f). If you have not set the 3D listener's focus point, the default value will be returned.

See also

criAtomEx3dListener_GetDistanceFocusLevel, criAtomEx3dListener_GetDirectionFocusLevel

criAtomEx3dListener_GetDistanceFocusLevel()

CriFloat32 criAtomEx3dListener_GetDistanceFocusLevel

(

CriAtomEx3dListenerHn

ex_3d_listener

)

Get the focus level of the distance sensor.

Parameters

[in]

ex_3d_listener

3D listener handle

Description:

Sets the focus level of the distance sensor.
The default value is 0.0f. If the focus level of the distance sensor is not set, the default value is returned.

See also

criAtomEx3dListener_GetDistanceFocusLevel, criAtomEx3dListener_GetDirectionFocusLevel

criAtomEx3dListener_GetDirectionFocusLevel()

CriFloat32 criAtomEx3dListener_GetDirectionFocusLevel

(

CriAtomEx3dListenerHn

ex_3d_listener

)

Get focus level of direction sensor.

Parameters

[in]

ex_3d_listener

3D listener handle

Description:

Gets the focus level of the direction sensor.
The default value is 0.0f. If you do not set the focus level of the direction sensor, the default value will be returned.

See also

criAtomEx3dListener_GetFocusPoint, criAtomEx3dListener_GetDistanceFocusLevel

criAtomEx_EnableCalculationAisacControlFrom3dPosition()

void criAtomEx_EnableCalculationAisacControlFrom3dPosition

(

CriBool

flag

)

When the pan type is Pan 3D, sets whether to reflect the distance attenuation AISAC and angle AISAC control values to the sound source.

Parameters

[in]

flag

Apply AISAC control value? (CRI_TRUE: yes, CRI_FALSE: no)

Description:

If you set the flag argument to CRI_TRUE, when playing a sound source whose pan type is Pan3D, the distance attenuation AISAC and angle AISAC calculation results will always be applied to the sound source when a 3D source and 3D listener handle are set.

Attention

By default in the Atom library, the calculation results of distance attenuation AISAC and angle AISAC are not applied to pan 3D sound source.
This function has been added for compatibility with the behavior of the CRI Atom library Ver.2.17.19 and earlier.

See also

criAtomEx_IsEnableCalculationAisacControlFrom3dPosition

criAtomEx_IsEnableCalculationAisacControlFrom3dPosition()

CriBool criAtomEx_IsEnableCalculationAisacControlFrom3dPosition

(

void

)

Gets whether distance attenuation AISAC and angle AISAC control values are reflected in the sound source when pan type is pan 3D.

Return values

CRI_TRUE	Applying calculation results
CRI_FALSE	Not applying calculation results

Description:

When playing Pan type 3D sound source, it acquires whether calculation results of set distance
attenuation AISAC and angle AISAC are applied to the sound source.

Attention

By default in the Atom library, the calculation results of distance attenuation AISAC and angle AISAC are not applied to pan 3D sound source.
This function has been added for compatibility with the behavior of the CRI Atom library ver.2.17.19 and earlier.

See also

criAtomEx_EnableCalculationAisacControlFrom3dPosition

criAtomEx3dListener_Set3dRegionHn()

void criAtomEx3dListener_Set3dRegionHn	(	CriAtomEx3dListenerHn	ex_3d_listener,
		CriAtomEx3dRegionHn	ex_3d_region
	)

Set 3D region handle for 3D listener handle.

Description:

Sets the 3D region handle for the 3D listener handle.

Attention

If the 3D sound source set to the same ExPlayer and the region set to the 3D listener are different, and there is no 3D transceiver set to the same region as the 3D sound source, the audio will be muted.
In order to actually apply the set parameters, you need to call the criAtomEx3dListener_Update function.

See also

criAtomEx3dRegion_Create, criAtomEx3dListener_Update

criAtomEx3dRegion_CalculateWorkSize()

CriSint32 criAtomEx3dRegion_CalculateWorkSize

(

const CriAtomEx3dRegionConfig *

config

)

Calculation of the work area size required to create a 3D region handle.

Parameters

[in]

config

Pointer to config structure for creating 3D region handle

Returns

CriSint32 Work size for 3D region handle creation

Return values

0	or more Completed
-1	An error has occured

Description:

Gets the size of the work area needed to create a 3D region handle.
When creating a 3D region handle without registering the allocator, it is necessary to set the memory for the work area size calculated by this function in advance as the work area in the criAtomEx3dRegion_Create function.

The size of the work memory required to create a 3D region handle changes depending on the contents of the 3D region handle creation config structure ( ::criAtomEx3dRegionConfig ).

If NULL is specified as the argument, the work area size will be calculated using the default settings (the same parameters as when criAtomEx3dRegion_SetDefaultConfig is applied).
If this function fails to calculate the size of the work buffer, it will return -1.
To know the reason of the failure, refer to the error callback message.

Remarks:

The information in the argument config is referenced only inside the function.
It is not referenced after exiting the function, so there is no problem in releasing the config area after executing the function.

See also

criAtomEx3dRegion_Create, CriAtomEx3dRegionConfig

criAtomEx3dRegion_Create()

CriAtomEx3dRegionHn criAtomEx3dRegion_Create	(	const CriAtomEx3dRegionConfig *	config,
		void *	work,
		CriSint32	work_size
	)

Create 3D region handle.

Parameters

[in]	config	Pointer to config structure for creating 3D region handle
[in]	work	Work area
[in]	work_size	Work size for making 3D transceiver handle

Returns

criAtomEx3dRegionHn 3D region handle

Description:

Create a 3D region handle based on the 3D region handle creation config.
Returns a 3D region handle if created successfully.
When creating a 3D region handle, you need to pass memory as a work area.
Calculate the required memory size with the criAtomEx3dRegion_CalculateWorkSize function.
(If a user-allocator has already been registered by using the criAtomEx_SetUserAllocator macro, you do not need to pass the work buffer.)

Attention

The library must be initialized before executing this function.

See also

criAtomEx3dRegion_CalculateWorkSize, criAtomEx3dRegion_Destroy

criAtomEx3dRegion_Destroy()

void criAtomEx3dRegion_Destroy

(

CriAtomEx3dRegionHn

ex_3d_region

)

Discard 3D region handle.

Parameters

[in]

ex_3d_region

3D region handle

Description:

Discard the 3D region handle.
When this function is executed, all the resources secured when creating the 3D region handle are released.
Also, the 3D region handle specified in the argument is invalid.
If there is a 3D sound source, 3D listener,or 3D transceiver with a 3D region handle set, be sure to discard or unset all handles that set the 3D region before executing this function.

See also

criAtomEx3dRegion_Create

criAtomEx3dTransceiver_CalculateWorkSize()

CriSint32 criAtomEx3dTransceiver_CalculateWorkSize

(

const CriAtomEx3dTransceiverConfig *

config

)

Calculating the work area size required to create a 3D transceiver handle.

Parameters

[in]

config

Pointer to the config structure for creating the 3D transceiver handle

Returns

CriSint32 Work size for making 3D transceiver handle

Return values

0	or more Completed
-1	An error has occured

Description:

Gets the size of the work area needed to create a 3D Transceiver handle.
When creating a 3D Transceiver handle without registering the allocator, it is necessary to set the memory for the work area size calculated by this function in advance as the work area in the criAtomEx3dTransceiver_Create function.

The size of the work memory required to create a 3D region handle changes depending on the contents of the 3D region handle creation config structure ( CriAtomEx3dTransceiverConfig ).

If NULL is specified as the argument, the work area size will be calculated using the default settings (the same parameters as when criAtomEx3dTransceiver_SetDefaultConfig is applied).
If this function fails to calculate the size of the work buffer, it will return -1.
To know the reason of the failure, refer to the error callback message.

Remarks:

The information in the argument config is referenced only inside the function.
It is not referenced after exiting the function, so there is no problem in releasing the config area after executing the function.

See also

criAtomEx3dTransceiver_Create, CriAtomEx3dTransceiverConfig

criAtomEx3dTransceiver_Create()

CriAtomEx3dTransceiverHn criAtomEx3dTransceiver_Create	(	const CriAtomEx3dTransceiverConfig *	config,
		void *	work,
		CriSint32	work_size
	)

Create 3D Transceiver handle.

Parameters

[in]	config	Pointer to config structure for creating 3D Transceiver handle
[in]	work	Pointer to the work area for creating the 3D transceiver handle
[in]	work_size	Work size for making 3D Transceiver handle

Returns

criAtomEx3dTransceiverHn 3D Transceiver handle

Description:

Create a 3D Transceiver handle based on the 3D Transceiver handle creation config.
Returns a 3D Transceiver handle if created successfully.
When creating a 3D Transceiver handle, you need to pass memory as a work area.
Calculate the required memory size with the criAtomEx3dTransceiver_CalculateWorkSize function.
(If a user-allocator has already been registered by using the criAtomEx_SetUserAllocator macro, you do not need to pass the work buffer.)

Attention

The library must be initialized before executing this function.

See also

criAtomEx3dTransceiver_CalculateWorkSize, criAtomEx3dTransceiver_Destroy

criAtomEx3dTransceiver_Destroy()

void criAtomEx3dTransceiver_Destroy

(

CriAtomEx3dTransceiverHn

ex_3d_transceiver

)

Discard 3D Transceiver handle.

Parameters

[in]

ex_3d_transceiver

3D Transceiver handle

Description:

Discard the 3D Transceiver handle.
When this function is executed, all the resources secured when creating the 3D Transceiver handle are released.
Also, the 3D Transceiver handle specified in the argument is invalid.

See also

criAtomEx3dTransceiver_Create

criAtomEx3dTransceiver_Update()

void criAtomEx3dTransceiver_Update

(

CriAtomEx3dTransceiverHn

ex_3d_transceiver

)

3D Transceiver Update

Parameters

[in]

ex_3d_transceiver

3D Transceiver handle

Description:

Updates the 3D transceiver with the parameters set for the 3D transceiver.
In this function, all parameters set in the 3D transceiver are updated. It is more efficient to update multiple parameters before performing the update process with this function each time one parameter is changed.

Examples:

CriAtomExVector in_pos, out_pos;
 
// Set input position
in_pos.x = 0.0f
in_pos.y = 0.0f
in_pos.z = 1.0f
criAtomEx3dTransceiver_SetInputPosition(transceiver, &in_pos);
 
// Set output position
out_pos.x = 0.0f
out_pos.y = 0.0f
out_pos.z = 1.0f
criAtomEx3dTransceiver_SetOutputPosition(transceiver, &out_pos);
 
// Update transceiver parameters
criAtomEx3dTransceiver_Update(transceiver);

Attention

This function works independently of the parameter update of AtomEx player. ( criAtomExPlayer_UpdateAll , criAtomExPlayer_Update ) When you change the parameter of 3D transceiver, please update it with this function.

criAtomEx3dTransceiver_SetInputPosition()

void criAtomEx3dTransceiver_SetInputPosition	(	CriAtomEx3dTransceiverHn	ex_3d_transceiver,
		const CriAtomExVector *	position
	)

Setting the position of the 3D transceiver input.

Parameters

[in]	ex_3d_transceiver	3D Transceiver handle
[in]	position	Position vector

Description:

Set the position of the 3D transceiver input.
The position is used for distance attenuation and localization calculations.
The position is specified as a 3D vector.
The default value is (0.0f, 0.0f, 0.0f).

Attention

In order to actually apply the set parameters, you need to call the criAtomEx3dTransceiver_Update function.

See also

criAtomEx3dTransceiver_Update

criAtomEx3dTransceiver_SetOutputPosition()

void criAtomEx3dTransceiver_SetOutputPosition	(	CriAtomEx3dTransceiverHn	ex_3d_transceiver,
		const CriAtomExVector *	position
	)

Setting the position of the 3D transceiver output.

Parameters

[in]	ex_3d_transceiver	3D Transceiver handle
[in]	position	Position vector

Description:

Sets the position of the 3D transceiver output.
The position is used for distance attenuation and localization calculations.
The position is specified as a 3D vector.
The default value is (0.0f, 0.0f, 0.0f).

Attention

In order to actually apply the set parameters, you need to call the criAtomEx3dTransceiver_Update function.

See also

criAtomEx3dTransceiver_Update

criAtomEx3dTransceiver_SetInputOrientation()

void criAtomEx3dTransceiver_SetInputOrientation	(	CriAtomEx3dTransceiverHn	ex_3d_transceiver,
		const CriAtomExVector *	front,
		const CriAtomExVector *	top
	)

Setting the orientation of the 3D transceiver input.

Parameters

[in]	ex_3d_transceiver	3D Transceiver handle
[in]	front	Forward vector
[in]	top	Upward vector

Description:

Sets the orientation of the 3D transceiver in the forward and upward vectors.
The orientation is specified as a 3D vector. The set orientation vector is normalized and used inside the library.
The default values are as follows:

• Forward vector: (0.0f, 0.0f, 1.0f)
• Upward vector : (0.0f, 1.0f, 0.0f)

Attention

In order to actually apply the set parameters, you need to call the criAtomEx3dTransceiver_Update function.

See also

criAtomEx3dTransceiver_Update

criAtomEx3dTransceiver_SetOutputOrientation()

void criAtomEx3dTransceiver_SetOutputOrientation	(	CriAtomEx3dTransceiverHn	ex_3d_transceiver,
		const CriAtomExVector *	front,
		const CriAtomExVector *	top
	)

Setting the orientation of the 3D transceiver output.

Parameters

[in]	ex_3d_transceiver	3D Transceiver handle
[in]	front	Forward vector
[in]	top	Upward vector

Description:

Sets the orientation of the 3D transceiver output.
The direction set by this function is set as the direction of the sound cone.
The sound cone represents the direction in which the sound is emitted from the 3D transceiver and is used to express the directionality of the sound.
The orientation of the sound cone is specified by a 3D vector. The set orientation vector is normalized and used inside the library.
The default values are as follows:

• Forward vector: (0.0f, 0.0f, 1.0f)
• Upward vector : (0.0f, 1.0f, 0.0f)

Attention

In order to actually apply the set parameters, you need to call the criAtomEx3dTransceiver_Update function.

See also

criAtomEx3dTransceiver_SetOutputConeParameter, criAtomEx3dTransceiver_Update

criAtomEx3dTransceiver_SetOutputConeParameter()

void criAtomEx3dTransceiver_SetOutputConeParameter	(	CriAtomEx3dTransceiverHn	ex_3d_transceiver,
		CriFloat32	inside_angle,
		CriFloat32	outside_angle,
		CriFloat32	outside_volume
	)

Setting sound cone parameters for 3D transceiver output.

Parameters

[in]	ex_3d_transceiver	3D Transceiver handle
[in]	inside_angle	Inside angle of sound cone
[in]	outside_angle	Outside angle of sound cone
[in]	outside_volume	Outside volume of sound cone

Description:

Set the sound cone parameters for the 3D transceiver output.
The sound cone represents the direction in which the sound is emitted from the 3D transceiver and is used to express the directionality of the sound.
The sound cone consists of an inner cone and an outer cone. The inside angle is the angle of the inner cone, the outside angle is the angle of the outer cone, and the outside volume is the volume above the angle of the outer cone.
At angles smaller than the inner cone angle, there is no cone attenuation. In the direction between the inner and outer cones, there is a gradual decay to the outside volume.
The inside angle and outside angle specify 0.0f-360.0f in degrees.
The outside volume specifies 0.0f-1.0f as a scale factor for the amplitude (the unit is not decibel).
The default values at library initialization are as follows, and there is no cone attenuation.

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

Default value can be changed with ::criAtomEx3dTransceiver_ChangeDefaultConeParameter function.

Attention

In order to actually apply the set parameters, you need to call the criAtomEx3dTransceiver_Update function.

See also

criAtomEx3dTransceiver_Update

criAtomEx3dTransceiver_SetOutputMinMaxAttenuationDistance()

void criAtomEx3dTransceiver_SetOutputMinMaxAttenuationDistance	(	CriAtomEx3dTransceiverHn	ex_3d_transceiver,
		CriFloat32	min_attenuation_distance,
		CriFloat32	max_attenuation_distance
	)

Set minimum/maximum distance for 3D transceiver.

Parameters

[in]	ex_3d_transceiver	3D Transceiver handle
[in]	min_attenuation_distance	Minimum distance
[in]	max_attenuation_distance	Maximum distance

Description:

Set the minimum distance/maximum distance of the 3D transceiver.
The minimum distance is the distance at which the volume does not increase any further. The maximum distance is the distance at which the volume is the lowest.
The default values at library initialization are as follows:

• Minimum distance : 0.0f
• Maximum distance : 0.0f

Attention

In order to actually apply the set parameters, you need to call the criAtomEx3dTransceiver_Update function.

See also

criAtomEx3dTransceiver_Update

criAtomEx3dTransceiver_SetOutputInteriorPanField()

void criAtomEx3dTransceiver_SetOutputInteriorPanField	(	CriAtomEx3dTransceiverHn	ex_3d_transceiver,
		CriFloat32	transceiver_radius,
		CriFloat32	interior_distance
	)

Set Interior Panning Boundary Distance for 3D Transceiver Output.

Parameters

[in]	ex_3d_transceiver	3D Transceiver handle
[in]	transceiver_radius	3D transceiver radius
[in]	interior_distance	Interior distance

Description:

Sets the interior panning boundary distance for 3D transceiver output.
The radius of the 3D transceiver output is the radius when the 3D transceiver output is a sphere.
Interior distance is the distance from the radius of the 3D transceiver that interior panning is applied.
Within the radius of the 3D transceiver, interior panning is applied, but since the interior distance is treated as 0.0, sound will be played at the same volume from all speakers.
Within the interior distance, interior panning is applied.
Outside the interior distance, no interior panning is applied and the sound is played from the one or two speakers closest to the 3D transceiver position.
The default values at library initialization are as follows:

• 3D Transceiver Radius : 0.0f
• Interior distance : 0.0f (Depends on minimum distance of 3D transceiver)

Attention

In order to actually apply the set parameters, you need to call the criAtomEx3dTransceiver_Update function.

See also

criAtomEx3dTransceiver_Update

criAtomEx3dTransceiver_SetInputCrossFadeField()

void criAtomEx3dTransceiver_SetInputCrossFadeField	(	CriAtomEx3dTransceiverHn	ex_3d_transceiver,
		CriFloat32	direct_audio_radius,
		CriFloat32	crossfade_distance
	)

Set Crossfade Boundary Distance for 3D Transceiver Input.

Parameters

[in]	ex_3d_transceiver	3D Transceiver handle
[in]	direct_audio_radius	Radius of direct sound area
[in]	crossfade_distance	Crossfade distance

Description:

Set the crossfade boundary distance of 3D transceiver input.
Within the radius of the direct sound area, the sound from the output of the 3D transceiver is not played, only the sound from the 3D sound source is played.
The crossfade distance is the distance from the direct sound area where the crossfade of the 3D transceiver output and the sound from the 3D source is applied.
In the direct sound area, the rate of crossfade is 1 from the sound source and 0 from the 3D transceiver, so the sound from the 3D transceiver output cannot be heard, and only the sound from the sound source is played.
Within the crossfade distance, a crossfade will be applied depending on the position of the listener.
Outside the crossfade distance, you will not hear audio from the 3D source, only the audio from the 3D transceiver output.
The default values at library initialization are as follows:

• Radius of direct sound area:0.0f
• Crossfade distance:0.0f

Attention

In order to actually apply the set parameters, you need to call the criAtomEx3dTransceiver_Update function.

See also

criAtomEx3dTransceiver_Update

criAtomEx3dTransceiver_SetOutputVolume()

void criAtomEx3dTransceiver_SetOutputVolume	(	CriAtomEx3dTransceiverHn	ex_3d_transceiver,
		CriFloat32	volume
	)

Setting the volume of the 3D transceiver output.

Parameters

[in]	ex_3d_transceiver	3D Transceiver handle
[in]	volume	Volume

Description:

Sets the volume of the 3D transceiver output.
The volume of the 3D transceiver output affects only the volume related to localization (L, R, SL, SR) and does not affect the output level to the LFE or the center.
For the volume value, specify a real value in the range 0.0f-1.0f.
The volume value is a scale factor for the amplitude of audio data (the unit is not decibel).
For example, if you specify 1.0f, the original sound will be output with the same volume.
When 0.5f is specified, the sound is output at the same volume (-6dB) as the data in which the amplitude of the original sound waveform is halved.
If you specify 0.0f, the audio will be muted (silent).
The default value at library initialization is 1.0f.

Attention

In order to actually apply the set parameters, you need to call the criAtomEx3dTransceiver_Update function.

See also

criAtomEx3dTransceiver_Update

criAtomEx3dTransceiver_AttachAisac()

void criAtomEx3dTransceiver_AttachAisac	(	CriAtomEx3dTransceiverHn	ex_3d_transceiver,
		const CriChar8 *	global_aisac_name
	)

Attach AISAC to 3D transceiver.

Parameters

[in]	ex_3d_transceiver	3D Transceiver handle
[in]	global_aisac_name	Global AISAC name

Description:

Attach AISAC to 3D transceiver. By attaching AISAC, you can get the effect of AISAC even if you have not set AISAC for the cue or track.

If the AISAC attach fails, an error callback will occur in the function.
Check the error callback message for the reason why the AISAC attach failed.

Remarks:

Only the global AISAC included in the global settings (ACF file) can be attached.
To get the effect of AISAC, it is necessary to set the appropriate AISAC control value as well as the AISAC set for the cue or track.

Attention

Even if "AISAC to change AISAC control value" is set for the cue or track, the applied AISAC control value does not affect the AISAC attached to the 3D transceiver.
Currently, it does not support control type AISAC attachment such as "automodulation" or "random".
Currently, the maximum number of AISACs that can be attached to a 3D transceiver is fixed at 8.

See also

criAtomEx3dTransceiver_DetachAisac

criAtomEx3dTransceiver_DetachAisac()

void criAtomEx3dTransceiver_DetachAisac	(	CriAtomEx3dTransceiverHn	ex_3d_transceiver,
		const CriChar8 *	global_aisac_name
	)

Detach AISAC from 3D transceiver.

Parameters

[in]	ex_3d_transceiver	3D Transceiver handle
[in]	global_aisac_name	Global AISAC name

Description:

Detach the AISAC from the 3D transceiver.

If AISAC detach fails, an error callback will occur in the function.
Check the error callback message for the reason why the AISAC detach failed.

See also

criAtomEx3dTransceiver_AttachAisac

criAtomEx3dTransceiver_SetMaxAngleAisacDelta()

void criAtomEx3dTransceiver_SetMaxAngleAisacDelta	(	CriAtomEx3dTransceiverHn	ex_3d_transceiver,
		CriFloat32	max_delta
	)

Setting of maximum change amount of angle AISAC control value.

Parameters

[in]	ex_3d_transceiver	3D Transceiver handle
[in]	max_delta	Maximum change in angle AISAC control value

Description:

Sets the maximum change amount when the AISAC control value is changed by the angle AISAC.
By changing the maximum change amount to a lower value, the change of the AISAC control value by the angle AISAC can be made smooth even if the relative angle between the 3D transceiver and the listener changes rapidly.
For example, if (0.5f/30.0f) is set, the change amount will change 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 side, the setting value of this function is always used.

Attention

In order to actually apply the set parameters, you need to call the criAtomEx3dTransceiver_Update function. The maximum change amount 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

criAtomEx3dTransceiver_Update

criAtomEx3dTransceiver_SetDistanceAisacControlId()

void criAtomEx3dTransceiver_SetDistanceAisacControlId	(	CriAtomEx3dTransceiverHn	ex_3d_transceiver,
		CriAtomExAisacControlId	aisac_control_id
	)

Set the distance AISAC control ID.

Parameters

[in]	ex_3d_transceiver	3D Transceiver handle
[in]	aisac_control_id	Distance AISAC control ID

Description:

Specify the AISAC control ID that works with the distance attenuation between the minimum distance and the maximum distance.
If the AISAC control ID is set by this function, the default distance attenuation will be invalid.

Attention

In order to actually apply the set parameters, you need to call the criAtomEx3dTransceiver_Update function.

See also

criAtomEx3dTransceiver_Update

criAtomEx3dTransceiver_SetListenerBasedAzimuthAngleAisacControlId()

void criAtomEx3dTransceiver_SetListenerBasedAzimuthAngleAisacControlId	(	CriAtomEx3dTransceiverHn	ex_3d_transceiver,
		CriAtomExAisacControlId	aisac_control_id
	)

Setting listener reference azimuth AISAC control ID.

Parameters

[in]	ex_3d_transceiver	3D Transceiver handle
[in]	aisac_control_id	Listener reference azimuth AISAC control ID

Description:

Specify the AISAC control ID that is linked to the azimuth angle of the 3D transceiver seen from the listener.

Attention

In order to actually apply the set parameters, you need to call the criAtomEx3dTransceiver_Update function.

See also

criAtomEx3dTransceiver_Update

criAtomEx3dTransceiver_SetListenerBasedElevationAngleAisacControlId()

void criAtomEx3dTransceiver_SetListenerBasedElevationAngleAisacControlId	(	CriAtomEx3dTransceiverHn	ex_3d_transceiver,
		CriAtomExAisacControlId	aisac_control_id
	)

Listener standard elevation/depression angle AISAC control ID setting.

Parameters

[in]	ex_3d_transceiver	3D Transceiver handle
[in]	aisac_control_id	Listener standard elevation/depression angle AISAC control ID

Description:

Specify the AISAC control ID linked to the elevation/depression angle of the 3D transceiver as seen from the listener.

Attention

In order to actually apply the set parameters, you need to call the criAtomEx3dTransceiver_Update function.

See also

criAtomEx3dTransceiver_Update

criAtomEx3dTransceiver_SetTransceiverOutputBasedAzimuthAngleAisacControlId()

void criAtomEx3dTransceiver_SetTransceiverOutputBasedAzimuthAngleAisacControlId	(	CriAtomEx3dTransceiverHn	ex_3d_transceiver,
		CriAtomExAisacControlId	aisac_control_id
	)

3D transceiver output reference azimuth AISAC control ID setting

Parameters

[in]	ex_3d_transceiver	3D Transceiver handle
[in]	aisac_control_id	3D transceiver standard azimuth AISAC control ID

Description:

Specify the AISAC control ID linked to the azimuth of the listener as seen from the position of the 3D transceiver output.

Attention

In order to actually apply the set parameters, you need to call the criAtomEx3dTransceiver_Update function.

See also

criAtomEx3dTransceiver_Update

criAtomEx3dTransceiver_SetTransceiverOutputBasedElevationAngleAisacControlId()

void criAtomEx3dTransceiver_SetTransceiverOutputBasedElevationAngleAisacControlId	(	CriAtomEx3dTransceiverHn	ex_3d_transceiver,
		CriAtomExAisacControlId	aisac_control_id
	)

3D transceiver output reference elevation angle AISAC control ID setting

Parameters

[in]	ex_3d_transceiver	3D Transceiver handle
[in]	aisac_control_id	3D transceiver standard elevation/depression angle AISAC control ID

Description:

Specify the AISAC control ID that is linked to the elevation angle of the listener as seen from the position of the 3D transceiver output.

Attention

In order to actually apply the set parameters, you need to call the criAtomEx3dTransceiver_Update function.

See also

criAtomEx3dTransceiver_Update

criAtomEx3dTransceiver_Set3dRegionHn()

void criAtomEx3dTransceiver_Set3dRegionHn	(	CriAtomEx3dTransceiverHn	ex_3d_transceiver,
		CriAtomEx3dRegionHn	ex_3d_region
	)

Setting the 3D region handle for the 3D transceiver handle.

Description:

Set the 3D region handle for the 3D transceiver handle.

Attention

If the 3D sound source set to the same ExPlayer and the region set to the 3D listener are different, and there is no 3D transceiver set to the same region as the 3D sound source, the audio will be muted.
In order to actually apply the set parameters, you need to call the criAtomEx3dTransceiver_Update function.

See also

criAtomEx3dRegion_Create, criAtomEx3dTransceiver_Update