com.docomostar.device
クラス RawImageCapture

Object
  com.docomostar.device.RawImageCapture

public class RawImageCapture

extends Object

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

端末のカメラデバイスを制御して RAW 画像を取得する機能を提供するクラスです。 カメラ機能、コード認識機能および動作認識機能と同じカメラデバイスを使用します。

RAW 画像取得機能では、以下のように状態を定義します。

状態	説明
START	カメラデバイス起動中かつ RAW 画像が取得可能な状態
STOP	カメラデバイス停止中かつ RAW 画像が取得不可能な状態

カメラを立ち上げて撮影を行うには、start() メソッドを呼び出します。 このメソッドを実行すると、ネイティブ側で必要なカメラのデバイスリソース獲得・初期化および撮影 が行われて START 状態になります。 Star アプリから RAW 画像を取得するには、getRawImage(byte[]) メソッドを呼び出します。 このメソッドは START 状態で呼び出します。STOP 状態で呼び出した場合は例外が発生します。 RAW 画像取得機能がSTART状態で、Star アプリがサスペンドした場合 stop() メソッドが呼ばれた場合と同様の動作となります。つまり、状態は STOP 状態に遷移します。

STOP 状態のとき、画像サイズ、接写モード、色空間の設定が可能です。 START 状態で設定を行った場合は無視されます。 設定可能な画像サイズ、接写モード、色空間については機種依存です。

Star アプリでは、Camera オブジェクトまたは CodeReader オブジェクトと RawImageCapture オブジェクトは互いの状態に影響を与えません。 Star アプリから Camera 機能、CodeReader 機能を起動し撮影した場合、 RAW 画像取得機能の START 状態、STOP 状態に関わらず Camera オブジェクトから撮影画像を、 CodeReader オブジェクトからコード認識結果を取り出せることを保証します。 なお、RawImageCapture で設定した画像サイズ、接写モードは端末のカメラデバイスを利用するネイティブのカメラ機能およびコード認識機能、Camera オブジェクト、 CodeReader オブジェクトの設定には影響を与えません。

ネイティブのカメラ機能およびコード認識機能が起動している場合には、同時に RAW 画像取得機能を利用することはできません。 start() を呼び出した時に例外が発生します。 また、同時に複数台のカメラを起動する事はできません。同様に例外が発生します。

ネイティブのカメラ機能およびコード認識機能が停止している場合には、 RAW 画像取得機能を利用することができます。 ネイティブのカメラ機能およびコード認識機能で取得したデータを未保存のまま Star アプリに処理が戻った場合でも、Star アプリで RAW 画像取得機能を利用可能です。 その場合、マルチタスク機能でネイティブのカメラ、コード認識機能に戻ることでデータを保存可能です。

動作認識機能と RAW 画像取得機能を同時に起動することはできません。 動作認識エンジン起動中に start() を呼び出すと、例外 DeviceException(BUSY_RESOURCE) が発生します。

このクラスは パーミッションとしてカメラからのRAW画像取得機能の利用が許可されているトラステッド Star アプリのみ利用可能です。

端末によってサポートされない場合があります。未サポートの場合、getRawImageCapture(int) メソッドが呼び出された時点で UnsupportedOperationException を発生します。

導入されたバージョン:

Star-1.0

フィールドの概要

static String	COLORSPACE_RGB565 色空間の１つで、RGB565 形式であることを表します(="RGB565")。
static String	COLORSPACE_RGB888 色空間の１つで、RGB888 形式であることを表します(="RGB888")。
static String	COLORSPACE_YUV422_YUY2 色空間の１つで、YUV422 Packed format YUY2 形式であることを表します(="YUV422_YUY2")。
static String	COLORSPACE_YUV422_YVYU 色空間の１つで、YUV422 Packed format YVYU 形式であることを表します(="YUV422_YVYU")。

コンストラクタの概要

protected

RawImageCapture() アプリケーションが直接このコンストラクタを呼び出して オブジェクトを生成することはできません。

メソッドの概要

