CriAtomHcaMx API

データ構造
struct	CriAtomHcaMxConfigTag
	HCA-MX初期化用コンフィグ構造体HCA-MXの動作仕様を指定するための構造体です。 criAtomHcaMx_Initialize 関数の引数に指定します。 [詳解]

マクロ定義
#define	CRIATOM_HCA_MX_MAX_MIXERS   (8)
	HCA-MXの最大ミキサー数 [詳解]
#define	CRIATOM_HCA_MX_MAX_OUTPUT_CHANNELS   (8)
	HCA-MXの出力チャンネル数の最大値 [詳解]
#define	criAtomHcaMx_SetDefaultConfig(p_config)
	HCA-MX初期化コンフィグ構造体にデフォルト値をセット [詳解]

型定義
typedef struct CriAtomHcaMxConfigTag	CriAtomHcaMxConfig
	HCA-MX初期化用コンフィグ構造体HCA-MXの動作仕様を指定するための構造体です。 criAtomHcaMx_Initialize 関数の引数に指定します。 [詳解]

関数
CriSint32	criAtomHcaMx_CalculateWorkSize (const CriAtomHcaMxConfig *config)
	HCA-MX初期化用ワーク領域サイズの計算 [詳解]
void	criAtomHcaMx_SetConfigForWorkSizeCalculation (const CriAtomHcaMxConfig *config)
	ワーク領域サイズ計算用コンフィグ構造体の設定 [詳解]
void	criAtomHcaMx_Initialize (const CriAtomHcaMxConfig *config, void *work, CriSint32 work_size)
	HCA-MXの初期化 [詳解]
void	criAtomHcaMx_Finalize (void)
	HCA-MXの終了 [詳解]
void	criAtomHcaMx_SetBusSendLevelByName (CriSint32 mixer_id, const CriChar8 *bus_name, CriFloat32 level)
	ミキサーのバスセンドレベル設定 [詳解]
void	criAtomHcaMx_SetFrequencyRatio (CriSint32 mixer_id, CriFloat32 ratio)
	ミキサーの出力周波数調整比の設定 [詳解]

詳解

マクロ定義詳解

CRIATOM_HCA_MX_MAX_MIXERS

#define CRIATOM_HCA_MX_MAX_MIXERS   (8)

HCA-MXの最大ミキサー数

説明:

HCA-MXの最大ミキサー数です。 CriAtomHcaMxConfig::num_mixers の値は、この値以下に設定する必要があります。

参照

CriAtomHcaMxConfig

CRIATOM_HCA_MX_MAX_OUTPUT_CHANNELS

#define CRIATOM_HCA_MX_MAX_OUTPUT_CHANNELS   (8)

HCA-MXの出力チャンネル数の最大値

説明:

HCA-MXの出力チャンネル数の最大値です。 CriAtomHcaMxConfig::output_channels の値は、この値以下に設定する必要があります。

参照

CriAtomHcaMxConfig

criAtomHcaMx_SetDefaultConfig

#define criAtomHcaMx_SetDefaultConfig

(

p_config

)

値:

{\
    (p_config)->server_frequency = 60.0f;\
    (p_config)->num_mixers = 1;\
    (p_config)->max_players = 16;\
    (p_config)->max_input_channels = CRIATOM_DEFAULT_INPUT_MAX_CHANNELS;\
    (p_config)->max_sampling_rate = CRIATOM_DEFAULT_OUTPUT_SAMPLING_RATE;\
    (p_config)->output_channels = CRIATOM_DEFAULT_OUTPUT_CHANNELS;\
    (p_config)->output_sampling_rate = CRIATOM_DEFAULT_OUTPUT_SAMPLING_RATE;\
    (p_config)->sound_renderer_type = CRIATOM_SOUND_RENDERER_DEFAULT;\
}

HCA-MX初期化コンフィグ構造体にデフォルト値をセット

説明:

criAtomHcaMx_Initialize 関数に設定するコンフィグ構造体 （ CriAtomHcaMxConfig ）に、デフォルト値をセットします。

参照

criAtomHcaMx_Initialize, CriAtomHcaMxConfig

型定義詳解

CriAtomHcaMxConfig

typedef struct CriAtomHcaMxConfigTag CriAtomHcaMxConfig

HCA-MX初期化用コンフィグ構造体HCA-MXの動作仕様を指定するための構造体です。
criAtomHcaMx_Initialize 関数の引数に指定します。

備考:

