About Handles

In Atom library, "handle" is used when working on objects such as a player or a Voice Pool.

In general, when working on objects, you must specify the "target object" and the "type of operation."
Atom library uses "handles" for specifying the target object and "functions" for specifying the type of operation.

About Handles

Handles are unique identifiers associated with objects.
A handle is returned as a return value when creating an object.
Subsequent operations for the created object can be performed through this handle.

For example, when creating an AtomEx player which is a player object, you can use a code as follows.

// AtomEx player handle (variable type holding a handle)
CriAtomExPlayerHn player;
 
// Create an AtomEx player
// Note: Handle is returned as a return value.
player = criAtomExPlayer_Create(...);

[Note]
In Atom library, there are several variable types depending on the objects you create; all of them have a suffix "Hn."
For example, type of the AtomEx player handle is CriAtomExPlayerHn .

Working on Handles

Operation performed on handles are determined by the function you invoke.

For example, when you want to stop the player, you can use Stop() function, which indicates the stopping operation.
In Atom library, module name is added as a prefix to the name of functions.
Therefore, all functions which works on an AtomEx player have a prefix criAtomExPlayer_. In order to perform stopping operation, you use the criAtomExPlayer_Stop function, in which prefix criAtomExPlayer_ is added to the above Stop function.

// AtomEx player handle (variable type holding a handle)
CriAtomExPlayerHn player;
 
// Create an AtomEx player
// Note: Handle is returned as a return value.
player = criAtomExPlayer_Create(...);
 
// Set data to the AtomEx player
// Note: Instruct the player (which is a handle) to set a buffer.
criAtomExPlayer_SetData(player, buffer, buffer_size);
 
// Plays the specified sound data
// Note: Instruct the player (which is a handle) to start playing.
criAtomExPlayer_Start(player);
    :
 
    :
// Stop playing
// Note: Instruct the player (which is a handle) to Stop.
criAtomExPlayer_Stop(player);
 
// Destroy the AtomEx player
// Note:  Instruct the player (which is a handle) to destroy itself (Destroy).
criAtomExPlayer_Destroy(player);

Next:Module Details