CriAtomExPlayer API

结构体
struct	CriAtomExPlayerConfigTag
	Configuration structure used when creating a player 更多...
struct	CriAtomExPlaybackTrackInfoTag
	Info structure for playback track information 更多...

宏定义
#define	CRIATOMEXPLAYER_NO_GROUP_LIMITATION   (-1)
	No group limitation 更多...
#define	CRIATOMEXPLAYER_NO_LOOP_LIMITATION   (CRIATOMPLAYER_NO_LOOP_LIMITATION)
	Constants used to cancel a fixed number of repetitions for the loops 更多...
#define	CRIATOMEXPLAYER_MAX_ASR_RACKS   (8)
	Maximum number of ASR racks that can be specified for the player 更多...
#define	CRIATOMEXPLAYER_MAX_OUTPUT_PORTS   CRIATOMEXPLAYER_MAX_ASR_RACKS
	Maximum number of output ports that can be specified per player 更多...
#define	criAtomExPlayer_SetDefaultConfig(p_config)
	Assign the default values to the configuration structure used to create an AtomeEx Player 更多...

类型定义
typedef void(*	CriAtomExAsrBusFilterCbFunc) (void *obj, CriAtomPcmFormat format, CriSint32 num_channels, CriSint32 num_samples, void *data[])
	Waveform filter callback function 更多...
typedef enum CriAtomExVoiceAllocationMethodTag	CriAtomExVoiceAllocationMethod
	Voice allocation method 更多...
typedef struct CriAtomExPlayerConfigTag	CriAtomExPlayerConfig
	Configuration structure used when creating a player 更多...
typedef CriAtomExPlayerObj *	CriAtomExPlayerHn
	Player handle 更多...
typedef enum CriAtomExPlayerStatusTag	CriAtomExPlayerStatus
	Player status 更多...
typedef enum CriAtomExVoiceControlMethodTag	CriAtomExVoiceControlMethod
	Voice playback control method 更多...
typedef enum CriAtomExSpeakerIdTag	CriAtomExSpeakerId
	Speaker ID 更多...
typedef CriUint32	CriAtomExPlaybackId
	Playback ID 更多...
typedef void(*	CriAtomExPlayerCbFunc) (void *obj, CriAtomExPlayerHn player)
	Player callback function type 更多...
typedef CriBool(*	CriAtomExPlaybackCbFunc) (void *obj, CriAtomExPlaybackId playback_id)
	Data request callback function 更多...
typedef void(*	CriAtomExPlayerDataRequestCbFunc) (void *obj, CriAtomExPlaybackId id, CriAtomPlayerHn player)
	Data request callback function 更多...
typedef void(*	CriAtomExPlayerFilterCbFunc) (void *obj, CriAtomExPlaybackId id, CriAtomPcmFormat format, CriSint32 num_channels, CriSint32 num_samples, void *data[])
	Waveform filter callback function 更多...
typedef void(*	CriAtomExPlayerBlockTransitionCbFunc) (void *obj, CriAtomExPlaybackId id, CriAtomExBlockIndex index)
	Block transition callback function 更多...
typedef struct CriAtomExPlaybackTrackInfoTag	CriAtomExPlaybackTrackInfo
	Info structure for playback track information
typedef void(*	CriAtomExPlayerPlaybackTrackInfoNotificationCbFunc) (void *obj, const CriAtomExPlaybackTrackInfo *info)
	Playback track information acquisition call back function 更多...
typedef CriBool(*	CriAtomExPlayerPanCbFunc) (void *object, CriSint32 input_channels, CriAtomChannelConfig channel_config, CriSint32 output_channels, CriAtomSpeakerMapping speaker_mapping, const CriAtomExSphericalCoordinates *location, const CriAtomEx3dAttenuationParameter *parameter, CriFloat32 *matrix[])
	Parameter ID 更多...
typedef enum CriAtomExParameterIdTag	CriAtomExParameterId
	Parameter ID 更多...

枚举
enum	CriAtomExVoiceAllocationMethodTag { CRIATOMEX_ALLOCATE_VOICE_ONCE = 0 , CRIATOMEX_RETRY_VOICE_ALLOCATION , CRIATOMEX_VOICE_ALLOCATION_METHOD_IS_4BYTE = 0x7FFFFFFF }
	Voice allocation method 更多...
enum	CriAtomExPlayerStatusTag {   CRIATOMEXPLAYER_STATUS_STOP = 0 , CRIATOMEXPLAYER_STATUS_PREP , CRIATOMEXPLAYER_STATUS_PLAYING , CRIATOMEXPLAYER_STATUS_PLAYEND ,   CRIATOMEXPLAYER_STATUS_ERROR , CRIATOMEXPLAYER_STATUS_ENUM_SIZE_IS_4BYTES = 0x7FFFFFFF }
	Player status 更多...
enum	CriAtomExVoiceControlMethodTag { CRIATOMEX_PREFER_LAST = 0 , CRIATOMEX_PREFER_FIRST = 1 , CRIATOMEX_PREFER_DATA = 2 , CRIATOMEX_CONTROL_METHOD_ENUM_SIZE_IS_4BYTES = 0x7FFFFFFF }
	Voice playback control method 更多...
enum	CriAtomExSpeakerIdTag {   CRIATOMEX_SPEAKER_FRONT_LEFT = 0 , CRIATOMEX_SPEAKER_FRONT_RIGHT = 1 , CRIATOMEX_SPEAKER_FRONT_CENTER = 2 , CRIATOMEX_SPEAKER_LOW_FREQUENCY = 3 ,   CRIATOMEX_SPEAKER_SURROUND_LEFT = 4 , CRIATOMEX_SPEAKER_SURROUND_RIGHT = 5 , CRIATOMEX_SPEAKER_SURROUND_BACK_LEFT = 6 , CRIATOMEX_SPEAKER_SURROUND_BACK_RIGHT = 7 ,   CRIATOMEX_SPEAKER_ENUM_SIZE_IS_4BYTES = 0x7FFFFFFF }
	Speaker ID 更多...
enum	CriAtomExParameterIdTag {   CRIATOMEX_PARAMETER_ID_VOLUME = 0 , CRIATOMEX_PARAMETER_ID_PITCH = 1 , CRIATOMEX_PARAMETER_ID_PAN3D_ANGLE = 2 , CRIATOMEX_PARAMETER_ID_PAN3D_DISTANCE = 3 ,   CRIATOMEX_PARAMETER_ID_PAN3D_VOLUME = 4 , CRIATOMEX_PARAMETER_ID_PAN_TYPE = 5 , CRIATOMEX_PARAMETER_ID_PAN_SPEAKER_TYPE = 6 , CRIATOMEX_PARAMETER_ID_PAN_CH0 = 7 ,   CRIATOMEX_PARAMETER_ID_PAN_CH1 = 8 , CRIATOMEX_PARAMETER_ID_BUS_SEND_LEVEL_0 = 9 , CRIATOMEX_PARAMETER_ID_BUS_SEND_LEVEL_1 = 10 , CRIATOMEX_PARAMETER_ID_BUS_SEND_LEVEL_2 = 11 ,   CRIATOMEX_PARAMETER_ID_BUS_SEND_LEVEL_3 = 12 , CRIATOMEX_PARAMETER_ID_BUS_SEND_LEVEL_4 = 13 , CRIATOMEX_PARAMETER_ID_BUS_SEND_LEVEL_5 = 14 , CRIATOMEX_PARAMETER_ID_BUS_SEND_LEVEL_6 = 15 ,   CRIATOMEX_PARAMETER_ID_BUS_SEND_LEVEL_7 = 16 , CRIATOMEX_PARAMETER_ID_BANDPASS_FILTER_COF_LOW = 17 , CRIATOMEX_PARAMETER_ID_BANDPASS_FILTER_COF_HIGH = 18 , CRIATOMEX_PARAMETER_ID_BIQUAD_FILTER_TYPE = 19 ,   CRIATOMEX_PARAMETER_ID_BIQUAD_FILTER_FREQ = 20 , CRIATOMEX_PARAMETER_ID_BIQUAD_FILTER_Q = 21 , CRIATOMEX_PARAMETER_ID_BIQUAD_FILTER_GAIN = 22 , CRIATOMEX_PARAMETER_ID_ENVELOPE_ATTACK_TIME = 23 ,   CRIATOMEX_PARAMETER_ID_ENVELOPE_HOLD_TIME = 24 , CRIATOMEX_PARAMETER_ID_ENVELOPE_DECAY_TIME = 25 , CRIATOMEX_PARAMETER_ID_ENVELOPE_RELEASE_TIME = 26 , CRIATOMEX_PARAMETER_ID_ENVELOPE_SUSTAIN_LEVEL = 27 ,   CRIATOMEX_PARAMETER_ID_START_TIME = 28 , CRIATOMEX_PARAMETER_ID_PRIORITY = 31 , CRIATOMEX_PARAMETER_ID_SILENT_MODE = 32 , CRIATOMEX_PARAMETER_ID_DSP_PARAMETER_0 = 33 ,   CRIATOMEX_PARAMETER_ID_DSP_PARAMETER_1 = 34 , CRIATOMEX_PARAMETER_ID_DSP_PARAMETER_2 = 35 , CRIATOMEX_PARAMETER_ID_DSP_PARAMETER_3 = 36 , CRIATOMEX_PARAMETER_ID_DSP_PARAMETER_4 = 37 ,   CRIATOMEX_PARAMETER_ID_DSP_PARAMETER_5 = 38 , CRIATOMEX_PARAMETER_ID_DSP_PARAMETER_6 = 39 , CRIATOMEX_PARAMETER_ID_DSP_PARAMETER_7 = 40 , CRIATOMEX_PARAMETER_ID_DSP_PARAMETER_8 = 41 ,   CRIATOMEX_PARAMETER_ID_DSP_PARAMETER_9 = 42 , CRIATOMEX_PARAMETER_ID_DSP_PARAMETER_10 = 43 , CRIATOMEX_PARAMETER_ID_DSP_BYPASS_FLAG = 44 , CRIATOMEX_PARAMETER_ID_ENUM_SIZE_IS_4BYTES = 0x7FFFFFFF }
	Parameter ID 更多...

函数
void	criAtomExPlayer_AddOutputPort (CriAtomExPlayerHn player, CriAtomExOutputPortHn output_port)
	Adding the output port handle 更多...
void	criAtomExPlayer_RemoveOutputPort (CriAtomExPlayerHn player, CriAtomExOutputPortHn output_port)
	Removing an output port handle 更多...
void	criAtomExPlayer_ClearOutputPorts (CriAtomExPlayerHn player)
	Clearing the output port handles 更多...
void	criAtomExPlayer_AddPreferredOutputPort (CriAtomExPlayerHn player, CriAtomExOutputPortHn output_port)
	Assigning a prioritary output port handle 更多...
void	criAtomExPlayer_RemovePreferredOutputPort (CriAtomExPlayerHn player, CriAtomExOutputPortHn output_port)
	Removing the prioritary output port handle 更多...
void	criAtomExPlayer_RemovePreferredOutputPortByName (CriAtomExPlayerHn player, CriChar8 *name)
	Removing a prioritary output port handle by name 更多...
void	criAtomExPlayer_ClearPreferredOutputPorts (CriAtomExPlayerHn player)
	Clearing all the prioritary output port handles 更多...
CriSint32	criAtomExPlayer_CalculateWorkSize (const CriAtomExPlayerConfig *config)
	Calculate the size of the work buffer required to create an AtomEx player 更多...
CriAtomExPlayerHn	criAtomExPlayer_Create (const CriAtomExPlayerConfig *config, void *work, CriSint32 work_size)
	Create an AtomEx player 更多...
void	criAtomExPlayer_SetCueId (CriAtomExPlayerHn player, CriAtomExAcbHn acb_hn, CriAtomExCueId id)
	Set the sound data to play (specifying a Cue ID) 更多...
void	criAtomExPlayer_SetCueName (CriAtomExPlayerHn player, CriAtomExAcbHn acb_hn, const CriChar8 *cue_name)
	Set the sound data to play (specifying a Cue name) 更多...
void	criAtomExPlayer_SetCueIndex (CriAtomExPlayerHn player, CriAtomExAcbHn acb_hn, CriAtomExCueIndex index)
	Set the sound data to play (specifying a Cue index) 更多...
void	criAtomExPlayer_SetData (CriAtomExPlayerHn player, void *buffer, CriSint32 size)
	Set the sound data to play (specifying in-memory data) 更多...
void	criAtomExPlayer_SetFile (CriAtomExPlayerHn player, CriFsBinderHn binder, const CriChar8 *path)
	Set the sound data to play (specifying a file name) 更多...
void	criAtomExPlayer_SetContentId (CriAtomExPlayerHn player, CriFsBinderHn binder, CriSint32 id)
	Set the sound data to play (specifying a CPK content ID) 更多...
void	criAtomExPlayer_SetWaveId (CriAtomExPlayerHn player, CriAtomAwbHn awb, CriAtomExWaveId id)
	Set the wave data to play (specifying a wave data ID) 更多...
CriAtomExPlaybackId	criAtomExPlayer_Start (CriAtomExPlayerHn player)
	Start the playback 更多...
CriAtomExPlaybackId	criAtomExPlayer_Prepare (CriAtomExPlayerHn player)
	Prepare the playback 更多...
void	criAtomExPlayer_Stop (CriAtomExPlayerHn player)
	Stop the playback 更多...
void	criAtomExPlayer_StopWithoutReleaseTime (CriAtomExPlayerHn player)
	Stop the playback (ignoring release time) 更多...
void	criAtomExPlayer_StopAllPlayers (void)
	Stopping playback in all the players 更多...
void	criAtomExPlayer_StopAllPlayersWithoutReleaseTime (void)
	Stopping playback in all the players (release time ignored) 更多...
void	criAtomExPlayer_Pause (CriAtomExPlayerHn player, CriBool sw)
	Pause/resume 更多...
void	criAtomExPlayer_Resume (CriAtomExPlayerHn player, CriAtomExResumeMode mode)
	Resume 更多...
CriBool	criAtomExPlayer_IsPaused (CriAtomExPlayerHn player)
	Get the pause status 更多...
CriAtomExPlayerStatus	criAtomExPlayer_GetStatus (CriAtomExPlayerHn player)
	Get the player status 更多...
void	criAtomExPlayer_EnumeratePlaybacks (CriAtomExPlayerHn player, CriAtomExPlaybackCbFunc func, void *obj)
	Get the number of sounds currently being played back 更多...
CriSint32	criAtomExPlayer_GetNumPlaybacks (CriAtomExPlayerHn player)
	Get the number of sounds currently playing 更多...
CriAtomExPlaybackId	criAtomExPlayer_GetLastPlaybackId (CriAtomExPlayerHn player)
	Get the playback ID of the last sound played 更多...
CriSint64	criAtomExPlayer_GetTime (CriAtomExPlayerHn player)
	Get the playback time 更多...
void	criAtomExPlayer_SetFormat (CriAtomExPlayerHn player, CriAtomExFormat format)
	Specify the format of a sound 更多...
void	criAtomExPlayer_SetNumChannels (CriAtomExPlayerHn player, CriSint32 num_channels)
	Specify the number of channels of a sound 更多...
void	criAtomExPlayer_SetSamplingRate (CriAtomExPlayerHn player, CriSint32 sampling_rate)
	Specify the sampling rate of a sound 更多...
void	criAtomExPlayer_SetSoundRendererType (CriAtomExPlayerHn player, CriAtomSoundRendererType type)
	Specify the Sound renderer type 更多...
void	criAtomExPlayer_SetGroupNumber (CriAtomExPlayerHn player, CriSint32 group_no)
	Specify the group number 更多...
void	criAtomExPlayer_SetVoiceControlMethod (CriAtomExPlayerHn player, CriAtomExVoiceControlMethod method)
	Specifying a voice control method 更多...
void	criAtomExPlayer_SetVoicePoolIdentifier (CriAtomExPlayerHn player, CriAtomExVoicePoolIdentifier identifier)
	Specify the Voice Pool identifier 更多...
void	criAtomExPlayer_SetHcaMxMixerId (CriAtomExPlayerHn player, CriSint32 mixer_id)
	Specify the mixer ID for HCA-MX decoding 更多...
void	criAtomExPlayer_SetAsrRackId (CriAtomExPlayerHn player, CriSint32 rack_id)
	Specifying the ASR Rack ID 更多...
void	criAtomExPlayer_SetAsrRackIdArray (CriAtomExPlayerHn player, const CriSint32 *rack_id_array, CriSint32 num_racks)
	Specifying multiple ASR Rack IDs 更多...
void	criAtomExPlayer_SetStartTime (CriAtomExPlayerHn player, CriSint64 start_time_ms)
	Specify the playback starting position 更多...
void	criAtomExPlayer_SetSyncPlaybackId (CriAtomExPlayerHn player, CriAtomExPlaybackId playback_id)
	Setting the synchronous playback ID 更多...
void	criAtomExPlayer_SetPlaybackRatio (CriAtomExPlayerHn player, CriFloat32 playback_ratio)
	Set the sequence playback ratio 更多...
void	criAtomExPlayer_LimitLoopCount (CriAtomExPlayerHn player, CriSint32 count)
	Set the the number of loops 更多...
void	criAtomExPlayer_UpdateAll (CriAtomExPlayerHn player)
	Update the playback parameters (for all sounds currently playing) 更多...
void	criAtomExPlayer_Update (CriAtomExPlayerHn player, CriAtomExPlaybackId id)
	Update the playback parameters (specifying a playback ID) 更多...
void	criAtomExPlayer_ResetParameters (CriAtomExPlayerHn player)
	Reset the playback parameters 更多...
CriFloat32	criAtomExPlayer_GetParameterFloat32 (CriAtomExPlayerHn player, CriAtomExParameterId id)
	Get the value of a parameter (as a floating point number) 更多...
CriUint32	criAtomExPlayer_GetParameterUint32 (CriAtomExPlayerHn player, CriAtomExParameterId id)
	Get the value of a parameter (as an unsigned integer) 更多...
CriSint32	criAtomExPlayer_GetParameterSint32 (CriAtomExPlayerHn player, CriAtomExParameterId id)
	Get the value of a parameter (as a signed integer) 更多...
void	criAtomExPlayer_SetVolume (CriAtomExPlayerHn player, CriFloat32 volume)
	Set the volume 更多...
void	criAtomExPlayer_SetPitch (CriAtomExPlayerHn player, CriFloat32 pitch)
	Set the pitch (detune) 更多...
void	criAtomExPlayer_SetMaxPitch (CriAtomExPlayerHn player, CriFloat32 pitch)
	Setting the maximum pitch 更多...
void	criAtomExPlayer_SetPan3dAngle (CriAtomExPlayerHn player, CriFloat32 pan3d_angle)
	Set the panning 3D angle 更多...
void	criAtomExPlayer_SetPan3dInteriorDistance (CriAtomExPlayerHn player, CriFloat32 pan3d_interior_distance)
	Set the panning 3D distance 更多...
void	criAtomExPlayer_SetPan3dVolume (CriAtomExPlayerHn player, CriFloat32 pan3d_volume)
	Set the panning 3D volume 更多...
void	criAtomExPlayer_SetPanType (CriAtomExPlayerHn player, CriAtomExPanType pan_type)
	Set the pan type 更多...
CriAtomExPanType	criAtomExPlayer_GetPanTypeOnPlayback (CriAtomExPlayerHn player)
	Get pan type during player playback 更多...
void	criAtomExPlayer_SetPanSpeakerType (CriAtomExPlayerHn player, CriAtomExPanSpeakerType pan_speaker_type)
	Output speaker type setting when panning 更多...
void	criAtomExPlayer_AddMixDownCenterVolumeOffset (CriAtomExPlayerHn player, CriFloat32 mixdown_center_volume_offset)
	Setting MixDownCenter volume offset value 更多...
void	criAtomExPlayer_AddMixDownLfeVolumeOffset (CriAtomExPlayerHn player, CriFloat32 mixdown_lfe_volume_offset)
	Setting MixDownLFE volume offset value 更多...
void	criAtomExPlayer_ChangeDefaultPanSpeakerType (CriAtomExPanSpeakerType pan_speaker_type)
	Changing the default output speaker type for panning 更多...
void	criAtomExPlayer_OverrideDefaultPanMethod (CriAtomExPlayerPanCbFunc func, void *obj)
	Override the default panning process 更多...
void	criAtomExPlayer_SetPanAngleType (CriAtomExPlayerHn player, CriAtomExPanAngleType pan_angle_type)
	Panning angle type setting 更多...
void	criAtomExPlayer_SetWideness (CriAtomExPlayerHn player, CriFloat32 wideness)
	Set the sound spread during panning 更多...
void	criAtomExPlayer_SetSpread (CriAtomExPlayerHn player, CriFloat32 spread)
	Spread Settings 更多...
void	criAtomExPlayer_SetSendLevel (CriAtomExPlayerHn player, CriSint32 ch, CriAtomExSpeakerId spk, CriFloat32 level)
	Set a send level 更多...
void	criAtomExPlayer_SetBusSendLevelByName (CriAtomExPlayerHn player, const CriChar8 *bus_name, CriFloat32 level)
	Setting the bus send level 更多...
void	criAtomExPlayer_ResetBusSends (CriAtomExPlayerHn player)
	Resetting Bus Send Levels 更多...
CriBool	criAtomExPlayer_GetBusSendLevelByName (CriAtomExPlayerHn player, const CriChar8 *bus_name, CriFloat32 *level)
	Get Bus Send Level 更多...
void	criAtomExPlayer_SetBusSendLevelOffsetByName (CriAtomExPlayerHn player, const CriChar8 *bus_name, CriFloat32 level_offset)
	Setting the bus send level (by specifying the offset) 更多...
CriBool	criAtomExPlayer_GetBusSendLevelOffsetByName (CriAtomExPlayerHn player, const CriChar8 *bus_name, CriFloat32 *level_offset)
	Get Bus Send Level Offset 更多...
void	criAtomExPlayer_SetPanAdx1Compatible (CriAtomExPlayerHn player, CriSint32 ch, CriFloat32 pan)
	Set the ADX1-compatible panning 更多...
void	criAtomExPlayer_SetBandpassFilterParameters (CriAtomExPlayerHn player, CriFloat32 cof_low, CriFloat32 cof_high)
	Set the band pass filter parameters 更多...
void	criAtomExPlayer_SetBiquadFilterParameters (CriAtomExPlayerHn player, CriAtomExBiquadFilterType type, CriFloat32 frequency, CriFloat32 gain, CriFloat32 q_value)
	Set the biquad filter parameters 更多...
void	criAtomExPlayer_SetVoicePriority (CriAtomExPlayerHn player, CriSint32 priority)
	Set the priority 更多...
void	criAtomExPlayer_SetAisacControlById (CriAtomExPlayerHn player, CriAtomExAisacControlId control_id, CriFloat32 control_value)
	Set an AISAC control value (specifying the control ID) 更多...
void	criAtomExPlayer_SetAisacControlByName (CriAtomExPlayerHn player, const CriChar8 *control_name, CriFloat32 control_value)
	Set AISAC control value (specifying a control name) 更多...
void	criAtomExPlayer_ClearAisacControls (CriAtomExPlayerHn player)
	Clear the AISAC control values set to the player 更多...
void	criAtomExPlayer_Set3dSourceHn (CriAtomExPlayerHn player, CriAtomEx3dSourceHn source)
	Set the 3D sound source handle 更多...
void	criAtomExPlayer_Set3dSourceListHn (CriAtomExPlayerHn player, CriAtomEx3dSourceListHn source_list)
	Assign a 3D sound source handle list to a player 更多...
void	criAtomExPlayer_Set3dListenerHn (CriAtomExPlayerHn player, CriAtomEx3dListenerHn listener)
	Set the 3D listener handle 更多...
CriFloat32	criAtomExPlayer_GetAisacControlById (CriAtomExPlayerHn player, CriAtomExAisacControlId control_id)
	Get an AISAC control value (specifying the control ID) 更多...
CriFloat32	criAtomExPlayer_GetAisacControlByName (CriAtomExPlayerHn player, const CriChar8 *control_name)
	Get an AISAC control value (specifying the control name) 更多...
void	criAtomExPlayer_SetCategoryById (CriAtomExPlayerHn player, CriUint32 category_id)
	Set the category (specifying its ID) 更多...
void	criAtomExPlayer_SetCategoryByName (CriAtomExPlayerHn player, const CriChar8 *category_name)
	Set the category (specifying its name) 更多...
void	criAtomExPlayer_UnsetCategory (CriAtomExPlayerHn player)
	Remove a category 更多...
CriSint32	criAtomExPlayer_GetNumCategories (CriAtomExPlayerHn player)
	Acquiring the number of categories 更多...
CriBool	criAtomExPlayer_GetCategoryInfo (CriAtomExPlayerHn player, CriUint16 index, CriAtomExCategoryInfo *info)
	Acquiring category information (by specifying an index) 更多...
void	criAtomExPlayer_SetTrackInfo (CriAtomExPlayerHn player, CriSint32 num_tracks, const CriSint32 *channels_per_track)
	Set the track information 更多...
void	criAtomExPlayer_SetTrackVolume (CriAtomExPlayerHn player, CriSint32 track_no, CriFloat32 volume)
	Set the track volume 更多...
void	criAtomExPlayer_SetSilentMode (CriAtomExPlayerHn player, CriAtomExSilentMode silent_mode)
	Set the silence-handling mode 更多...
void	criAtomExPlayer_SetCuePriority (CriAtomExPlayerHn player, CriSint32 cue_priority)
	Set the Cue priority 更多...
void	criAtomExPlayer_SetPreDelayTime (CriAtomExPlayerHn player, CriFloat32 predelay_time_ms)
	Setting the pre-delay time 更多...
void	criAtomExPlayer_SetEnvelopeAttackTime (CriAtomExPlayerHn player, CriFloat32 attack_time_ms)
	Set the attack time of the envelope 更多...
void	criAtomExPlayer_SetEnvelopeAttackCurve (CriAtomExPlayerHn player, CriAtomExCurveType curve_type, CriFloat32 strength)
	Setting the Envelope Attack Curve 更多...
void	criAtomExPlayer_SetEnvelopeHoldTime (CriAtomExPlayerHn player, CriFloat32 hold_time_ms)
	Setting the envelope hold time 更多...
void	criAtomExPlayer_SetEnvelopeDecayTime (CriAtomExPlayerHn player, CriFloat32 decay_time_ms)
	Set the decay time of the envelope 更多...
void	criAtomExPlayer_SetEnvelopeDecayCurve (CriAtomExPlayerHn player, CriAtomExCurveType curve_type, CriFloat32 strength)
	Setting the Envelope Decay Curve 更多...
void	criAtomExPlayer_SetEnvelopeReleaseTime (CriAtomExPlayerHn player, CriFloat32 release_time_ms)
	Setting the envelope release time 更多...
void	criAtomExPlayer_SetEnvelopeReleaseCurve (CriAtomExPlayerHn player, CriAtomExCurveType curve_type, CriFloat32 strength)
	Setting the envelope release curve 更多...
void	criAtomExPlayer_SetEnvelopeSustainLevel (CriAtomExPlayerHn player, CriFloat32 susutain_level)
	Setting the envelope sustain level 更多...
void	criAtomExPlayer_SetDataRequestCallback (CriAtomExPlayerHn player, CriAtomExPlayerDataRequestCbFunc func, void *obj)
	Register the data request callback function 更多...
void	criAtomExPlayer_SetFilterCallback (CriAtomExPlayerHn player, CriAtomExPlayerFilterCbFunc func, void *obj)
	Register the wave filter callback function 更多...
void	criAtomExPlayer_SetRandomSeed (CriAtomExPlayerHn player, CriUint32 seed)
	Set the random number seed 更多...
void	criAtomExPlayer_SetDspParameter (CriAtomExPlayerHn player, CriSint32 param_id, CriFloat32 param_val)
	Set a DSP parameter 更多...
void	criAtomExPlayer_SetDspBypass (CriAtomExPlayerHn player, CriBool is_bypassed)
	Set a DSP parameter 更多...
void	criAtomExPlayer_AttachAisac (CriAtomExPlayerHn player, const CriChar8 *global_aisac_name)
	Attach a global AISAC to a player 更多...
void	criAtomExPlayer_DetachAisac (CriAtomExPlayerHn player, const CriChar8 *global_aisac_name)
	Detach an AISAC from the player 更多...
void	criAtomExPlayer_DetachAisacAll (CriAtomExPlayerHn player)
	Detach all the AISACs from a player 更多...
CriSint32	criAtomExPlayer_GetNumAttachedAisacs (CriAtomExPlayerHn player)
	Get the number of AISACs attached to a player 更多...
CriBool	criAtomExPlayer_GetAttachedAisacInfo (CriAtomExPlayerHn player, CriSint32 aisac_attached_index, CriAtomExAisacInfo *aisac_info)
	Get information on a specific AISAC attached to a player 更多...
void	criAtomExPlayer_SetStreamingCacheId (CriAtomExPlayerHn player, CriAtomExStreamingCacheId cache_id)
	Set the streaming cache for player 更多...
void	criAtomExPlayer_AttachTween (CriAtomExPlayerHn player, CriAtomExTweenHn tween)
	Attach a Tween to a player 更多...
void	criAtomExPlayer_DetachTween (CriAtomExPlayerHn player, CriAtomExTweenHn tween)
	Detach a Tween from a player 更多...
void	criAtomExPlayer_DetachTweenAll (CriAtomExPlayerHn player)
	Detach all Tweens from a player 更多...
void	criAtomExPlayer_SetFirstBlockIndex (CriAtomExPlayerHn player, CriAtomExBlockIndex index)
	Set the start block (by specifying a block index) 更多...
void	criAtomExPlayer_SetBlockTransitionCallback (CriAtomExPlayerHn player, CriAtomExPlayerBlockTransitionCbFunc func, void *obj)
	Register the block transition callback function 更多...
CriAtomExSoundObjectHn	criAtomExPlayer_GetSoundObject (CriAtomExPlayerHn player)
	Acquire a sound object 更多...
void	criAtomExPlayer_SetDrySendLevel (CriAtomExPlayerHn player, CriAtomExSpeakerId spk, CriFloat32 offset, CriFloat32 gain)
	Set the dry send level (for compatibility with CRI Audio) 更多...
void	criAtomExPlayer_SetSelectorLabel (CriAtomExPlayerHn player, const CriChar8 *selector, const CriChar8 *label)
	Set selector information to the player 更多...