デフォルト設定を使用する場合、 criAtomHcaMx_SetDefaultConfig マクロで 構造体にデフォルトパラメーターをセットした後、 criAtomHcaMx_Initialize 関数 に構造体を指定してください。

注意

将来的にメンバが増える可能性があるため、 criAtomHcaMx_SetDefaultConfig マクロを使用しない場合には、使用前に必ず構造体をゼロクリアしてください。
（構造体のメンバに不定値が入らないようご注意ください。）

参照

criAtomHcaMx_Initialize, criAtomHcaMx_SetDefaultConfig

関数詳解

criAtomHcaMx_CalculateWorkSize()

CriSint32 criAtomHcaMx_CalculateWorkSize

(

const CriAtomHcaMxConfig *

config

)

HCA-MX初期化用ワーク領域サイズの計算

引数

[in]

config

HCA-MX初期化用コンフィグ構造体

戻り値

CriSint32 ワーク領域サイズ

戻り値

0以上	正常に処理が完了
-1	エラーが発生

説明:

HCA-MXの初期化に必要なワーク領域のサイズを取得します。
criAtom_SetUserAllocator マクロによるアロケーター登録を行わずに criAtomHcaMx_Initialize 関数でHCA-MXの初期化を行う場合、 本関数で計算したサイズ分のメモリをワーク領域として渡す必要があります。

ワーク領域サイズの計算に失敗すると、本関数は -1 を返します。
ワーク領域サイズの計算に失敗した理由については、エラーコールバックのメッセージで確認可能です。

備考:

HCA-MXの初期化に必要なワークメモリのサイズは、HCA-MX初期化用コンフィグ 構造体（ CriAtomHcaMxConfig ）の内容によって変化します。

引数にNULLを指定した場合、デフォルト設定 （ criAtomHcaMx_SetDefaultConfig 適用時と同じパラメーター）で ワーク領域サイズを計算します。
引数 config の情報は、関数内でのみ参照されます。
関数を抜けた後は参照されませんので、関数実行後に config の領域を解放しても 問題ありません。

参照

criAtom_SetUserAllocator, criAtomHcaMx_Initialize

criAtomHcaMx_SetConfigForWorkSizeCalculation()

void criAtomHcaMx_SetConfigForWorkSizeCalculation

(

const CriAtomHcaMxConfig *

config

)

ワーク領域サイズ計算用コンフィグ構造体の設定

引数

[in]

config

HCA-MX初期化用コンフィグ構造体

説明:

ワーク領域サイズの計算用に、HCA-MX初期化用コンフィグ構造体 （ CriAtomHcaMxConfig 構造体）を仮登録します。

HCA-MXプレーヤーの作成に必要なワーク領域のサイズは、 HCA-MX初期化時（ criAtomHcaMx_Initialize 関数実行時） に設定する構造体のパラメーターによって変化します。
そのため、通常はプレーヤーの作成に必要なワーク領域サイズを計算する前に、 HCA-MXを初期化する必要があります。
本関数を使用してHCA-MX初期化用コンフィグ構造体を登録した場合、 criAtomPlayer_CalculateWorkSizeForHcaMxPlayer 関数が初期化処理なしに使用可能となります。

備考:

引数（ config ）に NULL を指定した場合、デフォルト設定 （ criAtomPlayer_SetDefaultConfigForHcaMxPlayer 適用時と同じパラメーター）でワーク領域サイズを計算します。

現状、本関数で一旦コンフィグ構造体を設定すると、 設定前の状態（未初期化状態でのワーク領域サイズ計算をエラーとする動作） に戻すことができなくなります。
（関数を再度実行してパラメーターを上書きすることは可能です。）

注意

本関数で登録した初期化用コンフィグ構造体は、 HCA-MX未初期化状態でのワーク領域サイズ計算にしか使用されません。
HCA-MX初期化後には本関数に設定したパラメーターではなく、 初期化時に指定されたパラメーターがワーク領域サイズの計算に使用されます。
（本関数で登録する構造体のパラメーターと、 HCA-MX初期化時に使用する構造体のパラメーターが異なる場合、 ワーク領域サイズが不足し、ハンドルの作成に失敗する恐れがあります。）

例:

CriAtomHcaMxConfig hca_mx_config;
 
// ワーク領域計算用にHCA-MX初期化設定を仮登録
criAtomHcaMx_SetDefaultConfig(&hca_mx_config);
criAtomHcaMx_SetConfigForWorkSizeCalculation(&hca_mx_config);
 