String[]	getAvailableColorSpaces() 端末で設定できる色空間のリストを取得します。
int[]	getAvailableFocusModes() 端末で設定できるフォーカスの種類のリストを取得します。
int[][]	getAvailableImageSizes() 撮影可能な画像サイズを取得します。
String	getColorSpace() 色空間の設定状態を取得します。
int	getFocusMode() フォーカスの設定状態を取得します。
int[]	getImageSize() 撮影画像のサイズの設定状態を取得します。
byte[]	getRawImage(byte[] buffer) RawImageCapture オブジェクト内の撮影画像を取得します。
static RawImageCapture	getRawImageCapture(int id) RawImageCapture オブジェクトを取得します。
int	getRawImageLength() RAW 画像のデータサイズを取得します。
void	setColorSpace(String colorSpace) 色空間を設定します。
void	setFocusMode(int mode) フォーカスを設定します。
void	setImageSize(int width, int height) 撮影画像のサイズを設定します。
void	start() カメラデバイスを起動して START 状態にします。
void	stop() カメラデバイスを停止して STOP 状態にします。

クラス Object から継承したメソッド

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

フィールドの詳細

COLORSPACE_YUV422_YVYU

public static final String COLORSPACE_YUV422_YVYU

色空間の１つで、YUV422 Packed format YVYU 形式であることを表します(="YUV422_YVYU")。

関連項目:

定数フィールド値

COLORSPACE_YUV422_YUY2

public static final String COLORSPACE_YUV422_YUY2

色空間の１つで、YUV422 Packed format YUY2 形式であることを表します(="YUV422_YUY2")。

導入されたバージョン:

Star-1.1

関連項目:

定数フィールド値

COLORSPACE_RGB565

public static final String COLORSPACE_RGB565

色空間の１つで、RGB565 形式であることを表します(="RGB565")。

関連項目:

定数フィールド値

COLORSPACE_RGB888

public static final String COLORSPACE_RGB888

色空間の１つで、RGB888 形式であることを表します(="RGB888")。

関連項目:

定数フィールド値

コンストラクタの詳細

RawImageCapture

protected RawImageCapture()

アプリケーションが直接このコンストラクタを呼び出して オブジェクトを生成することはできません。

メソッドの詳細

getRawImageCapture

public static RawImageCapture getRawImageCapture(int id)

RawImageCapture オブジェクトを取得します。

カメラIDに対してこのメソッドが初めて呼ばれた場合はオブジェクトを生成して返します。

生成直後の RawImageCapture オブジェクトは撮影データを保持していない状態になっています。 以後、同じカメラIDに対しては、常に同じオブジェクトへの参照を返します。

Java から制御可能なカメラデバイスの台数、及びカメラ ID とカメラデバイスの対応関係は機種依存です。

パーミッションとしてカメラからのRAW画像取得機能の利用が許可されていない場合、このメソッドを呼び出した時点でセキュリティ違反として強制終了されます。

Javaから制御可能なカメラデバイスのうち、RAW 画像取得機能をサポートしないカメラ ID が存在することがあります。 このカメラ ID を指定した場合、例外 UnsupportedOperationException が発生します。

パラメータ:

id - カメラ ID を指定します。カメラIDについては Camera.getCamera(int) メソッドを参照してください。

戻り値:

RawImageCapture オブジェクトを返します。

例外:

UnsupportedOperationException -
引数 id に、カメラ機能はサポートしているが、RAW 画像取得機能はサポートしていないようなカメラ ID が指定された場合に発生します。

IllegalArgumentException -
引数 id に負の値が指定された場合、または Java から制御可能なカメラデバイスの台数以上の値が指定された場合に発生します。

DeviceException -
(NO_RESOURCES)
カメラデバイスを確保できない場合に発生します。

getAvailableColorSpaces

public String[] getAvailableColorSpaces()

端末で設定できる色空間のリストを取得します。

リストの取得は START/STOP 状態に関わらず可能です。

戻り値:

端末で設定できる色空間をリストで返します。

setColorSpace

public void setColorSpace(String colorSpace)

色空間を設定します。

引数 colorSpace に指定する値は、getAvailableColorSpaces() で取得できる文字列になります。 文字列の代わりに、このクラスで定義されている色空間のフィールドを指定することができます。 この端末でサポートされていない文字列を指定した場合には例外が発生します。

START 状態時にこのメソッドが呼び出した場合、設定は行われずに無視されます。

パラメータ:

colorSpace - 設定する色空間の値を指定します。

例外:

IllegalArgumentException -
引数 colorSpace にこの端末がサポートしていない色空間を指定した場合に発生します。

getColorSpace

public String getColorSpace()

