ハンドルについて

Atomライブラリでは、プレーヤやボイスプールといったオブジェクトを操作する際、"ハンドル"を使用して操作を行います。

オブジェクトを操作する際には、通常「どのオブジェクトに対して」「どういう操作を行うか」を指示する必要があります。
Atomライブラリでは、オブジェクトを指し示すものとして"ハンドル"を、操作内容を指し示すものとして"関数"を提供しています。

ハンドルについて

ハンドルは、オブジェクトに関連付けられた一意の識別子です。
ハンドルはオブジェクト作成時に戻り値として返されます。
作成されたオブジェクトに対する操作は、以降全てこのハンドルを指定して行います。

例えば、プレーヤオブジェクトであるAtomExプレーヤを作成する場合、以下のようなコードになります。

    // AtomExプレーヤハンドル（ハンドルを保持する変数型）
    CriAtomExPlayerHn player;
    
    // AtomExプレーヤの作成
    // 備考）ハンドルが戻り値として返されます。
    player = criAtomExPlayer_Create(…);

［備考］
Atomライブラリでは、ハンドルの変数型は作成するオブジェクトによって異なりますが、必ず末尾に「Hn」が付いています。
例えば、AtomExプレーヤハンドルの場合、 CriAtomExPlayerHn という型になります。

ハンドルを使った操作について

ハンドルに対する操作内容は、実行する関数によって決まります。

例えば、プレーヤにを停止する場合には、停止の操作を示す Stop 関数を使用します。
Atomライブラリでは、関数名の接頭辞にモジュール名を使用しています。
そのため、AtomExプレーヤに対する操作を行う関数は必ず criAtomExPlayer_ という接頭辞が付いています。停止処理の操作を行う場合は、上記の Stop 関数に対し、criAtomExPlayer_ の接頭辞を付けた、 criAtomExPlayer_Stop 関数が使われます。

    // AtomExプレーヤハンドル（ハンドルを保持する変数型）
    CriAtomExPlayerHn player;
    
    // AtomExプレーヤの作成
    // 備考）ハンドルが戻り値として返されます。
    player = criAtomExPlayer_Create(…);
    
    // AtomExプレーヤに対してデータをセット
    // 備考）ハンドルである player に対して buffer をセットするよう指示します。
    criAtomExPlayer_SetData(player, buffer, buffer_size);
    
    // セットされた音声データを再生
    // 備考）ハンドルである player に対して再生の開始（ Start ）を指示します。
    criAtomExPlayer_Start(player);
        ：
    
        ：
    // 再生を停止
    // 備考）ハンドルである player に対して停止（ Stop ）を指示します。
    criAtomExPlayer_Stop(player);
    
    // AtomExプレーヤの破棄
    // 備考）ハンドルである player に対して破棄（ Destroy ）を指示します。
    criAtomExPlayer_Destroy(player);