CriAtomDsp API

Data Structures
struct	CriAtomDspPitchShifterConfigTag
	Pitch shift attach parameter structure. More...
struct	CriAtomDspTimeStretchConfigTag
	Parameter structure for time stretching. More...
struct	CriAtomDspSpectraConfigTag
	Parameter structure for spectrum analyzer creation. More...
struct	CriAtomDspAfxConfigTag
	Insertion DSP AFX parameter structure. More...
struct	CriAtomExDspAfxConfigTag
	Configuration structure for attaching an AFX format insertion DSP. More...

Typedefs
typedef struct CriAtomDspPitchShifterConfigTag	CriAtomDspPitchShifterConfig
	Pitch shift attach parameter structure. More...
typedef enum CriAtomDspPitchShifterParameterIdTag	CriAtomDspPitchShifterParameterId
	Parameter for the pitch shifter. More...
typedef struct CriAtomDspTimeStretchConfigTag	CriAtomDspTimeStretchConfig
	Parameter structure for time stretching. More...
typedef enum CriAtomDspTimeStretchParameterIdTag	CriAtomDspTimeStretchParameterId
	Parameter for time stretching. More...
typedef struct CriAtomDspSpectraConfigTag	CriAtomDspSpectraConfig
	Parameter structure for spectrum analyzer creation. More...
typedef struct CriAtomDspAfxConfigTag	CriAtomDspAfxConfig
	Insertion DSP AFX parameter structure. More...
typedef struct CriAtomExDspAfxConfigTag	CriAtomExDspAfxConfig
	Configuration structure for attaching an AFX format insertion DSP. More...

Enumerations
enum	CriAtomDspPitchShifterParameterIdTag { CRIATOMDSP_PITCHSHIFTER_PARAM_PITCH = 0 , CRIATOMDSP_PITCHSHIFTER_PARAM_FORMANT = 1 , CRIATOMDSP_PITCHSHIFTER_PARAM_MODE = 2 }
	Parameter for the pitch shifter. More...
enum	CriAtomDspTimeStretchParameterIdTag { CRIATOMDSP_TIMESTRETCH_PARAM_RATIO = 0 , CRIATOMDSP_TIMESTRETCH_PARAM_FRAME_TIME = 1 , CRIATOMDSP_TIMESTRETCH_PARAM_QUALITY = 2 }
	Parameter for time stretching. More...

Functions
CriSint32	criAtomDspSpectra_CalculateWorkSize (const CriAtomDspSpectraConfig *config)
	Calculates the work area size required for spectrum analyzer creation. More...
CriAtomDspSpectraHn	criAtomDspSpectra_Create (const CriAtomDspSpectraConfig *config, void *work, CriSint32 work_size)
	Spectrum analyzer creation. More...
void	criAtomDspSpectra_Destroy (CriAtomDspSpectraHn spectra)
	Destroy spectrum analyzer. More...
void	criAtomDspSpectra_Reset (CriAtomDspSpectraHn spectra)
	Reset spectrum analyzer. More...
void	criAtomDspSpectra_Process (CriAtomDspSpectraHn spectra, CriUint32 num_channels, CriUint32 num_samples, CriFloat32 *pcm[])
	Spectrum analysis. More...
const CriFloat32 *	criAtomDspSpectra_GetLevels (CriAtomDspSpectraHn spectra)
	Acquire spectral analysis results. More...

Detailed Description

Typedef Documentation

CriAtomDspPitchShifterConfig

typedef struct CriAtomDspPitchShifterConfigTag CriAtomDspPitchShifterConfig

Pitch shift attach parameter structure.

Description:

A parameter that is specified when attaching the pitch shifter DSP.
It is specified as the member of the CriAtomExDspPitchShifterConfig structure to the ::criAtomExVoicePool_AttachPitchShifter function.

See also

criAtomExVoicePool_AttachDspPitchShifter

CriAtomDspPitchShifterParameterId

typedef enum CriAtomDspPitchShifterParameterIdTag CriAtomDspPitchShifterParameterId

Parameter for the pitch shifter.

Description:

Parameter specified for the pitch shifter DSP.
Specified for the param_id of criAtomExPlayer_SetDspParameter function.

See also

criAtomExPlayer_SetDspParameter

CriAtomDspTimeStretchConfig

typedef struct CriAtomDspTimeStretchConfigTag CriAtomDspTimeStretchConfig

Parameter structure for time stretching.

Description:

Parameter specified when attaching a time-stretching DSP.
Specify this parameter for the criAtomExVoicePool_AttachDspTimeStretch function, as a member of the CriAtomExDspTimeStretchConfig structure.

See also

criAtomExVoicePool_AttachDspTimeStretch

CriAtomDspTimeStretchParameterId

typedef enum CriAtomDspTimeStretchParameterIdTag CriAtomDspTimeStretchParameterId

Parameter for time stretching.