void	criAtomExPlayer_UnsetSelectorLabel (CriAtomExPlayerHn player, const CriChar8 *selector)
	Deleting the selector information set in the player 更多...
void	criAtomExPlayer_ClearSelectorLabels (CriAtomExPlayerHn player)
	Clear the selector information set to the player 更多...
void	criAtomExPlayer_SetPlaybackTrackInfoNotificationCallback (CriAtomExPlayerHn player, CriAtomExPlayerPlaybackTrackInfoNotificationCbFunc func, void *obj)
	Registering playback track number notification callback function 更多...
void	criAtomExPlayer_SetPlaybackEventCallback (CriAtomExPlayerHn player, CriAtomExPlaybackEventCbFunc func, void *obj)
	Registration of playback event callback 更多...
void	criAtomExPlayer_SetChannelConfig (CriAtomExPlayerHn player, CriSint32 num_channels, CriAtomChannelConfig channel_config)
	Specify the channel configuration of the input audio 更多...

详细描述

宏定义说明

CRIATOMEXPLAYER_NO_GROUP_LIMITATION

#define CRIATOMEXPLAYER_NO_GROUP_LIMITATION   (-1)

No group limitation

Description:

This constant is used to cancel any limitation by a Voice Limit Group.
When this value is passed to the criAtomExPlayer_SetGroupNumber function, the specified player will not be restricted by the Voice Limit Group.
(Whenever there is an empty voice or a voice with a lower priority, the player will acquire the voice regardless of the Voice Limit Group.)

参见

criAtomExPlayer_SetGroupNumber

CRIATOMEXPLAYER_NO_LOOP_LIMITATION

#define CRIATOMEXPLAYER_NO_LOOP_LIMITATION   (CRIATOMPLAYER_NO_LOOP_LIMITATION)

Constants used to cancel a fixed number of repetitions for the loops

Description:

No limit of loop count

CRIATOMEXPLAYER_MAX_ASR_RACKS

#define CRIATOMEXPLAYER_MAX_ASR_RACKS   (8)

Maximum number of ASR racks that can be specified for the player

Description:

The maximum number of ASR racks that can be specified for one player.

参见

criAtomExPlayer_SetAsrRackIdArray

CRIATOMEXPLAYER_MAX_OUTPUT_PORTS

#define CRIATOMEXPLAYER_MAX_OUTPUT_PORTS   CRIATOMEXPLAYER_MAX_ASR_RACKS

Maximum number of output ports that can be specified per player

Description:

The maximum number of output ports that can be specified per player.

参见

criAtomExPlayer_AddOutputPort, criAtomExPlayer_AddPreferredOutputPort

criAtomExPlayer_SetDefaultConfig

#define criAtomExPlayer_SetDefaultConfig

(

p_config

)

值:

{\
    (p_config)->voice_allocation_method = CRIATOMEX_ALLOCATE_VOICE_ONCE;\
    (p_config)->max_path_strings = 1;\
    (p_config)->max_path = 0;\
    (p_config)->updates_time = CRI_TRUE;\
    (p_config)->enable_audio_synced_timer = CRI_FALSE;\
    (p_config)->max_aisacs = 8;\
}

Assign the default values to the configuration structure used to create an AtomeEx Player

参数

[out]

p_config

pointer to the configuration structure used for the creation of an AtomEx Player

Description:

Assigns the default values to the configuration structure ( CriAtomExPlayerConfig ) that is passed to the criAtomExPlayer_Create function.

参见

CriAtomExPlayerConfig, criAtomExPlayer_Create

类型定义说明

CriAtomExAsrBusFilterCbFunc

typedef void(* CriAtomExAsrBusFilterCbFunc) (void *obj, CriAtomPcmFormat format, CriSint32 num_channels, CriSint32 num_samples, void *data[])

Waveform filter callback function

Description:

参数

[in]	obj	user specified object
[in]	format	format of PCM
[in]	num_channels	number of channels
[in]	num_samples	number of samples
[in,out]	data	channel array for PCM data

返回

NONE

Description:

This is the callback function that receives PCM data, and it can be assigned to a bus.

Use the criAtomExAsr_SetBusFilterCallback function to register a callback function.
By registering a callback function, every time sound renderer performs audio processing, the callback function is executed.

The format and number of channels of PCM data, the number of samples that can be referenced, and the address of the area in which the PCM data is stored are returned to the filter callback function.
In the callback function, values of PCM data can be referenced directly, and therefore, the callback function can be used for checking the amplitude of a playback sound.

Also, when PCM data is modified in the callback function, the modification is reflected in playback sounds, and it is possible to apply a user-own effect to PCM data.
(However, modifications such as a time-stretching process that will change the amount of data cannot be performed.)

Remarks:

PCM data consists of data separated for each channel.
(The data are not interleaved.)
In the sixth argument (data array), the first address of PCM data array for each channel is stored.
(It is not the first address of an two-dimensional array, but a one-dimensional pointer array that stores the first address of PCM data array for each channel.)
The stored PCM data is audio data processed by the effect specified in a bus.

The format of PCM data varies depending on each platform.
The data format of the execution environment can be identified by the third argument (format).
If the format of PCM data is a 16-bit integer type, format is CRIATOM_PCM_FORMAT_SINT16. If the format of PCM data is a 32-bit floating-point type, format is CRIATOM_PCM_FORMAT_FLOAT32.
Note that the range of PCM data depends on each format.

• For CRIATOM_PCM_FORMAT_SINT16 , the range is -32768 to +32767
• For CRIATOM_PCM_FORMAT_FLOAT32 , the range is -1.0f to +1.0f

(Depending on the mixing of multiplex sounds or the effects mentioned above, a value that exceeds the above ranges may occur.)

注意

Do not execute Atom library APIs in this callback function.
The callback function is executed from the server process in the Atom library.
Therefore, if an API that does not take account of interrupts to the server process is executed, an error or deadlock may occur.

If processes are blocked in the callback function for a long time, some problems such as a playback break may occur.

参见

criAtomExAsr_SetBusFilterCallback

CriAtomExVoiceAllocationMethod

typedef enum CriAtomExVoiceAllocationMethodTag CriAtomExVoiceAllocationMethod

Voice allocation method

Description:

Data type used to specify how an AtomEx Player allocates voices.
The voice allocation method is set in the CriAtomExPlayerConfig structure used when creating an AtomEx Player.

参见

CriAtomExPlayerConfig, criAtomExPlayer_Create

CriAtomExPlayerConfig

typedef struct CriAtomExPlayerConfigTag CriAtomExPlayerConfig

Configuration structure used when creating a player

Description:

Configuration structure used when creating an AtomEx Player.
It is passed to the criAtomExPlayer_Create function.

When the player is created, internal resources are allocated based on the values of the parameters in this configuration structure.
In particular, the size of the work buffer needed for the player depends on the parameters set in the structure.

注意

More members will be added in the future, so if you are not using the criAtomExPlayer_SetDefaultConfig macro, make sure to initialize the whole structure to zero before using it.
(Make sure that no member of the structure has an undefined value.)

参见

criAtomExPlayer_Create, criAtomExPlayer_SetDefaultConfig

CriAtomExPlayerHn

typedef CriAtomExPlayerObj* CriAtomExPlayerHn

Player handle

Description:

Handle used to reference a player created for audio playback across the application.
When the criAtomExPlayer_Create function is called, it returns as AtomEx player handle.
All playback-related operations (such as setting the audio data to play, starting playing and acquiring the status of the playback) are performed through an AtomEx player handle.

参见

criAtomExPlayer_Create

CriAtomExPlayerStatus

typedef enum CriAtomExPlayerStatusTag CriAtomExPlayerStatus

Player status

Description:

This enumeration defines the various playback statuses of an AtomEx Player.
The playback status can be acquired by using the criAtomExPlayer_GetStatus function.

Usually, the playback status of an AtomEx Player changes in the following order.

1. CRIATOMEXPLAYER_STATUS_STOP
2. CRIATOMEXPLAYER_STATUS_PREP
3. CRIATOMEXPLAYER_STATUS_PLAYING
4. CRIATOMEXPLAYER_STATUS_PLAYEND

Immediately after an AtomEx Player is created, it is set to the stop status (CRIATOMEXPLAYER_STATUS_STOP).
By setting the data to play using a function such as criAtomExPlayer_SetData and calling criAtomExPlayer_Start , the player's status changes to (CRIATOMEXPLAYER_STATUS_PREP) and starts preparing for the playback.
Once a sufficient amount of data has been provided and the playback is ready, the player status changes to (CRIATOMEXPLAYER_STATUS_PLAYING) and the audio playback starts.
When all the audio data has been played, the player status changes to (CRIATOMEXPLAYER_STATUS_PLAYEND).

Remarks:

Unlike an Atom Player, a single AtomEx Player can play back multiple sounds.
Therefore, by executing the criAtomExPlayer_Start function on a currently used AtomEx Player, two sounds are played back overlapping each other.
When the criAtomExPlayer_Stop function is executed during playback, all sounds being played back on the AtomEx Player are stopped, and the status returns to CRIATOMEXPLAYER_STATUS_STOP.
(Depending on when the criAtomExPlayer_Stop function was called, it may take time to change the status to CRIATOMEXPLAYER_STATUS_STOP.)

When the criAtomExPlayer_Start function is executed multiple times on a single AtomEx Player, if any sound is in preparation for the playback, the status becomes CRIATOMEXPLAYER_STATUS_PREP.
(Only after all sounds have started to play is the status changed to CRIATOMEXPLAYER_STATUS_PLAYING.)
Also, when the status of the player is CRIATOMEXPLAYER_STATUS_PLAYING and the criAtomExPlayer_Start function is executed again, the status temporarily returns to CRIATOMEXPLAYER_STATUS_PREP.

During playback, if invalid audio data is read or the file access has failed, the status is changed to CRIATOMEXPLAYER_STATUS_ERROR.
While multiple sounds are being played back, if an error occurs on a sound, the status of the player is changed to CRIATOMEXPLAYER_STATUS_ERROR, regardless of the status of the other sounds.

参见

criAtomExPlayer_GetStatus, criAtomExPlayer_SetData, criAtomExPlayer_Start, criAtomExPlayer_Stop

CriAtomExVoiceControlMethod

typedef enum CriAtomExVoiceControlMethodTag CriAtomExVoiceControlMethod

Voice playback control method

Description:

This is a data type for specifying how to control the pronunciation of audio played in the AtomEx player.
Used with the criAtomExPlayer_SetVoiceControlMethod function.

参见

criAtomExPlayer_SetVoiceControlMethod

CriAtomExSpeakerId

typedef enum CriAtomExSpeakerIdTag CriAtomExSpeakerId

Speaker ID

Description:

This ID is used to specify the speaker that will output audio.
Used with the criAtomExPlayer_SetSendLevel function.

参见

criAtomExPlayer_SetSendLevel

CriAtomExPlaybackId

typedef CriUint32 CriAtomExPlaybackId

Playback ID

Description:

This is the ID returned by the criAtomExPlayer_Start function.
If you want to change parameters or get the status of individual sounds played by the criAtomExPlayer_Start function, rather than on a per-player basis, you must use this ID to control them.
An invalid playback ID is represented by CRIATOMEX_INVALID_PLAYBACK_ID .

参见

criAtomExPlayer_Start, criAtomExPlayback_GetStatus, CRIATOMEX_INVALID_PLAYBACK_ID

CriAtomExPlayerCbFunc

typedef void( * CriAtomExPlayerCbFunc) (void *obj, CriAtomExPlayerHn player)

Player callback function type

参数

[in]	obj	User specified object
[in]	player	AtomEx player

Description:

This is the type of the callback function that is used to enumerate players.
By registering a callback function of this function type for the criAtomExPlayer_EnumeratePlayers function, you can receive a player that was created in the application in a callback.

注意

Do not destroy the AtomEx player passed as an argument.
(Serious problems, such as an access violation and hang-up may occur.)

Note that if processes are blocked in the callback function for a long time, some problems, such as a playback interruption may occur.

参见

criAtomExPlayer_EnumeratePlayers

CriAtomExPlaybackCbFunc

typedef CriBool( * CriAtomExPlaybackCbFunc) (void *obj, CriAtomExPlaybackId playback_id)

Data request callback function

参数

[in]	obj	User-specified objects
[in]	playback_id	Playback ID

返回

CriBool Whether to continue enumeration (CRI_TRUE: continue, CRI_FALSE: stop)

Description:

The type of callback function used for enumerating playbacks.
By registering this function type callback function to the criAtomExPlayer_EnumeratePlaybacks function, you can receive the playback ID currently being played on the player via callback.

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

参见

criAtomExPlayer_EnumeratePlaybacks

CriAtomExPlayerDataRequestCbFunc

typedef void( * CriAtomExPlayerDataRequestCbFunc) (void *obj, CriAtomExPlaybackId id, CriAtomPlayerHn player)

Data request callback function

Description:

参数

[in]	obj	user-specified object
[in]	id	playback ID
[in]	player	Atom player handle

返回

none

Description:

This callback function is used to specify the next block of data to be played back.
It is used for seamless playback of multiple audio buffers.

Use the criAtomExPlayer_SetDataRequestCallback function to register this callback function.
The registered callback function is executed when data for seamless playback is requested by an Atom Player (used internally by a voice).
(The callback function is executed when the previous buffer has been completely loaded and the next buffer to be played is requested.)

When a function such as criAtomPlayer_SetData is used to set data to an Atom player within a callback function, that data can be played back seamlessly after the data currently being played .
Furthermore, executing the criAtomPlayer_SetPreviousDataAgain function within this function will allow the same data to be played back repeatedly.

Remarks:

If no data is specified in this function, when the playback of the current data is complete, the status of the AtomEx Player is switched to CRIATOMEXPLAYER_STATUS_PLAYEND.

When you cannot specify data due to a problem of timing but you do not want to switch the status to CRIATOMEXPLAYER_STATUS_PLAYEND , execute the criAtomPlayer_DeferCallback function in the callback function.
By executing the criAtomPlayer_DeferCallback function, the data request callback function is invoked again about 1V later. (The callback process can be retried.)
However, if the criAtomPlayer_DeferCallback function is executed, audio breakup may occur during playback (i.e. the playback is silent for a certain time bewteen the two audio buffers).

注意

Note that the third argument (player) in this callback is not an AtomEx Player, but an Atom Player from the lower layer.
(If it is casted to an AtomExPlayerHn, serious problems such as an access violation will occur.)

If a Cue containing multiple waveforms is being played back, the callback function is executed for the first waveform whose data has finished to play.
Therefore, if concatenated playback is performed for a Cue containing multiple waveforms, an unintended combination of audio buffers may happen during the concatenation.
When using this function, please play a cue that contains only one waveform data, or play a file, on-memory data, etc.

Currently, callbacks are only allocated to voices that have begun waveform data playback.
Therefore, the callback will not be executed if a voice is virtualized.
(When the end of the data is reached, the callback will not be executed and the status will be change to PLAYEND.)

Do not perform anything else than seamless concatenated playback within this callback function.
The callback function is executed from the server process in the Atom library.
Therefore, if an API that does not take into account the interrupts to the server process is executed, an error or deadlock may occur.

The APIs that can be executed in a callback function are:

• criAtomExAcb_GetWaveformInfoById (NULL cannot be specified for the argument)
• criAtomExAcb_GetWaveformInfoByName (NULL cannot be specified for the argument)
• criAtomExAcb_GetOnMemoryAwbHandle
• criAtomExAcb_GetStreamingAwbHandle
• criAtomPlayer_SetData
• criAtomPlayer_SetFile
• criAtomPlayer_SetContentId
• criAtomPlayer_SetWaveId
• criAtomPlayer_SetPreviousDataAgain
• criAtomPlayer_DeferCallback

Note that if the process is blocked in the callback function for a long time, problems -such as the audio breaking up- may occur.

参见

criAtomExPlayer_SetDataRequestCallback, criAtomPlayer_SetData, criAtomPlayer_SetPreviousDataAgain, criAtomPlayer_DeferCallback

CriAtomExPlayerFilterCbFunc

typedef void( * CriAtomExPlayerFilterCbFunc) (void *obj, CriAtomExPlaybackId id, CriAtomPcmFormat format, CriSint32 num_channels, CriSint32 num_samples, void *data[])

Waveform filter callback function

Description:

参数

[in]	obj	user-specified object
[in]	id	playback ID
[in]	format	format of PCM
[in]	num_channels	number of channels
[in]	num_samples	number of samples
	[in/out]	data channel array for PCM data

返回

NONE

Description:

Callback function to receive decoded PCM data.

Call criAtomExPlayer_SetFilterCallback to register this callback function.
Then, every time a voice will decode audio data, this callback function will be executed.

The format and number of channels of PCM data, the number of samples that can be referenced, as well as the address of the buffer in which the PCM data is stored are all passed to the filter callback function.
In the callback function, the PCM data can be referenced directly. Therefore, it can be used to check the amplitude of a sound being played back.

Also, any modification of the PCM data in the callback function is reflected in the sound playback, making it possible to apply user effects to the PCM data.
(However, modifications such as time-stretching that change the amount of data cannot be performed.)

Remarks:

The PCM data is separated by channel.
(i.e the data is not interleaved.)
In the sixth argument (data array), the first address of PCM data array for each channel is stored.
(It is not the first address of a two-dimensional array, but a one-dimensional pointer array that stores the first address of the PCM data array for each channel.)

The format of the PCM data depends on the platform.
It can be identified by the third argument (format).
If a sample is coded on a 16-bit integer, the PCM data format is CRIATOM_PCM_FORMAT_SINT16. If a sample is coded on a 32-bit float, the PCM data format is CRIATOM_PCM_FORMAT_FLOAT32.
Note that the range of the valid values depends on the format:

• For CRIATOM_PCM_FORMAT_SINT16, the range is -32768 to +32767
• For CRIATOM_PCM_FORMAT_FLOAT32, the range is -1.0f to +1.0f

(Since clipping is not performed during the decoding, when the format is CRIATOM_PCM_FORMAT_FLOAT32, a value that slightly exceeds the range may be generated.)

注意

Do not execute any Atom library APIs within this callback function.
The callback function is executed from the server process in the Atom library.
Therefore, if an API that does not take into account the interrupts to the server process is executed, an error or deadlock may occur.

Note that if the process is blocked in the callback function for a long time, problems -such as the audio breaking up- may occur.

参见

criAtomExPlayer_SetFilterCallback

CriAtomExPlayerBlockTransitionCbFunc

typedef void( * CriAtomExPlayerBlockTransitionCbFunc) (void *obj, CriAtomExPlaybackId id, CriAtomExBlockIndex index)

Block transition callback function

Description:

参数

[in]	obj	user-specified object
[in]	id	playback ID
[in]	index	block index within a Cue

返回

none

Description:

Callback function that is called when a block transition occurs during the playback of a block sequence.

Call criAtomExPlayer_SetBlockTransitionCallback to register the callback function.
After registering the callback function, each time a block transition occurs, the callback function is executed.

注意

Do not execute any Atom library APIs within this callback function.
The callback function is executed from the server process in the Atom library.
Therefore, if an API that does not take into account the interrupts to the server process is executed, an error or deadlock may occur.

Note that if the process is blocked in the callback function for a long time, problems -such as the audio breaking up- may occur.

参见

criAtomExPlayer_SetBlockTransitionCallback

CriAtomExPlayerPlaybackTrackInfoNotificationCbFunc

typedef void( * CriAtomExPlayerPlaybackTrackInfoNotificationCbFunc) (void *obj, const CriAtomExPlaybackTrackInfo *info)

Playback track information acquisition call back function

Description:

参数

[in]	obj	User specified object
[in]	info	Playback track information

返回

なし

Description:

This is a callback function that notifies track information played back when playing a cue other than polyphonic type.

Use the criAtomExPlayer_SetPlaybackTrackInfoNotificationCallback function to register the callback function.

注意

Do not execute the Atom library APIs within this callback function.
The callback function is executed from the server process in the Atom library.
Therefore, if you execute an API that does not consider interrupts to server processing, errors may occur or deadlock may occur.

If block long processing within the callback function, problems such as out of sound may occur.

参见

criAtomExPlayer_SetPlaybackTrackInfoNotificationCallback

CriAtomExPlayerPanCbFunc

typedef CriBool( * CriAtomExPlayerPanCbFunc) (void *object, CriSint32 input_channels, CriAtomChannelConfig channel_config, CriSint32 output_channels, CriAtomSpeakerMapping speaker_mapping, const CriAtomExSphericalCoordinates *location, const CriAtomEx3dAttenuationParameter *parameter, CriFloat32 *matrix[])

Parameter ID

参数

[in]	object	User-specified objects
[in]	input_channels	Number of input audio channels
[in]	channel_config	Input audio channel configuration
[in]	output_channels	Number of output channels
[in]	speaker_mapping	Destination speaker mapping
[in]	location	Location information of the sound source
[in]	parameter	Distance attenuation parameter
[out]	matrix	Send Level Matrix

返回

CriBool Did you do your own panning

Description:

This is the type of the callback function for panning.
You can register a callback function by executing the criAtomExPlayer_OverrideDefaultPanMethod function.
This callback function is called during panning.
Use this if you want to perform your own panning process on the application side.

Additional information:

When the callback function is called, the send level matrix is cleared to zero. Therefore, there is no need to clear the send level matrix to zero within the callback function.

If the send level matrix is manipulated on the application side, the function must return CRI_TRUE.
If CRI_FALSE is returned, the send level specified within the callback will be ignored, and the default panning process of the Atom library will be applied.
(If you need to switch between the default panning process and your own panning process, for example to perform your own panning process only on audio with a specific number of channels, use the return value to control this.)

注意

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

参见

criAtomExPlayer_OverrideDefaultPanMethod

CriAtomExParameterId

typedef enum CriAtomExParameterIdTag CriAtomExParameterId

Parameter ID

Description:

This is the ID for specifying parameters.
It is used in functions such as criAtomExPlayer_GetParameterFloat32 .

参见

criAtomExPlayer_GetParameterFloat32, criAtomExPlayer_GetParameterSint32, criAtomExPlayer_GetParameterUint32

枚举类型说明

CriAtomExVoiceAllocationMethodTag

enum CriAtomExVoiceAllocationMethodTag

Voice allocation method

Description:

Data type used to specify how an AtomEx Player allocates voices.
The voice allocation method is set in the CriAtomExPlayerConfig structure used when creating an AtomEx Player.

参见

CriAtomExPlayerConfig, criAtomExPlayer_Create

枚举值
CRIATOMEX_ALLOCATE_VOICE_ONCE	Voice allocation is performed only once
CRIATOMEX_RETRY_VOICE_ALLOCATION	Voice allocation is performed repeatedly

CriAtomExPlayerStatusTag

enum CriAtomExPlayerStatusTag

Player status

Description:

This enumeration defines the various playback statuses of an AtomEx Player.
The playback status can be acquired by using the criAtomExPlayer_GetStatus function.

Usually, the playback status of an AtomEx Player changes in the following order.

1. CRIATOMEXPLAYER_STATUS_STOP
2. CRIATOMEXPLAYER_STATUS_PREP
3. CRIATOMEXPLAYER_STATUS_PLAYING
4. CRIATOMEXPLAYER_STATUS_PLAYEND

Immediately after an AtomEx Player is created, it is set to the stop status (CRIATOMEXPLAYER_STATUS_STOP).
By setting the data to play using a function such as criAtomExPlayer_SetData and calling criAtomExPlayer_Start , the player's status changes to (CRIATOMEXPLAYER_STATUS_PREP) and starts preparing for the playback.
Once a sufficient amount of data has been provided and the playback is ready, the player status changes to (CRIATOMEXPLAYER_STATUS_PLAYING) and the audio playback starts.
When all the audio data has been played, the player status changes to (CRIATOMEXPLAYER_STATUS_PLAYEND).

Remarks:

Unlike an Atom Player, a single AtomEx Player can play back multiple sounds.
Therefore, by executing the criAtomExPlayer_Start function on a currently used AtomEx Player, two sounds are played back overlapping each other.
When the criAtomExPlayer_Stop function is executed during playback, all sounds being played back on the AtomEx Player are stopped, and the status returns to CRIATOMEXPLAYER_STATUS_STOP.
(Depending on when the criAtomExPlayer_Stop function was called, it may take time to change the status to CRIATOMEXPLAYER_STATUS_STOP.)

When the criAtomExPlayer_Start function is executed multiple times on a single AtomEx Player, if any sound is in preparation for the playback, the status becomes CRIATOMEXPLAYER_STATUS_PREP.
(Only after all sounds have started to play is the status changed to CRIATOMEXPLAYER_STATUS_PLAYING.)
Also, when the status of the player is CRIATOMEXPLAYER_STATUS_PLAYING and the criAtomExPlayer_Start function is executed again, the status temporarily returns to CRIATOMEXPLAYER_STATUS_PREP.

During playback, if invalid audio data is read or the file access has failed, the status is changed to CRIATOMEXPLAYER_STATUS_ERROR.
While multiple sounds are being played back, if an error occurs on a sound, the status of the player is changed to CRIATOMEXPLAYER_STATUS_ERROR, regardless of the status of the other sounds.

参见

criAtomExPlayer_GetStatus, criAtomExPlayer_SetData, criAtomExPlayer_Start, criAtomExPlayer_Stop

枚举值
CRIATOMEXPLAYER_STATUS_STOP	Stopped
CRIATOMEXPLAYER_STATUS_PREP	In preparation for playback
CRIATOMEXPLAYER_STATUS_PLAYING	In playback
CRIATOMEXPLAYER_STATUS_PLAYEND	Playback complete
CRIATOMEXPLAYER_STATUS_ERROR	An error occurred

CriAtomExVoiceControlMethodTag

enum CriAtomExVoiceControlMethodTag

Voice playback control method

Description:

This is a data type for specifying how to control the pronunciation of audio played in the AtomEx player.
Used with the criAtomExPlayer_SetVoiceControlMethod function.

参见

criAtomExPlayer_SetVoiceControlMethod

枚举值
CRIATOMEX_PREFER_LAST	Last-come, first-served
CRIATOMEX_PREFER_FIRST	First-come, first-served
CRIATOMEX_PREFER_DATA	Setting in data preferred

CriAtomExSpeakerIdTag

enum CriAtomExSpeakerIdTag

Speaker ID

Description:

This ID is used to specify the speaker that will output audio.
Used with the criAtomExPlayer_SetSendLevel function.

参见

criAtomExPlayer_SetSendLevel

枚举值
CRIATOMEX_SPEAKER_FRONT_LEFT	Front left speaker
CRIATOMEX_SPEAKER_FRONT_RIGHT	Front right speaker
CRIATOMEX_SPEAKER_FRONT_CENTER	Front center speaker
CRIATOMEX_SPEAKER_LOW_FREQUENCY	LFE (approximately the same as a subwoofer)
CRIATOMEX_SPEAKER_SURROUND_LEFT	Surround left speaker
CRIATOMEX_SPEAKER_SURROUND_RIGHT	Surround right speaker
CRIATOMEX_SPEAKER_SURROUND_BACK_LEFT	Surround back left speaker
CRIATOMEX_SPEAKER_SURROUND_BACK_RIGHT	Surround back right speaker

CriAtomExParameterIdTag

enum CriAtomExParameterIdTag

Parameter ID

Description:

This is the ID for specifying parameters.
It is used in functions such as criAtomExPlayer_GetParameterFloat32 .

参见

criAtomExPlayer_GetParameterFloat32, criAtomExPlayer_GetParameterSint32, criAtomExPlayer_GetParameterUint32

枚举值
CRIATOMEX_PARAMETER_ID_VOLUME	Volume
CRIATOMEX_PARAMETER_ID_PITCH	Pitch
CRIATOMEX_PARAMETER_ID_PAN3D_ANGLE	Panning 3D angle
CRIATOMEX_PARAMETER_ID_PAN3D_DISTANCE	Panning 3D distance
CRIATOMEX_PARAMETER_ID_PAN3D_VOLUME	Panning 3D volume
CRIATOMEX_PARAMETER_ID_PAN_TYPE	Pan type
CRIATOMEX_PARAMETER_ID_PAN_SPEAKER_TYPE	Pan speaker type
CRIATOMEX_PARAMETER_ID_PAN_CH0	2D panning (channel 0)
CRIATOMEX_PARAMETER_ID_PAN_CH1	2D panning (channel 1)
CRIATOMEX_PARAMETER_ID_BUS_SEND_LEVEL_0	Bus send level 0
CRIATOMEX_PARAMETER_ID_BUS_SEND_LEVEL_1	Bus send level 1
CRIATOMEX_PARAMETER_ID_BUS_SEND_LEVEL_2	Bus send level 2
CRIATOMEX_PARAMETER_ID_BUS_SEND_LEVEL_3	Bus send level 3
CRIATOMEX_PARAMETER_ID_BUS_SEND_LEVEL_4	Bus send level 4
CRIATOMEX_PARAMETER_ID_BUS_SEND_LEVEL_5	Bus send level 5
CRIATOMEX_PARAMETER_ID_BUS_SEND_LEVEL_6	Bus send level 6
CRIATOMEX_PARAMETER_ID_BUS_SEND_LEVEL_7	Bus send level 7
CRIATOMEX_PARAMETER_ID_BANDPASS_FILTER_COF_LOW	Low cutoff frequency for a band pass filter
CRIATOMEX_PARAMETER_ID_BANDPASS_FILTER_COF_HIGH	High cutoff frequency for a band pass filter
CRIATOMEX_PARAMETER_ID_BIQUAD_FILTER_TYPE	Filter type of a biquad filter
CRIATOMEX_PARAMETER_ID_BIQUAD_FILTER_FREQ	Frequency for a biquad filter
CRIATOMEX_PARAMETER_ID_BIQUAD_FILTER_Q	Q value for a biquad filter
CRIATOMEX_PARAMETER_ID_BIQUAD_FILTER_GAIN	Gain of a biquad filter
CRIATOMEX_PARAMETER_ID_ENVELOPE_ATTACK_TIME	Attack time for an envelope
CRIATOMEX_PARAMETER_ID_ENVELOPE_HOLD_TIME	Hold time for an envelope
CRIATOMEX_PARAMETER_ID_ENVELOPE_DECAY_TIME	Decay time for an envelope
CRIATOMEX_PARAMETER_ID_ENVELOPE_RELEASE_TIME	Release time for an envelope
CRIATOMEX_PARAMETER_ID_ENVELOPE_SUSTAIN_LEVEL	Sustain level for an envelope
CRIATOMEX_PARAMETER_ID_START_TIME	Playback start position
CRIATOMEX_PARAMETER_ID_PRIORITY	Voice priority
CRIATOMEX_PARAMETER_ID_SILENT_MODE	Silent mode
CRIATOMEX_PARAMETER_ID_DSP_PARAMETER_0	Parameter 0 of a DSP effect
CRIATOMEX_PARAMETER_ID_DSP_PARAMETER_1	Parameter 1 of a DSP effect
CRIATOMEX_PARAMETER_ID_DSP_PARAMETER_2	Parameter 2 of a DSP effect
CRIATOMEX_PARAMETER_ID_DSP_PARAMETER_3	Parameter 3 of a DSP effect
CRIATOMEX_PARAMETER_ID_DSP_PARAMETER_4	Parameter 4 of a DSP effect
CRIATOMEX_PARAMETER_ID_DSP_PARAMETER_5	Parameter 5 of a DSP effect
CRIATOMEX_PARAMETER_ID_DSP_PARAMETER_6	Parameter 6 of a DSP effect
CRIATOMEX_PARAMETER_ID_DSP_PARAMETER_7	Parameter 7 of a DSP effect
CRIATOMEX_PARAMETER_ID_DSP_PARAMETER_8	Parameter 8 of a DSP effect
CRIATOMEX_PARAMETER_ID_DSP_PARAMETER_9	Parameter 9 of a DSP effect
CRIATOMEX_PARAMETER_ID_DSP_PARAMETER_10	Parameter 10 of a DSP effect
CRIATOMEX_PARAMETER_ID_DSP_BYPASS_FLAG	Bypass Flag for a DSP effect

