Vodafone Java(tm) テクノロジプラットフォーム仕様

com.vodafone.lcdui
クラス SVGImage

java.lang.Object
  拡張com.vodafone.lcdui.SVGImage

public class SVGImage
extends java.lang.Object

SVGImage クラスにより、MIDP に従ってアプリケーションで SVG Tiny 1.1 イメージの操作とレンダリングを行うことができます。

SVG イメージは拡大縮小が可能であり、好みのサイズに伸縮できます。さらにイメージをズームインして詳細を拡大表示したり、ズームアウトして表示領域を大きくできます。イメージを回転やパン (平行移動) することもできます。これらの操作はすべて画素化を伴わないため、どのような解像度ズーム倍率や回転角度であっても高画質レンダリングが可能です。

SVG イメージは、SVG 仕様の定義に従ってビューポートの SVG 概念を使用します。ビューポートは「ビューポート空間」と呼ばれる座標空間で定義されます。 ビューポート空間の 1 単位は 1 デバイスピクセルのサイズに等しく、正の X 軸の向きは左から右、正の Y 軸の向きは上から下です。SVGImage を最初に作成したあとのビューポートのサイズは、ルートの <svg> 要素の width 属性と height 属性によって定義されます。これらの値が百分率の座標を使用する場合、参照値 100 が使用されます。つまり、ルートの <svg> 要素の幅が 50% の場合、ビューポートの幅の計算結果は 50 になります。 ルート <svg> 要素に width/height 属性が指定されていない場合は、SVG 仕様に従ってデフォルト値の 100%/100% が使用されます。これらのことを参照値 100 に当てはめると、デフォルトの width/height は 100 になります。 ビューポートのサイズは、getViewportWidth メソッドと getViewportHeight メソッドを使用して決定できます。最初のビューポートのサイズは、setViewportSize メソッドで無効にできます。

SVGImage は、drawImage メソッドを呼び出して SVG コンテンツをレンダリングする際に SVG コンテンツをビューポートに適合させます。

コンテンツは、SVG ユーザー空間からビューポート空間に変換を適用することによって適合します。これを、ユーザー空間からビューポート空間への変換 F と呼びます。F は、イメージの preserveAspectRatio 属性と viewBox 属性を表します。

また、文書をズーム、パン、および回転するためにユーザー変換を適用できます。この変換は U と呼ばれます。

SVG ユーザー空間の点 (Pt[us]) は次の変換式によってビューポート空間の点 (Pt[vp]) へマッピングされ、さまざまな変換が可能です。

Pt[vp] = U.F.Pt[us]

この式の U および F は、3×3 の行列で表現されるアフィン変換です。 また、Pt[x] は、従来の [x, y, 1] 表記で表される点です。演算子「.」は、2 つの行列の乗算、または行列と点の乗算を表します。

SVG イメージは次のように描画できます。


 String svgURI = "http://www.foo.com/svgMap.svg";
 SVGImage svgRenderable 
    = SVGImage.createImage(svgURI);
 svgRenderable.setViewportSize(200, 300);
 svgImage.zoom(2);

 Graphics g = ...;
 svgRenderable.drawImage(g, 40, 60);
 

SVG Tiny では、URI 参照は、use、anchor、および image 要素上にあります。次のパラグラフでは、createImage 呼び出しにおけるこれらの各要素の場合のエラー処理について説明します。

anchor 要素の URI 参照は、この API では無視され、不正な場合でも、IOException が発生しません。

use 要素の URI 参照は、有効で、非循環であり、ローカルな参照でなければなりません。その他の参照、つまりローカルではない参照、循環参照、または不正な参照の場合、文書はエラーになり、IOException が発生します。

image 要素の URI 参照は、有効な外部参照である必要があります。image 要素のローカル参照は、有効でも、不正でもエラーになり、IOException が発生します。image 要素の不正な外部参照では、文書はエラーになりません。取得できない image 要素では何も引き起こされません。

導入されたバージョン:
VSCL2.0
関連項目:
Scalable Vector Graphics (SVG) 1.1 Specification, Mobile SVG Profiles: SVG Tiny and SVG Basic

メソッドの概要
static SVGImage createImage(java.io.InputStream is)
          新しい SVGImage を作成します。
static SVGImage createImage(java.lang.String svgURI)
          新しい SVGImage を作成します。
 void drawImage(javax.microedition.lcdui.Graphics g, int x, int y)
          SVG イメージを Graphics オブジェクトにレンダリングします。
 int getViewportHeight()
          ビューポートの高さを返します。
 int getViewportWidth()
          ビューポートの幅を返します。
 void pan(float panX, float panY)
          平行移動を現在のユーザー変換に事前に連結します。
 void resetUserTransform()
          ユーザー変換をアイデンティティ (自身への変換) にリセットします。
 void rotate(float theta, float x, float y)
          指定した中心を持つ回転を現在のユーザー変換に事前に連結します。
 void setViewportSize(int width, int height)
          SVG イメージのビューポートの幅と高さを設定します。
 void toUserSpace(int[] viewportCoordinate, float[] userSpaceCoordinate)
          入力ビューポート座標を SVG ユーザー空間座標にマッピングします。
 void toViewportSpace(float[] userSpaceCoordinate, int[] viewportCoordinate)
          入力 SVG ユーザー空間座標をビューポート座標にマッピングします。
 void zoom(float zoom)
          ズーム変換を現在のユーザー変換に事前に連結します。
 
