Initialization and Finalization of the Library

This section describes the initialization and finalization process of the CRI Atom library.

Types of the Initialization Functions

CRI Atom library allocates resources required for its operation at the time of initialization.
Therefore, in order to use the features of CRI Atom library, you must first initialize the library.

The initialization functions of the library is roughly divided into the following two groups.

• Initialization functions based on the features to be used
• Target-specific initialization functions

Users must call either of the above types of initialization functions in their applications.

The feature of each initialization function is as follows.

Initialization Functions Based on the Features

For initializing Atom library, there are following three initialization functions based on the features.

Initialization Function	Description
criAtomEx_Initialize function	Initializes the basic feature of the library. All the features except ASR and HCA-MX become available.
criAtomExAsr_Initialize function Initializes	"ASR." It is not required when you do not use ASR.
criAtomExHcaMx_Initialize function Initializes	"HCA-MX." It is not required when you do not use HCA-MX.

When neither ASR nor HCA-MX is used, unnecessary modules are not linked by calling only the criAtomEx_Initialize function.

Target-specific Initialization Functions

Atom library provides initialization functions optimal for each target as "target-specific initialization functions."

For PCs, initialization/finalization functions specific to each target are as follows.

• criAtomEx_Initialize_WASAPI
• criAtomEx_Finalize_WASAPI

By calling target-specific initialization functions, following three functions are called internally.

• criAtomEx_Initialize
• criAtomExAsr_Initialize
• criAtomExHcaMx_Initialize

Since all the features including ASR/HCA-MX are initialized by using target-specific initialization functions, it is possible to simplify the procedure of initialization.

[Note]
Target-specific initialization functions are used in the tutorials or the sample programs.

Initializing the Library

When initializing the library, you can specify the behavior of the library in detail.
The following is the details of how to initialize the library using the criAtomEx_Initialize function.

You need to pass configuration structure for initializing the library ( CriAtomExConfig for the criAtomEx_Initialize function ) and working memory to the initialization function as arguments.

Configuration Structure for Initializing the Library

The configuration structure for initializing the library ( CriAtomExConfig ) is the structure for specifying the behavior of the library.
The parameters that can be specified in the configuration structure are as follows.

• Thread model (thread_model)
• Frequency of server process (server_frequency)
• Maximum number of virtual voices (max_virtual_voices)
• Initialization parameters for CRI File System library (fs_config)

(1) Thread model (thread_model)

CRI Atom library builds a thread framework based on the specification specified in this structure.
For more information on the thread framework, see About Thread .

(2) Frequency of server process (server_frequency)

CRI Atom library performs most of the work inside the library such as managing file reading, decoding sound data, playing sound, or updating the status, in single function.
In CRI Middleware, the function which performs the work inside the library collectively like this is called a "server process."

In order to play back the sound without break, CRI Atom library performs the server process periodically at a fixed interval on a thread.
CRI Atom library performs the server process by the frequency specified by server_frequency.

If the frequency of executing the server process is increased, amount of the work per server process (such as the amount of decoding tasks) will decrease.
As a result, the load per server process becomes small (load is distributed). However, overhead for executing the server process becomes large.
(When the frequency of executing the server process is increased too much in environments where CPU resource is poor such as in portable game machine, overhead for executing the server process becomes nonnegligible.)

If the frequency of executing the server process is decreased, amount of the work per server process will increase.
Although the overhead for executing the server process is reduced, since the load per server process becomes high, there is a possibility that problems, such as dropping frames, may occur.

[Note]
Typically, server_frequency should be set to the same value as the frame rate of the application.

(3) Maximum number of virtual voices (max_virtual_voices)

It specifies the number of "virtual voices" simultaneously used in the application.
Virtual voice is a virtual voice object which offers the interface for controlling a Voice.
(Unlike Voice, virtual voice itself does not have resources for playback.)

When AtomEx player is instructed to play back sound data, Atom library allocates a virtual voice and will request the virtual voice to play back the sound.
The virtual voice tries to allocate a required Voice from the Voice Pool based on the playback request and to play back the sound.
If a Voice could be allocated, the sound is played back. Otherwise, the sound is not played back.
(The number of sounds played back is not necessarily the same as the number of virtual voices.)

Unlike hardware voices, you can create as many virtual voices in the library as memory allows.
Therefore, even in environments where the number of the sound which can be played back is limited, it is possible to control sounds beyond the maximum number of sounds temporarily.

Although the number of the Voices used in an application is determined when creating a Voice Pool, the number of virtual voices is specified at the time of initializing the library.
Although the number of Voices that can be controlled simultaneously increases by increasing the number of virtual voices, it increases required memory.

Attention

The number of virtual voices must be set to a value higher than the total number of voices (i.e., the total number of voices allocated by all voice pools).
If the total number of voices allocated by the voice pools exceeds the number of virtual voices, voice pool creation will fail.

Please note that virtual voices not only handle the management of voices which are actually playing sound, but also handle the management of sound playback requests.
(They also hold the sound data to be played until server processing is executed after calling the criAtomExPlayer_Start function.)

If there are not enough virtual voices, an error callback will be returned and the sound playback will fail.
(The playback request itself will not be executed at all, and therefore playback will always fail without any voice priority or other evaluations ever being performed.)
Set the value of max_virtual_voices to a value sufficiently greater than the number of actual voices when initializing your application in order to ensure that there are enough virtual voices.
(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 1 V.")

(4) Initialization Parameters for the CRI File System Library (fs_config)

CRI Atom library uses CRI File System library for reading files.
Therefore, when the criAtomEx_Initialize function is called, CRI File System library is initialized within the function.

When NULL is specified for fs_config, CRI Atom library initializes CRI File System library using default settings.
If you want to initialize CRI File System using non-default settings, you must set a CriFsConfig structure to fs_config and initialize CRI Atom library.

[Note]
There are several parameters that can be specified at library initialization other than those listed above.
Refer to the "::CriAtomExConfigTag" section for details on the configurable parameters.

If CRI File System library has already been initialized when the criAtomEx_Initialize function is called, the criAtomEx_Initialize function does not initialize CRI File System library.
For initialization of CRI File System library, refer to CRI File System "FileMagik PRO" manual.

Omitting the Configuration Structure

Specification of a configuration structure can be omitted when initializing the library.
Specifically, you can specify NULL as the argument of the criAtomEx_Initialize function as follows.

main()
{
        :
    /* Initialize without specifying a configuration structure */
    criAtomEx_Initialize(NULL, NULL, 0);
        :
}

When the configuration structure is omitted, CRI Atom library is initialized using the following settings.

• Framework is set to multi-thread model
• Frequency of the server process is set to 60 Hz
• The maximum number of virtual voices is set to 16
• CRI File System library is initialized using default settings

When initializing the library using the same settings as above, it is possible to omit the specification of a configuration structure.

Specifying Working Memory

In addition to the above parameters, you must specify working memory required for the operation of the library when initializing the library.
For information on specifying the working memory, see About Working Memory .

Finalizing the Library

When exiting the application, you must finalize the library.

When the library is initialized using the criAtomEx_Initialize function, you use the criAtomEx_Finalize function to finalize the library.
By finalizing the library, the working memory set at the time of initialization can be released or reused for other purposes.

Next:About Thread