Description:

Parameter specified for the time-stretching DSP.
Specify this parameter for param_id of the criAtomExPlayer_SetDspParameter function.

See also

criAtomExPlayer_SetDspParameter

CriAtomDspSpectraConfig

typedef struct CriAtomDspSpectraConfigTag CriAtomDspSpectraConfig

Parameter structure for spectrum analyzer creation.

Description:

Parameter specified when attaching a spectrum analyzer.
Used as an argument of the criAtomDspSpectra_Create function.

See also

criAtomDspSpectra_Create

CriAtomDspAfxConfig

typedef struct CriAtomDspAfxConfigTag CriAtomDspAfxConfig

Insertion DSP AFX parameter structure.

Description:

This parameter is specified when attaching an AFX format insertion DSP.
Specified as a member of the CriAtomExDspAfxConfig structure to criAtomExVoicePool_AttachDspAfx .

See also

criAtomExVoicePool_AttachDspAfx

CriAtomExDspAfxConfig

typedef struct CriAtomExDspAfxConfigTag CriAtomExDspAfxConfig

Configuration structure for attaching an AFX format insertion DSP.

Description:

This is the parameter to specify when attaching an AFX-format insertion DSP.
This is used as an argument to the criAtomExVoicePool_AttachDspAfx function.

See also

criAtomExVoicePool_AttachDspAfx

Enumeration Type Documentation

CriAtomDspPitchShifterParameterIdTag

enum CriAtomDspPitchShifterParameterIdTag

Parameter for the pitch shifter.

Description:

Parameter specified for the pitch shifter DSP.
Specified for the param_id of criAtomExPlayer_SetDspParameter function.

See also

criAtomExPlayer_SetDspParameter

Enumerator
CRIATOMDSP_PITCHSHIFTER_PARAM_PITCH	Pitch. Description: Amount of pitch shift by the pitch shifter. The unit is cent. The valid range of the value is -2400 to 2400. Remarks: When the value is 1200, the pitch is doubled from the original sound. When the value is -1200, the pitch is halved.
CRIATOMDSP_PITCHSHIFTER_PARAM_FORMANT	Formant. Description: Amount of formant shift by the pitch shifter. The unit is cent. The valid range of the value is -2400 to 2400. Remarks: When the value is 1200, the formant is doubled from the original sound. When the value is -1200, the formant is halved. Attention The formant shift is valid only when the pitch-shift mode is Vocal or Speech.
CRIATOMDSP_PITCHSHIFTER_PARAM_MODE	Pitch-shift mode. Description: Specifies the pitch shift processing method (algorithm). Depending on the sound, sound quality may be improved by changing this setting. Permitted values and their corresponding mode names are as follows: 0: Music 1: Vocal 2: SoundEffect 3: Speech

CriAtomDspTimeStretchParameterIdTag

enum CriAtomDspTimeStretchParameterIdTag

Parameter for time stretching.

Description:

Parameter specified for the time-stretching DSP.
Specify this parameter for param_id of the criAtomExPlayer_SetDspParameter function.

See also

criAtomExPlayer_SetDspParameter

Enumerator
CRIATOMDSP_TIMESTRETCH_PARAM_RATIO	Stretch ratio. Description: Scale factor for the playback time. The playback time of a stretched playback is calculated by multiplying the playback time of the original data by this ratio. The valid range of ratio is 0.5f to 2.0f. Attention Note that the value specifies the scale factor for the "playback time," and not the playback speed. To specify the stretch ratio in terms of playback speed, set the ratio to the inverse of the scale factor for the desired playback speed.
CRIATOMDSP_TIMESTRETCH_PARAM_FRAME_TIME	Frame time. Description: The frame time (in milliseconds) for time stretching. Sound quality can be improved by adjusting this value according to the type of sound. The valid range of frame_time is 10 to 60. Remarks: For optimal quality, set the frame time to around 20 msec for voices, and around 50 msec for music.
CRIATOMDSP_TIMESTRETCH_PARAM_QUALITY	Quality. Description: Quality of time stretching. Time stretch queality can be improved by adjusting this value, but high quality cause high cpu usage. The valid range of quality is 0 to 10. Remarks: Low quality value is enough for sound of voices, but not for music.

Function Documentation

criAtomDspSpectra_CalculateWorkSize()

CriSint32 criAtomDspSpectra_CalculateWorkSize

(

const CriAtomDspSpectraConfig *

config

)

Calculates the work area size required for spectrum analyzer creation.

Parameters

[in]

config

Parameters for spectrum analyzer creation

Returns

CriSint32 Required work area size (in bytes)

Description:

Calculates the work area size required for creating a spectrum analyzer.
The required work area size changes depending on the parameters specified by config.

Remarks:

If this function fails to calculate the work area size, it returns a negative value.
(The cause of the failure is passed to the error callback.)

See also