函数说明

criAtomExPlayer_AddOutputPort()

void criAtomExPlayer_AddOutputPort	(	CriAtomExPlayerHn	player,
		CriAtomExOutputPortHn	output_port
	)

Adding the output port handle

参数

[in]	player	AtomExPlayer handle
[in]	output_port	Output port handle

Description:

Assigns an output port to a player.
You can assign as many output ports as defined in CRIATOMEXPLAYER_MAX_OUTPUT_PORTS .

Remarks:

This parameter is cleared when using the criAtomExPlayer_ResetParameters or criAtomExPlayer_ClearOutputPorts functions. You can remove a specific output port by calling the criAtomExPlayer_RemoveOutputPort function.
When calling this function during Cue playback, all the following settings will be ignored, and all Cues will be played via the added output port.

• ASR rack ID settings of the parameter palette set data-side
• ASR rack ID specified with the criAtomExPlayer_SetAsrRackId or criAtomExPlayer_SetAsrRackIdArray functions
• The name of the output port of a Track set data-side.

注意

This function is only effective if the type of Voice renderer used is ASR.
(For other types of Voices, the settings passed to this function will be ignored.)

The output port must be assigned before the playback starts.
The output port cannot be changed once playback has started.

When using a player with multiple output ports, playback will occur only if the number of voices corresponds to the number of output ports.
Therefore, it is necessary to allocate as many Voices as output ports in advance.

When calling the criAtomExPlayer_SetData function for playback instead of playing a Cue, only the first output port specified by this function will be applied.

This function has no effect on HCA-MX encoded audio data.
To set the output destination of HCA-MX encoded audio data, calls the criAtomExHcaMx_SetAsrRackId function to set the ASR rack ID used for output in the HCA-MX mixer.

参见

criAtomExOutputPort_Create, criAtomExPlayer_RemoveOutputPort, criAtomExPlayer_ClearOutputPorts

criAtomExPlayer_RemoveOutputPort()

void criAtomExPlayer_RemoveOutputPort	(	CriAtomExPlayerHn	player,
		CriAtomExOutputPortHn	output_port
	)

Removing an output port handle

参数

[in]	player	AtomExPlayer handle
[in]	output_port	Output port handle

Description:

Removes an output port assigned to a player.

Remarks:

Removes a specific output handle previously assigned to a player by calling the criAtomExPlayer_AddOutputPort function. To remove all the output ports assigned to a player, call the criAtomExPlayer_ClearOutputPorts function.

注意

The output port cannot be changed once playback has started.

参见

criAtomExOutputPort_Create, criAtomExPlayer_AddOutputPort, criAtomExPlayer_ClearOutputPorts

criAtomExPlayer_ClearOutputPorts()

void criAtomExPlayer_ClearOutputPorts

(

CriAtomExPlayerHn

player

)

Clearing the output port handles

参数

[in]

player

AtomExPlayer handle

Description:

Clears all the added output port to the players.

Remarks:

Clears all output handles previously assigned the player by calling the criAtomExPlayer_AddOutputPort function. To remove a specific handle, call the criAtomExPlayer_RemoveOutputPort function.

注意

The output port cannot be changed once playback has started.

参见

criAtomExOutputPort_Create, criAtomExPlayer_AddOutputPort, criAtomExPlayer_RemoveOutputPort

criAtomExPlayer_AddPreferredOutputPort()

void criAtomExPlayer_AddPreferredOutputPort	(	CriAtomExPlayerHn	player,
		CriAtomExOutputPortHn	output_port
	)

Assigning a prioritary output port handle

参数

[in]	player	AtomExPlayer handle
[in]	output_port	Output port handle

Description:

Assigns the specified output port to the player prior to the global output port.
You can assign as many output ports as defined in CRIATOMEXPLAYER_MAX_OUTPUT_PORTS .

Remarks:

This parameter will be cleared by calling the criAtomExPlayer_ResetParameters or criAtomExPlayer_ClearPreferredOutputPorts functions. To remove a specific handle, you can call the criAtomExPlayer_RemovePreferredOutputPort or criAtomExPlayer_RemovePreferredOutputPortByName functions.
When playing a Cue including a track with an output port name, the audio is output from the global output port with the same name that was automatically generated when registering ACF. If this function was called to add a prioritary output port to the player, the audio will be output from the prioritary output port with the same name.

注意

This does not affect the playback of tracks that have not been assigned an output port name in the tool.

The output port must be assigned before the playback starts.
The output port cannot be changed once playback has started.

A prioritary output port must have a unique name in the player.
When calling the criAtomExPlayer_SetData function for playback instead of playing a Cue, only the first output port specified by this function will be applied.

If this function is executed after calling the criAtomExPlayer_SetAsrRackId function, it will overwrite the ASR rack ID set by criAtomExPlayer_SetAsrRackId .

This function has no effect on HCA-MX encoded audio data.

参见

criAtomExPlayer_RemovePreferredOutputPort, criAtomExPlayer_RemovePreferredOutputPortByName, criAtomExPlayer_ClearPreferredOutputPorts

criAtomExPlayer_RemovePreferredOutputPort()

void criAtomExPlayer_RemovePreferredOutputPort	(	CriAtomExPlayerHn	player,
		CriAtomExOutputPortHn	output_port
	)

Removing the prioritary output port handle

参数

[in]	player	AtomExPlayer handle
[in]	output_port	Output port handle

Description:

Removes the prioritary output port assigned to the player.

Remarks:

Removes the specific prioritary output port handle previously assigned to a player by criAtomExPlayer_AddPreferredOutputPort . To remove all the output ports assigned to a player, call the criAtomExPlayer_ClearOutputPorts function.

注意

Removing the prioritary output port does not affect any audio that has already started playing.

参见

criAtomExPlayer_AddOutputPort, criAtomExPlayer_RemovePreferredOutputPortByName, criAtomExPlayer_ClearPreferredOutputPorts

criAtomExPlayer_RemovePreferredOutputPortByName()

void criAtomExPlayer_RemovePreferredOutputPortByName	(	CriAtomExPlayerHn	player,
		CriChar8 *	name
	)

Removing a prioritary output port handle by name

参数

[in]	player	AtomExPlayer handle
[in]	name	Output port name

Description:

Removes the prioritary output port specified by name that was previously assigned to the player.

Remarks:

Removes the specific prioritary output port handle previously assigned to a player by criAtomExPlayer_AddPreferredOutputPort . To remove all the output ports assigned to a player, call the criAtomExPlayer_ClearOutputPorts function.

注意

Removing the prioritary output port does not affect any audio that has already started playing.

参见

criAtomExPlayer_AddOutputPort, criAtomExPlayer_RemovePreferredOutputPort, criAtomExPlayer_ClearPreferredOutputPorts

criAtomExPlayer_ClearPreferredOutputPorts()

void criAtomExPlayer_ClearPreferredOutputPorts

(

CriAtomExPlayerHn

player

)

Clearing all the prioritary output port handles

参数

[in]

player

AtomExPlayer handle

Description:

Clears all the prioritary output ports that were assigned to a player.

Remarks:

Clears all the prioritary output port handles assigned to a player by criAtomExPlayer_AddPreferredOutputPort . To remove a specific prioritary output port, call the criAtomExPlayer_RemovePreferredOutputPort or criAtomExPlayer_RemovePreferredOutputPortByName functions.

注意

Removing the prioritary output port does not affect any audio that has already started playing.

参见

criAtomExPlayer_AddOutputPort, criAtomExPlayer_RemovePreferredOutputPort, criAtomExPlayer_RemovePreferredOutputPortByName

criAtomExPlayer_CalculateWorkSize()

CriSint32 criAtomExPlayer_CalculateWorkSize

(

const CriAtomExPlayerConfig *

config

)

Calculate the size of the work buffer required to create an AtomEx player

参数

[in]

config

configuration structure used to create an AtomEx player

返回

CriSint32 work buffer size

返回值

>=	0 successfully completed
-1	error occurred

Description:

Calculates the size of the work buffer required to create an AtomEx player.
When creating an AtomEx player without having previously registered a user-allocator, a work buffer of the size returned by this function must be passed to the criAtomExPlayer_Create function.

The size of the work buffer required to create a player depends on the values of the parameters in the configuration structure ( CriAtomExPlayerConfig ).

If NULL is passed for config, the size of the work buffer is calculated from the default settings (i.e. the parameters obtained when calling criAtomExPlayer_SetDefaultConfig ).
If the size calculation fails, -1 is returned.
To know the reason of the failure, refer to the error callback message.

Remarks:

The config argument information is referenced only within the function.
It is not referenced after the function has exited, so there is no problem in freeing the config area after the function has been executed.

注意

You must initialize the library before calling this function.

参见

CriAtomExPlayerConfig, criAtomExPlayer_Create

criAtomExPlayer_Create()

CriAtomExPlayerHn criAtomExPlayer_Create	(	const CriAtomExPlayerConfig *	config,
		void *	work,
		CriSint32	work_size
	)

Create an AtomEx player

参数

[in]	config	configuration structure used for the creation of an AtomEx player
[in]	work	work buffer
[in]	work_size	work buffer size

返回

CriAtomExPlayerHn AtomEx player handle

Description:

Creates an AtomEx player.

When creating a player, the work buffer used internally by the library must be allocated.
There are two ways to allocate it:
(a) User-Allocator method: the user provides functions to allocate/release memory.
(b) Fixed Memory method: The required memory is passed directly to the functions of the library.

When using the User-Allocator method, you do not need to provide a work buffer to the function.
You can ask the library to allocate the required memory by calling the registered user-allocator functions, simply by specifying NULL for work and 0 for work_size.
The memory allocated when creating the AtomEx player will be released when the AtomEx player is destroyed (i.e. when executing the criAtomExPlayer_Destroy function).

When using the Fixed Memory method, you must pass a memory buffer for this function to work with.
The size of the work buffer can be obtained by calling the criAtomExPlayer_CalculateWorkSize function.
Allocate a work buffer of the size returned by the criAtomExPlayer_CalculateWorkSize function and pass it to the function that creates the AtomEx player .
If you use the Fixed Memory method, the work buffer will be used within the library until the AtomEx player is destroyed ( by calling the criAtomExPlayer_Destroy function).
Therefore, do not release the work buffer before destroying the AtomEx player.

Example:

[Creating an AtomEx player with the User-Allocator method]
When using the User-Allocator method, the AtomEx player creation/destruction procedure is as follows:

1. Before creating the AtomEx player: use the criAtomEx_SetUserAllocator function to register the user-allocator functions.
   
2. Set the parameters in the AtomEx player creation configuration structure.
   
3. Create the AtomEx player by calling the criAtomExPlayer_Create function.
   (Specify NULL for work and 0 for work_size.)
   
4. When the handle is no longer necessary, destroy the AtomEx player with the criAtomExPlayer_Destroy function.
   

The specific code is as follows:

// User's memory allocation function
void *user_malloc(void *obj, CriUint32 size)
{
    void *mem;
 
    // Allocate memory
    mem = malloc(size);
 
    return (mem);
}
 
// User's memory release function
void user_free(void *obj, void *mem)
{
    // Release memory
    free(mem);
 
    return;
}
 
main()
{
    CriAtomExPlayerConfig config;   // configuration structure used for AtomEx player creation 
    CriAtomExPlayerHn player;       // AtomEx player handle
        :
    // Register user's memory allocator
    criAtomEx_SetUserAllocator(user_malloc, user_free, NULL);
 
    // Set the configuration structure used for AtomEx player creation
    criAtomExPlayer_SetDefaultConfig(&config);
 
    // Create AtomEx player
    // Specify NULL and 0 for the work buffer and its size
    // -> Allocate the required memory using the registered memory allocation function
    player = criAtomExPlayer_Create(&config, NULL, 0);
        :
    // Sound playback processing
        :
    // Destroy AtomEx player when it is no longer needed
    // -> The memory allocated by the library when creating the AtomEx player is released.
    criAtomExPlayer_Destroy(player);
        :
}

*If memory the user-allocator functions were registered during the library initialization, they do mot need to be registered again when creating the AtomEx player.

[Creating an AtomEx player with the Fixed Memory Method]
When using the Fixed Memory method, the AtomEx player creation/destruction procedure is as follows:

1. Set the parameters in the configuration structure used for the creation of the AtomEx player.
   
2. Calculate the size of work buffer necessary to create the AtomEx player with the criAtomExPlayer_CalculateWorkSize function.
   
3. Allocate a memory buffer of that size.
   
4. Create the Atom Ex player by calling the criAtomExPlayer_Create function.
   (Specify the address of the allocated memory in work and its size in work_size.)
   
5. When the handle is no longer necessary, destroy the AtomEx player with the criAtomExPlayer_Destroy function.
   
6. Release the work buffer.
   

The specific code is as follows:

main()
{
    CriAtomExPlayerConfig config;   // configuration structure used for AtomEx player creation 
    CriAtomExPlayerHn player;       // AtomEx player handle
    void *work;                     // Work buffer address
    CriSint32 work_size;            // Work buffer size
        :
    // Set the configuration structure used for AtomEx player creation
    criAtomExPlayer_SetDefaultConfig(&config);
 
    // Calculate the size of the work buffer necessary to create the AtomEx player
    work_size = criAtomExPlayer_CalculateWorkSize(&config);
 
    // Allocate the memory for the work buffer
    work = malloc((size_t)work_size);
 
    // Create the AtomEx player
    // Specify the address of the work buffer and its size
    // -> use provided buffer
    player = criAtomExPlayer_Create(&config, work, work_size);
        :
    // Sound playback processing
    // -> Allocated memory is retained during this time
        :
    // Destroy the AtomEx player when it is no longer needed
    criAtomExPlayer_Destroy(player);
 
    // Release the work buffer when no longer necessary
    free(work);
        :
}

When you call the criAtomExPlayer_Create function, an AtomEx player is created and a handle (CriAtomExPlayerHn ) to control it is returned.
All operations, such as setting the audio data to play, starting the playback and acquiring the playback status, are performed on the player through this handle.

If the player creation fails, this function returns NULL.
To know the reason of the failure, refer to the error callback message.

The procedure to play the sound data using the AtomEx player handle is as follows:

1. Use the criAtomExPlayer_SetData function to specify the audio data to play to the AtomEx player.
   (For file playback, use the criAtomExPlayer_SetFile or the criAtomExPlayer_SetContentId functions.)
   
2. Start the playback with the criAtomExPlayer_Start function.
   

   Remarks:

   The config argument information is referenced only within the function.
   It is not referenced after the function has exited, so there is no problem in freeing the config area after the function has been executed.

   注意

   You must initialize the library before calling this function.
   
   This is a blocking function.
   The actual time required to create an AtomEx player varies depending on the platform.
   If this function is executed during a game loop or when regular graphic updates are expected, since processing will be blocked by the millisecond frames may be dropped.
   Create or destroy an AtomEx player only when a fluctuation in load is acceptable, for example when loading a game level.
   

   参见

   CriAtomExPlayerConfig, criAtomExPlayer_CalculateWorkSize, CriAtomExPlayerHn, criAtomExPlayer_Destroy, criAtomExPlayer_SetData, criAtomExPlayer_SetFile, criAtomExPlayer_SetContentId, criAtomExPlayer_Start

criAtomExPlayer_SetCueId()

void criAtomExPlayer_SetCueId	(	CriAtomExPlayerHn	player,
		CriAtomExAcbHn	acb_hn,
		CriAtomExCueId	id
	)

Set the sound data to play (specifying a Cue ID)

参数

[in]	player	AtomEx player handle
[in]	acb_hn	ACB handle
[in]	id	Cue ID

Description:

Associates a Cue ID to an AtomEx player.
After specifying a Cue ID with this function, call the criAtomExPlayer_Start function to start the playback of the specified Cue.

Example:

main()
{
        :
    // Set the sound data to play
    criAtomExPlayer_SetCueId(player, acb_hn, 100);
 
    // Play the sound data
    criAtomExPlayer_Start(player);
        :
}

Note that once the data has been set, it is retained within the AtomEx player until some other data is set.
Therefore, if you want to repeatedly play the same sound data, you do not need to set the data again each time you play.

Remarks:

When you specify NULL as the second argument ( ach_hn ), all loaded ACBs are tested for a match with the specified Cue ID.
(When an ACB with the specified Cue ID is found, the Cue of that ACB data is set in the player.)
During this operation, the order of search is the reverse of the ACB loading order.
(Search is performed starting from the data loaded the most recently.)

If you set the Cue with the criAtomExPlayer_SetCueId function, the parameters specified with the following functions are ignored:

• criAtomExPlayer_SetFormat
• criAtomExPlayer_SetNumChannels
• criAtomExPlayer_SetSamplingRate

(The sound format, number of channels and sampling rate are set automatically based on the data in the ACB file.)

参见

criAtomExPlayer_Start

criAtomExPlayer_SetCueName()

void criAtomExPlayer_SetCueName	(	CriAtomExPlayerHn	player,
		CriAtomExAcbHn	acb_hn,
		const CriChar8 *	cue_name
	)

Set the sound data to play (specifying a Cue name)

参数

[in]	player	AtomEx player handle
[in]	acb_hn	ACB handle
[in]	cue_name	Cue name Associates a Cue name to an AtomEx player. After specifying a Cue name with this function, call the criAtomExPlayer_Start function to start the playback of the specified Cue.

Example:

main()
{
        :
    // Set the sound data to play
    criAtomExPlayer_SetCueName(player, acb_hn, "gun_shot");
 
    // Play the sound data
    criAtomExPlayer_Start(player);
        :
}

Note that once the data has been set, it is retained within the AtomEx player until some other data is set.
Therefore, if you want to repeatedly play the same sound data, you do not need to set the data again each time you play.

Remarks:

When you specify NULL as the second argument ( ach_hn ), all loaded ACBs are tested for a match with the specified Cue name.
(When an ACB with the specified Cue name is found, the Cue of that ACB data is set in the player.)
During this operation, the order of search is the reverse of the ACB loading order.
(Search is performed starting from the data loaded the most recently.)

If you set the Cue with the criAtomExPlayer_SetCueName function, the parameters specified with the following functions are ignored:

• criAtomExPlayer_SetFormat
• criAtomExPlayer_SetNumChannels
• criAtomExPlayer_SetSamplingRate

(The sound format, number of channels and sampling rate are set automatically based on the data in the ACB file.)

参见

criAtomExPlayer_Start

criAtomExPlayer_SetCueIndex()

void criAtomExPlayer_SetCueIndex	(	CriAtomExPlayerHn	player,
		CriAtomExAcbHn	acb_hn,
		CriAtomExCueIndex	index
	)

Set the sound data to play (specifying a Cue index)

参数

[in]	player	AtomEx player handle
[in]	acb_hn	ACB handle
[in]	index	Cue index Associates a Cue index to an AtomEx player. After specifying a Cue index with this function, call the criAtomExPlayer_Start function to start the playback of the specified Cue.

Example:

main()
{
        :
    // Set the sound data to play
    criAtomExPlayer_SetCueIndex(player, acb_hn, 300);
 
    // Play the sound data
    criAtomExPlayer_Start(player);
        :
}

Note that once the data has been set, it is retained within the AtomEx player until some other data is set.
Therefore, if you want to repeatedly play the same sound data, you do not need to set the data again each time you play.

Remarks:

When you specify NULL as the second argument ( ach_hn ), all loaded ACBs are tested for a match with the specified Cue index.
(When an ACB with the specified Cue index is found, the Cue of that ACB data is set in the player.)
During this operation, the order of search is the reverse of the ACB loading order.
(Search is performed starting from the data loaded the most recently.)

If you set the Cue with the criAtomExPlayer_SetCueIndex function, the parameters specified with the following functions are ignored:

• criAtomExPlayer_SetFormat
• criAtomExPlayer_SetNumChannels
• criAtomExPlayer_SetSamplingRate

(The sound format, number of channels and sampling rate are set automatically based on the data in the ACB file.)

Using this function, it is possible to associate a sound to the player without specifying a Cue name or a Cue ID.
(It can be used for debugging purposes since you can play a sound from the ACB file even if you do not know the Cue name and the Cue ID.)

参见

criAtomExPlayer_Start

criAtomExPlayer_SetData()

void criAtomExPlayer_SetData	(	CriAtomExPlayerHn	player,
		void *	buffer,
		CriSint32	size
	)

Set the sound data to play (specifying in-memory data)

参数

[in]	player	AtomEx player handle
[in]	buffer	buffer address
[in]	size	buffer size

Description:

Associates the sound data in memory to an AtomEx player.
Specify the address and size of the buffer containing the sound data with this function, and then call the criAtomExPlayer_Start function to start the playback.

Example:

main()
{
        :
    // Set the sound data to play
    criAtomExPlayer_SetData(player, buffer, buffer_size);
 
    // Specify the format of the sound data
    criAtomExPlayer_SetFormat(player, CRIATOMEX_FORMAT_ADX);
    criAtomExPlayer_SetNumChannels(player, 1);
    criAtomExPlayer_SetSamplingRate(player, 24000);
 
    // Play the sound data
    criAtomExPlayer_Start(player);
        :
}

Note that once the data has been set, it is retained within the AtomEx player until some other data is set.
Therefore, if you want to repeatedly play the same sound data, you do not need to set the data again each time you play.

注意

The player only stores the address and the size of the buffer.
(The data inside the buffer is not copied.)
Therefore, the buffer must be maintained by the application until its playback is finished.

Even if you stop the AtomEx player playing memory, there is still a possibility that a voice referencing the memory area exists in the library.
To release the memory area set by this function, execute the criAtomEx_IsDataPlaying function beforehand to check that the memory area is not referenced anymore.
When setting the sound data with this function, you must also call the following functions to specify its format, number of channels and sampling rate:

• criAtomExPlayer_SetFormat
• criAtomExPlayer_SetNumChannels
• criAtomExPlayer_SetSamplingRate

参见

criAtomExPlayer_SetFormat, criAtomExPlayer_Start, criAtomEx_IsDataPlaying

criAtomExPlayer_SetFile()

void criAtomExPlayer_SetFile	(	CriAtomExPlayerHn	player,
		CriFsBinderHn	binder,
		const CriChar8 *	path
	)

Set the sound data to play (specifying a file name)

参数

[in]	player	AtomEx player handle
[in]	binder	binder handle
[in]	path	file path

Description:

Associates a sound file to an AtomEx player.
After passing a file to this function, call the criAtomExPlayer_Start function to start the streaming playback of that file.
Note that file loading is not started when you execute this function.
It is actually started when you call the criAtomExPlayer_Start function.

Example:

main()
{
      :
  // Set the sound file to play
  criAtomExPlayer_SetFile(player, NULL, "sample.hca");
 
  // Specify the format of the sound data
  criAtomExPlayer_SetFormat(player, CRIATOMEX_FORMAT_HCA);
  criAtomExPlayer_SetNumChannels(player, 2);
  criAtomExPlayer_SetSamplingRate(player, 48000);
 
  // Play the sound data
  criAtomExPlayer_Start(player);
      :
}

Note that once the file has been set, the data is retained within the AtomEx player until some other data is set.
Therefore, if you want to repeatedly play the same sound data, you do not need to set the data again each time you play.

Remarks:

Specify NULL when the data is not packed to CPK.

注意

When you execute the criAtomExPlayer_SetFile function, the specified path is stored within the AtomEx player.
By default, the AtomEx player allocates enough memory to store only one file path.
(in order to save memory.)
If you want to set another file to the AtomEx player while you are already playing one, two paths will need to be stored.
In that case, you must specify a larger value for max_path_strings when you create the player.
Increasing max_path_strings will allow the AtomEx player to store that many path strings simultaneously.
(By specifying a value equal to or larger than two for max_path_strings, it is possible to play back multiple files at the same time by specifying their paths.)
Note that the size of the work buffer required increases based on the value of max_path_strings.

When setting the sound data with this function, you must also call the following functions to specify its format, number of channels and sampling rate:

• criAtomExPlayer_SetFormat
• criAtomExPlayer_SetNumChannels
• criAtomExPlayer_SetSamplingRate

参见

CriAtomExPlayerConfig, criAtomExPlayer_Create, criAtomExPlayer_Start

criAtomExPlayer_SetContentId()

void criAtomExPlayer_SetContentId	(	CriAtomExPlayerHn	player,
		CriFsBinderHn	binder,
		CriSint32	id
	)

Set the sound data to play (specifying a CPK content ID)

参数

[in]	player	AtomEx player handle
[in]	binder	binder handle
[in]	id	content ID

Description:

Associates content to an AtomEx player.
This function is used to play back a content file in a CPK file using the CRI File System library. The file is specified by its ID.
After passing a binder and a content ID to this function, call the criAtomExPlayer_Start function to start the streaming playback of the content file.
Note that file loading is not started when you execute this function.
It is actually started when you call the criAtomExPlayer_Start function.

Example:

main()
{
        :
    // Bind the CPK file
    criFsBinder_BindCpk(binder, "sample.cpk", work, work_size, &bind_id);
 
    // Wait for the completion of the binding
    for (;;) {
        // Check the status
        criFsBinder_GetStatus(binder, &status);
        if (status == CRIFSBINDER_STATUS_COMPLETE) {
            break;
        }
 
        // Execute server processing
        criFs_ExecuteMain();
 
        // Wait for Vsync etc.
            :
    }
        :
    // Set the sound file to play
    // Set the first content in sample.cpk
    criAtomExPlayer_SetContentId(player, binder, 1);
 
    // Specify the format of the sound data to play
    criAtomExPlayer_SetFormat(player, CRIATOMEX_FORMAT_ADX);
    criAtomExPlayer_SetNumChannels(player, 2);
    criAtomExPlayer_SetSamplingRate(player, 44100);
 
    // Play the sound data
    criAtomExPlayer_Start(player);
        :
}

Note that once the file has been set, the data is retained within the AtomEx player until some other data is set.
Therefore, if you want to repeatedly play the same sound data, you do not need to set the data again each time you play.

Remarks:

Specify NULL when the data is not packed to CPK.

注意

When setting the sound data with this function, you must also call the following functions to specify its format, number of channels and sampling rate:

• criAtomExPlayer_SetFormat
• criAtomExPlayer_SetNumChannels
• criAtomExPlayer_SetSamplingRate

参见

CriAtomExPlayerConfig, criAtomExPlayer_Create, criAtomExPlayer_Start

criAtomExPlayer_SetWaveId()

void criAtomExPlayer_SetWaveId	(	CriAtomExPlayerHn	player,
		CriAtomAwbHn	awb,
		CriAtomExWaveId	id
	)

Set the wave data to play (specifying a wave data ID)

参数

[in]	player	AtomEx player handle
[in]	awb	AWB handle
[in]	id	wave data ID

Description:

Associates wave data to an AtomEx player.
After passing an AWB handle and a wave data ID to this function, call the criAtomExPlayer_Start function to start the streaming playback of the specified wave data.
Note that file loading is not started when you execute this function.
It is actually started when you call the criAtomExPlayer_Start function.

Example:

main()
{
        :
    // Create an AWB handle by loading the AWB TOC information
    awb = criAtomAwb_LoadToc(NULL, "sample.awb", NULL, 0);
        :
    // Set the wave data
    // (Set the first wave data in the AWB)
    criAtomExPlayer_SetWaveId(player, awb, 1);
 
    // Specify the format of the sound data to play
    criAtomExPlayer_SetFormat(player, CRIATOMEX_FORMAT_HCA_MX);
    criAtomExPlayer_SetNumChannels(player, 2);
    criAtomExPlayer_SetSamplingRate(player, 32000);
 
    // Play the sound data
    criAtomExPlayer_Start(player);
        :
}

Note that once the file has been set, the data is retained within the AtomEx player until some other data is set.
Therefore, if you want to repeatedly play the same sound data, you do not need to set the data again each time you play.

注意

When you set sound data in this function, use the function below to separately specify the information of the sound data to play.

• criAtomExPlayer_SetFormat
• criAtomExPlayer_SetNumChannels
• criAtomExPlayer_SetSamplingRate

Do not destroy data with the criAtomAwb_Release function while playing the sound that was set with this function.
To destroy the AWB file, make sure that playback is stopped and execute the criAtomAwb_Release function.

参见

CriAtomExPlayerConfig, criAtomExPlayer_Create, criAtomExPlayer_Start

criAtomExPlayer_Start()

CriAtomExPlaybackId criAtomExPlayer_Start

(

CriAtomExPlayerHn

player

)

Start the playback

参数

[in]

player

AtomEx player handle

返回

CriAtomExPlaybackId playback ID

Description:

Starts the playback of the sound data.
Before executing this function, you must call criAtomExPlayer_SetData to specify the sound data to be played by the AtomEx player.
For example, if you want to play on-memory audio data, you need to set the audio data beforehand using the criAtomExPlayer_SetData function as shown below, and then execute this function.

main()
{
        :
    // Set the sound data
    criAtomExPlayer_SetData(player, buffer, buffer_size);
 
    // Specify the format of the sound data to play
    criAtomExPlayer_SetFormat(player, CRIATOMEX_FORMAT_HCA_MX);
    criAtomExPlayer_SetNumChannels(player, 1);
    criAtomExPlayer_SetSamplingRate(player, 24000);
 
    // Play the sound data
    criAtomExPlayer_Start(player);
        :
}

