com.docomostar.ui.graphics3d
クラス Primitive

Object
  com.docomostar.ui.graphics3d.Object3D
      com.docomostar.ui.graphics3d.DrawableObject3D
          com.docomostar.ui.graphics3d.Primitive

public class Primitive
extends DrawableObject3D

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

プリミティブ図形群の頂点データなどを保持する、 プリミティブクラスを定義します。

プリミティブオブジェクトは、レンダリング機能のメソッド Graphics3D.renderObject3D(DrawableObject3D, Transform) において、描画対象となるポリゴン等の形状に関する情報を保持します。

プリミティブオブジェクトは、以下のレンダリング用の情報を保持します。

• テクスチャ歪み補正に関する設定
• 図形用ブレンドモード
• 透明度

各種パラメータは、初期状態では以下のようになります。

パラメータ	初期状態
テクスチャ歪み補正	無効 setPerspectiveCorrectionEnabled(false) が呼ばれた状態
図形用ブレンドモード	無設定 ( DrawableObject3D.BLEND_NORMAL )
透明度	100 パーセント(不透明)

プリミティブオブジェクトの 透明度は、設定されている図形用ブレンドモードが DrawableObject3D.BLEND_ALPHA, DrawableObject3D.BLEND_ADD のどちらかのときに有効になります。 このとき、プリミティブの型のすべて (点・線・三角形・四角形・ポイントスプライト)に該当する図形 の描画について、設定されている透明度は影響を与えます。

プリミティブオブジェクトは、 頂点・法線・色・テクスチャ座標・ポイントスプライト情報を それぞれ配列として格納することができます。 頂点情報を格納することは必須ですが、 それ以外の情報は個別に格納するかどうかを指定できます。

プリミティブオブジェクトに、テクスチャ座標の情報を設定するときには、 一つの モデル用の テクスチャ オブジェクトを、 setTexture(Texture) メソッドにより 設定する必要があります。 一つのプリミティブオブジェクトが利用できる モデル用の テクスチャ オブジェクトはただ一つです。 初期状態では、テクスチャ オブジェクトは設定されていません。

setTime(int) メソッド呼び出しによって 現在時刻が変更されても、保持しているデータ内容は変化しません。

プリミティブ図形の型ごとの、プリミティブ情報(属性)と配列との対応を 以下の表に示します。 各情報の値の範囲や制限等については、このクラスで定義されている 各プリミティブ情報の配列を扱うメソッドの説明を参照してください。

プリミティブオブジェクトを実際に描画するときは、 Graphics3D.renderObject3D(DrawableObject3D, Transform) メソッドを利用します。

• 点 ( PRIMITIVE_POINTS )
  

  プリミティブ情報(属性)	パラメータの値	配列のフォーマット
  頂点	----	プリミティブ一個につき頂点一個を格納します。 頂点一個につき (x, y, z) の順で三個の整数値を格納しますので、 配列の長さはプリミティブ数 x 3 となります。
  法線情報	----	使用しません。
  色情報
  	COLOR_PER_PRIMITIVE	プリミティブの個数に関わらず、共通に使われる色情報一個を格納します。 色情報一個につきRGB値を表す一個の整数値を格納しますので、配列の長さは常に 1 となります。
  	COLOR_PER_FACE	プリミティブ一個につき色情報一個を格納します。 色情報一個につき RGB 値を表す一個の整数値を格納しますので、 配列の長さはプリミティブ数 x 1 となります。
  テクスチャ座標情報	----	使用しません。
  ポイントスプライト情報	----	使用しません。

• 線 ( PRIMITIVE_LINES )
  

  プリミティブ情報(属性)	パラメータの値	配列のフォーマット
  頂点	----	プリミティブ一個につき頂点二個を格納します。 頂点一個につき (x, y, z) の順で三個の整数値を格納しますので、 配列の長さはプリミティブ数 x 6 となります。
  法線情報	----	使用しません。
  色情報
  	COLOR_PER_PRIMITIVE	プリミティブの個数に関わらず、共通に使われる色情報一個を格納します。 色情報一個につき RGB 値を表す一個の整数値を格納しますので、配列の長さは常に 1 となります。
  	COLOR_PER_FACE	プリミティブ一個につき色情報一個を格納します。 色情報一個につき RGB 値を表す一個の整数値を格納しますので、 配列の長さはプリミティブ数 x 1 となります。
  テクスチャ座標情報	----	使用しません。
  ポイントスプライト情報	----	使用しません。

• 三角形 ( PRIMITIVE_TRIANGLES )
  

  プリミティブ情報(属性)	パラメータの値	配列のフォーマット
  頂点	----	プリミティブ一個につき頂点三個を格納します。 頂点一個につき (x, y, z) の順で三個の整数値を格納しますので、 配列の長さはプリミティブ数 x 9 となります。
  法線情報	NORMAL_NONE	なし。
  	NORMAL_PER_FACE	プリミティブ一個につき法線情報一個を格納します。 法線情報一個につき (x, y, z) の順で三個の整数値を格納しますので、 配列の長さはプリミティブ数 x 3 となります。
  	NORMAL_PER_VERTEX	プリミティブ一個につき法線情報三個(頂点一個につき法線情報一個)を格納します。 法線情報一個につき (x, y, z) の順で三個の整数値を格納しますので、 配列の長さはプリミティブ数 x 9 となります。
  色情報	COLOR_NONE	なし。
  	COLOR_PER_PRIMITIVE	プリミティブの個数に関わらず、共通に使われる色情報一個を格納します。 色情報一個につき RGB 値を表す一個の整数値を格納しますので、配列の長さは常に 1 となります。
  	COLOR_PER_FACE	プリミティブ一個につき色情報一個を格納します。 色情報一個につき RGB 値を表す一個の整数値を格納しますので、 配列の長さはプリミティブ数 x 1 となります。
  テクスチャ座標情報	TEXTURE_COORD_NONE	なし。
  	TEXTURE_COORD_PER_VERTEX	プリミティブ一個につきテクスチャ座標情報三個 (頂点一個につきテクスチャ座標一個)を格納します。 テクスチャ座標情報一個につき (u, v) の順で二個の整数値を格納しますので、 配列の長さはプリミティブ数 x 6 となります。
  ポイントスプライト情報	----	使用しません。