クラス java.lang.Object から継承したメソッド
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

メソッドの詳細

createImage

public static SVGImage createImage(java.lang.String svgURI)
                            throws java.io.IOException
新しい SVGImage を作成します。イメージの最初のビューポートサイズは、上記のように決まります。最初のユーザー変換は、resetTransform メソッドを呼び出したあとと同じ状態のアイデンティティ (自身への変換) に設定されます。

パラメータ:
svgURI - 適切なプロトコルハンドラによって読み込まれる SVG URI (javax.microedition.io.Connector クラスの説明を参照)
戻り値:
URI の SVGImage
例外:
java.io.IOException - SVG コンテンツを読み込み中に IO エラーが発生した場合または、SVG 文書にエラーがある場合も例外が発生する (SVG 1.1 仕様の「付録 F」を参照)。最終的に、SVG コンテンツの use 要素にローカルではない参照、循環参照、または不正な URI 参照が含まれる、あるいは image 要素にローカル URI 参照が含まれる場合、IOException が発生する (クラスコメントを参照)。
java.lang.IllegalArgumentException - svgURI パラメータが不正な場合
関連項目:
createImage(java.io.InputStream)

createImage

public static SVGImage createImage(java.io.InputStream is)
                            throws java.io.IOException
新しい SVGImage を作成します。イメージの最初のビューポートサイズは、上記のように決まります。最初のユーザー変換は、resetTransform メソッドを呼び出したあとと同じ状態のアイデンティティ (自身への変換) に設定されます。

パラメータ:
is - 入力ストリーム。 ここから SVG コンテンツが読み取られる
戻り値:
ストリームの SVGImage
例外:
java.io.IOException - SVG コンテンツを読み込み中に IO エラーが発生した場合または、SVG 文書にエラーがある場合も例外が発生する (SVG 1.1 仕様の「付録 F」を参照)。最終的に、SVG コンテンツの use 要素にローカルではない参照、循環参照、または不正な URI 参照が含まれる、あるいは image 要素にローカル URI 参照が含まれる場合、IOException が発生する (クラスコメントを参照)。
関連項目:
createImage(java.lang.String)

setViewportSize

public void setViewportSize(int width,
                            int height)
                     throws java.lang.IllegalArgumentException
SVG イメージのビューポートの幅と高さを設定します。

パラメータ:
width - 新しいビューポートの幅
height - 新しいビューポートの高さ
例外:
java.lang.IllegalArgumentException - width が 0 未満であるか、height が 0 未満である場合
関連項目:
getViewportWidth(), getViewportHeight()

getViewportWidth

public int getViewportWidth()
ビューポートの幅を返します。

戻り値:
現在のビューポートの幅
関連項目:
setViewportSize(int, int)

getViewportHeight

public int getViewportHeight()
ビューポートの高さを返します。

戻り値:
現在のビューポートの高さ
関連項目:
setViewportSize(int, int)

drawImage

public void drawImage(javax.microedition.lcdui.Graphics g,
                      int x,
                      int y)
SVG イメージを Graphics オブジェクトにレンダリングします。ビューポートは、ビューポート空間の矩形 (0, 0, viewportWidth, viewportHeight) です。この矩形のキャンバス上の位置は、x パラメータと y パラメータによって決まります。

viewportWidth と viewportHeight はビューポート座標空間内の長さです。 つまりイメージの幅と高さのデバイスピクセル数を表します。

Graphics の平行移動 (translate メソッドで設定) はビューポートの位置にも影響を及ぼすので注意してください。たとえば、次のコードの抜粋について考えてみます。


// 初め、 graphics コンテキストの原点は (0, 0)
Graphics g = ...; 
 
// graphics の原点を (10, 30) に変更
 g.translate(10, 30);

//SVGImage を描画します
 SVGImage svgImage = ...;
 svgImage.drawImage(g, 20, 40);
 

drawImage 呼び出しは Graphics 平行移動とビューポートの原点を使用するため、ビューポートの位置は (30, 70) になります。

ビューポート座標をグラフィックス座標に変換する方法を数学的に表すと、次のようになります。


 [1  0 tx+x]
 [0  1 ty+y]
 [0  0   1 ]
 

tx は現在の Graphics の X 軸上の移動、ty は現在の Graphics の Y 軸上の移動、x は ビューポートの原点の X 座標、y はビューポートの原点の Y 座標です。

また、レンダリングは、現在の Graphics のクリップで定義された領域に制限されます。この呼び出しの影響を受ける領域は、ビューポートと現在のクリップの共通部分です。

