Configuration structure used to initialize the Atom libraryThis structure is used to specify the behavior of the CRI Atom library.
It is passed to the criAtomEx_Initialize function.
The CRI Atom library will allocate internal resources as needed during initialization according to the settings specified in this structure.
The size of the work area required by the library varies depending on the parameters specified in this structure.
More...
#include <cri_le_atom_ex.h>
Configuration structure used to initialize the Atom library
This structure is used to specify the behavior of the CRI Atom library.
It is passed to the criAtomEx_Initialize function.
The CRI Atom library will allocate internal resources as needed during initialization according to the settings specified in this structure.
The size of the work area required by the library varies depending on the parameters specified in this structure.
- Remarks:
- To use the default settings, call the criAtomEx_SetDefaultConfig macro on a CriAtomExConfigTag structure and pass it to the criAtomEx_Initialize function.
- Attention
- More members will be added in the future. So, if you are not using the criAtomEx_SetDefaultConfig macro, make sure to initialize the structure to zero before using it.
(To make sure that no indefinite value is set to any member of the structure.)
- See also
- criAtomEx_Initialize, criAtomEx_SetDefaultConfig
◆ thread_model
Threading model.
- Description:
- Specifies the threading model to use for the CRI Atom library.
- See also
- CriAtomExThreadModel
◆ server_frequency
| CriFloat32 server_frequency |
Execution frequency of the server process.
- Description:
- Specifies the execution frequency of the server process.
Typically, this should be set to the same value than the frame rate of the application.
The CRI Atom library performs most of its work (such as managing files, decoding sound data, playing sound or updating its status) within a single function.
In CRI Middleware, that function is called a "server process."
When the threading model is CRIATOMEX_THREAD_MODEL_MULTI , the server process is regularly executed in a thread created by the CRI Atom library.
When the threading model is CRIATOMEX_THREAD_MODEL_SINGLE or CRIATOMEX_THREAD_MODEL_USER_MULTI , the server process is executed when the application calls the criAtomEx_ExecuteMain function.
Set the execution frequency of the server process in server_frequency.
When the threading model is CRIATOMEX_THREAD_MODEL_MULTI , the CRI Atom library will adjust the interval at which the server process is called to match the specified frequency.
When the threading model is CRIATOMEX_THREAD_MODEL_SINGLE or CRIATOMEX_THREAD_MODEL_USER_MULTI , the application must call the criAtomEx_ExecuteMain function more frequently than what is set in server_frequency.
If the fluctuation of the frame rate of the application is very large and the interval is different each time the server process is executed, specify a value for server_frequency that assumes the worst frame rate or use the CRIATOMEX_THREAD_MODEL_MULTI threading model.
- Remarks:
- The following tasks are performed within the server process of the Atom library:
- Voice requests processing (voice acquisition and so on)
- Parameters updates (applying changes in volume, panning, pitch and so on)
- Decoding and output of the audio data
When the frequency of the server process is increased, the amount of audio data to decode per call of the server process will decrease.
As a result, the load per server process becomes smaller (the load is distributed). However, the overhead for executing the server process becomes larger.
(The number of thread wakeups and the number of parameter updates are both increasing.)
When the frequency of the server process is decreased, the number of thread wakeups, the frequency at which voice requests are processed and the number of parameter updates decrease and the processing load of the entire application decreases as well.
However, since the frequency at which the data is buffered decreases, the amount of decoding needed per server process increases, and a larger buffer is required to store the decoded data.
Also, since the frequency at which the voice requests are processed decreases, it takes a longer time to start the audio output after a voice request.
- Attention
- When CRIATOMEX_THREAD_MODEL_SINGLE or CRIATOMEX_THREAD_MODEL_USER_MULTI are specified for the threading model but the criAtomEx_ExecuteMain function is not executed more frequently than the frequency specified in server_frequency, problems such as the audio playback breaking up may occur.
- See also
- criAtomEx_ExecuteMain
◆ parameter_update_interval
| CriSint32 parameter_update_interval |
Parameter update interval.
- Description:
- Specifies the interval between two updates of the parameters.
By changing the value of parameter_update_interval, the frequency of the parameters updates can be decreased without changing the frequency at which the server process is executed.
For example, if parameter_update_interval is set to 2, the parameters will be updated once every other time that the server process is executed.
(The frequency of the parameter updates is therefore 1/2.)
- Remarks:
- If the server process frequency (server_frequency) is decreased, since the number of executions of the server process decreases, the processing load of the entire application decreases, but the interval between the server processes increases and therefore the amount of data to be buffered increases.
As a result, the memory size required for buffering increases too.
On the other hand, if the parameter update interval (parameter_update_interval) is increased without changing the server process frequency, the load can be decreased without increasing the memory size.
However, the process overhead due to activating the server process (i.e. waking up a thread) is not reduced, and therefore, in this case, the load reduction is smaller than when the server process frequency is decreased.
- Note:
- If the value of parameter_update_interval is changed, the frequency at which the voice requests are processed also decreases.
Therefore, in that case, it also takes longer to actually start the audio output after a voice request.
◆ enable_atom_sound_disabled_mode
| CriBool enable_atom_sound_disabled_mode |
Flag that specifies to output audio using modules that are not CRI Atom Library.
- Description:
- Specify CRI_TRUE when outputting audio without using CRI Atom Library.
At criAtomEx_SetDefaultConfig macro, CRI_FALSE is specified because CRI Atom Library is used.
When using an audio output library other than the CRI Atom Library, specify cri_TRUE for this flag before executing criAtomEx_Initialize.
- Attention
- If you need to change this flag, please terminate the Atom library with criAtomEx_Finalize, change the contents of the flag, and initialize with criAtomEx_Initialize again.
◆ max_virtual_voices
| CriSint32 max_virtual_voices |
Maximum number of virtual voices.
- Description:
- Specifies the maximum number of voices for which voice control is performed simultaneously in an application.
During initialization, the Atom library will allocate the resources required to manage max_virtual_voices voices.
- Remarks:
- More voices than the number specified by max_virtual_voices cannot be played back.
Also, even if you request exactly max_virtual_voices voices, the actual number of playing voices is not always equal to max_virtual_voices.
The actual number of playing voices depends on the number of voices reserved in a Voice Pool and the number of hardware voices available on the platform.
As a guideline, the number of virtual voices is the maximum number of voices that can be played back simultaneously + the number of voice requests per 1V.
If the number of virtual voices is smaller than the maximum number of voices that can be played back simultaneously or if the sum of the number of playing voices and the number of requests exceeds the maximum number of virtual voices, the error callback function may be triggered with a warning.
In addition, if the AtomEx Player is created by specifying CRIATOMEX_RETRY_VOICE_ALLOCATION, more virtual voices may be required than what is described above.
◆ max_parameter_blocks
| CriSint32 max_parameter_blocks |
Maximum number of parameter blocks.
- Description:
- The number of buffers to be used for parameter management during audio playback.
The Atom library allocates the resources required for the management of parameters based on the max_parameter_blocks specified at initialization.
- Remarks:
- The number of parameter blocks required to play a single Cue depends on the contents of that Cue.
(The number of parameter blocks required increases proportionally with the number of parameters manipulated.)
If there are not enough parameter blocks, some parameters may not be set for the Cue that will be played.
(Parameters such as volume, pitch or filters may not be set to their intended values.)
If an error is triggered in your application due to an insufficient number of parameter blocks, increase the value of max_parameter_blocks.
◆ max_voice_limit_groups
| CriSint32 max_voice_limit_groups |
Maximum number of Voice Limit Groups.
- Description:
- Specifies the maximum number of Voice Limit Groups that can be created in the application.
The Atom library allocates the resources needed to create max_voice_limit_groups Voice Limit Groups during the initialization.
- Attention
- You can not create more Voice Limit Groups than the number specified in max_voice_limit_group.
If the number of Voice Limit Groups created within the authoring tool exceeds the value set in max_voice_limit_groups, the loading of the corresponding ACF file will fail.
◆ max_categories
Maximum number of categories.
- Description:
- Specifies the maximum number of categories that can be created in the application.
The Atom library allocates the resources needed to create max_categories categories during the initialization.
- Attention
- You can not create more categories than the number specified in max_categories.
If the number of categories created within the authoring tool exceeds the value set in max_categories, the loading of the corresponding ACF file will fail.
◆ max_aisacs
Maximum number of AISACs.
- Description:
- This is the maximum number of AISAC that can be associated with one cue.
The Atom library allocates resources to reference the number of AISACs specified by max_aisacs when initializing and creating AtomExPlayer.
The upper limit of the value that can be specified for max_aisacs is 55.
This applies to cue, track and category AISAC. Mixer AISAC is not affected by this setting.
◆ max_bus_sends
Maximum number of Bus sends.
- Description:
- The maximum number of Buses to which a voice can be sent simultaneously.
The maximum value valid for max_bus_sends is 32.
◆ categories_per_playback
| CriSint32 categories_per_playback |
Number of category references per playback.
- Description:
- Specifies the number of categories that can be referenced per playback.
During the initialization, The Atom library allocates only enough resources to reference the number of categories set in categories_per_playback.
The maximum number that can be specified is CRIATOMEXCATEGORY_MAX_CATEGORIES_PER_PLAYBACK .
- Attention
- You cannot reference more categories than the number specified in categories_per_playback from a Cue or a player.
If the number of categories referenced in a Cue created within the authoring tool exceeds categories_per_playback, the corresponding ACF file will fail to load.
◆ max_sequences
Maximum number of playback sequences.
- Description:
- Specifies the maximum number of sequences that can be played back simultaneously in the application.
At initialization, the Atom library allocates only enough resources to play the number of sequences represented by the sum of max_sequences and max_virtual_voices .
- Attention
- From version 2.00 onward, all Cues are played as sequences so resources are allocated for max_virtual_voices in addition to the specified max_sequences.
You cannot play back more sequences than the number specified for max_sequences.
If an error callback occurs, increase this value.
◆ max_tracks
Maximum number of playback Tracks.
- Description:
- Specifies the total number of Tracks in a sequence that can be played back simultaneously in an application.
At initialization, the Atom library allocates only enough resources to play the number of tracks represented by the sum of max_tracks and max_virtual_voices.
- Attention
- From version 2.00 onward, all Cues are played as sequences so resources are allocated for max_virtual_voices in addition to the specified max_tracks.
You cannot play back more tracks than the number specified for max_tracks.
If an error callback occurs, increase this value.
◆ max_track_items
| CriUint32 max_track_items |
Maximum number of Track items.
- Description:
- Specifies the total number of events in a sequence that can be played back simultaneously in an application.
At initialization, the Atom library allocates only enough resources to play the number of track items represented by the sum of max_track_items and max_virtual_voices.
- Attention
- From version 2.00 onward, all Cues are played as sequences so resources are allocated for max_virtual_voices in addition to the specified max_track_items.
You cannot play back more Track items than the number specified for max_track_items.
A Track item is an event, such as a waveform or a loop event, that must be managed during the playback of a sequence Track.
If an error callback occurs, increase this value.
◆ max_aisac_auto_modulations
| CriUint32 max_aisac_auto_modulations |
Maximum number of AISAC Auto Modulation (obsolete)
- Description:
- This has been discontinued in libraries from version 2.00.00 onwards. This member will not be referenced within the library.
◆ max_pitch
Upper limit of the pitch change.
- Description:
- Specifies the upper limit of the pitch change applied in the Atom library.
A pitch change greater than the value specified by max_pitch will be clipped.
Specify the pitch in cents.
A cent is a 1/1200th of an octave. A half-tone is equal to 100 cents.
For example, when max_pitch is set to 1200.0f, even if a Cue is played back with a pitch setting greater than 1200 cents, the playback pitch is reduced to 1200 cents.
- Remarks:
- When the pitch is also modified due to an AISAC or a Doppler effect, it may rise to unexpected levels.
(The amount of decoding per unit of time increases in proportion to the pitch. Therefore, if a large number of sounds with an extremely high pitch are played back, the processing load may increase rapidly.)
By setting the upper limit of the pitch with this parameter, unexpected load fluctuations can be avoided.
For example, when max_pitch is set to 1200.0f, whatever happens in the application, the pitch will be limited to 1200 cents (= double-speed playback), and therefore the amount of decoding per unit of time will also be limited (in that case: up to two times the decoding needed for the standard playback).
- Note:
- The value of max_pitch must be 0.0f or higher.
(if 0.0f is specified, no pitch change is performed.)
◆ max_faders
Maximum number of faders.
- Description:
- Specifies the maximum number of faders used in the Atom library.
The faders are allocated during the initialization based on the value set here. They are used internally by the library when playing back TrackTransitionBySelector data.
◆ coordinate_system
Coordinate system for 3D positioning calculation.
- Description:
- Specifies the coordinate system used by the Atom library for 3D positioning calculations.
◆ enable_auto_matching_in_pan_type_auto
| CriBool enable_auto_matching_in_pan_type_auto |
Enable the listener auto-matching function.
- Description:
- When the pan type is auto, set whether to enable the auto matching function of the listener.
- Note:
- When the pan type is 3D positioning, the listener auto matching function is always enabled.
◆ enable_category_override_by_ex_player
| CriBool enable_category_override_by_ex_player |
Enable category overrides.
- Description:
- Enables the functionality to overwrite the cue category settings when a category is set in AtomExPlayer using the criAtomExPlayer_SetCategoryById or criAtomExPlayer_SetCategoryByName functions.
- Note:
- If the category of the library is set to CRI Atom Ver.2.20.31 or less for the player, the category set in the cue was invalidated by overwriting. Please set this flag to CRI_FALSE if you need to restore the behavior below Ver.2.20.31.
◆ sequence_prepare_ratio
| CriFloat32 sequence_prepare_ratio |
Specifying the sequence read-ahead ratio.
- Description:
- Specifies the percentage of the amount that the sequencer reads in one server process. If 1.5f is specified, 0.5 server minutes will be read ahead from the estimated time when the next server processing will occur. Maximum 3.0f and minimum 1.1f can be specified. If it exceeds the range, it will be clipped.
- Note:
- It is difficult to cause a timing difference due to fluctuations in the server cycle.
◆ rng_if
Random Number Generator interface.
- Description:
- Specifies the Random Number Generator interface used by the CRI Atom library.
If NULL is specified, the default Random Number Generator is used.
◆ fs_config
Pointer to the CRI File System initialization parameters.
- Description:
- Specifies a pointer to the CRI File System initialization parameters. If NULL is specified, the CRI File System is initialized with default parameters.
- See also
- criAtomEx_Initialize
◆ acf_info
Pointer to ACF information.
- Description:
- Specify a pointer to ACF information when registering ACF at initialization. When NULL is specified, ACF registration is not performed at initialization. When setting this member and registering ACF in the initialization processing, each member value of max_voice_limit_groups, max_categories, categories_per_playback of CriAtomExConfig structure is compared with the ACF setting value and the larger value is set for initialization It is used as a value. When ACF registration is done at initialization of CriAtomEx, some setting values in ACF are also used for module initialization such as CriAtomExAsr, CriAtomExHcaMx depending on the environment.
If you want to initialize these modules without using the setting values in the ACF, initialize the library without using this member and then register the ACF.
- Attention
- When setting this member, you need to register a memory allocator function and an error callback function before calling the initialization function in order to dynamically secure the work required for initialization based on the ACF data registered during the initialization process.
When using this member, the work area is allocated using the registered memory allocator function. Initialization cannot be performed using memory area that has already been allocated.
- See also
- criAtomEx_Initialize, criAtomEx_SetUserAllocator
◆ context
Pointer to platform-specific initialization parameters.
- Description:
- Specifies a pointer to platform-specific initialization parameters required to use the CRI Atom library. If NULL is specified, the initialization required for each platform is performed with the corresponding default parameters.
Parameter structures are defined in each platform-specific header. If a parameter structure is not defined for a platform, always specify NULL.
- See also
- criAtomEx_Initialize
◆ version
Library version number.
- Description:
- The CRI Atom library version number.
The version number defined in the cri_atom.h header is set by the criAtomEx_SetDefaultConfig macro.
- Attention
- Do not change this value in your application.
◆ version_ex
Module version number.
- Description:
- The CRI Atom Ex version number.
The version number defined in this header is set by the criAtomEx_SetDefaultConfig macro.
- Attention
- Do not change this value in your application.
◆ version_string
| const CriChar8* version_string |
Library version string.
- Description:
- The version string of the CRI Atom library.
The criAtomEx_SetDefaultConfig macro sets the version string defined in the cri_atom.h header.
- Attention
- Do not change this value in your application.
◆ version_ex_string
| const CriChar8* version_ex_string |
Module Version String.
- Description:
- The CRI Atom Ex version string.
The criAtomEx_SetDefaultConfig macro sets the version string defined in this header.
- Attention
- Do not change this value in your application.
The documentation for this struct was generated from the following file:
