CRI ADX  Last Updated: 2024-09-25 17:41 p
出力ポート
出力ポートは、音声の出力先の管理や制御を容易にするための機能です。
メインの出力先とは別のデバイスでの再生や、プラットフォーム機能を用いた特殊な再生の時に役に立ちます。

出力ポートの基本

出力ポートが指定された音声を再生すると、自動的にその出力ポートを経由して再生されます。
ただし、出力ポートは実際の出力先(出力デバイス)ではないことに注意してください。
CRI ADXにおける出力先は、原則ASRラックを作成して扱います。 出力ポートには、実際の出力先としてASRラックIDを設定しなければなりません。
出力ポートに出力先としてASRラックを設定することで、 当該出力ポートを経由する音声は設定した出力先から出力されるようになります。

出力ポートの使用パターン

出力ポートには、主に2通りの使用パターンがあります。
  1. CRI Atom Craft で事前に出力ポートを設定する
  2. アプリケーションから出力ポートを作成する

1. CRI Atom Craft で事前に出力ポートを設定する

CRI Atom Craft での出力ポートの設定

CRI Atom Craftで出力ポートを設定し、トラックに出力ポート名を指定します。
設定方法など、詳しくは 出力ポート を参照してください。

アプリケーションで行う作業

ランタイムにおける出力ポートは、出力ポートハンドルで扱います。
CRI Atom Craftで設定した出力ポートは、ACFファイルの登録時にACFの中でハンドルが作成されます。
出力ポート名を指定したトラックが再生されると、 ACFの中から同じ名前を持つ出力ポートハンドルを探し、その出力ポートを経由して再生します。
アプリケーションでは出力ポートを経由する音声が再生される前に、 出力ポートハンドルに適切な出力先(ASRラック)を設定します。
ACF内の出力ポートハンドルは出力ポート名で取得します。 ACFに設定された出力ポート名は、ACFヘッダーに記載されています。
/* ACFファイルを登録 */
criAtomEx_RegisterAcfFile(NULL, ACF_PATH, NULL, 0);
:
:
/* ACF内の出力ポートハンドルを取得 */
port_hn = criAtomExAcf_GetOutputPortHnByName("Output_port_name");
/* 出力ポートに適切な出力先(ASRラック)を作成 */
rack_id = create_asr_rack_for_output_port();
/* 出力ポートハンドルにASRラックIDを設定 */
CriAtomExOutputPortHn criAtomExAcf_GetOutputPortHnByName(const CriChar8 *name)
ACFの出力ポートハンドルの取得(名前指定)
CriBool criAtomEx_RegisterAcfFile(CriFsBinderHn binder, const CriChar8 *path, void *work, CriSint32 work_size)
ACFファイルの登録
void criAtomExOutputPort_SetAsrRackId(CriAtomExOutputPortHn output_port, CriAtomExAsrRackId rack_id)
ASRラックIDの指定
CRI Atom Craftで予めトラック単位で出力ポート名を指定できるため、 一つのキューで異なる出力先を持つトラックを同時に再生することも可能です。
またパッドスピーカー再生や配信を制限した再生などの特殊な再生を行いたい場合でも、 CRI Atom Craftで事前に音声に出力ポートを指定し、その機能を持つASRラックを出力ポートに設定するだけで済むため、ランタイムの操作が簡単になります。
以下の図は例として、CRI Atom Craftでパッドスピーカーで再生を行うトラックを指定したケースを表しています。
同じキューのトラックでも、出力ポート名の指定があるトラックのみが出力ポートを経由して意図した出力先のASRラックから再生されます。

2. アプリケーションから出力ポートを作成する

ACF内の出力ポートとは別に、アプリケーションから出力ポートハンドルを作成することもできます。 この機能は、アプリケーションの状況に合わせて出力先を変更する必要がある場合に役に立ちます。
アプリケーションから作成した出力ポートは、以下の2つの機能で使用します。
  • プレーヤーの全ての音声の出力先を指定する
  • CRI Atom Craftで指定した出力ポートの代わりを指定する

プレーヤーの全ての音声の出力先を指定する

