com.docomostar.ui
クラス ImageEncoder

Object
  com.docomostar.ui.ImageEncoder

public class ImageEncoder
extends Object

キャンバスやオフスクリーンイメージに描画された画像を JPEG形式等にエンコードする機能を提供します。

getEncoderメソッドにより、 ImageEncoderのインスタンスを取得します。 例えば、JPEG形式に変換するImageEncoderを取得する場合、 getEncoderメソッドの引数に"JPEG"と指定します。

ImageEncoderオブジェクトのencodeメソッドを呼び出すことにより、 CanvasやImageオブジェクトの内容を取り出して、 JPEG形式などに変換します。 変換結果は、EncodedImageオブジェクトとして得られます。 EncodedImageオブジェクトからは、 エンコードされた画像のファイルイメージおよびそのサイズを取得できます。 また、MediaImageオブジェクトとして取り出すことも可能です。 ImageEncoderオブジェクトは再利用することができ、 encodeメソッドを何度でも呼び出すことができます。

変換対象の画像は、Canvasオブジェクト、 およびgetGraphicsメソッドがUnsupportedOperationExceptionをスローしない Imageオブジェクトです。 これらのオブジェクトと変換対象の領域を指定して encodeメソッドを呼び出すことにより、変換が行われます。

ミニマムスペック:

• ミニマムスペックでは、 JPEG形式(JFIF ベースライン)をサポートします。 JPEG形式へ変換するためには、 getEncoder(String) メソッドの引数で"JPEG"を指定してください。 その場合に得られるファイルイメージや MediaImage オブジェクトには再配布不可識別子は設定されていません (再配布可能な状態になっています)。
• ミニマムスペックでは、 オプションAPIに定義されるImageまたはCanvasのサブクラスのオブジェクトに対しては変換できません。
• ミニマムスペックでは、 キャンバスの大きさ(幅および高さ)までの領域を Canvas, Imageの対象によらず変換できることを保証します。 それ以上の大きさについては機種依存であり、 変換できない場合はUIException(NO_RESOURCES)をスローします。

導入されたバージョン:

Star-1.0

フィールドの概要

static int	ATTR_QUALITY_HIGH 変換品質属性の一つで品質優先を表します(=0)。
static int	ATTR_QUALITY_LOW 変換品質属性の一つで変換結果のデータサイズ優先を表します(=2)。
static int	ATTR_QUALITY_STANDARD 変換品質属性の一つで標準を表します(=1)。
static int	QUALITY 変換の品質を制御する属性です(=0)。

メソッドの概要

EncodedImage	encode(Canvas canvas, int x, int y, int width, int height) 指定するCanvasオブジェクトの内容をJPEGデータ等に変換します。
EncodedImage	encode(Image img, int x, int y, int width, int height) 指定するImageオブジェクトの内容をJPEGデータ等に変換します。
static ImageEncoder	getEncoder(String format) 変換する画像の形式を指定してImageEncoderのインスタンスを取得します。
boolean	isAvailable(int attr) 属性が制御可能かどうかを調べます。
void	setAttribute(int attr, int value) 変換に関する属性値を設定します。

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

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

フィールドの詳細

QUALITY

public static final int QUALITY

変換の品質を制御する属性です(=0)。

属性値として、 ATTR_QUALITY_LOW、 ATTR_QUALITY_STANDARD、 ATTR_QUALITY_HIGH を指定することができます。 品質属性がどのように変換に使用されるかは変換アルゴリズムに依存しますが、 通常、高品質になるほど、変換結果のデータサイズも大きくなります。

JPEG形式の場合、 Camera クラスの品質属性と同じ意味を持ちます。

関連項目:

setAttribute(int, int), isAvailable(int), 定数フィールド値

ATTR_QUALITY_HIGH

public static final int ATTR_QUALITY_HIGH

変換品質属性の一つで品質優先を表します(=0)。

関連項目:

定数フィールド値

ATTR_QUALITY_STANDARD

public static final int ATTR_QUALITY_STANDARD

変換品質属性の一つで標準を表します(=1)。 品質属性のデフォルト値です。

関連項目:

定数フィールド値

ATTR_QUALITY_LOW

public static final int ATTR_QUALITY_LOW

変換品質属性の一つで変換結果のデータサイズ優先を表します(=2)。

関連項目:

定数フィールド値

メソッドの詳細

getEncoder

public static ImageEncoder getEncoder(String format)

変換する画像の形式を指定してImageEncoderのインスタンスを取得します。

パラメータ:

format - 変換する画像の形式を文字列で指定します。 JPEG形式に変換する場合、"JPEG"を指定します。

戻り値:

ImageEncoderのインスタンスを返します。

例外:

NullPointerException -
引数 format が null の場合に発生します。

IllegalArgumentException -
サポートされない画像の形式を指定した場合に発生します。

encode