パラメータ:
g - SVG コンテンツが描画される Graphics
x - SVG コンテンツが描画される X 座標。これは、キャンバス上のビューポートの x 位置である
y - SVG コンテンツが描画される Y 座標。これは、キャンバス上のビューポートの y 位置である
例外:
java.lang.NullPointerException - Graphics g が null の場合
関連項目:
Graphics

toUserSpace

public void toUserSpace(int[] viewportCoordinate,
                        float[] userSpaceCoordinate)
入力ビューポート座標を SVG ユーザー空間座標にマッピングします。入力座標は、[0, 0, viewportWidth, viewportHeight] で表される矩形内に含まれない場合があります。

この変換は、ルートの <svg> 要素上での preserveAspectRatio と viewBox の処理による SVG ユーザー空間からビューポート空間への変換とあらゆるユーザー変換を表します (zoom メソッド、pan メソッド、および rotate メソッドを参照)。クラスの説明の UF 表記を使うと、入力座標の変換は次のようになります。inverse(U.F) ここで、inverse() は、inverse(U.F).U.F が自身への変換となる関数です。

パラメータ:
viewportCoordinate - ビューポート座標空間内の 2 つの整数値の配列。最初の配列値は X 座標、2 番目の配列値は Y 座標である
userSpaceCoordinate - SVG ユーザー空間座標系の 2 つの浮動小数点値の配列。ここに結果が書き込まれる。最初の配列値は X 座標、2 番目の配列値は Y 座標である
例外:
java.lang.IllegalArgumentException - 入力引数の少なくとも一方が null の場合、または引数の長さが 2 でない場合
関連項目:
toViewportSpace(float[], int[])

toViewportSpace

public void toViewportSpace(float[] userSpaceCoordinate,
                            int[] viewportCoordinate)
入力 SVG ユーザー空間座標をビューポート座標にマッピングします。

適用される変換は、ほかのユーザー変換と同様、ルートの <svg> 要素上の preserveAspectRatio と viewBox の処理によるユーザー空間からビューポート空間への変換が含まれます (zoom メソッド、pan メソッド、および rotate メソッドを参照)。クラスの説明の UF の表記を使用すると、入力座標に適用される変換は U.F です。

結果の座標は、[0, 0, viewportWidth, viewportHeight] で表される矩形内に含まれない場合があることに注意してください。

パラメータ:
userSpaceCoordinate - ユーザー空間座標系の 2 つの浮動小数点値の配列。
viewportCoordinate - ビューポート座標空間内の 2 つの整数値の配列。ここに結果が書き込まれる
例外:
java.lang.IllegalArgumentException - 入力引数の少なくとも一方が null の場合、または引数の長さが 2 でない場合
関連項目:
toUserSpace(int[], float[])

zoom

public void zoom(float zoom)
ズーム変換を現在のユーザー変換に事前に連結します。

このメソッドを呼び出した場合、新しいユーザー変換は次のようになります。


 U' = Z.U
 

U は以前のユーザー変換、Z はユニフォームスケール変換です。


 [zoom    0   0]
 [  0   zoom  0]
 [  0     0   1]
 

パラメータ:
zoom - ユーザー変換に追加されるズーム係数
例外:
java.lang.IllegalArgumentException - 入力ズーム係数が 0 以下の場合

pan

public void pan(float panX,
                float panY)
平行移動を現在のユーザー変換に事前に連結します。

このメソッドを呼び出した場合、新しいユーザー変換は次のようになります。


 U' = T.U
 

U は以前のユーザー変換、T は次の変換です。


 [1    0   panX]
 [0    1   panY]
 [0    0      1]
 

パラメータ:
panX - X 軸上の移動
panY - Y 軸上の移動

rotate

public void rotate(float theta,
                   float x,
                   float y)
指定した中心を持つ回転を現在のユーザー変換に事前に連結します。

このメソッドを呼び出した場合、新しいユーザー変換は次のようになります。


 U' = R.U
 

U は以前のユーザー変換、R はユニフォームスケール変換です。


 [1    0   x][cos(theta) -sin(theta)   0][1    0   -x]
 [0    1   y][sin(theta)  cos(theta)   0][0    1   -y]
 [0    0   1][    0           0        1][0    0    1]
 

座標系の方向のため、正の角度は時計回りで表されます。

パラメータ:
theta - 追加角度 (度数)
x - X 軸方向の回転の中心
y - Y 軸方向の回転の中心

resetUserTransform

public void resetUserTransform()
ユーザー変換をアイデンティティ (自身への変換) にリセットします。

結果として、ユーザー変換は次のようになります。


 [1    0   0]
 [0    1   0]
 [0    0   1]
 


Vodafone Java(tm) テクノロジプラットフォーム仕様

Vodafone Java テクノロジプラットフォーム仕様 バージョン 1.0.5
Java は、米国およびその他の国における米国 Sun Microsystems, Inc. の商標もしくは登録商標です。Copyright(c) 2004, Vodafone Group Copyright 2003-2004 Sun Microsystems All Rights Reserved.