After executing this function, you can check the progress of playback (whether playback has started, whether playback has finished, etc.) by getting the status.
To get the status, use the criAtomExPlayer_GetStatus function.
The criAtomExPlayer_GetStatus function returns five types of status.

1. CRIATOMEXPLAYER_STATUS_STOP
2. CRIATOMEXPLAYER_STATUS_PREP
3. CRIATOMEXPLAYER_STATUS_PLAYING
4. CRIATOMEXPLAYER_STATUS_PLAYEND
5. CRIATOMEXPLAYER_STATUS_ERROR

When an AtomEx player is created, it has the stopped status ( CRIATOMEXPLAYER_STATUS_STOP ).
After having specified the sound data to play, the AtomEx player status changes to the preparation status ( CRIATOMEXPLAYER_STATUS_PREP ) when this function is executed.
(In CRIATOMEXPLAYER_STATUS_PREP status, the player is waiting to receive data or start decoding.)
When there is sufficient data to start playing, the AtomEx player status changes to the playing status ( CRIATOMEXPLAYER_STATUS_PLAYING ) and the sound output starts.
When the playback of all the data completes, the AtomEx player status changes to the play end status ( CRIATOMEXPLAYER_STATUS_PLAYEND ).
If an error occurs during playback, the AtomEx player status changes to ( CRIATOMEXPLAYER_STATUS_ERROR ).

By checking the status of the AtomEx player and switching the process accordingly, it is possble to write a program that takes action based on the sound playback.
For example, the following code can be used to wait for the sound playback to complete before continuing.

main()
{
        :
    // Set the sound data to play
    criAtomExPlayer_SetData(player, buffer, buffer_size);
 
    // Specify the format of the sound data
    criAtomExPlayer_SetFormat(player, CRIATOMEX_FORMAT_ADX);
    criAtomExPlayer_SetNumChannels(player, 1);
    criAtomExPlayer_SetSamplingRate(player, 22050);
 
    // Play the sound data
    criAtomExPlayer_Start(player);
 
    // Wait for playback completion
    for (;;) {
        // Get the status
        status = criAtomExPlayer_GetStatus(player);
 
        // Check the status
        if (status == CRIATOMEXPLAYER_STATUS_PLAYEND) {
            // Exit the loop when the playback is complete
            break;
        }
 
        // Execute the server processing
        criAtomEx_ExecuteMain();
 
        // Refresh the screen display etc.
            :
    }
        :
}

Remarks:

If the sound resources cannot be allocated during this function execution (for example when all voices are in use and no voice can be stolen), CRIATOMEX_INVALID_PLAYBACK_ID is returned.
However, in most cases, there is no need to check the error from the return code.
Indeed, if you pass CRIATOMEX_INVALID_PLAYBACK_ID to a function that needs a playback ID ( CriAtomExPlaybackId ), the Atom library will simply do nothing.
Therefore, you do not need to change the application processing according to the result of this function.
(When CRIATOMEX_INVALID_PLAYBACK_ID is returned, no error callback occurs even if you perform the same processing as when a valid playback ID is returned.)

参见

criAtomExPlayer_SetData, criAtomExPlayer_SetFile, criAtomExPlayer_GetStatus, criAtomExPlayer_Pause, criAtomEx_ExecuteMain

criAtomExPlayer_Prepare()

CriAtomExPlaybackId criAtomExPlayer_Prepare

(

CriAtomExPlayerHn

player

)

Prepare the playback

参数

[in]

player

AtomEx player handle

返回

CriAtomExPlaybackId playback ID

Description:

Prepares the playback of sound data.
Before executing this function, you must call the criAtomExPlayer_SetData function to specify the sound data to be played by the AtomEx player.

This function starts the sound playback in paused mode.
When the function is called, the resources required for the sound playback are allocated and the buffering (loading of the file to be streamed) starts. However, the playback does not start after the completion of the buffering (i.e. the playback stays paused even after it becomes possible to play the sound).

In the case where there is only one sound to play back, this function behaves similarly to the following code.

    :
// Set the player to paused status
criAtomExPlayer_Pause(player, CRI_TRUE);
 
// Start the sound playback
id = criAtomExPlayer_Start(player);
    :

In order to start the playback of a sound prepared by this function, pass the playback ID ( CriAtomExPlaybackId ) it returned and call ::criAtomExPlayback_Pause(id, CRI_FALSE);

Remarks:

In streaming playback, when you call the criAtomExPlayer_Start function, there is a time lag before the sound is actually played back.
(This is because the buffering of the sound data takes some time.)

By performing the following operations, you can control the timing of the start of the playback even when streaming:

1. Prepare the playback using the criAtomExPlayer_Prepare function.
2. Check the status of the playback ID acquired at step 1, using the criAtomExPlayback_GetStatus function.
3. Resume the playback by calling the criAtomExPlayback_Pause function when the status becomes CRIATOMEXPLAYBACK_STATUS_PLAYING.
4. After resuming, the playback will start (the next time the server process is called).

The specific code is as follows:

main()
{
        :
    // Set the sound data to play
    criAtomExPlayer_SetFile(player, NULL, "sample.adx");
 
    // Specify the format of the sound data
    criAtomExPlayer_SetFormat(player, CRIATOMEX_FORMAT_ADX);
    criAtomExPlayer_SetNumChannels(player, 2);
    criAtomExPlayer_SetSamplingRate(player, 48000);
 
    // Start preparing the playback of the sound data
    playback_id = criAtomExPlayer_Prepare(player);
        :
    // Wait until it is possible to start the playback
    for (;;) {
        // Check the playback status
        playback_status = criAtomExPlayback_GetStatus(playback_id);
        if (playback_status == CRIATOMEXPLAYBACK_STATUS_PLAYING) {
            // Exit the loop when the status becomes "PLAYING"
            break;
        }
 
        // Execute the server processing
        criAtomEx_ExecuteMain();
 
        // Refresh screen display etc.
            :
    }
 
    // Resume
    criAtomExPlayback_Pause(playback_id, CRI_FALSE);
        :
}

When using the criAtomExPlayback_Pause function to resume, both the pause from playback preparation (by this function) and the pause from playback suspension (by the criAtomExPlayer_Pause function) are released.
To play back the sound prepared by this function while pausing the sound by the criAtomExPlayer_Pause function, use the criAtomExPlayer_Resume function (or the criAtomExPlayback_Resume function).

参见

criAtomExPlayback_GetStatus, criAtomExPlayback_Pause

criAtomExPlayer_Stop()

void criAtomExPlayer_Stop

(

CriAtomExPlayerHn

player

)

Stop the playback

参数

[in]

player

AtomEx player handle

Description:

Issues a request to stop the the playback.
When you execute this function on an AtomEx player that is playing a sound, the AtomEx player stops playback (stops reading the file and outputting sound) and switch to the stopped state (CRIATOMEXPLAYER_STATUS_STOP).

Remarks:

If you execute this function on an AtomEx player that is already stopped (i.e. an AtomEx player with the CRIATOMEXPLAYER_STATUS_PLAYEND or the CRIATOMEXPLAYER_STATUS_ERROR status), the AtomEx player changes its status to CRIATOMEXPLAYER_STATUS_STOP.

注意

This function is not a blocking function.
Therefore, processing is not blocked in the function for a long time. However, note that playback may be in progress when the function is finished.
(It may take some time until playback is stopped.)
If the stop of playback must be guaranteed, make sure that the AtomEx player is in the stop status (CRIATOMEXPLAYER_STATUS_STOP) after calling this function.

参见

criAtomExPlayer_Start, criAtomExPlayer_GetStatus

criAtomExPlayer_StopWithoutReleaseTime()

void criAtomExPlayer_StopWithoutReleaseTime

(

CriAtomExPlayerHn

player

)

Stop the playback (ignoring release time)

参数

[in]

player

AtomEx player handle

Description:

Issues a request to stop the the playback.
This function stops the sound immediately, even when a release time is set for the envelope.
When you execute this function on an AtomEx player that is playing a sound, the AtomEx player stops playback (stops reading the file and outputting sound) and switch to the stopped state (CRIATOMEXPLAYER_STATUS_STOP).

Remarks:

If you execute this function on an AtomEx player that is already stopped (i.e. an AtomEx player with the CRIATOMEXPLAYER_STATUS_PLAYEND or the CRIATOMEXPLAYER_STATUS_ERROR status), the AtomEx player changes its status to CRIATOMEXPLAYER_STATUS_STOP.

注意

This function is not a blocking function.
Therefore, processing is not blocked in the function for a long time. However, note that playback may be in progress when the function is finished.
(It may take some time until playback is stopped.)
If the stop of playback must be guaranteed, make sure that the AtomEx player is in the stop status (CRIATOMEXPLAYER_STATUS_STOP) after calling this function.

参见

criAtomExPlayer_Start, criAtomExPlayer_GetStatus

criAtomExPlayer_StopAllPlayers()

void criAtomExPlayer_StopAllPlayers

(

void

)

Stopping playback in all the players

Description:

Issues a playback stop request to all the AtomEx players.
When you execute this function, the AtomEx players stop playback (loading files and playing sounds) and move to the stop status (CRIATOMEXPLAYER_STATUS_STOP).

Remarks:

If you execute this function to an AtomEx player that is already stopped (CRIATOMEXPLAYER_STATUS_PLAYEND or CRIATOMEXPLAYER_STATUS_ERROR status), its status changes to CRIATOMEXPLAYER_STATUS_STOP.

注意

This function is not a blocking function.
Therefore, processing is not blocked in the function for a long time. However, note that playback may be in progress when the function is finished.
(It may take some time until playback is stopped.)
If the stop of playback must be guaranteed, make sure that the AtomEx player is in the stop status (CRIATOMEXPLAYER_STATUS_STOP) after calling this function.

参见

criAtomExPlayer_Start, criAtomExPlayer_GetStatus

criAtomExPlayer_StopAllPlayersWithoutReleaseTime()

void criAtomExPlayer_StopAllPlayersWithoutReleaseTime

(

void

)

Stopping playback in all the players (release time ignored)

Description:

Issues a playback stop request to all the AtomEx players.
In this case, even if the release time for the envelope is set for sound that is being played, it is ignored and playback is stopped.
When you execute this function, the AtomEx players stop playback (loading files and playing sounds) and move to the stop status (CRIATOMEXPLAYER_STATUS_STOP).

Remarks:

If you execute this function to an AtomEx player that is already stopped (CRIATOMEXPLAYER_STATUS_PLAYEND or CRIATOMEXPLAYER_STATUS_ERROR status), its status changes to CRIATOMEXPLAYER_STATUS_STOP.

注意

This function is not a blocking function.
Therefore, processing is not blocked in the function for a long time. However, note that playback may be in progress when the function is finished.
(It may take some time until playback is stopped.)
If the stop of playback must be guaranteed, make sure that the AtomEx player is in the stop status (CRIATOMEXPLAYER_STATUS_STOP) after calling this function.

参见

criAtomExPlayer_Start, criAtomExPlayer_GetStatus

criAtomExPlayer_Pause()

void criAtomExPlayer_Pause	(	CriAtomExPlayerHn	player,
		CriBool	sw
	)

Pause/resume

参数

[in]	player	AtomEx player handle
[in]	sw	switch (CRI_FALSE = Resume, CRI_TRUE = Pause)

Description:

Pauses or resumes playback.
When you call this function by passing CRI_TRUE in sw, the AtomEX player pauses the output of sound being played.
If you call it and pass CRI_FALSE in sw, the AtomEX player resumes the playback of paused sound.

Remarks:

The default status (i.e. the status immediately after the creation of a player) is resumed.

注意

If you release the pause by passing CRI_FALSE, not only sounds paused by this function but also sounds in playback preparation (after the criAtomExPlayer_Prepare was called) will start to play.
(This is done to maintain compatibility with older versions.)
If you want to release the pause only for the sounds paused by this function, execute the following code instead:

• criAtomExPlayer_Resume(player, CRIATOMEX_RESUME_PAUSED_PLAYBACK);
  
  By executing this function, all sounds played by the player are paused/resumed.
  In order to individually pause/resume each sound being played, call the criAtomExPlayback_Pause function.

参见

criAtomExPlayer_IsPaused, criAtomExPlayback_Pause, criAtomExPlayer_Resume

criAtomExPlayer_Resume()

void criAtomExPlayer_Resume	(	CriAtomExPlayerHn	player,
		CriAtomExResumeMode	mode
	)

Resume

参数

[in]	player	AtomEx player handle
[in]	mode	resume target

Description:

Resumes paused playback.
Unlike the criAtomExPlayer_Pause function, this function can be used to independently resume the playback of either the audio set in the waiting state by the criAtomExPlayer_Prepare function or the audio paused by the criAtomExPlayer_Pause and criAtomExPlayback_Pause functions.

If you call this function with CRIATOMEX_RESUME_PAUSED_PLAYBACK for the second argument (mode), the audio playback paused by the criAtomExPlayer_Pause or the criAtomExPlayback_Pause functions is resumed.
If you specifiy CRIATOMEX_RESUME_PREPARED_PLAYBACK for the second argument (mode), the audio prepared using the criAtomExPlayer_Prepare function will play.

When the criAtomExPlayer_Prepare function is used to prepare the playback on a player itself paused by the criAtomExPlayer_Pause function, two calls to the resume function, one passing CRIATOMEX_RESUME_PAUSED_PLAYBACK and the other passing CRIATOMEX_RESUME_PREPARED_PLAYBACK, are needed to resume the playback.

Remarks:

Regardless of whether the criAtomExPlayer_Pause function or criAtomExPlayer_Prepare function is used, playback can always be started by specifying CRIATOMEX_RESUME_ALL_PLAYBACK for the second argument (mode) of this function, or by calling criAtomExPlayer_Pause(player, CRI_FALSE) ;.

注意

Executing this function will resume playback of "all" sounds played by the player.
To resume the playback of each sound individually, use the criAtomExPlayback_Resume function instead.

参见

criAtomExPlayback_Resume, criAtomExPlayer_Pause

criAtomExPlayer_IsPaused()

CriBool criAtomExPlayer_IsPaused

(

CriAtomExPlayerHn

player

)

Get the pause status

参数

[in]

player

AtomEx player handle

返回

CriBool pause status (CRI_FALSE = not paused, CRI_TRUE = paused)

Description:

Returns whether a player is paused or not.

注意

This function returns CRI_TRUE only when all sounds on the player are paused.
It will return CRI_FALSE if an individual sound was resumed (by passing its playback ID to the criAtomExPlayback_Pause function) after calling criAtomExPlayer_Pause .

This function does not differentiate between sounds paused by the criAtomExPlayer_Pause function and sounds paused by the criAtomExPlayer_Prepare function.
(The function only determines if all sounds are paused, regardless of the method used.)

参见

criAtomExPlayer_Pause, criAtomExPlayback_Pause

criAtomExPlayer_GetStatus()

CriAtomExPlayerStatus criAtomExPlayer_GetStatus

(

CriAtomExPlayerHn

player

)

Get the player status

参数

[in]

player

AtomEx player handle

返回

CriAtomExPlayerStatus status

Description:

Gets the status of an AtomEx player.
The status indicates in what mode is the AtomEx player. It can have the following five values:

1. CRIATOMEXPLAYER_STATUS_STOP
2. CRIATOMEXPLAYER_STATUS_PREP
3. CRIATOMEXPLAYER_STATUS_PLAYING
4. CRIATOMEXPLAYER_STATUS_PLAYEND
5. CRIATOMEXPLAYER_STATUS_ERROR

When an AtomEx player is created, its status is stopped ( CRIATOMEXPLAYER_STATUS_STOP ).
Once the sound data to play has been specified, a call to the criAtomExPlayer_Start function will change the player status to preparation ( CRIATOMEXPLAYER_STATUS_PREP ).
(In CRIATOMEXPLAYER_STATUS_PREP status, the player is waiting to receive data or to start decoding.)
When there is enough data to start playing, the AtomEx player will switch to playing status ( CRIATOMEXPLAYER_STATUS_PLAYING ) and the sound output will start.
When the playback has completed, the AtomEx player status changes to the play end status ( CRIATOMEXPLAYER_STATUS_PLAYEND ).
If an error occurs during playback, the AtomEx player status changes to ( CRIATOMEXPLAYER_STATUS_ERROR ).

By checking the status of the AtomEx player and switching the process accordingly, it is possble to write a program that takes action based on the sound playback.
For example, the following code can be used to wait for the sound playback to complete before continuing.

main()
{
        :
    // Set the sound data to play
    criAtomExPlayer_SetData(player, buffer, buffer_size);
 
    // Specify the format of the sound data
    criAtomExPlayer_SetFormat(player, CRIATOMEX_FORMAT_ADX);
    criAtomExPlayer_SetNumChannels(player, 1);
    criAtomExPlayer_SetSamplingRate(player, 24000);
 
    // Play the sound data
    criAtomExPlayer_Start(player);
 
    // Wait for the playback completion
    for (;;) {
        // Get the status
        status = criAtomExPlayer_GetStatus(player);
 
        // Check the status
        if (status == CRIATOMEXPLAYER_STATUS_PLAYEND) {
            // Exit loop when the playback is complete
            break;
        }
 
        // Execute the server processing
        criAtomEx_ExecuteMain();
 
        // Refresh screen display etc.
            :
    }
        :
}

参见

criAtomExPlayer_Start

criAtomExPlayer_EnumeratePlaybacks()

void criAtomExPlayer_EnumeratePlaybacks	(	CriAtomExPlayerHn	player,
		CriAtomExPlaybackCbFunc	func,
		void *	obj
	)

Get the number of sounds currently being played back

参数

[in]	player	AtomEx Player Handle
[in]	func	Playback Callback Function
[in]	obj	User-specified objects

Description:

Enumerates the playbacks currently playing on the player.

When this function is executed, the callback function set in the second argument (func) will be called the number of times that playback is in progress.
(The playback ID is passed as an argument to the callback function.)

Remarks:

The value set in the third argument (obj) will be passed as an argument to the callback function.
For other arguments to the callback function, please refer to the separate description of CriAtomExPlaybackCbFunc .

参见

CriAtomExPlaybackCbFunc

criAtomExPlayer_GetNumPlaybacks()

CriSint32 criAtomExPlayer_GetNumPlaybacks

(

CriAtomExPlayerHn

player

)

Get the number of sounds currently playing

参数

[in]

player

AtomEx player handle

返回

CriSint32 number of sounds being played back

Description:

Gets the number of sounds currently being played by a player.

Remarks:

This function returns the number of sounds that have been started using the criAtomExPlayer_Start function and are currently being played back.
(It is not the number of Voices currently in use: when a sequence with multiple waveforms is played it is only counted as one.)
Use the criAtomExVoicePool_GetNumUsedVoices function if you want to get the number of Voices in use.

参见

criAtomExPlayer_Start, criAtomExVoicePool_GetNumUsedVoices

criAtomExPlayer_GetLastPlaybackId()

CriAtomExPlaybackId criAtomExPlayer_GetLastPlaybackId

(

CriAtomExPlayerHn

player

)

Get the playback ID of the last sound played

参数

[in]

player

AtomEX player handle

返回

CriSint32 Playback ID

Description:

Gets the playback ID of the sound that was the last to be played on a player.

Remarks:

参见

criAtomExPlayer_Start

criAtomExPlayer_GetTime()

CriSint64 criAtomExPlayer_GetTime

(

CriAtomExPlayerHn

player

)

Get the playback time

参数

[in]

player

AtomEx player handle

返回

Sint64 playback time (in milliseconds)

Description:

Gets the playback time of the last sound that was played by an AtomEx player.

If the playback time was successfully acquired, this function returns 0 or a larger value.
If the function failed to get playback time (for example if it could not get a Voice), it returns a negative value.

Remarks:

When multiple sounds are played using the same player and this function is called, it returns the playback time of the sound that was played last.
If you want to check the playback time of multiple sounds, you have to create a player for each of them and then call the criAtomExPlayback_GetTime function on each player.

The playback time returned by this function is the time elapsed since the start of playback.
This means that it is never decremented according to the playback position, even when using looping playback or seamless concatenated playback.

When the playback is paused using the criAtomExPlayer_Pause function, the incrementation of the playback time is also stopped.
(The incrementation starts again when the playback is resumed.)
The accuracy of the time that can be obtained by this function depends on the frequency of the server processing.
(The time is updated during the server processing.)
If you need a more accurate time, use the criAtomExPlayback_GetNumPlayedSamples function instead. It returns the exact number of samples that have been played.

注意

Although the type of return value is CriSint64, the accuracy is currently limited to 32 bits.
If you control the playback based on the playback time, note that the time becomes invalid after about 24 days.
(Playback time overflows and becomes a negative value when it exceeds 2147483647 milliseconds.)

When creating an AtomEx player, if you set updates_time in the CriAtomExPlayerConfig structure to CRI_FALSE, it will not be possible to get the playback time from the player.

If the sound being played is stopped by the voice management, the counting of the playback time will be stopped at that point.
In addition, if the voice management didn't allocate a Voice at the time of starting the playback, this function will not return a valid time.
(A negative value will be returned.)

Even if there is a media reading issue and the sound data is temporarily not supplied, the counting of the playback time will not stop.
(The time will continue to be incremented even when the playback is stopped due to a discontinuation of the data supply.)
Therefore, if you synchronize the sound with avideo based on the time acquired by this function, there will be an increasing loss of synchronization with each read-retry.
If you have to strictly synchronize the wave data with video, use the criAtomExPlayback_GetNumPlayedSamples function instead. It will allow you to synchronize based on the number of samples that have been played.

参见

criAtomExPlayback_GetTime, criAtomExPlayback_GetNumPlayedSamples

criAtomExPlayer_SetFormat()

void criAtomExPlayer_SetFormat	(	CriAtomExPlayerHn	player,
		CriAtomExFormat	format
	)

Specify the format of a sound

参数

[in]	player	AtomEx player handle
[in]	format	format

Description:

Specifies the format of a sound played back by an AtomEx player.
This function is one of the functions that narrows down the voices to be acquired when retrieving voices from the voice pool with the criAtomExPlayer_Start function.
This function narrows down the voices to be acquired to those that can play data in the specified format.
In addition to this function, there are also the criAtomExPlayer_SetSamplingRate and criAtomExPlayer_SetNumChannels functions that perform narrowing.

• The default setting before the function is executed is the ADX format.
  

Remarks:

You only need to call this function when you play back sounds without using the information contained in an ACB file.
When playing back a Cue, you do not have to call this function because the format is automatically obtained from the CueSheet.

参见

criAtomExPlayer_SetSamplingRate, criAtomExPlayer_SetNumChannels

criAtomExPlayer_SetNumChannels()

void criAtomExPlayer_SetNumChannels	(	CriAtomExPlayerHn	player,
		CriSint32	num_channels
	)

Specify the number of channels of a sound

参数

[in]	player	AtomEx player handle
[in]	num_channels	number of channels

Description:

Specifies the number of channels of a sound played back by an AtomEx player.
This function is one of the functions that narrows down the voices to be acquired when retrieving voices from the voice pool with the criAtomExPlayer_Start function.
This function narrows down the voices to be acquired to those that can play data for the specified number of channels.
In addition to this function, the criAtomExPlayer_SetFormat function and criAtomExPlayer_SetSamplingRate function also perform the narrowing down function.
The default number of channels is 2 (stereo).

Remarks:

You only need to call this function when you play back sounds without using the information contained in an ACB file.
When playing back a Cue, you do not have to call this function because the format is automatically obtained from the CueSheet.

参见

criAtomExPlayer_SetFormat, criAtomExPlayer_SetSamplingRate

criAtomExPlayer_SetSamplingRate()

void criAtomExPlayer_SetSamplingRate	(	CriAtomExPlayerHn	player,
		CriSint32	sampling_rate
	)

Specify the sampling rate of a sound

参数

[in]	player	AtomEx player handle
[in]	sampling_rate	sampling rate

Description:

Specifies the sampling rate of a sound played back by an AtomEx player.
This function is one of the functions that narrows down the voices to be acquired when retrieving voices from the voice pool with the criAtomExPlayer_Start function.
This function narrows down the voices to be acquired to those that can play data at the specified sampling rate.
In addition to this function, the other functions that narrow down the voices are the criAtomExPlayer_SetFormat function and criAtomExPlayer_SetNumChannels function.
The default sampling rate is set to ::CRIATOM_DEFAULT_OUTPUT_SAMPLING_RATE.

Remarks:

You only need to call this function when you play back sounds without using the information contained in an ACB file.
When playing back a Cue, you do not have to call this function because the format is automatically obtained from the CueSheet.

参见

criAtomExPlayer_SetFormat, criAtomExPlayer_SetNumChannels

criAtomExPlayer_SetSoundRendererType()

void criAtomExPlayer_SetSoundRendererType	(	CriAtomExPlayerHn	player,
		CriAtomSoundRendererType	type
	)

Specify the Sound renderer type

参数

[in]	player	AtomEx player handle
[in]	type	Sound renderer type

Description:

Specifies the sound renderer used to output the sounds played back by the AtomEX player.
When a sound is played via the criAtomExPlayer_Start function, the AtomEx player acquires a Voice from a Voice Pool that outputs the data to the specified sound renderer.
The default value is CRIATOM_SOUND_RENDERER_ANY .

Remarks:

If CRIATOM_SOUND_RENDERER_ANY is specified, the first Voice Pool found will be used for sound playback, regardless of the voice output destination.

参见

CriAtomSoundRendererType

criAtomExPlayer_SetGroupNumber()

void criAtomExPlayer_SetGroupNumber	(	CriAtomExPlayerHn	player,
		CriSint32	group_no
	)

Specify the group number

参数

[in]	player	AtomEx player handle
[in]	group_no	group number

Description:

Specifies the Voice Limit Group from which a Voice is acquired when playing back a sound.
When you pass CRIATOMEXPLAYER_NO_GROUP_LIMITATION for group_no, the player is not restricted by a Voice Limit Group.
(A Voice is acquired irrespective of the Voice Limit Group when a Voice is available or when there is a Voice with a lower priority than itself.)

Remarks:

When the playback is started using the criAtomExPlayer_Start function, if all Voices in the specified Voice Limit Group are in use, whether the played-back sound is heard or not is determined by the voice priority control.
(For details about voice priority, see the description of the criAtomExPlayer_SetVoicePriority function .)

This function, when called while a Cue is being played, overrides the settings of the voice limit group set in the data (the setting value from the data is ignored) .
However, if CRIATOMEXPLAYER_NO_GROUP_LIMITATION is specified for group_no, the voice limit group set on the data side is used.

参见

CRIATOMEXPLAYER_NO_GROUP_LIMITATION, criAtomExPlayer_Start, criAtomExPlayer_SetVoicePriority, criAtomExPlayer_SetVoiceControlMethod

criAtomExPlayer_SetVoiceControlMethod()

void criAtomExPlayer_SetVoiceControlMethod	(	CriAtomExPlayerHn	player,
		CriAtomExVoiceControlMethod	method
	)

Specifying a voice control method

参数

[in]	player	AtomEx player handle
[in]	method	Voice control method

Description:

Sets a voice control method for an AtomEx player.
If you set a voice control method using this function and then play sound using the criAtomExPlayer_Start function, the control method specified with this function is applied to the waveform data played with the player.

The voice control method (method) can be one of the following:

• CRIATOMEX_PREFER_LAST
• CRIATOMEX_PREFER_FIRST
• CRIATOMEX_PREFER_DATA

If a sound of the same priority as the voice that is being played is played when no voice is available, and CRIATOMEX_PREFER_LAST is specified as the voice control method, then the voice that is being played is stopped and playback of a new sound is started.
If CRIATOMEX_PREFER_FIRST is specified under the same conditions, a new playback request is canceled, and playback of the existing voice is continued.

If CRIATOMEX_PREFER_DATA is specified, the voice control method that is preset for the data (the value specified with the authoring tool) is used.
If CRIATOMEX_PREFER_DATA is specified, but a voice control method is not specified for the data, as in single file playback, the voice is controlled on a last-come-first-served basis (CRIATOMEX_PREFER_LAST).

The default value before executing this function is CRIATOMEX_PREFER_DATA. The method that is set for the data is used.

Remarks:

If an AtomEx player plays waveform data and the number of sounds in the voice limit group that the waveform data belongs to reaches the upper limit or all the voices in the voice pool are used, voices are controlled according to their priorities.

The voice control method that is set with this function is used for sound control if the waveform data to play is the same as the waveform data that is being played in priority.
(For more information about voice control according to voice priority, criAtomExPlayer_SetVoicePriority refer to the description of the function.)

参见

criAtomExPlayer_Start, criAtomExPlayer_SetVoicePriority

criAtomExPlayer_SetVoicePoolIdentifier()

void criAtomExPlayer_SetVoicePoolIdentifier	(	CriAtomExPlayerHn	player,
		CriAtomExVoicePoolIdentifier	identifier
	)

Specify the Voice Pool identifier

参数

[in]	player	AtomEx player handle
[in]	identifier	Voice Pool identifier

Description:

Specifies the Voice Pool from which a Voice should be acquired when playing a sound.
After calling this function, the player will only get Voices from the specified Voice Pool.

Remarks:

The default Voice Pool identifier is set to 0.

This parameter is cleared by criAtomExPlayer_ResetParameters function.

参见

CriAtomExStandardVoicePoolConfig, criAtomExVoicePool_AllocateStandardVoicePool, criAtomExPlayer_ResetParameters

criAtomExPlayer_SetHcaMxMixerId()

void criAtomExPlayer_SetHcaMxMixerId	(	CriAtomExPlayerHn	player,
		CriSint32	mixer_id
	)

Specify the mixer ID for HCA-MX decoding

参数

[in]	player	AtomEx player handle
[in]	mixer_id	mixer ID

Description:

Specifies the mixer ID for HCA-MX decoding.

Remarks:

This parameter is cleared by criAtomExPlayer_ResetParameters function.

注意

This function takes effect only when a HCA-MX Voice is used.
(It is ignored when other types of Voices are used.)

The mixer ID must be set before starting playback.
You cannot modify the mixer ID of a sound which has already started to play.

参见

CriAtomExHcaMxVoicePoolConfig, criAtomExVoicePool_AllocateHcaMxVoicePool

criAtomExPlayer_SetAsrRackId()

void criAtomExPlayer_SetAsrRackId	(	CriAtomExPlayerHn	player,
		CriSint32	rack_id
	)

Specifying the ASR Rack ID

参数

