Audio3D (Star-2.0 (APIリファレンス))

概要

パッケージ

クラス

階層ツリー

非推奨 API

索引

ヘルプ

前のクラス 次のクラス

フレームあり フレームなし

概要: 入れ子 | フィールド | コンストラクタ | メソッド

詳細: フィールド | コンストラクタ | メソッド

com.docomostar.ui
クラス Audio3D

Object
  com.docomostar.ui.Audio3D

public class Audio3D
extends Object
extends Object

[iアプリオプションAPI]

3D サウンドの制御を行うためのコントローラを定義します。

SMF や MFi などのサウンドデータを再生しながら 3D サウンドの制御を行うためには、サウンドデータの再生のために必要なリソースと、 3D サウンドの制御に必要なリソースとの両方が必要になります。サウンドデータの再生のために必要なリソースは AudioPresenter オブジェクトによって確保と解放が行われます。一方、3D サウンドの制御に必要なリソースは、このクラスのオブジェクトを通してアプリから明示的に確保と解放を行う必要があります。 3D サウンドの制御に使用するリソースを確保する際にはリソース数を指定しますが、リソース数は仮想音源の数と同じです。

3D サウンドの制御方法には、サウンドデータに埋め込まれた 3D サウンドイベントによって 3D 環境をコントロールする方法と、サウンドデータを再生しながらアプリから 3D 環境をコントロールする方法があります。

サウンドデータに埋め込まれた 3D サウンドイベントによって 3D 環境をコントロールする場合は、明示的にサウンドデータによってコントロールを行うことを指定して 3D サウンドの制御を有効化します。
3D サウンドの制御の有効化を行わずに再生した場合、サウンドデータに埋め込まれた 3D サウンドイベントは無視されます。

具体的には、以下のような手順で制御を行います(例外処理などについては省略しています)。

 MediaSound ms = MediaManager.getSound(url);
 ms.use();
 AudioPresenter ap = AudioPresenter.getAudioPresenter();
 ap.setSound(ms);
 Audio3D a3d = ap.getAudio3D();
 int resources = Integer.parseInt(ms.getProperty(MediaSound.AUDIO_3D_RESOURCES));
 a3d.enable(Audio3D.MODE_CONTROL_BY_DATA, resources);
 ap.play();
   ...
 ap.stop();
 a3d.disable();
 ms.unuse();

サウンドデータを再生しながらアプリから 3D 環境をコントロールする場合は、明示的にアプリからコントロールを行うことを指定して 3D サウンドの制御を有効化します。アプリからは、3D 環境を 3D 定位で指定します。
アプリからコントロールを行う方法で 3D サウンドの制御の有効化を行って再生した場合、サウンドデータに埋め込まれた 3D サウンドイベントは無視されます。

具体的には、以下のような手順で制御を行います(例外処理などについては省略しています)。

 MediaSound ms = MediaManager.getSound(url);
 ms.use();
 AudioPresenter ap = AudioPresenter.getAudioPresenter();
 ap. setSound(ms);
 Audio3D a3d = ap.getAudio3D();
 a3d.enable(Audio3D.MODE_CONTROL_BY_APP, 1));
 Audio3DLocalization a3dl1 = (3D 定位を表すオブジェクトを生成);
 a3d.setLocalization(a3dl1);
 ap.play();
   ...
 Audio3DLocalization a3dl2 = (3D 定位を表すオブジェクトを生成);
 a3d.setLocalization(a3dl2);
   ...
 ap.stop();
 a3d.disable();
 ms.unuse();

なお、オーディオ・プレゼンタの再生中に 3D サウンドの制御の有効化や無効化を行うことはできません。

3D サウンドの制御を有効化した場合、制御対象のチャンネルではサウンドデータの中のパンポットなどステレオでの音の定位を指定するイベントは無視され、全ての音が 3D 空間の中の一点から聴こえるようになります。

ミニマムスペック:

ミニマムスペックでは、3D サウンドの制御に必要なリソースは 2 つサポートしています。

導入されたバージョン:: Star-1.0
関連項目:: AudioPresenter

フィールドの概要
`static int`	`MODE_CONTROL_BY_APP` アプリケーションから 3D 環境のコントロールを行うことを指定します(= 2)。
`static int`	`MODE_CONTROL_BY_DATA` サウンドデータに埋め込まれた 3D サウンドイベントによる 3D 環境のコントロールを行うことを指定します(= 1)。
`static int`	`SOUND_MOTION_COMPLETE` 定位の移動が完了したことを表すイベントです(= 1)。

メソッドの概要
`void`	`disable()` 3D サウンドの制御を無効化します。
`void`	`enable(int mode)` 3D サウンドの制御を有効化します。
`void`	`enable(int mode, int resources)` 3D サウンドの制御を有効化します。
`static int`	`getFreeResources()` 未使用状態の 3D サウンドの制御を行うためのリソース数を取得します。
`static int`	`getResources()` 端末が持っている 3D サウンドの制御を行うためのリソース数を取得します。
`int`	`getTimeResolution()` 3D 定位の設定に関する時間の解像度を取得します。
`boolean`	`isEnabled()` 3D サウンドの制御が有効化されているかどうかを取得します。
`void`	`setListener(Audio3DListener listener)` リスナを登録します。
`void`	`setLocalization(Audio3DLocalization localization)` 3D サウンドの制御を行うための 3D 環境のうち、3D 定位を設定します。