CriAtomDspSpectraConfig, criAtomDspSpectra_Create

criAtomDspSpectra_Create()

CriAtomDspSpectraHn criAtomDspSpectra_Create	(	const CriAtomDspSpectraConfig *	config,
		void *	work,
		CriSint32	work_size
	)

Spectrum analyzer creation.

Parameters

[in]	config	Parameters for spectrum analyzer creation
[in]	work	Work area
[in]	work_size	Work area size

Returns

CriAtomDspSpectraHn Spectrum analyzer handle

Description:

Creates a spectrum analyzer.
The spectrum analyzer is a module that analyzes PCM data and measures the signal strength of each spectrum.

Use the criAtomDspSpectra_Process function for PCM data input.
Use the criAtomDspSpectra_GetLevels function to obtain the results of the analysis.

You can explicitly destroy an unneeded spectrum analyzer with the criAtomDspSpectra_Destroy function.

Remarks:

If the spectrum analyzer fails to be created, this function returns NULL.
(The cause of the failure is passed to the error callback.)
If this function is executed without registering an allocator with the criAtom_SetUserAllocator function, you must pass the amount of memory calculated by the criAtomDspSpectra_CalculateWorkSize function as the work area.

Attention

The library must be initialized before this function is executed.

The work area that is set in this function must be maintained by the application until the criAtomDspSpectra_Destroy function is executed.
(Do not release the memory for the work area before executing the criAtomDspSpectra_Destroy function.)

This function is a synchronous type.
Executing this function blocks server processing of the Atom library for a while.
If this function is executed during audio playback, problems such as audio dropout may occur. Call this function only when load fluctuations are acceptable, such as when the game scene is changed.

See also

CriAtomDspSpectraConfig, criAtomDspSpectra_CalculateWorkSize, criAtomDspSpectra_Destroy

criAtomDspSpectra_Destroy()

void criAtomDspSpectra_Destroy

(

CriAtomDspSpectraHn

spectra

)

Destroy spectrum analyzer.

Description:

Destroys a spectrum analyzer.
This function releases the memory area allocated when the spectrum analyzer was created.
(If a work area was passed when the spectrum analyzer was created, the work area can be released after this function is executed.)

Attention

This function is a synchronous type.
Executing this function blocks server processing of the Atom library for a while.
If this function is executed during audio playback, problems such as audio dropout may occur. Call this function only when load fluctuations are acceptable, such as when the game scene is changed.

See also

criAtomDspSpectra_Create

criAtomDspSpectra_Reset()

void criAtomDspSpectra_Reset

(

CriAtomDspSpectraHn

spectra

)

Reset spectrum analyzer.

Description:

Resets a spectrum analyzer.
When this function is executed, the PCM information set to criAtomDspSpectra_Process is cleared.

Remarks:

Execute this function if you want to clear the return value of the criAtomDspSpectra_GetLevels function to zero.

See also

criAtomDspSpectra_Process, criAtomDspSpectra_GetLevels

criAtomDspSpectra_Process()

void criAtomDspSpectra_Process	(	CriAtomDspSpectraHn	spectra,
		CriUint32	num_channels,
		CriUint32	num_samples,
		CriFloat32 *	pcm[]
	)

Spectrum analysis.

Description:

Analyzes PCM data.
Use the criAtomDspSpectra_GetLevels function to obtain the results of the analysis.

Remarks:

The input data stream (pcm) value is expected to be within the range of -1.0f to +1.0f.
However, even if you enter a value that exceeds the range of ±1, he value returned by the criAtomDspSpectra_GetLevels function will simply increase, so there is no need to clip the data at the time of input.
This function waits for 1024 samples to be accumulated internally before performing FFT processing, so the spectrum is updated every 1024 samples input.

See also

criAtomDspSpectra_GetLevels

criAtomDspSpectra_GetLevels()

const CriFloat32* criAtomDspSpectra_GetLevels

(

CriAtomDspSpectraHn

spectra

)

Acquire spectral analysis results.

Description:

Returns the analysis results for the PCM data set by the criAtomDspSpectra_Process function.

The analysis results are returned as a CriFloat32 array.
The number of elements in the array is equal to the value specified for CriAtomDspSpectraConfig::num_bands when the criAtomDspSpectra_Create function was executed.
The 0th element is the amplitude value of the lowest band and the (num_bands - 1) element is the amplitude value of the highest band.

Remarks:

To analyze multiple channels of PCM data at once, you must mix all channels of PCM data together, and then analyze the results of that mix.
Therefore, even if multiple channels of sound data are set to the criAtomDspSpectra_Process function, this function will return a one-dimensional array of length num_bands.

Attention

The values returned by the criAtomDspSpectra_GetLevels function are the amplitude values for each band.
To display the analysis results like a commercially available spectral analyzer, you must convert the values returned by this function to decibel values.

See also

criAtomDspSpectra_Process