アプリケーションから作成した出力ポートハンドルは、 criAtomExPlayer_AddOutputPort 関数を使用してプレーヤーに追加することができます。
出力ポートハンドルを追加すると、そのプレーヤーから再生される全ての音声は、 他の設定を無視して追加した出力ポートを経由して再生されます。
一つのプレーヤーに複数の出力ポートハンドルを追加することも可能です。その場合、追加した出力分ボイスを消費します。
以下の図は例として、新しいパッドスピーカーに対応する出力ポートをプレーヤーに追加したケースを表しています。
出力ポートを追加したプレーヤーから再生された音声は、出力ポート名の指定を含め他の設定を無視して追加した出力ポートを経由します。

CRI Atom Craftで指定した出力ポートの代わりを指定する

ACF内の出力ポートと同じ名前の出力ポートハンドルを、 criAtomExPlayer_AddPreferredOutputPort 関数を使用してプレーヤーに優先出力ポートとして追加することができます。
優先出力ポートは、同じ名前のACF内の出力ポートの代わりに使用されます。
例えば、 Hoge という出力ポート名を指定したトラックが再生されると、通常はACF内の Hoge 出力ポートを経由して再生されます。
しかし同じ Hoge という名前の出力ポートハンドルを作成し、プレーヤーに優先出力ポートとして追加すると、 そのトラックは優先出力ポートを経由して再生されます。
優先出力ポートは、出力ポート名を指定していないトラックや別の出力ポート名を指定したトラックには影響しません。
以下の図は例として、新しいパッドスピーカーに対応する出力ポートを優先出力ポートとして追加したケースを表しています。
ACF内の出力ポートと同じ名前の優先出力ポートは、その出力ポート名の指定があるトラックにのみ影響します。


出力ポートのタイプ

出力ポートハンドルを作成する時、タイプを指定します(ACF内の出力ポートの場合、CRI Atom Craftで設定したタイプが指定されます)。
出力ポートのタイプは、その出力ポートを経由する音声をどう再生するかによって選択します。
ただし出力ポートそのものは出力先ではないため、ある出力ポートを経由した音声がどう出力されるかは、当該出力ポートに設定したASRラックに依存することに注意してください。
現在出力ポートには2つのタイプがあります。
  • 音声
  • 振動

音声

出力ポートを経由する音声を通常のオーディオとして再生したい時に指定するタイプです。
メイン出力先への再生だけでなく、パッドスピーカー再生や配信を制限した再生など特殊な再生を行う出力ポートでも、オーディオとして再生する場合こちらを指定します。
このタイプの出力ポートに設定するASRラックに制限はありません。

振動

出力ポートを経由する音声を音声ベース振動として再生したい時に指定するタイプです。
音声ベース振動が使用できるプラットフォームでは、適切なASRラックを作成してこのタイプの出力ポートに設定します。
このタイプの出力ポートには、振動を制御するための追加の機能が使用できます。詳しくは、各プラットフォームのサンプルを参照してください。
このタイプの出力ポートに設定するASRラックは、出力チャンネルが2である必要があります。

音声ベース振動が非対応のプラットフォームの場合

マルチプラットフォーム開発などで、振動タイプの出力ポートを設定したACFファイルを音声ベース振動非対応のプラットフォームでも使用する場合があります。
この場合、何もせずに振動タイプの出力ポートが指定されたトラックを再生すると、警告を発生してメイン出力先で再生されます。
振動を目的としたトラックの再生を防ぐためには、例えば以下のような方法が考えられます。
  1. 出力チャンネルを2に設定したASRラックを作成
  2. 振動タイプの出力ポートに作成したASRラックを設定
  3. ASRラックのマスターバスのボリュームを0に設定


出力ポートのカテゴリ無効化

出力ポートには特定の カテゴリ の影響を無効にする機能があります。
この機能は、キューに設定されたカテゴリの影響を、キュー内の、特定の出力ポートが設定されたトラックには適用したくない場合に使用します。
例えばSEのキューは、発音用のトラックと振動用のトラックを両方含むことがあります。
このようなキューにSEのカテゴリを設定すると、カテゴリのボリュームが振動用のトラックにも適用されます。
振動タイプの出力ポートにSEのカテゴリの影響を無効にすることで、SEのカテゴリのボリュームを調整しても振動用のトラックは影響されなくなります。
無効化するカテゴリは criAtomExOutputPort_IgnoreCategoryParametersById 関数で設定できます。
また設定したカテゴリは、 criAtomExOutputPort_ResetIgnoreCategory 関数でリセットできます。
無効化できるカテゴリの最大数は、 CriAtomExOutputPortConfig::max_ignored_categories で指定されます。
覚え書き
criAtomExOutputPort_SetDefaultConfig で設定されるデフォルト値は4です。