Audio3D (DoJa-5.1 (APIリファレンス))

概要

パッケージ

クラス

階層ツリー

非推奨 API

索引

ヘルプ

前のクラス 次のクラス

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

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

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

com.nttdocomo.ui
クラス Audio3D

Object
  com.nttdocomo.ui.Audio3D

public class Audio3D
extends Object

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 つサポートしています。

導入されたバージョン:: DoJa-4.0 (901i)
関連項目:: 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 サウンドの制御を行うためのリソース数を取得します。このメソッドは同じ端末では常に同じ値を返します。

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

getFreeResources

public static int getFreeResources()

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

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

getTimeResolution

public int getTimeResolution()

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

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

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() が呼ばれるまで確保されたままです。

パラメータ:: mode - 3D サウンドの制御のモードを指定します。 MODE_CONTROL_BY_DATA または MODE_CONTROL_BY_APP のいずれかを指定します。これらの値以外は不正な値であるとみなされます。; resources - 3D サウンドの制御に使用するリソース数を指定します。
例外:: UIException - サラウンド機能 が明示的に有効に設定されている場合に発生します(ILLEGAL_STATE)。; UIException - 既に 3D サウンドの制御が有効化されている場合に発生します(ILLEGAL_STATE)。; UIException - オーディオ・プレゼンタの再生中に 3D 制御の有効化を行おうとした場合に発生します(ILLEGAL_STATE)。; IllegalArgumentException - 引数 mode に不正な値が指定された場合に発生します。; IllegalArgumentException - 引数 resources に 0 以下の値が指定された場合に発生します。; UIException - 3D サウンドの制御に使用するリソースを確保できなかった場合に発生します(NO_RESOURCES)。

enable

public void enable(int mode)

3D サウンドの制御を有効化します。 enable(int, int) メソッドのコンビニエンスメソッドで、 3D サウンドの制御のモードに応じたリソース数を確保して 3D サウンドの制御を有効化します。

[DoJa-4.0 (901i、901iS)] モードとして MODE_CONTROL_BY_DATA が指定された場合は、オーディオ・プレゼンタに設定されているサウンドデータから 3D サウンドの制御に必要なリソース数を取り出して、その数だけのリソースを確保します。
[DoJa-4.1 (902i) 以降] モードとして MODE_CONTROL_BY_DATA が指定された場合は、 サウンドデータが必要とするリソース数 と 未使用状態のリソース数 のうち少ない方の数だけリソースを確保します。ただし、確保するリソース数が 0 以下の場合は 3D サウンドの制御を有効化しません。
モードとして MODE_CONTROL_BY_DATA が指定された場合に、オーディオ・プレゼンタにサウンドデータが設定されていない場合は例外が発生します。
モードとして MODE_CONTROL_BY_APP が指定された場合は、 1 つのリソースを確保します。

具体的には、以下の処理を行うことと同等です。また、以下の処理を行う過程で発生した例外はそのままスローされます。

 int resources = 0;
 switch (mode) {
 case MODE_CONTROL_BY_DATA:
   try {
     resources = Integer.parseInt(audiopresenter.getMediaResource().getProperty(MediaSound.AUDIO_3D_RESOURCES));
   } catch (NumberFormatException nfe) {
   }
   int freeResources = Audio3D.getFreeResources();   // [DoJa-4.1 (902i) 以降]
   if (resources > freeResources) {                  // [DoJa-4.1 (902i) 以降]
     resources = freeResources;                      // [DoJa-4.1 (902i) 以降]
   }                                                 // [DoJa-4.1 (902i) 以降]
   if (resources <= 0) {                             // [DoJa-4.1 (902i) 以降]
     return;                                         // [DoJa-4.1 (902i) 以降]
   }                                                 // [DoJa-4.1 (902i) 以降]
   break;
 case MODE_CONTROL_BY_APP:
   resources = 1;
   break;
 }
 enable(mode, resources);

パラメータ:: mode - 3D サウンドの制御のモードを指定します。 MODE_CONTROL_BY_DATA または MODE_CONTROL_BY_APP のいずれかを指定します。これらの値以外は不正な値であるとみなされます。
例外:: NullPointerException - 引数 mode に MODE_CONTROL_BY_DATA が指定された場合に、オーディオプレゼンタにメディアサウンドが設定されていなかった場合に発生します。; UIException - 引数 mode に MODE_CONTROL_BY_DATA が指定された場合に、オーディオプレゼンタに設定されているメディアサウンドが use 状態でない場合に発生します(ILLEGAL_STATE)。; UIException - サラウンド機能 が明示的に有効に設定されている場合に発生します(ILLEGAL_STATE)。; UIException - 既に 3D サウンドの制御が有効化されている場合に発生します(ILLEGAL_STATE)。; UIException - オーディオ・プレゼンタの再生中に 3D 制御の有効化を行おうとした場合に発生します(ILLEGAL_STATE)。; IllegalArgumentException - 引数 mode に不正な値が指定された場合に発生します。; IllegalArgumentException - [DoJa-4.0 (901i、901iS)] 引数 mode に MODE_CONTROL_BY_DATA が指定された場合に、サウンドデータが必要とするリソース数が 0 以下の場合に発生します。; UIException - 3D サウンドの制御に使用するリソースを確保できなかった場合に発生します(NO_RESOURCES)。

disable

public void disable()

3D サウンドの制御を無効化します。既に 3D サウンドの制御が無効化されている場合は何もしません。

このメソッドでは、enable(int, int) で確保されたリソースを解放します。

例外:: UIException - オーディオ・プレゼンタの再生中に 3D 制御の無効化を行おうとした場合に発生します(ILLEGAL_STATE)。

isEnabled

public boolean isEnabled()

3D サウンドの制御が有効化されているかどうかを取得します。

戻り値:: 3D サウンドの制御が有効化されている場合は true を、そうでない場合は false を返します。

setListener

public void setListener(Audio- 3D 繧ｵ繧ｦ繝ｳ繝峨

フィールドの概要
`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 定位を設定します。

com.nttdocomo.ui クラス Audio3D

MODE_CONTROL_BY_DATA

MODE_CONTROL_BY_APP

SOUND_MOTION_COMPLETE

getResources

getFreeResources

getTimeResolution

enable

enable

disable

isEnabled

setListener

com.nttdocomo.ui
クラス Audio3D