[in]	player	AtomEx player handle
[in]	rack_id	ASR Rack ID

Description:

Specifies the ID of the voice output ASR rack.
If you want to specify more than one ASR Rack ID, use the criAtomExPlayer_SetAsrRackIdArray function.

Remarks:

This parameter is cleared by criAtomExPlayer_ResetParameters function.

Calling this function at the time of Cue playback will overwrite the ASR Rack ID setting of the parameter palette set on the data side. (The set values on the data side are ignored.)

注意

This function takes effect only when ASR is used for the sound renderer type of the voice.
(The settings for this function are ignored when other voices are used.)

The ASR Rack ID must be set before starting playback.
You cannot modify the ASR Rack ID for the sound for which playback has already started.

If this function is executed after the criAtomExPlayer_SetAsrRackIdArray function is executed, the multiple ASR Rack ID settings set in the criAtomExPlayer_SetAsrRackIdArray function will be overwritten.

For the sound data encoded for HCA-MX, the settings for this function are not applied.
To set the ID of the output ASR rack for the sound data encoded for HCA-MX, use the criAtomExHcaMx_SetAsrRackId function to set the ID of the output ASR rack for the HCA-MX mixer.

参见

criAtomExAsr_CreateRack, criAtomExPlayer_SetAsrRackIdArray, criAtomExHcaMx_SetAsrRackId, criAtomExPlayer_ResetParameters

criAtomExPlayer_SetAsrRackIdArray()

void criAtomExPlayer_SetAsrRackIdArray	(	CriAtomExPlayerHn	player,
		const CriSint32 *	rack_id_array,
		CriSint32	num_racks
	)

Specifying multiple ASR Rack IDs

参数

[in]	player	AtomEx player handle
[in]	rack_id_array	ASR Rack ID array
[in]	num_racks	ASR Rack ID count

Description:

Specify multiple destination ASR Rack IDs for voice output.
It is possible to specify as many ASR Rack IDs defined for CRIATOMEXPLAYER_MAX_ASR_RACKS.
When specifying a single ASR Rack ID, it can also be specified by using the criAtomExPlayer_SetAsrRackId function.

Remarks:

This parameter is cleared by the criAtomExPlayer_ResetParameters function.

When this function is called during cue playback, the ASR Rack ID setting of the parameter palette set on the data side is overwritten (the setting value on the data side is ignored).

注意

This function is effective only when ASR is used as the sound renderer type of voice.
(When using another voice, the set value of this function is ignored.)

The ASR Rack ID must be set before starting playback.
It is NOT possible to change the ASR Rack ID later for the sound which has already started playback.

When playing a player with multiple ASR Rack IDs, the number of voices will be used as many as the specified ASR Rack ID.
Therefore, it is necessary to reserve the number of voices corresponding to the number of ASR Rack IDs specified in advance.

For playback other than cue playback using the criAtomExPlayer_SetData function etc, only the ASR Rack ID stored in the element of the first (array index 0) among the multiple ASR Rack IDs specified by this function applies It will be.

If you execute this function after the criAtomExPlayer_SetAsrRackId function, the ASR Rack ID setting set by the criAtomExPlayer_SetAsrRackId function is overwritten.

This function setting is not applied to audio data encoded for HCA-MX.
When setting the destination ASR Rack ID for audio data encoded for HCA-MX, use the criAtomExHcaMx_SetAsrRackId function to set the destination ASR Rack ID of the HCA-MX mixer itself.

参见

criAtomExAsr_CreateRack, criAtomExPlayer_SetAsrRackId, criAtomExHcaMx_SetAsrRackId, criAtomExPlayer_ResetParameters

criAtomExPlayer_SetStartTime()

void criAtomExPlayer_SetStartTime	(	CriAtomExPlayerHn	player,
		CriSint64	start_time_ms
	)

Specify the playback starting position

参数

[in]	player	AtomEx player handle
[in]	start_time_ms	starting position (in milliseconds) of the playback

Description:

Specifies the starting position for the sound playback.
If you want to start playing the sound data from another position that the beginning of the sound, you must call this function to specify that position (before starting playback).

The starting position is specified in milliseconds.
For example, if you set start_time_ms to 10000 when calling this function, the player will start playing from 10 seconds within the waveform.

Remarks:

When playing back from the middle of audio data, the timing at which sound begins will be delayed compared to when playing back from the beginning of the audio data.
This is because the header of the audio data is first analyzed, then a jump to the specified position is made, and the data is reread and playback begins.
This parameter is cleared by the criAtomExPlayer_ResetParameters function.

注意

Although it is possible to set a 64-bit value for start_time_ms, only 32 bits are taken into account.

It is not possible to specify a playback starting position for some target-specific sound formats.

When you play back a sequence by specifying a starting position, the wavefdorm data placed before the specified position is not played.
(Each waveform in the sequence is played from the starting position.)

criAtomExPlayer_SetSyncPlaybackId()

void criAtomExPlayer_SetSyncPlaybackId	(	CriAtomExPlayerHn	player,
		CriAtomExPlaybackId	playback_id
	)

Setting the synchronous playback ID

参数

[in]	player	AtomEx player handle
[in]	playback_id	ID of the target playback

Description:

Synchronizes the sound played in the AtomEx player with the sound of the specified playback ID.
When you play a sound after setting the playback ID with this function, playback of the sound is started after seeking the same playback position as the specified playback ID.

Remarks:

If the target playback ID is invalid, playback is started at the beginning of the sound data.
When you specify CRIATOMEX_INVALID_PLAYBACK_ID for playback_id, the playback ID is unregistered.

注意

You can use this function only to play single waveform data.
You cannot use it for sequence data.
(When you use it for sequence data, it synchronizes the first waveform data that is found in the sequence.)

This function can adjust the playback position only for the following codecs:

• ADX
• HCA
• Wave

For other codecs, this function cannot provide synchronous playback.
(This feature cannot be used for HCA-MX and sound codecs that perform hardware decoding.)

This feature synchronizes the playback position on a sample basis whenever possible. We do not guarantee combination without an error of one sample.
(Use this feature only when a difference of milliseconds is acceptable.)
Accuracy of synchronization of the playback positions depends on platforms.

You cannot use this function and the criAtomExPlayer_SetStartTime function at the same time.
When you use this function, the playback start position of a sound is automatically adjusted in the library.
Therefore, you cannot use this function and the criAtomExPlayer_SetStartTime function at the same time.
(The settings for the criAtomExPlayer_SetStartTime function are ignored.)

When you use this function for playback, a noise may occur when playback is started.
When you use this feature, use fade-in whenever possible.

When you use this function for cue playback, you cannot acquire correct playback time by using the criAtomExPlayer_GetTime function or the criAtomExPlayback_GetTime function.
To acquire playback time, use the criAtomExPlayback_GetNumPlayedSamples function instead of these functions.

参见

criAtomExPlayback_GetNumPlayedSamples

criAtomExPlayer_SetPlaybackRatio()

void criAtomExPlayer_SetPlaybackRatio	(	CriAtomExPlayerHn	player,
		CriFloat32	playback_ratio
	)

Set the sequence playback ratio

参数

[in]	player	AtomEx player handle
[in]	playback_ratio	Sequence playback ratio

Description:

Sets the playback ratio for the sequences played by the AtomEx player.
The valid range for the playback ratio is from 0.0f to 2.0f.
If a value outside this range is set, it is clamped back to the valid range.

Remarks:

This parameter is cleared by criAtomExPlayer_ResetParameters function.

注意

The value set by this function is only applied to a sequence-type Cue playback.
It cannot be used for the playback ratio of the waveform data played in a sequence.

参见

criAtomExPlayer_ResetParameters

criAtomExPlayer_LimitLoopCount()

void criAtomExPlayer_LimitLoopCount	(	CriAtomExPlayerHn	player,
		CriSint32	count
	)

Set the the number of loops

参数

[in]	player	AtomEx player handle
[in]	count	number of loops

Description:

Limits the number of times the waveform data will be looped.
For example, when specifying one for the count, the playback of the waveform data is looped only once.
(After reaching the loop-end point, it is returned to the loop start position.)

By default, any audio data that has a loop point is looped infinitely.
After limiting the number of loops, if you want to return to an infinite loop, just specify CRIATOMEXPLAYER_NO_LOOP_LIMITATION for the count.

You can also specify CRIATOMEXPLAYER_IGNORE_LOOP for the count to play wave data while ignoring its loop point.

This parameter is cleared by criAtomExPlayer_ResetParameters function.

注意

You have to specify the number of loops before starting the audio playback.
If you execute this function during the playback, the number of loops you set will be ignored.
To stop the loop at any time, use the seamless concatenated playback.

The number of loops set by this function is only applied when the waveform data contained loop points beforehand.
If no loop points are present in the waveform data, this function will have no effect.

When encoding the waveforms with loop points in CRI Atom Craft or CRI Atom Encoder, the data after the loop-end point is discarded to reduce the data size.
(After looping the specified number of times, playback will stop at the loop end point.)

As an exception, it is possible to play back the data after the loop point in one shot only if the following conditions are met (however, it will not loop).

• The data is encoded with the "-nodelterm" flag by criatomencd.exe.
• The playback is executed after passing CRIATOMEXPLAYER_IGNORE_LOOP to this function.

This function can set the number of loops only for the ADX and the HCA data.
Do not execute this function on data encoded by platform-dependent audio codecs.
(Doing so may result in the playback not finishing, in noise or other issues.)

参见

criAtomExPlayer_ResetParameters

criAtomExPlayer_UpdateAll()

void criAtomExPlayer_UpdateAll

(

CriAtomExPlayerHn

player

)

Update the playback parameters (for all sounds currently playing)

参数

[in]

player

AtomEx player handle

Description:

Assigns the playback parameters (including AISAC control values) set to the AtomEx player to all the sounds it is playing.

Example:

CriFloat32 volume;
// Start playback
criAtomExPlayer_Start(player);
               :
criAtomExPlayer_Start(player);
               :
// Change Volume
volume = 0.3f;
criAtomExPlayer_SetVolume(player, volume);
criAtomExPlayer_UpdateAll(player);

参见

criAtomExPlayer_Update

criAtomExPlayer_Update()

void criAtomExPlayer_Update	(	CriAtomExPlayerHn	player,
		CriAtomExPlaybackId	id
	)

Update the playback parameters (specifying a playback ID)

参数

[in]	player	AtomEx player handle
[in]	id	playback ID

Description:

Assigns the playback parameters (including AISAC control values) set to the AtomEx player to a sound specified by its playback ID.

Example:

CriFloat32 volume;
// Start playback
id = criAtomExPlayer_Start(player);
               :
// Change Volume
volume = 0.3f;
criAtomExPlayer_SetVolume(player, volume);
criAtomExPlayer_Update(player, id);

Remarks:

The playback ID must reference a sound being played back by this AtomEx player.

参见

criAtomExPlayer_UpdateAll

criAtomExPlayer_ResetParameters()

void criAtomExPlayer_ResetParameters

(

CriAtomExPlayerHn

player

)

Reset the playback parameters

参数

[in]

player

AtomEx player handle

Description:

Restore the default values of the AtomEx player playback parameters (including the AISAC control values).
After executing this function, if you call criAtomExPlayer_Start, the sound will be played using the default playback parameters.

Example:

CriFloat32 volume;
// Start playback
id = criAtomExPlayer_Start(player);
               :
// Change Volume
volume = 0.3f;
criAtomExPlayer_SetVolume(player, volume);
criAtomExPlayer_Update(player, id);
               :
// Reset Parameters
criAtomExPlayer_ResetParameters(player);
id = criAtomExPlayer_Start(player);

Remarks:

After calling this function, if you call the criAtomExPlayer_Update or criAtomExPlayer_UpdateAll functions, the parameters of the sound being already played back will not be restored to their initial values.
If you want to modify the parameters of a sound being played, explicitly call functions such as criAtomExPlayer_SetVolume .

Parameters to be reset by this function may or may not be covered by the function to set each parameter, please refer to it.

The parameters of the 3D sound sources and 3D listener are not reset. Only their handles set in the AtomEx player are reset.
If the parameters related to a specific handle should be reset, call the parameter's reset function of that handle.

参见

criAtomEx3dSource_ResetParameters, criAtomEx3dListener_ResetParameters

criAtomExPlayer_GetParameterFloat32()

CriFloat32 criAtomExPlayer_GetParameterFloat32	(	CriAtomExPlayerHn	player,
		CriAtomExParameterId	id
	)

Get the value of a parameter (as a floating point number)

参数

[in]	player	AtomEx player handle
[in]	id	parameter ID

返回

value of the parameter

Description:

Gets the value of a parameter of an AtomEx player.
The value is returned as a floating point number.

参见

CriAtomExParameterId, criAtomExPlayer_GetParameterUint32, criAtomExPlayer_GetParameterSint32

criAtomExPlayer_GetParameterUint32()

CriUint32 criAtomExPlayer_GetParameterUint32	(	CriAtomExPlayerHn	player,
		CriAtomExParameterId	id
	)

Get the value of a parameter (as an unsigned integer)

参数

[in]	player	AtomEx player handle
[in]	id	parameter ID

返回

value of the parameter

Description:

Gets the value of a parameter of an AtomEx player.
The value is returned as an unsigned integer.

参见

CriAtomExParameterId, criAtomExPlayer_GetParameterFloat32, criAtomExPlayer_GetParameterSint32

criAtomExPlayer_GetParameterSint32()

CriSint32 criAtomExPlayer_GetParameterSint32	(	CriAtomExPlayerHn	player,
		CriAtomExParameterId	id
	)

Get the value of a parameter (as a signed integer)

参数

[in]	player	AtomEx player handle
[in]	id	parameter ID

返回

value of the parameter

Description:

Gets the value of a parameter of an AtomEx player.
The value is returned as a signed integer.

参见

CriAtomExParameterId, criAtomExPlayer_GetParameterFloat32, criAtomExPlayer_GetParameterUint32

criAtomExPlayer_SetVolume()

void criAtomExPlayer_SetVolume	(	CriAtomExPlayerHn	player,
		CriFloat32	volume
	)

Set the volume

参数

[in]	player	AtomEx player handle
[in]	volume	volume

Description:

Sets the volume of the sound output of a player.
If you set the volume with this function and then start the playback by calling criAtomExPlayer_Start, the new sound will be played back at the specified volume.
You can also call the criAtomExPlayer_Update or criAtomExPlayer_UpdateAll functions after executing this function to update the volume of the sounds that are already playing.

Volume is a simple scaling factor for the amplitude of the waveform data (it is not expressed in decibels).
For example, if you specify 1.0f, the sound will be output with its volume unchanged.
If you specify 0.5f, it will be output at half the original volume (-6dB).

• If you specify 0.0f, the sound is muted (silent).
  The default volume is 1.0f.
  

Example:

  ：
// Set the Volume
criAtomExPlayer_SetVolume(player, 0.5f);
 
// Start the playback
// Remarks: The playback volume used is the value set to the player (0.5f). 
id = criAtomExPlayer_Start(player);
  ：
// Change the volume
// Note: The volume of the sounds currently playing is not affected at this point 
criAtomExPlayer_SetVolume(player, 0.3f);
 
// Apply the volume set to the player to the sounds currently playing
criAtomExPlayer_Update(player, id);
  ：

Remark:

A volume value higher than 1.0f can be specified (from version 1.21.07 of the CRI Atom library).
When specifying a value over 1.0f, it is possible that the waveform will be played at a volume greater than supported by the platform.
If you pass a negative value for the volume, it will be changed to 0.0f.
(Passing a negative volume value is not a way to inverse the phase.)
If you specify a value less than 0.0f for the volume value, the value will be clipped to 0.0f.
(Even if you set the volume value to a negative value, the phase of the waveform data will not be inverted.)

When playing a Cue, the volume has also been set on the data side (i.e. within the authoring tool). In that case, the final volume value will be the volume from the data side multiplied by the volume set with this function.
For example, if the data side volume is 0.8f and the AtomEx player volume is 0.5f, the volume actually applied will be 0.4f.

If you have a volume in decibels, you can convert it to a scaling factor using this formula:

volume = powf(10.0f, db_vol / 20.0f);

• db_vol is a decibel value, and volume is the scaling value.

Remarks:

This parameter is cleared by criAtomExPlayer_ResetParameters function.

注意

When specifying a volume over 1.0f, the following points should be considered:

• The behavior may differ on each platform.
• Crackling sounds may occur.

Even when specifying a volume over 1.0f, whether or not the sound will be played at a volume higher than the source waveform depends on the platform or the audio compression codec.
Therefore, when adjusting the volume on a multi-platform title, it is recommended to not use a volume over 1.0f.
(When specifying a volume over 1.0f, the same waveform may be played at different volumes depending on the platforms.)

Moreover, even on platforms where the volume can be increased, the hardware itself has a limit above which noise or crackling may be generated.

参见

criAtomExPlayer_Start, criAtomExPlayer_Update, criAtomExPlayer_UpdateAll, criAtomExPlayer_ResetParameters

criAtomExPlayer_SetPitch()

void criAtomExPlayer_SetPitch	(	CriAtomExPlayerHn	player,
		CriFloat32	pitch
	)

Set the pitch (detune)

参数

[in]	player	AtomEx player handle
[in]	pitch	pitch (cents)

Description:

If you set the pitch (detune) with this function and
then start the playback by calling criAtomExPlayer_Start, the new sound will be played back with the adjusted pitch.
You can also call the criAtomExPlayer_Update or criAtomExPlayer_UpdateAll functions after executing this function to update the pitch of the sounds that are already playing.

The pitch (detune) is specified in cents.
A cent is 1/1200th of an octave. A half-tone is equal to 100 cents.
For example, if you specify 100.0f, the pitch will be raised by half a tone. If you specify -100.0f, the pitch will be lowered by half a tone.
The default pitch is 0.0f (i.e. no detune).

Example:

    ：
// Set the pitch
criAtomExPlayer_SetPitch(player, 100.0f);
 
// Start the playback
// Remarks: The pitch used is the value set to the player (0.5f). 
id = criAtomExPlayer_Start(player);
    ：
// Change the pitch
// Note: The pitch of the sounds currently playing is not affected at this point 
criAtomExPlayer_SetPitch(player, -200.0f);
 
// Apply the pitch set to the player to the sounds currently playing
criAtomExPlayer_Update(player, id);
    ：

Remark:

During cue playback, if you call this function while a pitch is already set in the data, the final pitch will be the value set in the data added to the value set by the function.
For example, if the pitch in the data is -100.0f and the pitch in the AtomEx player is 200.0f, the actual pitch is 100.0f.
If you want to set the pitch as a frequency ratio of the sampling rate, use the following formula:

pitch = 1200.0f*logf(freq_ratio)/logf(2.0f);

• pitch is the value of the pitch; freq_ratio is the frequency ratio.
  This parameter is cleared by criAtomExPlayer_ResetParameters function.

注意

You cannot change the pitch of any sound data that is encoded with HCA-MX.
(Even if this function is executed, the pitch will not change.)
If you want to change the pitch of a sound, use another codec such as ADX or HCA to encode the sound.

The maximum configurable pitch change depends on the sampling rate of the sound data and the maximum sampling rate of the voice pool.
For example, if the sampling rate of the sound data is 24 kHz and the maximum sampling rate of the voice pool is 48 kHz, the maximum configurable pitch is 1200 (the frequency ratio is 2:1).

Since the pitch is changed by increasing or decreasing the playback sampling rate, the playback speed also changes when you change the pitch.

参见

criAtomExPlayer_Start, criAtomExPlayer_Update, criAtomExPlayer_UpdateAll, criAtomExPlayer_SetMaxPitch, criAtomExPlayer_ResetParameters

criAtomExPlayer_SetMaxPitch()

void criAtomExPlayer_SetMaxPitch	(	CriAtomExPlayerHn	player,
		CriFloat32	pitch
	)

Setting the maximum pitch

参数

[in]	player	AtomEx player handle
[in]	pitch	pitch (cents)

Description:

Sets the maximum pitch of the sound.
By specifying the maximum pitch with this function, pitch change within the specified range will be reflected immediately.

Remarks:

In previous CRI Atom library versions, pitch increasing might cause interuption of playback. (Sound data supplying could not catch up the playback speed.)
CRI Atom library ver.2.10.00 fixed this problem. In this new implementation,
enough size of sound data is buffered before pitch shift processing.
With this fix, the pitch manipulations no longer break up the sound, but the pitch change may be slower than in the previous version because the pitch change is delayed by the amount of time it takes to wait for buffering when raising the pitch.
(So, if pitch shift processing run many times in short period, strange noise may be made.)
If you set the maximum pitch in advance with this function, buffering will always be performed assuming the specified speed, so pitch changes will occur immediately (for frequencies within the specified range) without buffering.
If you want to raise or lower the pitch in a short period of time, set the expected maximum pitch in advance with this function before playing.

This parameter is cleared by criAtomExPlayer_ResetParameters function.

参见

criAtomExPlayer_SetPitch, criAtomExPlayer_ResetParameters

criAtomExPlayer_SetPan3dAngle()

void criAtomExPlayer_SetPan3dAngle	(	CriAtomExPlayerHn	player,
		CriFloat32	pan3d_angle
	)

Set the panning 3D angle

参数

[in]	player	AtomEx player handle
[in]	pan3d_angle	panning 3D angle (from -180.0f to 180.0f degrees)

Description:

Sets the panning 3D angle.
After setting the 3D panning angle with this function, when you start playback with the criAtomExPlayer_Start function, it will be played at the 3D panning angle that you set.
After setting this, you can update the 3D panning angle of audio that has already been played by calling the criAtomExPlayer_Update function and the criAtomExPlayer_UpdateAll function.

Specify the angle in degrees.
The front is 0 degree. You can specify an angle from -180.0f in the left direction (counterclockwise) to 180.0f in the right direction (clockwise).
For example, if you specify 45.0f, the sound is located at 45 degrees of the front, on the right. If you specify -45.0f, the sound is located at 45 degrees of the front, on the left.

Example:

    ：
// Set the panning 3D angle
criAtomExPlayer_SetPan3dAngle(player, 45.0f);
 
// Start the playback
// Note: The value that is set in the player (=45.0f) is used for the panning 3D angle.
id = criAtomExPlayer_Start(player);
    ：
// Change the panning 3D angle
// Note: The panning 3D angle of the sound that is being played is not changed here.
criAtomExPlayer_SetPan3dAngle(player, -45.0f);
 
// The panning 3D angle that is set in the player is now used.
criAtomExPlayer_Update(player, id);
    ：

Remarks:

During cue playback, if you call this function while the panning 3D angle is already set in the data, the final panning 3D angle will be the value set in the data added to the value set by this function.
For example, when the panning 3D angle in the data is 15.0f and the one set by this function is 30.0f, the actual panning 3D angle will be 45.0f.
When the panning 3D angle exceeds 180.0f, 360.0f is subtracted from the value so that it stays within the range.
Similarly, if the actual volume is smaller than -180.0f, 360.0f is added to the value so that it stays within the range as well.
(Since the position of the sound does not change when 360.0f is added or subtracted, you can set the value beyond the range going from -180.0f to 180.0f.)
This parameter is cleared by criAtomExPlayer_ResetParameters function.

参见

criAtomExPlayer_Start, criAtomExPlayer_Update, criAtomExPlayer_UpdateAll, criAtomExPlayer_ResetParameters

criAtomExPlayer_SetPan3dInteriorDistance()

void criAtomExPlayer_SetPan3dInteriorDistance	(	CriAtomExPlayerHn	player,
		CriFloat32	pan3d_interior_distance
	)

Set the panning 3D distance

参数

[in]	player	AtomEx player handle
[in]	pan3d_interior_distance	panning 3D distance (from -1.0f to 1.0f)

Description:

Sets the distance for the interior panning in panning 3D.
After setting the panning 3D distance with this function, when you start playback with the criAtomExPlayer_Start function, it will be played at the set panning 3D distance.
After setting this, you can also call the criAtomExPlayer_Update and criAtomExPlayer_UpdateAll functions to update the 3D panning distance of audio that has already been played.
The distance to the listener is 0.0f and the distance to the circumference on which the speakers are placed is 1.0f. You can specify a value from -1.0f to 1.0f.
If a negative value is specified, the panning 3D angle is inverted by 180 degrees and the direction is reversed.

Example:

    ：
// Set the panning 3D distance
criAtomExPlayer_SetPan3dInteriorDistance(player, 0.5f);
 
// Start the playback
// Note: The value that is set in the player (=0.5f) is used for the panning 3D distance.
id = criAtomExPlayer_Start(player);
    ：
// Change the panning 3D distance
// Note: The panning 3D distance of the sound that is being played is not changed here.
// Note: The following process is equal to reversing the panning 3D angle by 180 degrees.
criAtomExPlayer_SetPan3dInteriorDistance(player, -0.5f);
 
// The panning 3D distance that is set in the player is now used for the sound already being played.
criAtomExPlayer_Update(player, id);
    ：

Remarks:

During cue playback, if you call this function while the panning 3D distance is set in the data, the final panning 3D distance will be the value set in the data multiplied by the value set by this function.
For example, when the panning 3D distance in the data is 0.8f and the one in the AtomEx player is 0.5f, the actual panning 3D distance is 0.4f.
If the actual panning 3D distance exceeds 1.0f, the value is clamped to 1.0f.
Similarly, if the actual panning 3D distance is over -1.0f, the value is clamped to -1.0f.

This parameter is cleared by criAtomExPlayer_ResetParameters function.

参见

criAtomExPlayer_Start, criAtomExPlayer_Update, criAtomExPlayer_UpdateAll, criAtomExPlayer_ResetParameters

criAtomExPlayer_SetPan3dVolume()

void criAtomExPlayer_SetPan3dVolume	(	CriAtomExPlayerHn	player,
		CriFloat32	pan3d_volume
	)

Set the panning 3D volume

参数

[in]	player	AtomEx player handle
[in]	pan3d_volume	panning 3D volume (from 0.0f to 1.0f)

Description:

Sets the panning 3D volume.
After setting the panning 3D volume with this function, when playback is started with the criAtomExPlayer_Start function, playback will be performed with the set panning 3D volume.
After setting, you can also update the panning 3D volume of audio that has already been played by calling the criAtomExPlayer_Update function and criAtomExPlayer_UpdateAll function.

The panning 3D volume is used to control the panning 3D component and the output level of the center/LFE separately.
For example, you may want to use the send level to output at a fixed volume for the LFE and to use panning 3D to control the orientation.
The range and handling of the panning 3D volume is the same than for a normal volume. See the criAtomExPlayer_SetVolume function.

Example:

    ：
// Set the panning 3D volume
criAtomExPlayer_SetPan3dVolume(player, 0.8f);
 
// Start the playback
// Note: The value that is set in the player (=0.5f) is used for the panning 3D volume.
id = criAtomExPlayer_Start(player);
    ：
// Change the panning 3D volume
// Note: The panning 3D volume of the sound that is being played is not changed here. 
criAtomExPlayer_SetPan3dVolume(player, 0.7f);
 
// The panning 3D volume that is set in the player is now used for the sound already being played.
criAtomExPlayer_Update(player, id);
    ：

Remarks:

This parameter is cleared by criAtomExPlayer_ResetParameters function.

参见

criAtomExPlayer_Start, criAtomExPlayer_Update, criAtomExPlayer_UpdateAll, criAtomExPlayer_SetVolume, criAtomExPlayer_ResetParameters

criAtomExPlayer_SetPanType()

void criAtomExPlayer_SetPanType	(	CriAtomExPlayerHn	player,
		CriAtomExPanType	pan_type
	)

Set the pan type

参数

[in]	player	AtomEx player handle
[in]	pan_type	pan type

Description:

Sets the pan type.
If you specify the pan type with this function and then start the playback with the criAtomExPlayer_Start function, the sound is played using the specified pan type.
After specifying the pan type, you can call the criAtomExPlayer_Update function or the criAtomExPlayer_UpdateAll function to update the pan type of a sound that is already being played.

Remarks:

If you call this function during cue playback, the pan type that is set in the data is overwritten (the value in the data is ignored).
Usually, you do not need to call this function, because the pan type is set in the data.
If you want to enable 3D positioning when a sound is played without using an ACB file, call this function by passing CRIATOMEX_PAN_TYPE_3D_POS to specify the Pos3d mode.
This parameter is cleared by criAtomExPlayer_ResetParameters function.

注意

If you run with CRIATOMEX_PAN_TYPE_UNKNOWN , you will get an error.

参见

criAtomExPlayer_Start, criAtomExPlayer_Update, criAtomExPlayer_UpdateAll, CriAtomExPanType, criAtomExPlayer_ResetParameters

criAtomExPlayer_GetPanTypeOnPlayback()

CriAtomExPanType criAtomExPlayer_GetPanTypeOnPlayback

(

CriAtomExPlayerHn

player

)

Get pan type during player playback

参数

[in]

player

AtomEx Player Handle

返回

CriAtomExPanType Pan type during player playback

Description:

Gets the pan type when playing on the player.
This function returns the pan type according to the pan type set by the criAtomExPlayer_SetPanType function.
If the setting function is not called, the type will depend on the data setting value, so CRIATOMEX_PAN_TYPE_UNKNOWN will be returned.

Remarks:

If CRIATOMEX_PAN_TYPE_AUTO is set, the pan type returned will change according to the following:

• CriAtomExConfig::enable_auto_matching_in_pan_type_auto setting
• Whether CriAtomEx3dListenerHn is set
• Whether CriAtomEx3dSourceHn is set
• Whether CriAtomEx3dSourceListHn is set

参见

criAtomExPlayer_SetPanType

criAtomExPlayer_SetPanSpeakerType()

void criAtomExPlayer_SetPanSpeakerType	(	CriAtomExPlayerHn	player,
		CriAtomExPanSpeakerType	pan_speaker_type
	)

Output speaker type setting when panning

参数

[in]	player	AtomEx player handle
[in]	pan_speaker_type	type of speaker output (used for panning)

Description:

Sets the type of the speaker output (used for panning).
After setting the output speaker type for panning with this function, when playback is started with the criAtomExPlayer_Start function, panning will be calculated with the set output speaker type.
After setting this, you can update the output speaker type for sounds that have already been played by calling the criAtomExPlayer_Update function or the criAtomExPlayer_UpdateAll function.

Remarks:

The parameter passed to this function affects the panning calculation in both pan 3D and 3D positioning modes.
The default value at the library initialization is 4ch panning (CRIATOMEX_PAN_SPEAKER_TYPE_4CH).
It can be changed by the criAtomExPlayer_ChangeDefaultPanSpeakerType function.
In the case of platforms with stereo output, the sound is eventually mixed down to stereo, irrespective of the selection.