// HCA-MXプレーヤー作成用ワーク領域サイズの計算
hca_mx_vp_work_size = criAtomPlayer_CalculateWorkSizeForHcaMxPlayer(NULL);
    ：

参照

criAtomPlayer_CalculateWorkSizeForHcaMxPlayer, criAtomPlayer_SetDefaultConfigForHcaMxPlayer

criAtomHcaMx_Initialize()

void criAtomHcaMx_Initialize	(	const CriAtomHcaMxConfig *	config,
		void *	work,
		CriSint32	work_size
	)

HCA-MXの初期化

引数

[in]	config	HCA-MX初期化用コンフィグ構造体
[in]	work	ワーク領域
[in]	work_size	ワーク領域サイズ

説明:

HCA-MXの初期化を行います。
本関数を実行することで、HCA-MXデータの出力機能が起動されます。

備考:

HCA-MXの初期化に必要なワークメモリのサイズは、HCA-MX初期化用コンフィグ 構造体（ CriAtomHcaMxConfig ）の内容によって変化します。

引数にNULLを指定した場合、デフォルト設定 （ criAtomHcaMx_SetDefaultConfig 適用時と同じパラメーター）で初期化処理を行います。

引数 config の情報は、関数内でのみ参照されます。
関数を抜けた後は参照されませんので、関数実行後に config の領域を解放しても 問題ありません。

注意

本関数を実行する前に、ライブラリを初期化しておく必要があります。

本関数は完了復帰型の関数です。
本関数を実行すると、しばらくの間Atomライブラリのサーバー処理がブロックされます。
音声再生中に本関数を実行すると、音途切れ等の不具合が発生する可能性があるため、 本関数の呼び出しはシーンの切り替わり等、負荷変動を許容できるタイミングで行ってください。
本関数を実行後、必ず対になる criAtomHcaMx_Finalize 関数を実行してください。
また、 criAtomHcaMx_Finalize 関数を実行するまでは、本関数を再度実行しないでください。

参照

criAtom_SetUserAllocator, criAtomHcaMx_CalculateWorkSize

criAtomHcaMx_Finalize()

void criAtomHcaMx_Finalize

(

void

)

HCA-MXの終了

説明:

HCA-MXの終了処理を行います。
本関数を実行することで、HCA-MXデータの出力が停止されます。
criAtom_SetUserAllocator マクロを使用してアロケーターを登録済みの場合、 HCA-MX初期化時に確保されたメモリ領域が解放されます。
（HCA-MX初期化時にワーク領域を渡した場合、本関数実行後であれば ワーク領域を解放可能です。）

注意

本関数は完了復帰型の関数です。
本関数を実行すると、しばらくの間Atomライブラリのサーバー処理がブロックされます。
音声再生中に本関数を実行すると、音途切れ等の不具合が発生する可能性があるため、 本関数の呼び出しはシーンの切り替わり等、負荷変動を許容できるタイミングで行ってください。

参照

criAtom_SetUserAllocator, criAtomHcaMx_Initialize

criAtomHcaMx_SetBusSendLevelByName()

void criAtomHcaMx_SetBusSendLevelByName	(	CriSint32	mixer_id,
		const CriChar8 *	bus_name,
		CriFloat32	level
	)

ミキサーのバスセンドレベル設定

引数

[in]	mixer_id	ミキサーID
[in]	bus_name	バス名
[in]	level	センドレベル値（0.0f～1.0f）

説明:

ミキサーのバスセンドレベルを設定します。
デフォルト状態では、HCA-MXのデコード結果はミキサーに格納された後、 バス0へ1.0fのレベルで送信されます。
本関数を使用することで、デコード結果を他のバスへもセンドすることが可能になります。
（ミキサーごとに異なるバスエフェクトを適用可能になります。）

criAtomHcaMx_SetFrequencyRatio()

void criAtomHcaMx_SetFrequencyRatio	(	CriSint32	mixer_id,
		CriFloat32	ratio
	)

ミキサーの出力周波数調整比の設定

引数

[in]	mixer_id	ミキサーID
[in]	ratio	センドレベル値（0.25f～4.0f）

説明:

ミキサーの出力周波数調整比を設定します。
周波数調整比は、音声データの周波数と再生周波数の比率で、再生速度の倍率と等価です。
周波数比が1.0fを超える場合、音声データは原音より高速に再生され、 1.0f未満の場合は、音声データは原音より低速で再生されます。
本関数を使用することで、対象のミキサーを使用する全てのプレーヤーの再生速度を 変更することができます（個々のプレーヤーの再生速度は変更できません）。