public EncodedImage encode(Image img,
                           int x,
                           int y,
                           int width,
                           int height)

指定するImageオブジェクトの内容をJPEGデータ等に変換します。 Image.getGraphics()メソッドによりGraphicsオブジェクトが取得できる Imageオブジェクトのみ指定することができます。

透過色指定が有効な Image オブジェクトを指定した場合、 そのイメージの透過ピクセルは、 透過色指定を無効にした場合の色 (透過色として指定されている色) のピクセルとして変換されます。

ダブルバッファリングを使用している場合、 バックバッファ内容が取得されます。 すなわち、 lockメソッドを使用する場合も使用しない場合も、 描画内容が同じであれば同じ結果が得られます。

XStringの文字列が描画されたImageオブジェクトを指定して このメソッドを実行すると、 セキュリティ違反により強制終了します。 (XStringクラスを参照)

パラメータ:

img - 変換するImageオブジェクトを指定します。

x - 変換する領域の左上のX座標を指定します。

y - 変換する領域の左上のY座標を指定します。

width - 変換する領域の幅を指定します。

height - 変換する領域の高さを指定します。

戻り値:

変換された画像をEncodedImageオブジェクトとして返します。

関連項目:

Image.getGraphics()

例外:

UnsupportedOperationException -
引数 img のオブジェクトがオプションAPIで定義された Imageのサブクラスであり、 かつ、encode がサポートされていない場合に発生します。

NullPointerException -
引数 img が null の場合に発生します。

IllegalArgumentException -
width、height のいずれかまたは両方が0以下の場合に発生します。

UIException -
(ILLEGAL_STATE)
引数 img のオブジェクトがdisposeされている場合に発生します。

IllegalArgumentException -
getGraphicsメソッドによりGraphicsオブジェクトを取得できない Imageオブジェクトを指定した場合に発生します。

IllegalArgumentException -
指定した領域が指定したImageオブジェクトの領域をはみ出している場合に発生します。

UIException -
(NO_RESOURCES)
リソース不足により変換できなかった場合に発生します。

UIException -
(UNDEFINED)
リソース不足以外の理由により変換に失敗した場合に発生します。

encode

public EncodedImage encode(Canvas canvas,
                           int x,
                           int y,
                           int width,
                           int height)

指定するCanvasオブジェクトの内容をJPEGデータ等に変換します。 指定するCanvasがカレントフレームであり、 IMEが起動されていない場合にのみ変換できます。

ダブルバッファリングを使用している場合、 バックバッファ内容が取得されます。 すなわち、lock メソッドを使用する場合も使用しない場合も、 描画内容が同じであれば同じ結果が得られます。

XStringの文字列が描画されたCanvasオブジェクトを指定して このメソッドを実行すると、 セキュリティ違反により強制終了します。 (XStringクラスを参照)

パラメータ:

canvas - 変換するCanvasオブジェクトを指定します。

x - 変換する領域の左上のX座標を指定します。

y - 変換する領域の左上のY座標を指定します。

width - 変換する領域の幅を指定します。

height - 変換する領域の高さを指定します。

戻り値:

変換された画像をEncodedImageオブジェクトとして返します。

例外:

UnsupportedOperationException -
引数 canvas のオブジェクトがオプションAPIで定義された Canvasのサブクラスであり、 かつ、encode がサポートされていない場合に発生します。

NullPointerException -
引数 canvas が null の場合に発生します。

IllegalArgumentException -
引数 width、height のいずれかまたは両方が0以下場合に発生します。

IllegalArgumentException -
指定した領域が指定したCanvasオブジェクトの領域をはみ出している場合に発生します。

UIException -
(ILLEGAL_STATE)
指定したCanvasオブジェクトがカレントフレームでない場合、 Dialogが表示中である場合、 IME起動中である場合に発生します。

UIException -
(NO_RESOURCES)
リソース不足により変換できなかった場合に発生します。

UIException -
(UNDEFINED)
リソース不足以外の理由により変換に失敗した場合に発生します。

setAttribute

public void setAttribute(int attr,
                         int value)

変換に関する属性値を設定します。 制御可能でない属性、 存在しない属性が指定された場合は何も行わずに無視されます。

パラメータ:

attr - 設定する属性を指定します。

value - 設定する属性の値を指定します。

例外:

IllegalArgumentException -
引数 attr で指定された有効な属性に対して、 引数 value に不正な値が指定された場合に発生します。

isAvailable

public final boolean isAvailable(int attr)

属性が制御可能かどうかを調べます。 このメソッドが true を返した場合は、 そのリソースを setAttribute(int, int) メソッドで制御することが可能です。 ImageEncoderが属性の制御をサポートしていない場合は false を返します。 存在しない属性が指定された場合は false を返します。

パラメータ:

attr - 属性の種類を指定します。

戻り値:

属性が制御可能な場合は true を、 そうでなければ false を返します。