Since this parameter cannot be set on the data side, the value passed to this function is always applied as it is.

This parameter is cleared by criAtomExPlayer_ResetParameters function.

参见

criAtomExPlayer_Start, criAtomExPlayer_Update, criAtomExPlayer_UpdateAll, CriAtomExPanSpeakerType, criAtomExPlayer_ResetParameters

criAtomExPlayer_AddMixDownCenterVolumeOffset()

void criAtomExPlayer_AddMixDownCenterVolumeOffset	(	CriAtomExPlayerHn	player,
		CriFloat32	mixdown_center_volume_offset
	)

Setting MixDownCenter volume offset value

参数

[in]	player	AtomEx player handle
[in]	mixdown_center_volume_offset	MixDownCenter Volume offset value

Description:

Set the volume value to mix signals that are not Center or LFE to monaural and output to Center.
The setting value by this function is added and applied to the data setting value by the CRI Atom Craft.
For the second argument of this function, set 0 to 1 floating point value as output volume.

注意

Valid setting outside the set value is not confirmed. Please pay attention to the following points when setting out of range.
A value larger than 1: Clipping noise etc. may occur due to amplification of the output amplitude value.
Negative value: When the sum with the data setting value becomes negative, the result of inverting the phase with respect to the positive result is output.

参见

criAtomExPlayer_Start, criAtomExPlayer_Update, criAtomExPlayer_UpdateAll, CriAtomExPanSpeakerType, criAtomExPlayer_ResetParameters

criAtomExPlayer_AddMixDownLfeVolumeOffset()

void criAtomExPlayer_AddMixDownLfeVolumeOffset	(	CriAtomExPlayerHn	player,
		CriFloat32	mixdown_lfe_volume_offset
	)

Setting MixDownLFE volume offset value

参数

[in]	player	AtomEx player handle
[in]	mixdown_lfe_volume_offset	MixDownLFE Volume offset value

Description:

Set the volume value to mix signals that are not Center or LFE to monaural and output to LFE.
The setting value by this function is added and applied to the data setting value by the CRI Atom Craft.
For the second argument of this function, set 0 to 1 floating point value as output volume.

注意

Valid setting outside the set value is not confirmed. Please pay attention to the following points when setting out of range.
A value larger than 1: Clipping noise etc. may occur due to amplification of the output amplitude value.
Negative value: When the sum with the data setting value becomes negative, the result of inverting the phase with respect to the positive result is output.

参见

criAtomExPlayer_Start, criAtomExPlayer_Update, criAtomExPlayer_UpdateAll, CriAtomExPanSpeakerType, criAtomExPlayer_ResetParameters

criAtomExPlayer_ChangeDefaultPanSpeakerType()

void criAtomExPlayer_ChangeDefaultPanSpeakerType

(

CriAtomExPanSpeakerType

pan_speaker_type

)

Changing the default output speaker type for panning

参数

[in]

pan_speaker_type

Output speaker type for panning

Description:

Changes the default output speaker type for panning.
For all the AtomEx players to which the criAtomExPlayer_SetPanSpeakerType function is not executed, the output speaker type that is set with this function is used for playback.

Remarks:

The setting in this function affects the panning calculation in pan 3D and 3D positioning.
The default value when the library is initialized is 4 ch panning (CRIATOMEX_PAN_SPEAKER_TYPE_4CH).
For a stereo speaker platform, sounds are eventually mixed down to stereo, irrespective of the selection.

Because this parameter cannot be set for data, the setting in this function is always applied.

注意

When the sound that is being played references the default value depends on user operation.
Therefore, if the default value is changed during playback, the change may not be reflected at an expected timing.
If you use this function, execute it before playing sounds, such as at initialization.

参见

criAtomExPlayer_SetPanSpeakerType, CriAtomExPanSpeakerType

criAtomExPlayer_OverrideDefaultPanMethod()

void criAtomExPlayer_OverrideDefaultPanMethod	(	CriAtomExPlayerPanCbFunc	func,
		void *	obj
	)

Override the default panning process

参数

[in]	func	Panning Functions
[in]	obj	User-specified objects

Description:

Replace the panning process with your own.

Remarks:

When you register a panning function with this function, the Atom library's panning process is disabled, and the behavior is changed so that the callback function specified by the user is called when panning.
By manipulating the send level matrix within the callback, it is possible to use the user's own panning algorithm.

参见

CriAtomExPlayerPanCbFunc

criAtomExPlayer_SetPanAngleType()

void criAtomExPlayer_SetPanAngleType	(	CriAtomExPlayerHn	player,
		CriAtomExPanAngleType	pan_angle_type
	)

Panning angle type setting

参数

[in]	player	AtomEx Player Handle
[in]	pan_angle_type	Panning angle type

Description:

Specifies the angle type when panning.
The angle type indicates the angle at which each input channel is treated when panning multi-channel (stereo, 5.1ch, etc.) audio material.
After setting the angle type when panning with this function, when playback is started with the criAtomExPlayer_Start function, panning will be calculated with the set angle type.
After setting the angle type, you can update the angle type of audio that has already been played by calling the criAtomExPlayer_Update function or the criAtomExPlayer_UpdateAll function.

Remarks:

The setting of this function affects panning calculations in Pan 3D and 3D positioning.
The default value is an offset (CRIATOMEX_PAN_ANGLE_TYPE_OFFSET).
This function is mainly used for compatibility with CRI Audio. By setting CRIATOMEX_PAN_ANGLE_TYPE_FIX in this function, the behavior will be the same as the Pan 3D calculations in CRI Audio.

Since this parameter cannot be set on the data side, the value passed to this function is always applied as it is.

This parameter is cleared by criAtomExPlayer_ResetParameters function.

参见

criAtomExPlayer_Start, criAtomExPlayer_Update, criAtomExPlayer_UpdateAll, CriAtomExPanAngleType, criAtomExPlayer_ResetParameters

criAtomExPlayer_SetWideness()

void criAtomExPlayer_SetWideness	(	CriAtomExPlayerHn	player,
		CriFloat32	wideness
	)

Set the sound spread during panning

参数

[in]	player	AtomEx player handle
[in]	spread	Multi-channel sound spread

Description:

Sets the sound spread used for panning calculations.
The spread specifies the angular distance between each input channel when panning multi-channel sound materials (stereo, 5.1 ch, etc.).
The valid range for the spread goes from 0.0 to 1.0, the default value being 1.0.
For example, if a stereo sound is played with a spread of 0.5, panning calculations would localize the left channel at -15 degrees from the front (-30 degrees * 0.5) and the right channel at 15 degrees (30 degrees * 0.5).
This setting does not affect mono sounds.

Remarks:

If you specify the spread with this function and then start the playback by calling criAtomExPlayer_Start, the panning of the new sound will be calculated based on the specified spread.
After specifying the spread, you can also call the criAtomExPlayer_Update or the criAtomExPlayer_UpdateAll functions to update spread of the sounds that were already being played.

This parameter is cleared by the criAtomExPlayer_ResetParameters function.

参见

criAtomExPlayer_Start, criAtomExPlayer_Update, criAtomExPlayer_UpdateAll, criAtomExPlayer_ResetParameters, criAtomExPlayer_SetSpread

criAtomExPlayer_SetSpread()

void criAtomExPlayer_SetSpread	(	CriAtomExPlayerHn	player,
		CriFloat32	spread
	)

Spread Settings

参数

[in]	player	AtomEx Player Handle
[in]	spread	Spread

Description:

Specifies the spread.
Spread is a parameter that controls the sense of positioning of the sound source.
The value range of the argument spread is 0.0 to 1.0. The default value is 0.0.
The larger the spread value, the weaker the sense of positioning of the sound image.
For example, an audio placed at -30 degrees will be output only from the L speaker in the default setting (spread value is 0).
If you change the spread value, the audio will be output not only from the L speaker but also from multiple surrounding speakers.
Unlike the criAtomExPlayer_SetWideness function, it can also be applied to mono sound sources.

Remarks:

After setting the panning angle type with this function, when playback is started with the criAtomExPlayer_Start function, panning will be calculated with the set spread.
After setting this, you can update the spread of sounds that have already been played by calling the criAtomExPlayer_Update function and the criAtomExPlayer_UpdateAll function.

This parameter is cleared by criAtomExPlayer_ResetParameters function.

参见

criAtomExPlayer_Start, criAtomExPlayer_Update, criAtomExPlayer_UpdateAll, criAtomExPlayer_ResetParameters, criAtomExPlayer_SetWideness

criAtomExPlayer_SetSendLevel()

void criAtomExPlayer_SetSendLevel	(	CriAtomExPlayerHn	player,
		CriSint32	ch,
		CriAtomExSpeakerId	spk,
		CriFloat32	level
	)

Set a send level

参数

[in]	player	AtomEx player handle
[in]	ch	channel number
[in]	spk	speaker ID
[in]	level	send level value (from 0.0f to 1.0f)

Description:

Specifies the send level.
Send level is a mechanism for specifying the volume at which each channel of audio data is output from which speaker.
If you specify the send level with this function and then start the playback with the criAtomExPlayer_Start function, the sound is played with the specified send level.
After specifying the send level, you can call the criAtomExPlayer_Update or the criAtomExPlayer_UpdateAll functions to update the send level of a sound that is already being played.

The second argument (channel number) specifies the channel number for the sound data.
The third argument (speaker ID) specifies the speaker to which the data for the specified channel number is sent. The fourth argument specifies the send level (volume).
For example, if you want to play channel 0 of the sound data on the right speaker at full volume (1.0f), call this function as follows:

criAtomExPlayer_SetSendLevel(player, 0, CRIATOMEX_SPEAKER_FRONT_RIGHT, 1.0f);

The range and handling of the send level value is the same than for the volume. See the criAtomExPlayer_SetVolume function.

In a platform with a center speaker, if you want to send mono sounds only to the center speaker, it is recommended to call criAtomExPlayer_SetPanSpeakerType instead of this function and pass CRIATOMEX_PAN_SPEAKER_TYPE_5CH for the parameter.

Example:

CriSint32 ch = 0;   // channel number 0
CriAtomExSpeakerId spk = CRIATOMEX_SPEAKER_FRONT_CENTER;
CriFloat32 level = 1.0f;
// Set send level(ch0 to center)
criAtomExPlayer_SetSendLevel(player, ch, spk, level);
// Start playback
id = criAtomExPlayer_Start(player);
               :
// Change send level
level = 0.7f;
criAtomExPlayer_SetSendLevel(player, ch, spk, level);
criAtomExPlayer_Update(player, id);

Remarks:

Two types of send level settings are available: "automatic setting" and "manual setting."
Immediately after an AtomEx player is created or if a parameter is cleared with the criAtomExPlayer_ResetParameters function, the send level setting is "automatic setting."
On the other hand, when this function is executed, the send level is set to "manual setting."
(The user must control the send level to each speaker to perform panning.)

In "automatic setting," the AtomEx player assigns the sound as follows:

[When playing back monaural sound]
The sound on channel 0 is output from the right and left speakers at a volume of 0.7f (-3dB).

[When playing back stereo sound]
The sound on channel 0 is output from the left speaker, and the sound on channel 1 is output from the right speaker.

[When playing 4 channel sound]
The sound for channel 0 is output from the left speaker, and the sound for channel 1 is output from the right speaker. The sound for channel 2 is output from the surround left speaker, and the sound for channel 3 is output from the surround right speaker.

[When playing 5.1 channel sound]
The sound for channel 0 is output from the left speaker, and the sound for channel 1 is output from the right speaker. The sound for channel 2 is output from the center speaker, and the sound for channel 3 is output from the LFE. The sound for channel 4 is output from the surround left speaker, and the sound for channel 5 is output from the surround right speaker.

[When playing 7.1 ch sound]
The sound for channel 0 is output from the left speaker, and the sound for channel 1 is output from the right speaker. The sound for channel 2 is output from the center speaker, and the sound for channel 3 is output from the LFE. The sound for channel 4 is output from the surround left speaker, and the sound for channel 5 is output from the surround right speaker.
The sound for channel 6 is output from the surround back left speaker, and the sound for channel 7 is output from the surround back right speaker.

On the other hand, when this function was used for "manual setting", the sound is sent with the specified send level setting regardless of the number of sound data channels.
(You must switch send level settings as required depending on the number of sound data channels.)

If you want to clear the specified send level and restore routing to "automatic setting", execute the criAtomExPlayer_ResetParameters function.

The value set in this function is always used, because this parameter cannot be set from the data side (i.e. within the tool).

注意

If no send level is set for a chanel, no sound is output.
For example, when the sound data is stereo but a send level is set only for one of the channels, the sound of the other channel is muted.
If you want to control the send levels manually, be sure to set the send levels for all the channels that you want to output.

When this function is used to set the send level, the pan 3D and 3D positioning settings are ignored.

参见

criAtomExPlayer_Start, criAtomExPlayer_Update, criAtomExPlayer_UpdateAll, criAtomExPlayer_SetVolume, criAtomExPlayer_SetPanSpeakerType, criAtomExPlayer_ResetParameters

criAtomExPlayer_SetBusSendLevelByName()

void criAtomExPlayer_SetBusSendLevelByName	(	CriAtomExPlayerHn	player,
		const CriChar8 *	bus_name,
		CriFloat32	level
	)

Setting the bus send level

参数

[in]	player	AtomEx player handle
[in]	bus_name	Bus name
[in]	level	Send level value (0.0f to 1.0f)

Description:

Sets the bus send level.
A bus send level specifies the sound is sent to which bus at which level.
When playback is started with the criAtomExPlayer_Start function after this function is used to set the bus send level, the sound is played at the specified bus send level.
After the setting, you can call the criAtomExPlayer_Update function or the criAtomExPlayer_UpdateAll function to update the bus send level of the sound that has already been played.
If you call this function during Cue playback when the bus send level is set in the data, the value obtained by multiplying the value set in the data with the value set with this function is applied.

For the second argument, specify the bus name in the DSP bus setting.
For the third argument, specify the send level (volume).

If the bus specified as the bus name for the second argument does not exist in the applied DSP bus setting, the setting value is handled as an invalid value.
The range and handling of the send level is the same as the volume. See the criAtomExPlayer_SetVolume function.

Example:

 :
// Set bus send level
cosnt CriChar8* bus_name = "Reverb";
CriFloat32 level = 0.3f;
criAtomExPlayer_SetBusSendLevelByName(player, bus_name, level);
 
// Start playback
id = criAtomExPlayer_Start(player);
 :
// Change parameters
// Note: The parameters for the sound that is being played are not changed at this time.
level = 0.5f;
criAtomExPlayer_SetBusSendLevelByName(player, bus_name, level);
 
// Reflect the parameters that are set for the player also on the sound that is being played
criAtomExPlayer_Update(player, id);
 :

Remarks:

You can send the sound to multiple buses by specifying different bus names and calling this function several times.

This parameter is cleared by criAtomExPlayer_ResetParameters function.

参见

criAtomExPlayer_Start, criAtomExPlayer_Update, criAtomExPlayer_UpdateAll, criAtomExPlayer_SetVolume, criAtomExPlayer_ResetParameters

criAtomExPlayer_ResetBusSends()

void criAtomExPlayer_ResetBusSends

(

CriAtomExPlayerHn

player

)

Resetting Bus Send Levels

参数

[in]

player

AtomEx Player Handle

Description:

Resets the bus send information set in the AtomEx player and returns it to the initial state (unset state).

参见

criAtomExPlayer_SetBusSendLevelByName

criAtomExPlayer_GetBusSendLevelByName()

CriBool criAtomExPlayer_GetBusSendLevelByName	(	CriAtomExPlayerHn	player,
		const CriChar8 *	bus_name,
		CriFloat32 *	level
	)

Get Bus Send Level

参数

[in]	player	AtomEx Player Handle
[in]	bus_name	Bus name
[out]	level	Bus send level value (0.0f to 1.0f)

返回

CriBool Was the bus send level value obtained? (Obtained: CRI_TRUE / Not obtained: CRI_FALSE)

Description:

Retrieves the specific bus send level that is set for the specified AtomEx player.

The second argument specifies the bus name in the DSP bus settings.

Note that retrieval of the bus send level will fail if any of the following cases apply.

• The bus specified in the second argument bus name does not exist in the applied DSP bus settings.
• The bus send level for the second argument bus name has not been set in the AtomEx player specified in the first argument.

参见

criAtomExPlayer_SetBusSendLevelByName

criAtomExPlayer_SetBusSendLevelOffsetByName()

void criAtomExPlayer_SetBusSendLevelOffsetByName	(	CriAtomExPlayerHn	player,
		const CriChar8 *	bus_name,
		CriFloat32	level_offset
	)

Setting the bus send level (by specifying the offset)

参数

[in]	player	AtomEx player handle
[in]	bus_name	Bus name
[in]	level_offset	Send level value (0.0f to 1.0f)

Description:

Specifies the bus send level with its offset.
If you call this function during Cue playback when the bus send level is set in the data, the value obtained by adding the value set in the data to the value set with this function is applied.
The other specifications are the same as for the ::criAtomExPlayer_SetBusSendLevel function.

Remarks:

By setting 0.0f with the ::criAtomExPlayer_SetBusSendLevel function and setting the offset value with this function,
you can ignore the bus send level that is set in the data and set a new level. (Overwriting)

This parameter is cleared by criAtomExPlayer_ResetParameters function.

参见

criAtomExPlayer_SetBusSendLevel, criAtomExPlayer_ResetParameters

criAtomExPlayer_GetBusSendLevelOffsetByName()

CriBool criAtomExPlayer_GetBusSendLevelOffsetByName	(	CriAtomExPlayerHn	player,
		const CriChar8 *	bus_name,
		CriFloat32 *	level_offset
	)

Get Bus Send Level Offset

参数

[in]	player	AtomEx Player Handle
[in]	bus_name	Bus name
[out]	level_offset	Bus send level offset value (0.0f to 1.0f)

返回

CriBool Was the bus send level offset value obtained? (Obtained: CRI_TRUE / Not obtained: CRI_FALSE)

Description:

Retrieves the offset for a particular bus send level set for the specified AtomEx player.

The second argument specifies the bus name in the DSP bus settings.

Note that retrieval of the bus send level offset will fail if the following cases apply:

• The bus specified by the bus name in the second argument does not exist in the applied DSP bus settings
• The bus send level for the bus name in the second argument has not been set in the AtomEx player specified in the first argument

参见

criAtomExPlayer_SetBusSendLevelByName

criAtomExPlayer_SetPanAdx1Compatible()

void criAtomExPlayer_SetPanAdx1Compatible	(	CriAtomExPlayerHn	player,
		CriSint32	ch,
		CriFloat32	pan
	)

Set the ADX1-compatible panning

参数

[in]	player	AtomEx player handle
[in]	ch	channel number
[in]	pan	panning setting (from -1.0f to 1.0f)

Description:

This is a pan setting function compatible with ADX1.

Remarks:

This parameter is cleared by criAtomExPlayer_ResetParameters function.

注意

It is only provided to make it easier to port existing titles that were using ADX1.
If you are developing a new application that performs panning operations in ADX2, use the criAtomExPlayer_SetPan3dAngle function instead.

After setting the pan with this function, when you start playback with the criAtomExPlayer_Start function, it will be played with the set pan.
If you want to change the pan of an audio that is already being played, you must specify the new pan setting to the player with this function, and then apply the parameters to the audio being played with the criAtomExPlayer_Update and criAtomExPlayer_UpdateAll functions.

Only mono and stereo sounds can be controlled by this function. In addition, only the horizontal orientation can be controlled.
If you want to control panning for sounds with more channels, or if you want to control the orientation including the front/back position, you must use the criAtomExPlayer_SetPan3dAngle or criAtomExPlayer_SetSendLevel functions.

If the sound data to be played back is stereo, you can control the panning of channel 0 and channel 1 independently.
However, since there is nothing to enforce setting the panning to the right number of channels, when you use an AtomEx player configured for stereo and play a mono sound, the sound source may be badly panned.

If the audio data being played is stereo but pan is set for only one of the channels, the audio position for the channel without pan setting will be 0.0f (output from the center).
When controlling the pan of stereo audio, be sure to set the pan for both channels.

Do not use this function in conjunction with the criAtomExPlayer_SetPan3dAngle or criAtomExPlayer_SetSendLevel functions.
When they are used together, it may be played in the unintended pan setting.

参见

criAtomExPlayer_Start, criAtomExPlayer_Update, criAtomExPlayer_UpdateAll, criAtomExPlayer_SetPan3dAngle, criAtomExPlayer_SetSendLevel, criAtomExPlayer_ResetParameters

criAtomExPlayer_SetBandpassFilterParameters()

void criAtomExPlayer_SetBandpassFilterParameters	(	CriAtomExPlayerHn	player,
		CriFloat32	cof_low,
		CriFloat32	cof_high
	)

Set the band pass filter parameters

参数

[in]	player	AtomEx player handle
[in]	cof_low	Normalized low-range cutoff frequency (from 0.0f to 1.0f)
[in]	cof_high	Normalized high-range cutoff frequency (from 0.0f to 1.0f)

Description:

Sets the cutoff frequencies for the band pass filter.
If you set the cutoff frequencies with this function and then start the playback with the criAtomExPlayer_Start function, the band pass filter will only allow the frequencies between them to pass.
After specifying the frequencies, you can also call the criAtomExPlayer_Update function or the criAtomExPlayer_UpdateAll function to update the cutoff frequencies of the band pass filter of a sound that is already being played.

Cutoff frequencies are normalized when they are mapped from values in the range from 24 Hz to 24,000 Hz on a logarithmic scale to values in the range from 0.0f to 1.0f.
For example, when you specify 0.0f for the normalized low-range cutoff frequency and 1.0f for the normalized high-range cutoff frequency, the band pass filter passes the entire frequency range. The higher the normalized low-range cutoff frequency or the lower the normalized high-range cutoff frequency are, the narrower the range of frequencies that are passed by the filter will be.

Example:

    ：
// Set the filter parameters
CriFloat32 cof_low = 0.0f;
CriFloat32 cof_high = 0.3f;
criAtomExPlayer_SetBandpassFilterParameters(player, cof_low, cof_high);
 
// Start the playback
id = criAtomExPlayer_Start(player);
    ：
// Change the parameters
// Note: The parameters of the sound that is being played are not yet changed here.
cof_low = 0.7f;
cof_high = 1.0f;
criAtomExPlayer_SetBandpassFilterParameters(player, cof_low, cof_high);
 
// The parameters that are set in the player are now used by the filter of the sound already being played.
criAtomExPlayer_Update(player, id);
    ：

Remarks:

During cue playback, if you call this function while the parameters of the band pass filter are already set in the data, the parameters will be set as follows:

• cof_low
  「cof_low_rev = 1.0f - cof_low」is multiplied by the value that is set in the data. Then 「cof_low = 1.0f - cof_low_rev」 is applied.
  In short, 0.0f indicates that "the filter is opened the widest to low frequencies." The openness is adjusted by the multiplication.
• cof_high
  cof_hight is multiplied by the value that is set in the data.
  In short, 1.0f indicates that "the filter is opened the widest to high frequencies." The openness is adjusted by the multiplication.

If a normalized cutoff frequency is higher than 1.0f, the value is clipped to 1.0f.
Similarly, if a normalized cutoff frequency is lower than 0.0f, the value is clipped to 0.0f.

This parameter is cleared by criAtomExPlayer_ResetParameters function.

参见

criAtomExPlayer_Start, criAtomExPlayer_Update, criAtomExPlayer_UpdateAll, criAtomExPlayer_ResetParameters

criAtomExPlayer_SetBiquadFilterParameters()

void criAtomExPlayer_SetBiquadFilterParameters	(	CriAtomExPlayerHn	player,
		CriAtomExBiquadFilterType	type,
		CriFloat32	frequency,
		CriFloat32	gain,
		CriFloat32	q_value
	)

Set the biquad filter parameters

参数

[in]	player	AtomEx player handle
[in]	type	filter type
[in]	frequency	Normalized frequency (from 0.0f to 1.0f)
[in]	gain	gain (in decibels)
[in]	q_value	Q-value

Description:

Sets the parameters of the biquad filter.
If you set the biquad filter parameters with this function and then start the playback with the criAtomExPlayer_Start function, the biquad filter will use the specified parameters.
After specifying the parameters, you can call the criAtomExPlayer_Update function or the criAtomExPlayer_UpdateAll function to update the parameters for a sound that is already being played.

The normalized frequency is a value where a frequency in the range from 24 Hz to 24,000 Hz on a logarithmic scale is normalized to the range from 0.0f to 1.0f.
The gain must be specified in decibels.
The gain is valid only when the filter type is one of the following:

• CRIATOMEX_BIQUAD_FILTER_TYPE_LOWSHELF: Low shelf filter
• CRIATOMEX_BIQUAD_FILTER_TYPE_HIGHSHELF: High shelf filter
• CRIATOMEX_BIQUAD_FILTER_TYPE_PEAKING: Peaking filter

Example:

    ：
// Set the filter parameters
CriAtomExBiquadFilterType type = CRIATOMEX_BIQUAD_FILTER_TYPE_LOWPASS;
CriFloat32 frequency = 0.5f;
CriFloat32 gain = 1.0f;
CriFloat32 q_value = 3.0f;
criAtomExPlayer_SetBiquadFilterParameters(player, type, frequency, gain, q_value);
 
// Start the playback
id = criAtomExPlayer_Start(player);
    ：
// Change the parameters
// Note: The parameters for the sound that is being played are not changed here.
frequency = 0.7f;
criAtomExPlayer_SetBiquadFilterParameters(player, type, frequency, gain, q_value);
 
// The parameters that are set in the player are now used by the sound that is being played.
criAtomExPlayer_Update(player, id);
    ：

Remarks:

• type
  Overwrites the value that is set in the data.
• frequency
  Added to the value that is set in the data.
• gain
  Multiplied by the value that is set in the data.
• q_value
  Added to the value that is set in the data.

If the normalized cutoff frequency is higher than 1.0f, the value is clipped to 1.0f.
Similarly, if the normalized cutoff frequency is lower than 0.0f, the value is clipped to 0.0f.

This parameter is cleared by criAtomExPlayer_ResetParameters function.

注意

The biquad filter will not be applied to audio data encoded for HCA-MX.
If you want to use the biquad filter, encode the audio with another codec, such as ADX or HCA.

In an environment where ASR is available, the filter cannot be used when outputting native voice.
If you want to use the biquad filter in an environment where ASR is available, you must set the output sound renderer to ASR.

参见

criAtomExPlayer_Start, criAtomExPlayer_Update, criAtomExPlayer_UpdateAll, criAtomExPlayer_ResetParameters

criAtomExPlayer_SetVoicePriority()

void criAtomExPlayer_SetVoicePriority	(	CriAtomExPlayerHn	player,
		CriSint32	priority
	)

Set the priority

参数

[in]	player	AtomEx player handle
[in]	priority	voice priority (from -255 to 255)

Description:

Sets the priority of the AtomEx player.
If you set the priority with this function and then start the playback with the criAtomExPlayer_Start function, the player will use the specified priority to play the sounds.
After specifying the priority, you can call the criAtomExPlayer_Update or the criAtomExPlayer_UpdateAll functions to update the priority of the sounds that are already being played.

For the priority value, specify an integer between -255 and 255. If a value outside of the valid range is specified, it will be clamped.
The default value is 0.

Remarks:

If the number of sounds in the voice limit group to which the waveform data belongs reaches the limit or if all the voices in the voice pool are in use when the AtomEx player tries to play the waveform data, voices are controlled based on the voice priority.
(Whether to play the specified waveform data or not is determined based on the voice priority.)

Specifically, if the waveform data you are trying to play has a higher priority than the waveform data currently being played by a voice, the AtomEx player will take over the currently playing voice and start playing the requested waveform data.
(The sound being played back is stopped, and another sound is played.)

Conversely, if the priority of the waveform data you are trying to play、 is lower than the priority of the waveform data currently being played by the voice, the AtomEx player will not play the requested waveform data.
(The requested voice will not be played, and the voice currently being played will continue to play.)

f the priority of the waveform data you are trying to play is equal to the priority of the waveform data being played by the voice, the AtomEx player will follow the pronunciation control method (first come first served or last come first served) and will control as follows.

• When first come first served, the currently playing waveform data takes priority and the requested waveform data will not be played.
• When last-arrival priority is given, the requested waveform data is given priority and the voice is snatched away.

If you call this function during cue playback and the voice priority is already set in the data, the final priority is the value set in the data added to the value passed to this function.
For example, if the priority in the data is 255 and the one you set to the AtomEx Player is 45, the actual priority value is 300.
The range of values that can be set with this function is -255 to 255, but because calculations within the library are performed in the range of CriSint32, the result of adding it to the data side may exceed -255 to 255.

This parameter is cleared by criAtomExPlayer_ResetParameters function.

注意

This function controls the voice priority, which is set for the waveform data.
Note that it does not affect the category cue priority, which is set for a cue in Atom Craft.

参见

criAtomExPlayer_Start, criAtomExPlayer_Update, criAtomExPlayer_UpdateAll, criAtomExPlayer_SetVoiceControlMethod, criAtomExPlayer_ResetParameters

criAtomExPlayer_SetAisacControlById()

void criAtomExPlayer_SetAisacControlById	(	CriAtomExPlayerHn	player,
		CriAtomExAisacControlId	control_id,
		CriFloat32	control_value
	)

Set an AISAC control value (specifying the control ID)

参数

[in]	player	AtomEx player handle
[in]	control_id	control ID
[in]	control_value	control value (from 0.0f to 1.0f)

Description:

Sets the control value for the AISAC specified by its control ID.
If you specify the AISAC control value with this function and then start the playback with the criAtomExPlayer_Start function, the sound is played back by using the specified AISAC control value.
After specifying the value, you can call the criAtomExPlayer_Update function or the criAtomExPlayer_UpdateAll function to update the AISAC control value of a sound that is already being played.
To remove the value set to an AISAC control, use the criAtomExPlayer_ClearAisacControls function.

Specify a float value between 0.0f and 1.0f for the AISAC control value.

Example:

    ：
// Set the AISAC control value
CriAtomExAisacControlId control_id = 0;
CriFloat32 control_value = 0.5f;
criAtomExPlayer_SetAisacControlById(player, control_id, control_value);
 
// Start the playback
id = criAtomExPlayer_Start(player);
    ：
// Change parameters
// Note: The parameters for the sound that is being played are not changed here.
control_value = 0.3f;
criAtomExPlayer_SetAisacControlById(player, control_id, control_value);
 