色空間の設定状態を取得します。

最後に setColorSpace(java.lang.String) で設定した値を返します。 一度も setColorSpace(java.lang.String) を呼び出していない状態で、 このメソッドを呼び出した場合に、 どのような値が取得されるかは機種依存です。

色空間の設定状態の取得は START/STOP 状態に関わらず可能です。

戻り値:

色空間の設定状態を返します。

getAvailableFocusModes

public int[] getAvailableFocusModes()

端末で設定できるフォーカスの種類のリストを取得します。

リストの値は、Camera クラスで定義されているフォーカスの種類の定数になります。

フォーカス切替が未サポートである場合には、このメソッドは Camera.FOCUS_NORMAL_MODE を返します。

フォーカス切替がハードウェアによる機構である場合には、このメソッドは Camera.FOCUS_HARDWARE_SWITCH を返します。この場合、Star アプリからフォーカス制御をすることはできません。

リストの取得は START/STOP 状態に関わらず可能です。

戻り値:

端末で設定できるフォーカスの種類をリストで返します。

setFocusMode

public void setFocusMode(int mode)

フォーカスを設定します。

getAvailableFocusModes() で取得したリストから任意の値を設定します。

引数 mode に指定する値は、Camera クラスで定義されているフォーカスの種類の定数になります。 Camera クラスで定義されていない定数、または、リストにない値を指定した場合には例外が発生します。

フォーカス切替がハードウェアによる機構である場合には、引数 mode に Camera.FOCUS_HARDWARE_SWITCH が指定 された場合は何も行わずに無視されます。

START 状態時にこのメソッドが呼び出された場合、設定は行われずに無視されます。

パラメータ:

mode - フォーカスの種類の値を指定します。

例外:

IllegalArgumentException -
引数 mode に不正な値が指定された場合に発生します。

getFocusMode

public int getFocusMode()

フォーカスの設定状態を取得します。

取得した値は、Camera クラスで定義されているフォーカスの種類の定数になります。

最後に setFocusMode(int) で設定した値を返します。 一度も setFocusMode(int) を呼び出していない状態で、このメソッド を呼び出した場合に、どのような値が取得されるかは機種依存です。

フォーカス切り替えが未サポートである場合には、フォーカスの設定状態として Camera.FOCUS_NORMAL_MODE を 返します。

フォーカス切り替えがハードウェアによる機構である場合には、このメソッドは Camera.FOCUS_HARDWARE_SWITCH を返します。この場合、Star アプリからフォーカス制御することはできません。

フォーカス設定状態の取得は START/STOP 状態に関わらず可能です。

戻り値:

フォーカスの設定状態を返します。

getAvailableImageSizes

public int[][] getAvailableImageSizes()

撮影可能な画像サイズを取得します。戻り値は、幅、高さの順でピクセル数が指定される二次元配列です。 例えば、240×320、640×480の2つのサイズが撮影可能な場合、戻り値の内容は次のようになります。

{{240, 320}, {640, 480}}

撮影可能な画像サイズの取得は START/STOP 状態に関わらず可能です。

戻り値:

撮影可能な画像サイズを二次元配列で返します。返される配列は、このオブジェクトが内部で 保持している配列のコピーです。

setImageSize

public void setImageSize(int width,
                         int height)

撮影画像のサイズを設定します。 画像サイズは矩形領域の幅と高さを指定します。

引数 width、height に指定する値は、getAvailableImageSizes() で取得できる幅、高さの組になります。 これ以外の値を指定した場合は例外が発生します。

画像サイズは撮影前に設定してください。画像サイズを設定せずに撮影を実行した場合、機種依存 のデフォルトのサイズにて撮影されます。

START 状態時にこのメソッドが呼び出された場合、設定は行われずに無視されます。

パラメータ:

width - 画像サイズの幅を指定します。

height - 画像サイズの高さを指定します。

例外:

IllegalArgumentException -
引数 width, height に撮影可能ではない画像サイズを指定した場合に発生します。

getImageSize

public int[] getImageSize()

撮影画像のサイズの設定状態を取得します。戻り値は幅、高さの順でピクセル数が指定された配列です。

最後に setImageSize(int, int) で設定した値を返します。 一度も setImageSize(int, int) を呼び出していない状態で、 このメソッドを呼び出した場合は、画像サイズのデフォルト値を返します。 画像サイズのデフォルト値は機種依存です。