クラス Object から継承されたメソッド
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

フィールドの詳細

MODE_CONTROL_BY_DATA

public static final int MODE_CONTROL_BY_DATA

サウンドデータに埋め込まれた 3D サウンドイベントによる 3D 環境のコントロールを行うことを指定します(= 1)。アプリケーションからの 3D 環境の指定は無視されます。

関連項目:: 定数フィールド値

MODE_CONTROL_BY_APP

public static final int MODE_CONTROL_BY_APP

アプリケーションから 3D 環境のコントロールを行うことを指定します(= 2)。サウンドデータに埋め込まれた 3D サウンドイベントは無視されます。

関連項目:: 定数フィールド値

SOUND_MOTION_COMPLETE

public static final int SOUND_MOTION_COMPLETE

定位の移動が完了したことを表すイベントです(= 1)。イベントのパラメータには常に 0 が渡されます。

サウンドデータによって 3D 環境をコントロールする場合は、このイベントは発生しません。
アプリケーションから 3D 環境をコントロールする場合は、 SoundMotion による定位の移動が完了した時に発生します。

関連項目:: SoundMotion, 定数フィールド値

メソッドの詳細

getResources

public static int getResources()

端末が持っている 3D サウンドの制御を行うためのリソース数を取得します。このメソッドは同じ端末では常に同じ値を返します。

[Star-2.0 以降]
3D サウンド機能をサポートしていない端末では、このメソッドを呼び出すと常に 2 を返します。

戻り値:: 3D サウンドの制御を行うためのリソース数を返します。

getFreeResources

public static int getFreeResources()

未使用状態の 3D サウンドの制御を行うためのリソース数を取得します。

[Star-2.0 以降]
3D サウンド機能をサポートしていない端末では、このメソッドを呼び出すと常に 2 を返します。

戻り値:: 未使用状態の 3D サウンドの制御を行うためのリソース数を返します。

getTimeResolution

public int getTimeResolution()

3D 定位の設定に関する時間の解像度を取得します。このオブジェクトに対して一度3D 定位を設定した後、次に 3D 定位の設定を行うまでの時間間隔として推奨する値を返します。このメソッドが返す値よりも短い時間間隔で 3D 定位の設定を行った場合、端末によっては 3D 定位の設定に時間がかかったり、 3D サウンドの処理に負荷がかかったりする場合があります。

[Star-2.0 以降]
3D サウンド機能をサポートしていない端末では、このメソッドを呼び出すと常に 100 を返します。

戻り値:: 時間の解像度をミリ秒単位で返します。

enable

public void enable(int mode,
                   int resources)

3D サウンドの制御を有効化します。

3D サウンドの制御のモードとして、サウンドデータに埋め込まれた 3D サウンドイベントで 3D 環境の制御を行うか、アプリケーションから 3D 環境の制御を行うかを指定します。また、3D サウンドの制御のために確保するリソース数を指定します。

サウンドデータに埋め込まれた 3D サウンドイベントで 3D 環境のコントロールを行う場合 (すなわち、引数 mode に MODE_CONTROL_BY_DATA を指定する場合) は、確保するリソース数にはサウンドデータから取得したリソース数を指定します。サウンドデータが必要とするリソース数と異なる数を指定した場合も、アプリから指定された数だけリソースを確保して、その範囲で再生を行います。
すなわち、サウンドデータが必要とするリソース数よりも少ない数を指定した場合は、アプリから指定された数を超える分については 3D サウンドの制御が行われません。また、サウンドデータが必要とするリソース数よりも多い数を指定した場合は、アプリから指定された数だけリソースを確保しますが、サウンドデータが必要とするリソース数を超える分についてはリソースが使用されません (3D サウンドイベントが埋め込まれていないサウンドデータに対して 3D サウンドの制御を有効化して再生した場合も同様です)。
アプリケーションから 3D 環境のコントロールを行う場合 (すなわち、引数 mode に MODE_CONTROL_BY_APP を指定する場合) は、確保するリソース数には 1 を指定します。このオブジェクトを通して 3D サウンドの制御を行うのに必要以上のリソース数が指定された場合は、実際には必要な数だけのリソースを確保します。

このメソッドで確保されたリソースは、disable() が呼ばれるまで確保されたままです。

[Star-2.0 以降]
3D サウンド機能をサポートしていない端末では、このメソッドを呼び出しても何も行いません。また、このとき例外は発生しません。

パラメータ:: mode - 3D サウンドの制御のモードを指定します。 MODE_CONTROL_BY_DATA または MODE_CONTROL_BY_APP のいずれかを指定します。これらの値以外は不正な値であるとみなされます。; resources - 3D サウンドの制御に使用するリソース数を指定します。
例外:: UIException -
(ILLEGAL_STATE)
サラウンド機能 が明�

com.docomostar.ui クラス Audio3D