// The parameters that are set in the player are used for the sound that is already being played.
criAtomExPlayer_Update(player, id);
    ：

Remarks:

The behavior of the system changes as follows, depending on the AISAC control type:

• Off
  • If the AISAC control value is not set with this function, the AISCA does not work.
• Auto modulation
  • The value that is set with this function has no effect. The AISAC control value automatically changes with time.
• Random
  • The final AISAC control value is randomized within the random range set in the data. The AISAC control value specified by this function is used as the median value.
  • The parameters are randomized before the playback is started. You cannot change the AISAC control value for a sound during playback.
  • If the AISAC control value is not set when playback is started, 0.0f is used as the median value for randomization.

This parameter is cleared by criAtomExPlayer_ResetParameters function.

参见

criAtomExPlayer_Start, criAtomExPlayer_Update, criAtomExPlayer_UpdateAll, criAtomExPlayer_SetAisacByName, criAtomExPlayer_ResetParameters

criAtomExPlayer_SetAisacControlByName()

void criAtomExPlayer_SetAisacControlByName	(	CriAtomExPlayerHn	player,
		const CriChar8 *	control_name,
		CriFloat32	control_value
	)

Set AISAC control value (specifying a control name)

参数

[in]	player	AtomEx player handle
[in]	control_name	control name
[in]	control_value	control value (from 0.0f to 1.0f)

Description:

Sets the control value of the AISAC specified by its control name.
If you specify the AISAC control value with this function and then start the playback with the criAtomExPlayer_Start function, the sound will be played back by using the specified AISAC control value.
After specifying the value, you can call the criAtomExPlayer_Update function or the criAtomExPlayer_UpdateAll function to update the AISAC control value of a sound that is already being played.
To remove the value set to an AISAC control, use the criAtomExPlayer_ClearAisacControls function.

The AISAC control value is handled in the same way than when using the criAtomExPlayer_SetAisacControlById function.

Example:

    ：
// Set the AISAC control value
const CriChar8 *control_name = "Any";
CriFloat32 control_value = 0.5f;
criAtomExPlayer_SetAisacControlByName(player, control_name, control_value);
 
// Start the playback
id = criAtomExPlayer_Start(player);
    ：
// Change the parameters
// Note: The parameters for the sound that is being played are not changed here.
control_value = 0.3f;
criAtomExPlayer_SetAisacControlByName(player, control_name, control_value);
 
// The parameters that are set in the player are now used by the sound that is being played.
criAtomExPlayer_Update(player, id);
    ：

Remarks:

This parameter is cleared by criAtomExPlayer_ResetParameters function.

参见

criAtomExPlayer_Start, criAtomExPlayer_Update, criAtomExPlayer_UpdateAll, criAtomExPlayer_SetAisacById, criAtomExPlayer_ResetParameters

criAtomExPlayer_ClearAisacControls()

void criAtomExPlayer_ClearAisacControls

(

CriAtomExPlayerHn

player

)

Clear the AISAC control values set to the player

参数

[in]

player

AtomEx player handle

Description:

Clear all the AISAC control values set to the player.
Once they have been cleared, you can call the criAtomExPlayer_Update or criAtomExPlayer_UpdateAll function to clear them from any sound currently playing.

参见

criAtomExPlayer_SetAisacControlById, criAtomExPlayer_SetAisacControlByName, criAtomExPlayer_Update, criAtomExPlayer_UpdateAll

criAtomExPlayer_Set3dSourceHn()

void criAtomExPlayer_Set3dSourceHn	(	CriAtomExPlayerHn	player,
		CriAtomEx3dSourceHn	source
	)

Set the 3D sound source handle

参数

[in]	player	AtomEx player handle
[in]	source	3D sound source handle

Description:

Set the 3D sound source handle used for 3D positioning.
If you set a 3D listener handle and a 3D sound source handle, the orientation, volume and pitch are automatically applied (based on the the relative position of the 3D sound source from the 3D listener).
If you set the 3D sound soource handle with this function and then start the playback by calling criAtomExPlayer_Start, the sound will be played back based on the 3D sound source properties.
After specifying the sound source, you can also call the criAtomExPlayer_Update or criAtomExPlayer_UpdateAll functions to modify the 3D sound source referenced by the sounds that are already being played.
Passing NULL clears the 3D sound source handle that was previously set.

Remarks:

This parameter is cleared by criAtomExPlayer_ResetParameters function.

注意

To modify or update the parameters of a 3D sound source object, use the functions for the 3D sound source object instead of those of the AtomEx player.
By default, a left-handed coordinate system is used to calculate the 3D positioning.
If you want to use a right-handed coordinate system, pass CRIATOMEX_COORDINATE_SYSTEM_RIGHT_HANDED for CriAtomExConfig::coordinate_system when initializing the library ( criAtomEx_Initialize function). When the sound is played back without using an ACB file, you must pass CRIATOMEX_PAN_TYPE_3D_POS to the ::criAtomExSetPanType function to explicitly enable the 3D positioning.

This function and ::CriAtomExPlayer_Set3dSourceListHn function overwrite the setting with each other.
For example, if you set a 3D sound source handle list to the AtomEx player using the criAtomExPlayer_Set3dSourceListHn function, and then set a 3D sound source handle to the AtomEx player using this function, a new 3D sound source handle will be set in the AtomEx player, and the previously set 3D sound source handle list will be cleared from the AtomEx player.
The 3D sound source handle setting by the AtomEx player using this function can not be added to the 3D sound source handle list. If you want to add it to the 3D sound source handle list, clear the 3D sound source handle setting of the AtomEx player already set.

Example:

CriAtomEx3dListenerHn listener;
CriAtomEx3dSourceHn source;
CriAtomExVector pos;
 
listener = criAtomEx3dListener_Create(NULL, NULL, 0);
source = criAtomEx3dSource_Create(NULL, NULL, 0);
player = criAtomExPlayer_Create(NULL, NULL, 0);
criAtomExPlayer_Set3dListenerHn(player, listener);
criAtomExPlayer_Set3dSourceHn(player, source);
 
pos.x = 0.0f;
pos.y = 0.0f;
pos.z = 0.0f;
criAtomEx3dSource_SetPosition(source, &pos);
criAtomEx3dSource_Update(source);
// Start playback
id = criAtomExPlayer_Start(player);
               :
pos.x += 10.0f;
criAtomEx3dSource_SetPosition(source, &pos);
criAtomEx3dSource_Update(source);

参见

CriAtomEx3dSourceHn, CriAtomEx3dSourceListHn, criAtomExPlayer_Set3dSourceListHn, criAtomEx3dListenerHn, criAtomExPlayer_SetListenerHn, criAtomExPlayer_Update, criAtomExPlayer_ResetParameters

criAtomExPlayer_Set3dSourceListHn()

void criAtomExPlayer_Set3dSourceListHn	(	CriAtomExPlayerHn	player,
		CriAtomEx3dSourceListHn	source_list
	)

Assign a 3D sound source handle list to a player

参数

[in]	player	AtomEx player handle
[in]	source_list	3D sound source handle list

Description:

Sets the 3D sound source list to a player to provide multi-positioning playback.
By setting the 3D listener handle and the 3D sound source list, sound localization, volume, pitch, etc. are automatically applied.
If you start the playback with the criAtomExPlayer_Start function after setting the 3D sound source list with this function, positioning wil be based on the 3D sound sources.
Like for other parameters, after setting the handle, you can call the criAtomExPlayer_Update or criAtomExPlayer_UpdateAll functions to actually apply it.
If the "source_list" argument is set to NULL, the current 3D sound source list handle is cleared.

Remarks:

This parameter is cleared by criAtomExPlayer_ResetParameters function.

注意

The 3D sound source handles added to the 3D sound source list are changed and updated using a function from the 3D sound source handle, not a function from the AtomEX player.
To pass the various vectors in the right hand coordinate system, specify CRIATOMEX_COORDINATE_SYSTEM_RIGHT_HANDED for CriAtomExConfig::coordinate_system in the library initialization (criAtomEx_Initialize) setting.
When playing audio without using ACB files, you need to set CRIATOMEX_PAN_TYPE_3D_POS by calling the ::criAtomExSetPanType function to explicitly enable 3D positioning.

This function and the ::CriAtomExPlayer_Set3dSourceHn function are mutually overwriting their settings.
For example, if you set a 3D sound source handle to the AtomEx player using the criAtomExPlayer_Set3dSourceHn function, and then set a 3D sound source handle list to the AtomEx player using this function, a new 3D sound source handle list will be set to the AtomEx player, and the previously set 3D sound source handle will be cleared from the AtomEx player.

Example:

CriAtomEx3dListenerHn listener;
CriAtomEx3dSourceListHn source_list;
CriAtomEx3dSourceHn source[8];
CriAtomExVector pos[8];
CriSint32 i;
 
listener = criAtomEx3dListener_Create(NULL, NULL, 0);
source_list = criAtomEx3dSourceList_Create(NULL, NULL, 0);
for (i = 0; i < 8; i++) {
    source[i] = criAtomEx3dSource_Create(NULL, NULL, 0);
 
    pos[i].x = (CriFloat32)i;
    pos[i].y = 0.0f;
    pos[i].z = 0.0f;
    criAtomEx3dSource_SetPosition(source, &pos);
    criAtomEx3dSource_Update(source);
 
    criAtomEx3dSourceList_Add(source_list, source[i]);
}
 
player = criAtomExPlayer_Create(NULL, NULL, 0);
criAtomExPlayer_Set3dListenerHn(player, listener);
criAtomExPlayer_Set3dSourceListHn(player, source_list);
 
// Start playback
id = criAtomExPlayer_Start(player);
               :
pos[2].x += 25.0f;
criAtomEx3dSource_SetPosition(source[2], &pos);
criAtomEx3dSource_Update(source[2]);
pos[5].z += 10.0f;
criAtomEx3dSource_SetPosition(source[5], &pos);
criAtomEx3dSource_Update(source[5]);

参见

CriAtomEx3dSourceListHn, CriAtomEx3dSourceHn, criAtomExPlayer_Set3dSourceHn, CriAtomEx3dListenerHn, CriAtomExPlayer_Set3dListenerHn, criAtomExPlayer_Update, criAtomExPlayer_ResetParameters

criAtomExPlayer_Set3dListenerHn()

void criAtomExPlayer_Set3dListenerHn	(	CriAtomExPlayerHn	player,
		CriAtomEx3dListenerHn	listener
	)

Set the 3D listener handle

参数

[in]	player	AtomEx player handle
[in]	listener	3D listener handle

Description:

Set the 3D listener handle used for 3D positioning.
If you set a 3D listener handle and a 3D sound source handle, the orientation, volume and pitch are automatically applied (based on the the relative position of the 3D sound source from the 3D listener).
If you set the 3D listener handle with this function and then start the playback by calling criAtomExPlayer_Start, the sound will be played back based on the 3D listener properties.
After specifying the listener, you can also call the criAtomExPlayer_Update or criAtomExPlayer_UpdateAll functions to modify the 3D listener referenced by the sounds that are already being played.
Passing NULL clears the 3D listener handle that was previously set.

Remarks:

Even if you don't set the 3D listener handle in this function, the closest 3D listener will be automatically assigned to the 3D sound source if any of the following conditions are met:

• 3D sound source handles or 3D sound source handle list is set.
• The 3D listener is created by criAtomEx3dListener_Create.

This parameter is cleared by the criAtomExPlayer_ResetParameters function.

注意

Changes and updates to 3D listener handle parameters are done using the 3D listener handle's functions, not the AtomEx player's functions.
By default, 3D positioning calculations are done in a left-handed coordinate system.
If you want to set various vectors in a right-handed coordinate system, specify CRIATOMEX_COORDINATE_SYSTEM_RIGHT_HANDED for CriAtomExConfig::coordinate_system when initializing the library ( criAtomEx_Initialize function).

Example:

CriAtomEx3dListenerHn listener;
CriAtomEx3dSourceHn source;
CriAtomExVector pos;
 
listener = criAtomEx3dListener_Create(NULL, NULL, 0);
source = criAtomEx3dSource_Create(NULL, NULL, 0);
player = criAtomExPlayer_Create(NULL, NULL, 0);
criAtomExPlayer_Set3dListenerHn(player, listener);
criAtomExPlayer_Set3dSourceHn(player, source);
 
pos.x = 0.0f;
pos.y = 0.0f;
pos.z = 0.0f;
criAtomEx3dSource_SetPosition(source, &pos);
criAtomEx3dSource_Update(source);
// Start playback
id = criAtomExPlayer_Start(player);
               :
pos.x += 10.0f;
criAtomEx3dSource_SetPosition(source, &pos);
criAtomEx3dSource_Update(source);

参见

CriAtomEx3dListenerHn, criAtomExPlayer_Set3dSourceHn, criAtomExPlayer_Update, criAtomExPlayer_ResetParameters

criAtomExPlayer_GetAisacControlById()

CriFloat32 criAtomExPlayer_GetAisacControlById	(	CriAtomExPlayerHn	player,
		CriAtomExAisacControlId	control_id
	)

Get an AISAC control value (specifying the control ID)

参数

[in]	player	AtomEx player handle
[in]	control_id	control ID

返回

CriFloat32 control value (from 0.0f to 1.0f), -1.0f if not specified

Description:

Gets the control value of an AISAC (specified by its control ID).
If no value has been set, -1.0f is returned.

注意

This function gets the AISAC control value set to the AtomEx player.
If the sound currently being played has an AISAC which controls the AISAC control value, you cannot get the modified value.

Example:

CriAtomExAisacControlId control_id = 0;
CriFloat32 control_value = 0.5f;
// Set AISAC control value
criAtomExPlayer_SetAisacControlById(player, control_id, control_value);
// Start playback
id = criAtomExPlayer_Start(player);
               :
// Get AISAC control value
control_value = criAtomExPlayer_GetAisacControlById(player, control_id);

参见

criAtomExPlayer_SetAisacControlById, criAtomExPlayer_GetAisacControlByName

criAtomExPlayer_GetAisacControlByName()

CriFloat32 criAtomExPlayer_GetAisacControlByName	(	CriAtomExPlayerHn	player,
		const CriChar8 *	control_name
	)

Get an AISAC control value (specifying the control name)

参数

[in]	player	AtomEx player handle
[in]	control_name	control name

返回

CriFloat32 control value (from 0.0f to 1.0f), -1.0f if not specified

Description:

Gets the control value of an AISAC (specified by its control name).
If no value has been set, -1.0f is returned.

注意

This function gets the AISAC control value set to the AtomEx player.
If the sound currently being played has an AISAC which controls the AISAC control value, you cannot get the modified value.

Example:

const CriChar8 *control_name = "Any";
CriFloat32 control_value = 0.5f;
// Set AISAC control value
criAtomExPlayer_SetAisacControlByName(player, control_name, control_value);
// Start playback
id = criAtomExPlayer_Start(player);
               :
// Get AISAC control value
control_value = criAtomExPlayer_GetAisacControlByName(player, control_name);

参见

criAtomExPlayer_SetAisacControlByName, criAtomExPlayer_GetAisacControlById

criAtomExPlayer_SetCategoryById()

void criAtomExPlayer_SetCategoryById	(	CriAtomExPlayerHn	player,
		CriUint32	category_id
	)

Set the category (specifying its ID)

参数

[in]	player	AtomEx player handle
[in]	category_id	category ID

Description:

Sets the category by specifying its ID.
In order to remove the current category, use the criAtomExPlayer_UnsetCategory function.

Remarks:

Calling this function at the time of playback Cue will merge with the category settings that are set on the data side. In that case, if there are conflicting category groups, the setting of this function will be valid. Before CRI Atom Library Ver.2.20.31, category settings set in the data side were overwritten.(The settings on the data side were ignored.)
If you want to operate with the previous specifications, set CriAtomExConfig::enable_category_override_by_ex_player to CRI_TRUE when initializing the library ( criAtomEx_Initialize function). The category information set with this function will be cleared when you register or unregister ACF.

This parameter is cleared by criAtomExPlayer_ResetParameters function.

Example:

// Set default category
criAtomExPlayer_SetCategoryById(player, (CriUint32)CRIATOMEXCATEGORY_DEFAULT_ID_BGM);

注意

Set the category before starting the playback. If you update the category of a sound already playing, the category playback count may not be correct.

参见

criAtomExPlayer_UnsetCategory, criAtomExPlayer_SetCategoryByName, criAtomExPlayer_ResetParameters

criAtomExPlayer_SetCategoryByName()

void criAtomExPlayer_SetCategoryByName	(	CriAtomExPlayerHn	player,
		const CriChar8 *	category_name
	)

Set the category (specifying its name)

参数

[in]	player	AtomEx player handle
[in]	category_name	category name

Description:

Sets the category by specifying its name.
In order to remove the current category, use the criAtomExPlayer_UnsetCategory function.

Remarks:

It is similar to the criAtomExPlayer_SetCategoryById function, except that the category is specified by name. Use CRIATOMEXCATEGORY_DEFAULT_NAME_??? for the default category name.

This parameter is cleared by criAtomExPlayer_ResetParameters function.

Example:

// Set default category
criAtomExPlayer_SetCategoryByName(player, CRIATOMEXCATEGORY_DEFAULT_NAME_BGM);

注意

Please set the category before starting playback. The category of the audio being played will not be updated.

参见

criAtomExPlayer_UnsetCategory, criAtomExPlayer_SetCategoryById, criAtomExPlayer_ResetParameters

criAtomExPlayer_UnsetCategory()

void criAtomExPlayer_UnsetCategory

(

CriAtomExPlayerHn

player

)

Remove a category

参数

[in]

player

AtomEx player handle

Description:

Removes the category set to a player handle.

Example:

// Unset category
criAtomExPlayer_UnsetCategory(player);

参见

criAtomExPlayer_SetCategoryByName, criAtomExPlayer_SetCategoryById

criAtomExPlayer_GetNumCategories()

CriSint32 criAtomExPlayer_GetNumCategories

(

CriAtomExPlayerHn

player

)

Acquiring the number of categories

参数

[in]

player

AtomEx player handle

返回

CriSint32 Number of categories

Description:

Acquires the number of categories that are set for the player handle.

criAtomExPlayer_GetCategoryInfo()

CriBool criAtomExPlayer_GetCategoryInfo	(	CriAtomExPlayerHn	player,
		CriUint16	index,
		CriAtomExCategoryInfo *	info
	)

Acquiring category information (by specifying an index)

参数

[in]	player	AtomEx player handle
[in]	index	Index
[out]	info	Category information

返回

CriBool Whether information is acquired or not. (Acquired: CRI_TRUE/not acquired: CRI_FALSE)

Description:

Acquires category information that is set for the player handle by specifying an index.
If the category for the specified index does not exist, this function returns CRI_FALSE.

criAtomExPlayer_SetTrackInfo()

void criAtomExPlayer_SetTrackInfo	(	CriAtomExPlayerHn	player,
		CriSint32	num_tracks,
		const CriSint32 *	channels_per_track
	)

Set the track information

参数

[in]	player	AtomEx player handle
[in]	num_tracks	the number of tracks
[in]	channels_per_track	the number of channels per track

Description:

Sets the track configuration for a multichannel sound.
By using this function, you can treat a 6ch sound as 6 mono tracks or 3 stereo tracks.

Example:

    :
// Specify the track information
// Remark) Treat the 6ch sound as 3 stereo tracks
CriSint32 channels_per_track[3] = { 2, 2, 2 };
criAtomExPlayer_SetTrackInfo(params.player, 3, channels_per_track);
    :
// Set the volume for each track
criAtomExPlayer_SetTrackVolume(params.player, 0, 1.0f);
criAtomExPlayer_SetTrackVolume(params.player, 1, 0.5f);
criAtomExPlayer_SetTrackVolume(params.player, 2, 0.25f);
    :

注意

This function uses the criAtomExPlayer_SetSendLevel function internally.
Therefore, when you use the criAtomExPlayer_SetSendLevel function after calling this function, the output position or the volume of the sound may not be as intended.
(Similarly, the criAtomExPlayer_SetPan3dAngle and criAtomExPlayer_SetSendLevel functions cannot be used at the same time.)
This function is available only on platforms which support 3 or more input channels.
A linking error happens for platforms which only support 2 (stereo) or fewer channels.

参见

criAtomExPlayer_SetTrackVolume

criAtomExPlayer_SetTrackVolume()

void criAtomExPlayer_SetTrackVolume	(	CriAtomExPlayerHn	player,
		CriSint32	track_no,
		CriFloat32	volume
	)

Set the track volume

参数

[in]	player	AtomEx player handle
[in]	track_no	track number
[in]	volume	track volume

Description:

Sets the volume of a track.

Remarks:

This parameter is cleared by criAtomExPlayer_ResetParameters function.

注意

This function can be only be called on a player for which the track information was set (by using criAtomExPlayer_SetTrackInfo ).

This function uses the criAtomExPlayer_SetSendLevel function internally.
Therefore, when you use the criAtomExPlayer_SetSendLevel function after calling this function, the output position or the volume of the sound may not be as intended.
(Similarly, the criAtomExPlayer_SetPan3dAngle and criAtomExPlayer_SetSendLevel functions cannot be used at the same time.)
This function is available only on platforms which support 3 or more input channels.
A linking error happens for platforms which only support 2 (stereo) or fewer channels.

参见

criAtomExPlayer_SetTrackInfo, criAtomExPlayer_ResetParameters

criAtomExPlayer_SetSilentMode()

void criAtomExPlayer_SetSilentMode	(	CriAtomExPlayerHn	player,
		CriAtomExSilentMode	silent_mode
	)

Set the silence-handling mode

参数

[in]	player	AtomEx player handle
[in]	silent_mode	silence-handling mode

Description:

Determines how the silence is handled.
If you specify the silence-handling mode with this function and then start the playback by calling criAtomExPlayer_Start , the sound will be played using the specified silence-handling mode.
After specifying the mode, you can also call the criAtomExPlayer_Update or the criAtomExPlayer_UpdateAll functions to update mode for the sounds that are already playing.

For more information on the silence-handling mode, see CriAtomExSilentMode .
Its default value is CRIATOMEX_SILENT_MODE_NORMAL.

Example:

// Set silent mode
criAtomExPlayer_SetSilentMode(player, CRIATOMEX_SILENT_MODE_STOP);
// Start playback
id = criAtomExPlayer_Start(player);
               :
// Change volume to silent
volume = 0.0f;
criAtomExPlayer_SetVolume(player, volume);
criAtomExPlayer_Update(player, id);

Remarks:

This parameter is cleared by criAtomExPlayer_ResetParameters function.

参见

CriAtomExSilentMode, criAtomExPlayer_Start, criAtomExPlayer_Update, criAtomExPlayer_UpdateAll, criAtomExPlayer_ResetParameters

criAtomExPlayer_SetCuePriority()

void criAtomExPlayer_SetCuePriority	(	CriAtomExPlayerHn	player,
		CriSint32	cue_priority
	)

Set the Cue priority

参数

[in]	player	AtomEx player handle
[in]	cue_priority	Cue priority

Description:

Sets the cue priority for an AtomEx player.
If you set a cue priority with this function and then play a sound with the criAtomExPlayer_Start function, that sound will be played back based on the cue priority that you set.
The default priority value before this function is executed is 0.

Remarks:

If the maximum number of sounds allowed for the cue's category is reached when the AtomEx player plays the cue, voices are controlled / limited based on the priority.
If the AtomEx player's playback request has a higher priority than the cue being played, the AtomEx player stops the current cue and starts the requested playback.
(The sound being played back is stopped, and another sound is played.)
On the other hand, if the AtomEx player's playback request has a lower priority, the playback request is rejected.
(The requested cue is not played.)
If the AtomEx player's playback request has the priority than the cue being played, the AtomEx player controls voices in a last-in, first-out order.

This parameter is cleared by criAtomExPlayer_ResetParameters function.

参见

criAtomExPlayer_Start, criAtomExPlayer_ResetParameters

criAtomExPlayer_SetPreDelayTime()

void criAtomExPlayer_SetPreDelayTime	(	CriAtomExPlayerHn	player,
		CriFloat32	predelay_time_ms
	)

Setting the pre-delay time

参数

[in]	player	AtomEx player handle
[in]	predelay_time_ms	Pre-delay (0.0f - 10000.0f)

Description:

Sets the pre-delay time.
After setting the pre-delay time with this function, when playback is started by the criAtomExPlayer_Start function, wait for the set pre-delay time pronunciation.

For the pre-delay time, specify a real value in the range of 0.0f to 10000.0f. The unit is ms (milliseconds).
The default value of the pre-delay time is 0.0f.

注意

It can not be updated by the criAtomExPlayer_Update function or the criAtomExPlayer_UpdateAll function during playback.

Remarks:

When the cue is played back, if this function is called when the pre-delay time is set on the data side, the value set on the data side plus the setting value of this function is applied.

参见

criAtomExPlayer_Start

criAtomExPlayer_SetEnvelopeAttackTime()

void criAtomExPlayer_SetEnvelopeAttackTime	(	CriAtomExPlayerHn	player,
		CriFloat32	attack_time_ms
	)

Set the attack time of the envelope

参数

[in]	player	AtomEx player handle
[in]	attack_time_ms	attack time (from 0.0f to 2000.0f)

Description:

Sets the attack time of an envelope.
If you set the attack time with this function and then start the playback with the criAtomExPlayer_Start function, the sound will be played back using the specified attack time.

For the attack time, specify a real number from 0.0f to 2000.0f (the unit is a millisecond).
The default attack time is 0.0f (i.e. no attack).

注意

You cannot update the attack time using the criAtomExPlayer_Update or criAtomExPlayer_UpdateAll functions during playback.

Example:

CriFloat32 attack_time_ms = 10.0f;
// Set attack time
criAtomExPlayer_SetEnvelopeAttackTime(player, attack_time_ms);
// Start playback(attack time=10ms)
criAtomExPlayer_Start(player);

Remarks:

If you call this function during cue playback, any attack time already set in the data will be overwritten (i.e. the setting in the data is ignored).

This parameter is cleared by criAtomExPlayer_ResetParameters function.

参见

criAtomExPlayer_Start, criAtomExPlayer_ResetParameters

criAtomExPlayer_SetEnvelopeAttackCurve()

void criAtomExPlayer_SetEnvelopeAttackCurve	(	CriAtomExPlayerHn	player,
		CriAtomExCurveType	curve_type,
		CriFloat32	strength
	)

Setting the Envelope Attack Curve

参数

[in]	player	AtomEx Player Handle
[in]	curve_type	Curve Type
[in]	strength	Curve Strength

Description:

Sets the attack curve of the envelope.
After setting the attack curve with this function, when playback is started with the criAtomExPlayer_Start function, playback will be performed with the set attack curve.

The curve type is specified as defined in CriAtomExCurveType .
The default curve type is CRIATOMEX_CURVE_TYPE_LINEAR .

The strength of the curve is specified as a real value in the range of 0.0f to 2.0f.
The default value of the strength of the curve is 1.0f.

注意

It is not possible to update using the criAtomExPlayer_Update or criAtomExPlayer_UpdateAll function during playback.

Remarks:

During cue playback, if an attack curve is set in the data, calling this function will overwrite the value set in the data (the value set in the data will be ignored).

This parameter is cleared by the criAtomExPlayer_ResetParameters function.

参见

criAtomExPlayer_Start, criAtomExPlayer_ResetParameters

criAtomExPlayer_SetEnvelopeHoldTime()

void criAtomExPlayer_SetEnvelopeHoldTime	(	CriAtomExPlayerHn	player,
		CriFloat32	hold_time_ms
	)

Setting the envelope hold time

参数

[in]	player	AtomEx Player Handle
[in]	hold_time_ms	Hold Time

Description:

Sets the envelope hold time.
After setting the hold time with this function, if you start playback with the criAtomExPlayer_Start function, it will play with the hold time that you set.

The unit of hold time is ms (milliseconds).
The default value of hold time is 0.0f.

注意

You cannot update using the criAtomExPlayer_Update or criAtomExPlayer_UpdateAll functions while playing.

Example:

CriFloat32 hold_time_ms = 10.0f;
// Set hold time
criAtomExPlayer_SetEnvelopeHoldTime(player, hold_time_ms);
// Start playback(hold time=10ms)
criAtomExPlayer_Start(player);

Remarks:

If you call this function during cue playback, any hold time already set in the data will be overwritten(i.e. the setting in the data is ignored).

This parameter is cleared by criAtomExPlayer_ResetParameters function.

参见

criAtomExPlayer_Start, criAtomExPlayer_ResetParameters

criAtomExPlayer_SetEnvelopeDecayTime()

void criAtomExPlayer_SetEnvelopeDecayTime	(	CriAtomExPlayerHn	player,
		CriFloat32	decay_time_ms
	)

Set the decay time of the envelope

参数

[in]	player	AtomEx player handle
[in]	decay_time_ms	decay time (from 0.0f to 2000.0f)

Description:

Sets the decay time of the envelope.
If you specify the decay time with this function and then start the playback with the criAtomExPlayer_Start function, the sound will be played with the specified decay time.

For the decay time, specify a real number from 0.0f to 2000.0f (the unit is a millisecond).
The default decay time is 0.0f (no decay).

注意

You cannot update the decay time using the criAtomExPlayer_Update or criAtomExPlayer_UpdateAll functions during playback.

Example:

CriFloat32 decay_time_ms = 10.0f;
// Set decay time
criAtomExPlayer_SetEnvelopeDecayTime(player, decay_time_ms);
// Start playback(decay time=10ms)
criAtomExPlayer_Start(player);

Remarks:

If you call this function during cue playback, any decay time already set in the data will be overwritten (i.e. the setting in the data is ignored).

This parameter is cleared by criAtomExPlayer_ResetParameters function.

参见

criAtomExPlayer_Start, criAtomExPlayer_ResetParameters

criAtomExPlayer_SetEnvelopeDecayCurve()

void criAtomExPlayer_SetEnvelopeDecayCurve	(	CriAtomExPlayerHn	player,
		CriAtomExCurveType	curve_type,
		CriFloat32	strength
	)

Setting the Envelope Decay Curve

参数

[in]	player	AtomEx Player Handle
[in]	curve_type	Curve Type
[in]	strength	Curve Strength

Description:

Sets the decay curve of the envelope.
After setting the decay curve with this function, when playback is started with the criAtomExPlayer_Start function, playback will be performed with the decay curve that was set.

The curve type is specified as defined in CriAtomExCurveType .
The default curve type is CRIATOMEX_CURVE_TYPE_LINEAR .