• 四角形 ( PRIMITIVE_QUADS )
  

  プリミティブ情報(属性)	パラメータの値	配列のフォーマット
  頂点	----	プリミティブ一個につき頂点四個を格納します。 頂点一個につき (x, y, z) の順で三個の整数値を格納しますので、 配列の長さはプリミティブ数 x 12 となります。
  法線情報	NORMAL_NONE	なし。
  	NORMAL_PER_FACE	プリミティブ一個につき法線情報一個を格納します。 法線情報一個につき (x, y, z) の順で三個の整数値を格納しますので、 配列の長さはプリミティブ数 x 3 となります。
  	NORMAL_PER_VERTEX	プリミティブ一個につき法線情報四個(頂点一個につき法線情報一個)を格納します。 法線情報一個につき (x, y, z) の順で三個の整数値を格納しますので、 配列の長さはプリミティブ数 x 12 となります。
  色情報	COLOR_NONE	なし。
  	COLOR_PER_PRIMITIVE	プリミティブの個数に関わらず、共通に使われる色情報一個を格納します。 色情報一個につき RGB 値を表す一個の整数値を格納しますので、配列の長さは常に 1 となります。
  	COLOR_PER_FACE	プリミティブ一個につき色情報一個を格納します。 色情報一個につき RGB 値を表す一個の整数値を格納しますので、 配列の長さはプリミティブ数 x 1 となります。
  テクスチャ座標情報	TEXTURE_COORD_NONE	なし。
  	TEXTURE_COORD_PER_VERTEX	プリミティブ一個につきテクスチャ座標情報四個 (頂点一個につきテクスチャ座標一個)を格納します。 テクスチャ座標情報一個につき (u, v) の順で二個の整数値を格納しますので、 配列の長さはプリミティブ数 x 8 となります。
  ポイントスプライト情報	----	使用しません。

• ポイントスプライト ( PRIMITIVE_POINT_SPRITES )
  

  プリミティブ情報(属性)	パラメータの値	配列のフォーマット
  頂点	----	プリミティブ一個につき頂点一個を格納します。 頂点一個につき (x, y, z) の順で三個の整数値を格納しますので、 配列の長さはプリミティブ数 x 3 となります。
  法線情報	----	使用しません。
  色情報	----	使用しません。
  テクスチャ座標情報	----	使用しません。
  ポイントスプライト情報	POINT_SPRITE_PER_PRIMITIVE	プリミティブの個数に関わらず、共通に使われるプリミティブ情報(属性) 一個を格納します。 ポイントスプライト情報一個につき、 ポイントスプライトの幅・高さ・回転角・ポイントスプライト の左上に対応するテクスチャ位置情報 (u0, v0) ・右下に対応するテクスチャ位置情報 (u1, v1) ・表示フラグの八個の整数値を格納しますので、 配列の長さは常に 8 となります。
  	POINT_SPRITE_PER_VERTEX	プリミティブ一個につきポイントスプライト情報一個を格納します。 ポイントスプライト情報一個につき、 ポイントスプライトの幅・高さ・回転角・ポイントスプライト の左上に対応するテクスチャ位置情報 (u0, v0) ・右下に対応するテクスチャ位置情報 (u1, v1) ・フラグの八個の整数値を格納しますので、配列の長さはプリミティブ数 x 8 となります。

ポリゴンのプリミティブ(三角形・四角形)に関して、特記事項を以下に 示します。

• ポリゴンのプリミティブ(三角形・四角形)は、素材に関して固定値が 設定されます。具体的には、 Ambient 値が 0.2 、Diffuse 値が0.8 の 固定となります。従いまして、法線を持つポリゴンに対して、 白色かつ強度 1.0 の環境以外の光源を法線に向かうように照射したときに、 環境光源が白色かつ強度 1.0 で設定されているとき、ポリゴンに設定 されている色(テクスチャ含む)そのものとして描画されます。
• 法線を持たない場合、設定されている色(テクスチャ含む)によって ポリゴンが描画されます。このとき、あらゆる光源の影響を受けません。

プリミティブ型のうち、ポリゴンではない特殊プリミティブ (点・線・ポイントスプライト)については、以下の制限事項があります。

• 透明度の解像度は、アルファブレンドの場合は 3 段階です。 設定が0％のときは、0％そのまま、 0％超〜50％以下のときは50％に、50％超のときは100％に解釈されます。
• 透明度の解像度は、加算ブレンドの場合は 2 段階です。 設定が0％〜50％以下のときは0％に、50％超のときは100％に解釈されます。
• 平行投影時、ニア面でのクリップは行われません。
• 透視投影時、ニア面に非常に近くに配置されている図形は、 演算誤差により描画されたりされなかったりする可能性があります。
• 透視投影時、ニア面の距離の値が非常に小さい場合(特に1.0以下) には、演算時のオーバフローが起こりやすくなります。 オーバフローの結果として、描画されるはずの図形が欠けたり、 不正な位置に移動したりする状況が発生することがありえます。
• 透視投影時、ニア面の距離と、ファー面の距離の差が非常に大きい場合 (特に1000.0以上)には、演算時のオーバフローが起こりやすくなります。 オーバフローの結果として、描画されるはずの図形が欠け