画像サイズの設定状態の取得は START/STOP 状態に関わらず可能です。

戻り値:

設定されている画像サイズの幅、高さを返します。

getRawImage

public byte[] getRawImage(byte[] buffer)

RawImageCapture オブジェクト内の撮影画像を取得します。

新しい撮影データが端末側に確保されたメモリに上書きされている最中にこのメソッドを呼び出しても、 新旧の撮影データが混じることなく1フレーム分の撮影データを取得できることが保証されています。

引数 buffer に null 以外を指定した場合、結果はその配列に格納されます。引数 buffer に null を指定した場合、このメソッドが自動的に配列を確保し、その配列に結果を返します。

このメソッドを呼び出す前に、start() メソッドを呼び出して START 状態に しておく必要があります。

サスペンド発生時、STOP状態になるためレジューム時にこのメソッドを呼び出すと、例外が発生します。再度 start() を呼び出してから、このメソッドを呼び出してください。

パラメータ:

buffer - null でない場合、RAW 画像の値はここに書き込まれます。

戻り値:

RAW 画像データの配列を返します。引数 buffer が null でない場合は、buffer と同じ値です。

例外:

ArrayIndexOutOfBoundsException -
引数 buffer が null でない場合に、buffer の長さが撮影データのサイズより短い場合に発生します。

DeviceException -
(ILLEGAL_STATE)
STOP 状態で呼び出された場合に発生します。

DeviceException -
(UNDEFINED)
その他の理由により、RAW 画像が取得できない場合に発生します。

getRawImageLength

public int getRawImageLength()

RAW 画像のデータサイズを取得します。

setImageSize(int, int) メソッドおよび setColorSpace(java.lang.String) メソッドを呼び出さずに呼び出した場合のデータサイズは機種依存です。

撮影データのサイズの取得は START/STOP 状態に関わらず可能です。

戻り値:

setImageSize(int, int) で指定された解像度と、 setColorSpace(java.lang.String) で設定された色空間を元に、RAW 画像 のデータサイズをバイト単位で返します。

start

public void start()

カメラデバイスを起動して START 状態にします。

このメソッドを実行すると、ネイティブのカメラデバイスリソースを獲得し、カメラを立ち上げて定期的な撮影を開始します。 このメソッドを実行した時に設定されている色空間、フォーカスの種類、画像サイズで撮影されます。 撮影データは端末側に確保したメモリに逐次上書きされます。

カメラデバイス起動が正常に完了し、getRawImage(byte[]) が呼び出せる状態になった時点 (START 状態)でこのメソッドから復帰します。

サスペンド発生時、STOP状態になるため、レジューム時に撮影を継続するにはこのメソッドを再度呼び出す必要があります。

START状態で呼び出された場合、後発の呼び出しは無視されます。

例外:

DeviceException -
(BUSY_RESOURCE)
カメラデバイスが使用中により START 状態にできない場合に発生します。

DeviceException -
(NO_RESOURCES)
リソース不足により START 状態にできない場合に発生します。

DeviceException -
(INTERRUPTED)
Suspended 状態に遷移した場合に発生します。

DeviceException -
(RACE_CONDITION)
[Star-1.1 以降] 以下のいずれかの状態でこのメソッドを呼び出した場合に発生します。

• 音声通話中
• テレビ電話通話中
• [Star-1.1 まで] PTT 呼通信中

DeviceException -
(RACE_CONDITION)
[Star-1.1 以降] 音再生をするネイティブアプリの優先設定がONの状態で、 バックグラウンドで音再生が可能な機能（音楽プレイヤー、ミュージックチャネル再生プレイヤー、デジタルテレビアプリケーション）実行中にこのメソッドを呼び出した場合に発生します。

SecurityException -
ロック機能などのネイティブ独自のセキュリティ設定によりSTART状態にできない場合に発生します。

DeviceException -
(UNDEFINED)
上記以外の理由によりSTART状態にできない場合に発生します。

stop

public void stop()

カメラデバイスを停止して STOP 状態にします。

このメソッドを実行すると、起動しているカメラデバイスの停止とリソースの開放を行います。 処理が完了するまでこのメソッドはブロックされます。

再度カメラを起動するには、start()を呼び出す必要があります。

STOP 状態で呼び出された場合、後発の呼び出しは無視されます。