The strength of the curve is specified as a real value in the range of 0.0f to 2.0f.
The default value of the strength of the curve is 1.0f.

注意

It is not possible to update using the criAtomExPlayer_Update or criAtomExPlayer_UpdateAll function during playback.

Remarks:

During cue playback, if a decay curve is set on the data side and this function is called, the value set on the data side will be overwritten and applied (the value set on the data side will be ignored).

This parameter is cleared by the criAtomExPlayer_ResetParameters function.

参见

criAtomExPlayer_Start, criAtomExPlayer_ResetParameters

criAtomExPlayer_SetEnvelopeReleaseTime()

void criAtomExPlayer_SetEnvelopeReleaseTime	(	CriAtomExPlayerHn	player,
		CriFloat32	release_time_ms
	)

Setting the envelope release time

参数

[in]	player	AtomEx Player Handle
[in]	release_time_ms	Release Time

Description:

Sets the release time of the envelope.
After setting the release time with this function, if you start playback with the criAtomExPlayer_Start function, it will play at the release time that you set.

The release time is measured in milliseconds.
The default release time is 0.0f.

Example:

CriFloat32 release_time_ms = 3000.0f;
// Set release time
criAtomExPlayer_SetEnvelopeReleaseTime(player, release_time_ms);
// Start playback(release time=3000ms)
criAtomExPlayer_Start(player);

Remarks:

If you call this function during cue playback, any release time already set in the data will be overwritten (i.e. the setting in the data is ignored).

This parameter is cleared by criAtomExPlayer_ResetParameters function.

参见

criAtomExPlayer_Start, criAtomExPlayer_ResetParameters

criAtomExPlayer_SetEnvelopeReleaseCurve()

void criAtomExPlayer_SetEnvelopeReleaseCurve	(	CriAtomExPlayerHn	player,
		CriAtomExCurveType	curve_type,
		CriFloat32	strength
	)

Setting the envelope release curve

参数

[in]	player	AtomEx Player Handle
[in]	curve_type	Curve Type
[in]	strength	Curve Strength

Description:

Sets the release curve of the envelope.
After setting the release curve with this function, when playback is started with the criAtomExPlayer_Start function, playback will be performed with the set release curve.

The curve type is specified as defined in CriAtomExCurveType .
The default curve type is CRIATOMEX_CURVE_TYPE_LINEAR .

The strength of the curve is specified as a real value in the range of 0.0f to 2.0f.
The default value of the strength of the curve is 1.0f.

注意

It cannot be updated by the criAtomExPlayer_Update function or the criAtomExPlayer_UpdateAll function during playback.

Remarks:

During cue playback, if a release curve is set in the data, calling this function will overwrite the value set in the data (the value set in the data will be ignored).

This parameter is cleared by the criAtomExPlayer_ResetParameters function.

参见

criAtomExPlayer_Start, criAtomExPlayer_ResetParameters

criAtomExPlayer_SetEnvelopeSustainLevel()

void criAtomExPlayer_SetEnvelopeSustainLevel	(	CriAtomExPlayerHn	player,
		CriFloat32	susutain_level
	)

Setting the envelope sustain level

参数

[in]	player	AtomEx player handle
[in]	susutain_level	sustain level (from 0.0f to 1.0f)

Description:

Sets the sustain level of the envelope.
If you specify the sustain level with this function and then start the playback with the criAtomExPlayer_Start function, the sound will be played with the specified sustain level.

For the sustain level, specify a real number between 0.0f to 1.0f.
The default sustain level is 0.0f (no sustain).

注意

You cannot update the sustain level using the criAtomExPlayer_Update or criAtomExPlayer_UpdateAll function while playing back.

Example:

CriFloat32 susutain_level = 0.5f;
// Set susutain level
criAtomExPlayer_SetEnvelopeSustainLevel(player, susutain_level);
// Start playback(sustain level=0.5)
criAtomExPlayer_Start(player);

Remarks:

If you call this function during cue playback, any sustain level already set in the data will be overwritten (i.e. the setting in the data is ignored).

This parameter is cleared by criAtomExPlayer_ResetParameters function.

参见

criAtomExPlayer_Start, criAtomExPlayer_ResetParameters

criAtomExPlayer_SetDataRequestCallback()

void criAtomExPlayer_SetDataRequestCallback	(	CriAtomExPlayerHn	player,
		CriAtomExPlayerDataRequestCbFunc	func,
		void *	obj
	)

Register the data request callback function

参数

[in]	player	AtomEx player handle
[in]	func	data request callback function
[in]	obj	user-specified object

Description:

Registers a data request callback function.

The data request callback is used to play back multiple sounds by seamlessly concatenating them.
It is called when the Atom player used internally by a Voice requires data for the concatenated playback.
(The callback function is called when the next chunk of data to be played back is required.)
By supplying the new data to the Atom player (within the registered callback, using functions such as criAtomPlayer_SetData), it can be concatenated seamlessly with the previous data and played back.
In addition, by calling the criAtomPlayer_SetPreviousDataAgain function within the callback, the same data can be played back repeatedly.

Remarks:

If no new data is supplied within the registered callback function, the status of the AtomEx player changes to CRIATOMEXPLAYER_STATUS_PLAYEND when the playback of current data is finished.

If you do not want the status to be changed to CRIATOMEXPLAYER_STATUS_PLAYEND even when you cannot supply data due to problems such as timing issues, call criAtomPlayer_DeferCallback within the callback function.
By executing this function, the data request callback function wil be called again after about 1V.
However, if you call the criAtomPlayer_DeferCallback function, the playback may stop temporarily (silence will be inserted at the concatenation point).

Example:

By executing the following code, the data in buffer1 and buffer2 is concatenated and played back seamlessly.
(Then, the data in buffer2 is repeatedly played back.)

// Data request callback function
void on_data_request(void *obj, CriAtomExPlaybackId id, CriAtomPlayerHn player)
{
    // Set the data to be played back without a break
    criAtomPlayer_SetData(player, buffer2, buffer_size2);
}
 
main()
{
        :
    // Register the data request callback function
    criAtomExPlayer_SetDataRequestCallback(player, on_data_request, NULL);
 
    // Set the sound data
    criAtomExPlayer_SetData(player, buffer1, buffer_size1);
 
    // Play the sound data
    criAtomExPlayer_Start(player);
        :
}

By using the following code, the same sound data can be played back in loop infinitely.

// Data request callback function
void on_data_request(void *obj, CriAtomExPlaybackId id, CriAtomPlayerHn player)
{
    // Set the previously-played data again
    criAtomPlayer_SetPreviousDataAgain(player);
}
 
main()
{
        :
    // Register the data request callback function
    criAtomExPlayer_SetDataRequestCallback(player, on_data_request, NULL);
 
    // Set the sound data
    criAtomExPlayer_SetData(player, buffer, buffer_size);
 
    // Play the sound data
    criAtomExPlayer_Start(player);
        :
}

注意

The callback function must be set before starting playback.
You cannot set a callback for sounds already being played or change a callback that has already been set.

When a Cue containing multiple waveforms is played, the callback function is triggered when the playback of the first waveform has finished.
Therefore, when concatenated playback is performed on a Cue containing multiple waveforms, they may be played back in unexpected ways.
When you use this feature, you should play Cues containing only one waveform or play back file or in-memory data.

Note that if you block the processing in the data request callback function for a long time, problems -such as the audio breaking up- may occur.

The functions that can be called within the callback are:

• criAtomExAcb_GetWaveformInfoById (argument cannot be NULL)
• criAtomExAcb_GetWaveformInfoByName (argument cannot be NULL)
• criAtomExAcb_GetOnMemoryAwbHandle
• criAtomExAcb_GetStreamingAwbHandle
• criAtomPlayer_SetData
• criAtomPlayer_SetFile
• criAtomPlayer_SetContentId
• criAtomPlayer_SetWaveId
• criAtomPlayer_SetPreviousDataAgain
• criAtomPlayer_DeferCallback

When a function that is not listed above is called within a callback function, problems such as error callback or deadlock may occur.

If you are using a codec that does not support seamless playback, the data will not be played continuously even if you set the next data in the data request callback function.

• When using the HCA-MX codec, the data is not seamlessly joined and there will be silence between the current audio stream and the next audio stream.
• If you are using platform-specific audio compression codecs, errors may occur.

The format of the waveform data used for seamless concatenated playback should all be the same.
Specifically, the following parameters must be the same:

• Codec
• Number of channels
• Sampling rate

If you try to concatenate waveforms with different parameters, you may encounter problems such as unintended speed of audio data playback or error callbacks.

Also, when waveform data with loop information is set within the data request callback function, the loop playback is not performed.
(The loop points are discarded and the playback ends.)

Only one callback function can be registered.
If perform a registration operation more than once, the already registered callback function will be overwritten by the callback function registered later.

Registering registered functions can be canceled by specifying NULL for func.

参见

CriAtomExPlayerDataRequestCbFunc, criAtomPlayer_SetData, criAtomPlayer_SetPreviousDataAgain, criAtomPlayer_DeferCallback

criAtomExPlayer_SetFilterCallback()

void criAtomExPlayer_SetFilterCallback	(	CriAtomExPlayerHn	player,
		CriAtomExPlayerFilterCbFunc	func,
		void *	obj
	)

Register the wave filter callback function

参数

[in]	player	AtomEx player handle
[in]	func	wave filter callback function
[in]	obj	user-specified object

Description:

Registers a callback function to be called when decoded PCM data is supplied.
This callback is triggered when the sound data for the Voice has been decoded.

注意

When playing a cue that contains multiple audio data, the callback will only be executed for the first waveform data found.
(For cues that contain multiple waveform data, information on the second and subsequent waveform data cannot be obtained.)

Do not execute the API of the Atom library in the callback function.
The callback function is executed from the server process in the Atom library.
Therefore, if you execute an API that does not take into account interrupts to server processing, an error or deadlock may occur.

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

Filter callbacks are not available when using the HCA-MX codec or platform-specific audio compression codecs.

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.

The filter callback is not available when using HCA-MX or a platform-specific codec.

参见

CriAtomExPlayerFilterCbFunc

criAtomExPlayer_SetRandomSeed()

void criAtomExPlayer_SetRandomSeed	(	CriAtomExPlayerHn	player,
		CriUint32	seed
	)

Set the random number seed

参数

[in]	player	AtomEx player handle
[in]	seed	random number seed

Description:

Sets the random seed used for the pseudo random number generator of this AtomEx player.
By setting the random seed, a random playback process can be reproduced.

参见

criAtomEx_SetRandomSeed

criAtomExPlayer_SetDspParameter()

void criAtomExPlayer_SetDspParameter	(	CriAtomExPlayerHn	player,
		CriSint32	param_id,
		CriFloat32	param_val
	)

Set a DSP parameter

参数

[in]	player	AtomEx player handle
[in]	param_id	parameter ID (0 - 10)
[in]	param_val	parameter value (0.0f - 1.0f)

Description:

Sets the value of a DSP parameter.
Before enabling a DSP, it must be attached to a Voice Pool.

Remarks:

This parameter is cleared by criAtomExPlayer_ResetParameters function.

参见

criAtomExPlayer_ResetParameters

criAtomExPlayer_SetDspBypass()

void criAtomExPlayer_SetDspBypass	(	CriAtomExPlayerHn	player,
		CriBool	is_bypassed
	)

Set a DSP parameter

参数

[in]	player	AtomEx player handle
[in]	is_bypassed	With or without bypass

Description:

Sets whether to bypass the insertion DSP maintained by the AtomEx player.
The Insertion DSP is not bypassed unless explicitly specified in this function.

Remarks:

This parameter is cleared by criAtomExPlayer_ResetParameters function.

参见

criAtomExPlayer_ResetParameters

criAtomExPlayer_AttachAisac()

void criAtomExPlayer_AttachAisac	(	CriAtomExPlayerHn	player,
		const CriChar8 *	global_aisac_name
	)

Attach a global AISAC to a player

参数

[in]	player	AtomEx player handle
[in]	global_aisac_name	name of the global AISAC to be attached

Description:

Attaches a global AISAC to a player. An AISAC can be used even if it is not set to a Cue or a track.
After attaching an AISAC with this function, when you call criAtomExPlayer_Start various parameters of the new sound can be modified based on the AISAC.
After attaching the AISAC, you can also call the criAtomExPlayer_Update or criAtomExPlayer_UpdateAll functions to apply the AISAC to the sounds already being played.

If the attachment failed, an error callback occurs.
To know the reason of the failure, refer to the error callback message.

Example:

// Attach Aisac
criAtomExPlayer_AttachAisac(player, "GlobalAisac1");
criAtomExPlayer_SetAisacControlByName(player, "Any", 0.5f);
criAtomExPlayer_Start(player);

Remarks:

Only global AISACs defined in the global settings (ACF file) can be attached.
In order for the global AISAC to have an effect, the relevant AISAC control value must be set, like for any AISAC configured for Cues or tracks.

This parameter is cleared by criAtomExPlayer_ResetParameters function.

注意

Even when an AISAC is set to a Cue or a track, the resulting AISAC control value does not affect the global AISAC attached to the player. Currently, attaching an AISAC whose control type is "auto modulation" or "random" is not supported.
Also, the maximum number of AISACs that can be attached to a player is eight.

参见

criAtomExPlayer_DetachAisac, criAtomExPlayer_ResetParameters

criAtomExPlayer_DetachAisac()

void criAtomExPlayer_DetachAisac	(	CriAtomExPlayerHn	player,
		const CriChar8 *	global_aisac_name
	)

Detach an AISAC from the player

参数

[in]	player	AtomEx player
[in]	global_aisac_name	name of the global AISAC to be detached

Description:

Detaches a global AISAC from a player.
After detaching an AISAC with this function, if you start a new sound by calling criAtomExPlayer_Start , the now-detached AISAC will not affect the playback anymore.
After detaching the AISAC, if you call the criAtomExPlayer_Update or criAtomExPlayer_UpdateAll functions, even the sounds already being played will not be affected by the AISAC anymore.

If this function fails, an error callback will be triggered.
To know the reason of the failure, refer to the error callback message.

参见

criAtomExPlayer_AttachAisac

criAtomExPlayer_DetachAisacAll()

void criAtomExPlayer_DetachAisacAll

(

CriAtomExPlayerHn

player

)

Detach all the AISACs from a player

参数

[in]

player

AtomEx player

Description:

Detaches all global AISACs from a player.
After detaching the AISACs with this function, if you start a new sound by calling criAtomExPlayer_Start , no global AISAC will affect the playback anymore.
After detaching the AISACs, if you call the criAtomExPlayer_Update or criAtomExPlayer_UpdateAll functions, even the sounds already being played will not be affected by the AISACs anymore.

参见

criAtomExPlayer_AttachAisac

criAtomExPlayer_GetNumAttachedAisacs()

CriSint32 criAtomExPlayer_GetNumAttachedAisacs

(

CriAtomExPlayerHn

player

)

Get the number of AISACs attached to a player

参数

[in]

player

AtomEx player

返回

The number of AISACs attached to the player

Description:

Gets the number of AISACs attached to a player.

criAtomExPlayer_GetAttachedAisacInfo()

CriBool criAtomExPlayer_GetAttachedAisacInfo	(	CriAtomExPlayerHn	player,
		CriSint32	aisac_attached_index,
		CriAtomExAisacInfo *	aisac_info
	)

Get information on a specific AISAC attached to a player

参数

[in]	player	AtomEx player
[in]	aisac_attached_index	The index of the attached AISAC
[out]	aisac_info	AISAC information

返回值

CRI_TRUE	= the information was successfully obtained
CRI_FALSE	= failed to get information

Description:

Gets information on a specific AISAC attached to a player.
If an invalid index was specified, CRI_FALSE is returned.

参见

criAtomExPlayer_GetNumAttachedAisacs

criAtomExPlayer_SetStreamingCacheId()

void criAtomExPlayer_SetStreamingCacheId	(	CriAtomExPlayerHn	player,
		CriAtomExStreamingCacheId	cache_id
	)

Set the streaming cache for player

参数

[in]	player	AtomEx player
[in]	cache_id	ID of the streaming cache to be used in the player

Description:

Sets a streaming cache (by specifying its ID) to be used by a player.

注意

Later, you have to destroy the player before destroying the streaming cache.
If they are not destroyed in this order, the result is undefined.

参见

criAtomStreamingCache_Create, criAtomStreamingCache_Destroy

criAtomExPlayer_AttachTween()

void criAtomExPlayer_AttachTween	(	CriAtomExPlayerHn	player,
		CriAtomExTweenHn	tween
	)

Attach a Tween to a player

参数

[in]	player	AtomEx player handle
[in]	tween	Tween handle

Description:

Attaches a Tween to a player. A Tween makes it possible to modify the player's parameters smoothly over time.
After attaching a Tween, the parameters will be updated according to the Tween when a new sound is started with the criAtomExPlayer_Start function.
The parameters of already-playing sounds will also be modified by the Tween after calling the criAtomExPlayer_Update or the criAtomExPlayer_UpdateAll functions.

Example:

// Create a Tween to fade the volume
CriAtomExTweenConfig config;
criAtomExTween_SetDefaultConfig(&config);
 
config.parameter_type = CRIATOMEX_PARAMETER_TYPE_BASIC;
config.id.parameter_id = CRIATOMEX_PARAMETER_ID_VOLUME;
fade_tween = criAtomExTween_Create(&config, NULL, 0);
 
// Attach the Tween
criAtomExPlayer_AttachTween(player, fade_tween);
 
// Start the playback
criAtomExPlayer_Start(player);
            :
// Fade the volume to 0.2 over one second
criAtomExTween_MoveTo(fade_tween, 1000, 0.2f);
            :
// Restore the volume to 1.0 over two seconds
criAtomExTween_MoveTo(fade_tween, 2000, 1.0f);

Remarks:

Parameters changed by a Tween are added to, multiplied by, or overwrite the parameters set for the AtomEx Player.
The operation (addition, multiplication, or overwriting) is the same than for the corresponding AtomEx Player setting functions ( criAtomExPlayer_SetVolume etc.). For example, the volume is multiplied, while an AISAC control value is overwritten.
Currently, up to eight Tweens can be attached to a player.

This parameter is cleared by criAtomExPlayer_ResetParameters function.

参见

criAtomExPlayer_DetachTween, criAtomExPlayer_DetachTweenAll, criAtomExTween_Create, criAtomExPlayer_ResetParameters

criAtomExPlayer_DetachTween()

void criAtomExPlayer_DetachTween	(	CriAtomExPlayerHn	player,
		CriAtomExTweenHn	tween
	)

Detach a Tween from a player

参数

[in]	player	AtomEx Player
[in]	tween	handle of the Tween to be detached

Description:

Detaches a Tween from a player.
Once this function is called, a sound started by the criAtomExPlayer_Start function will not be affected by the Tween.
Calling the criAtomExPlayer_Update or criAtomExPlayer_UpdateAll functions after detaching the Tween will also cancel its effect on the sounds that are being played back.

参见

criAtomExPlayer_AttachTween

criAtomExPlayer_DetachTweenAll()

void criAtomExPlayer_DetachTweenAll

(

CriAtomExPlayerHn

player

)

Detach all Tweens from a player

参数

[in]

player

AtomEx Player

Description:

Detaches all the Tweens from a player.
Once this function is called, sounds started by the criAtomExPlayer_Start function will not be affected by any Tween.
Calling the criAtomExPlayer_Update or criAtomExPlayer_UpdateAll functions after detaching the Tweens will also cancel their effect on the sounds that are being played back.

参见

criAtomExPlayer_AttachTween

criAtomExPlayer_SetFirstBlockIndex()

void criAtomExPlayer_SetFirstBlockIndex	(	CriAtomExPlayerHn	player,
		CriAtomExBlockIndex	index
	)

Set the start block (by specifying a block index)

参数

[in]	player	AtomEx player handle
[in]	index	block index

Description:

Sets the index of the starting block for playback with an AtomEx player.
If you use this function and then start playing the block sequence cue by calling the criAtomExPlayer_Start function, the playback will start at the specified block.

Example:

main()
{
      :
  // Specify the audio data to play
  criAtomExPlayer_SetCueIndex(player, acb_hn, 300);
 
  // Specify the start block
  criAtomExPlayer_SetFirstBlockIndex(player, 1);
 
  // Start the playback
  criAtomExPlayer_Start(player);
      :
}

Remarks:

By default, the index of the starting block for an AtomEx player is 0.
If the cue that is set for the player is not a block sequence when the criAtomExPlayer_Start function starts playback, the value set with this function is ignored.
If there is no block with the specified index, playback is started at the first block.
In this case, a warning appears saying that a block is missing at the specified index.

Remarks:

The criAtomExPlayback_SetNextBlockIndex function is used to transition to a another block after the playback is started. The criAtomExPlayback_GetCurrentBlockIndex function is used to get the index of the block being played back.

This parameter is cleared by criAtomExPlayer_ResetParameters function.

参见

criAtomExPlayer_Start, criAtomExPlayback_SetNextBlockIndex, criAtomExPlayback_GetCurrentBlockIndex, criAtomExPlayer_ResetParameters

criAtomExPlayer_SetBlockTransitionCallback()

void criAtomExPlayer_SetBlockTransitionCallback	(	CriAtomExPlayerHn	player,
		CriAtomExPlayerBlockTransitionCbFunc	func,
		void *	obj
	)

Register the block transition callback function

参数

[in]	player	AtomEx player handle
[in]	func	block transition callback function
[in]	obj	user-specified object

Description:

Registers a callback function that is called when a block transition occurs during block sequence playback.
The registered callback function is called when a block transition occurs.

Do not execute the API of the Atom library in the callback function.
The callback function is executed from the server process in the Atom library.
Therefore, if you execute an API that does not take into account interrupts to server processing, an error or deadlock may occur.

If the process is blocked within the callback function over a long period of time, problems -such as the audio breaking up- 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.

参见

CriAtomExPlayerBlockTransitionCbFunc

criAtomExPlayer_GetSoundObject()

CriAtomExSoundObjectHn criAtomExPlayer_GetSoundObject

(

CriAtomExPlayerHn

player

)

Acquire a sound object

参数

[in]

player

AtomEx player handle

返回

Sound object handle

Description:

Acquires the sound object associated with the specified AtomEx player.
NULL is returned if no sound object is associated.

参见

CriAtomExSoundObjectHn, criAtomExSoundObject_AddPlayer

criAtomExPlayer_SetDrySendLevel()

void criAtomExPlayer_SetDrySendLevel	(	CriAtomExPlayerHn	player,
		CriAtomExSpeakerId	spk,
		CriFloat32	offset,
		CriFloat32	gain
	)

Set the dry send level (for compatibility with CRI Audio)

参数

[in]	player	AtomEx player handle
[in]	spk	Speaker ID
[in]	offset	Dry send level offset (added value)
[in]	gain	Dry send level gain (multiplied value)

Description:

Sets the dry send level of the output sound.
This function is provided for CRI Audio compatibility. It exhibits the same behavior than the dry send level in CRI Audio.
After setting the dry send level with this function, any new sound started by calling criAtomExPlayer_Start will use that level.
After executing this function, you can also call the criAtomExPlayer_Update or criAtomExPlayer_UpdateAll functions to update the dry send level of the sounds that have already been playing.

You can specify the dry send level for each speaker individually during playback.
Which input channel is sent to each speaker depends on the number of channels of the waveform. For example, in the case of a mono waveform, channel 0 is output to all speakers. A stereo waveform will output channel 0 (L channel) to all the left-side speakers (L, SL, SBL) and channel 1 (R channel) to all the right-side speakers (R, SR, SBL). (When a dry send level is used, the stereo sound is not output to the center speaker or LFE.)

The dry send level is added to the output level based on the pan 3D and send level settings.
The range and handling of the dry send level are basically the same than for the volume. Therefore, refer to the criAtomExPlayer_SetVolume function for details.
The default dry send level is 0.0f.

Example:

main()
{
    :
 // Remarks: Here it is assumed that the sound to be played is mono
    // Set the dry send level (halve the data-side value and add 0.2f).
    criAtomExPlayer_SetDrySendLevel(player, CRIATOMEX_SPEAKER_FRONT_CENTER, 0.2f, 0.5f);
 
 // Start the playback
 // Remarks: The dry send level used is the value set to the player. 
 id = criAtomExPlayer_Start(player);
    :
    // Set the dry send level (disable the data-side value and overwrite with 0.8f).
 // Note: the dry send level of the sounds currently playing is not changed at this point. 
    criAtomExPlayer_SetDrySendLevel(player, CRIATOMEX_SPEAKER_FRONT_CENTER, 0.8f, 0.0f);
 
 // Apply the dry send level to the sounds that were already playing.
 criAtomExPlayer_Update(player, id);
    :
}

Remarks:

If this function is called when there is a dry send level set from the data side (e.g. during Cue playback), the value set in the data is multiplied by the gain parameter and the offset parameter is added to that result.
For example, if the data-side dry send level is 1.0f and the AtomEx player dry send level has an offset of 0.2f and gain of 0.5f, the actual send level will be 0.7f.
The dry send level can normally not be set using CRI Atom Craft. It will be set in the data only when importing a project file created with CRI Audio Craft.
Normally when playing 6-channel materials, the sound is output automatically from the center and LFE channels, but that will not be the case if the dry send level is set, either on the data-side or by using this function. Similarly, the center/LFE channel mix levels set in CRI Atom Craft are disabled when the dry send level is set.

This parameter is cleared by criAtomExPlayer_ResetParameters function.

参见

criAtomExPlayer_Start, criAtomExPlayer_Update, criAtomExPlayer_UpdateAll, criAtomExPlayer_ResetParameters

criAtomExPlayer_SetSelectorLabel()

void criAtomExPlayer_SetSelectorLabel	(	CriAtomExPlayerHn	player,
		const CriChar8 *	selector,
		const CriChar8 *	label
	)

Set selector information to the player

参数

[in]	player	AtomEx player handle
[in]	selector	Selector name
[in]	label	Label name

Description:

Set a selector and a label (specified by their names) to the player.
When playing a Cue that has selector labels specified for its tracks, only the tracks matching the selector label passed to this function will be played.
The selector and label names are both defined in the ACF header.
To delete individual label information set on the player, execute the criAtomExPlayer_UnsetSelectorLabel function.
To delete all label information set on the player at once, execute the criAtomExPlayer_ClearSelectorLabels function.
To delete all player settings, including label information, execute the criAtomExPlayer_ResetParameters function.

参见

criAtomExPlayer_ClearSelectorLabels, criAtomExPlayer_ResetParameters, criAtomExPlayer_Update, criAtomExPlayer_UpdateAll

criAtomExPlayer_UnsetSelectorLabel()

void criAtomExPlayer_UnsetSelectorLabel	(	CriAtomExPlayerHn	player,
		const CriChar8 *	selector
	)

Deleting the selector information set in the player

参数

[in]	player	AtomEx Player Handle
[in]	selector	Selector name

Description:

Deletes the specified selector name and the label name associated with it that are set in the player.
After deletion, you can delete the selector information for audio that is already playing by calling the criAtomExPlayer_Update function or criAtomExPlayer_UpdateAll function, but the audio will not stop playing.

参见

criAtomExPlayer_SetSelectorLabel, criAtomExPlayer_Update, criAtomExPlayer_UpdateAll

criAtomExPlayer_ClearSelectorLabels()

void criAtomExPlayer_ClearSelectorLabels

(

CriAtomExPlayerHn

player

)

Clear the selector information set to the player

参数

[in]

player

AtomEx player handle

Description:

Clear all selector and label names set to the player.
After executing this function, you can call the criAtomExPlayer_Update or criAtomExPlayer_UpdateAll functions to clear the selector information from the currently playing sounds. However, note that no currently playing sound will be stopped.

参见

criAtomExPlayer_SetSelectorLabel, criAtomExPlayer_Update, criAtomExPlayer_UpdateAll

criAtomExPlayer_SetPlaybackTrackInfoNotificationCallback()

void criAtomExPlayer_SetPlaybackTrackInfoNotificationCallback	(	CriAtomExPlayerHn	player,
		CriAtomExPlayerPlaybackTrackInfoNotificationCbFunc	func,
		void *	obj
	)

Registering playback track number notification callback function

参数

[in]	player	AtomEx Player handle
[in]	func	Playback track number notification callback function
[in]	obj	User specified object

Description:

Register the callback function to notify the played track number.
The registered callback function is called when playing a cue other than polyphonic type.

Do not execute the API of the Atom library in the callback function.
The callback function is executed from the server process in the Atom library.
Therefore, if you execute an API that does not take into account interrupts to server processing, an error or deadlock may occur.

Please note that if you block processing for a long period of time within the callback function, 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.

参见

CriAtomExPlayerPlaybackTrackInfoNotificationCbFunc

criAtomExPlayer_SetPlaybackEventCallback()

void criAtomExPlayer_SetPlaybackEventCallback	(	CriAtomExPlayerHn	player,
		CriAtomExPlaybackEventCbFunc	func,
		void *	obj
	)

Registration of playback event callback

参数

[in]	player	AtomEx Player Handle
[in]	func	Replay event callback function
[in]	obj	User specified object

Description:

Register playback event callback.
By registering a playback event callback using this function, detailed information (play source AtomEx player or playback ID) that a playback event (securement / release of playback resource, voice assignment, virtualization) occurs can be gotten.

Remarks:

The value set in the second argument (obj) is passed as an argument of the callback function.
Please refer to the explanation of the CriAtomExPlaybackEventCbFunc for other arguments of callback function.

By specifying NULL for func, you can unregister registered functions.

注意

Only one callback function can be registered for one AtomEx player.
If you perform registration operation multiple times, already registered callback function will be overwritten by the callback function registered later.

参见

CriAtomExVoiceEventCbFunc

criAtomExPlayer_SetChannelConfig()

void criAtomExPlayer_SetChannelConfig	(	CriAtomExPlayerHn	player,
		CriSint32	num_channels,
		CriAtomChannelConfig	channel_config
	)

Specify the channel configuration of the input audio

参数

[in]	player	AtomEx Player Handle
[in]	num_channels	Number of Channels
[in]	channel_config	Channel Config

Description:

Specifies the channel configuration for the input audio.
If an audio with the specified number of channels is played after executing this function, the attributes of each channel of the audio will be determined based on the specified channel configuration.

Remarks:

The default value can be changed using the criAtom_ChangeDefaultChannelConfig function.
This parameter is cleared by the criAtomExPlayer_ResetParameters function.

参见

criAtom_ChangeDefaultChannelConfig, criAtomExPlayer_ResetParameters