From 38ef0529cbbdb2e6bc56e580178ad72d64372af4 Mon Sep 17 00:00:00 2001
From: nyatla <nyatla@7cac0a50-4618-4814-88d0-24b83990f816>
Date: Wed, 2 Feb 2011 03:42:30 +0000
Subject: [PATCH] git-svn-id:
 http://svn.sourceforge.jp/svnroot/nyartoolkit/NyARToolkit/trunk@810
 7cac0a50-4618-4814-88d0-24b83990f816

---
 .../core/types/matrix/NyARDoubleMatrix44.java      |  2 +-
 .../rpf/reality/nyartk/gl/NyARRealityGl.java       | 64 ++++++++++++++++------
 .../nyartoolkit/jogl/utils/NyARGLDrawUtil.java     | 54 ++++++++++++++----
 .../nyatla/nyartoolkit/jogl/utils/NyARGLUtil.java  | 22 +++++---
 4 files changed, 102 insertions(+), 40 deletions(-)

diff --git a/lib/src/jp/nyatla/nyartoolkit/core/types/matrix/NyARDoubleMatrix44.java b/lib/src/jp/nyatla/nyartoolkit/core/types/matrix/NyARDoubleMatrix44.java
index aad07fe..5a5db35 100644
--- a/lib/src/jp/nyatla/nyartoolkit/core/types/matrix/NyARDoubleMatrix44.java
+++ b/lib/src/jp/nyatla/nyartoolkit/core/types/matrix/NyARDoubleMatrix44.java
@@ -305,7 +305,7 @@ public class NyARDoubleMatrix44 implements INyARDoubleMatrix
 	 * この関数は、行列の回転成分から、ZXY系の角度値を計算します。
 	 * @param o_out
 	 *　角度値を受け取るオブジェクトです。
-	 * 角度値の範囲は、0-PIです。
+	 * 角度値の範囲は、0-PI(要確認)です。
 	 */
 	public final void getZXYAngle(NyARDoublePoint3d o_out)
 	{
diff --git a/utils/jogl/src.rpf/jp/nyatla/nyartoolkit/rpf/reality/nyartk/gl/NyARRealityGl.java b/utils/jogl/src.rpf/jp/nyatla/nyartoolkit/rpf/reality/nyartk/gl/NyARRealityGl.java
index 8880653..9a1881f 100644
--- a/utils/jogl/src.rpf/jp/nyatla/nyartoolkit/rpf/reality/nyartk/gl/NyARRealityGl.java
+++ b/utils/jogl/src.rpf/jp/nyatla/nyartoolkit/rpf/reality/nyartk/gl/NyARRealityGl.java
@@ -13,22 +13,39 @@ import jp.nyatla.nyartoolkit.jogl.utils.NyARGLDrawUtil;
 import jp.nyatla.nyartoolkit.jogl.utils.NyARGLUtil;
 
 /**
- * OpenGLに特化したNyARRealityクラスです。
- * @author nyatla
+ * このクラスは、OpenGLに特化した{@link NyARReality}クラスです。
+ * OpenGL形式の値をそのまま扱う関数を定義しています。
  */
 public class NyARRealityGl extends NyARReality
 {
 	private double[] _gl_frustum_rh=new double[16];
 	/**
-	 * ARToolKitスタイルのModelView行列を、OpenGLスタイルのモデルビュー行列に変換します。
+	 * この関数は、 ARToolKitスタイルのModelView行列を、OpenGLスタイルのモデルビュー行列に変換します。
 	 * @param i_ny_style_mat
+	 * NyARToolkitスタイルの行列を指定します。
 	 * @param o_gl_style_mat
+	 * OpenGL形式の行列を受け取る配列を指定します。16要素である必要があります。
 	 */
 	public static void toGLViewMat(NyARDoubleMatrix44 i_ny_style_mat,double[] o_gl_style_mat)
 	{
 		NyARGLUtil.toCameraViewRH(i_ny_style_mat, 1, o_gl_style_mat);
 	}
-	
+	/**
+	 * コンストラクタです。
+	 * カメラパラメータ、視錐体パラメータを元に、インスタンスを作成します。
+	 * @param i_param
+	 * カメラパラメータを指定します。
+	 * @param i_near
+	 * 視錐体のnear-pointをmm単位で指定します。
+	 * 標準値は{@link #FRASTRAM_ARTK_NEAR}です。
+	 * @param i_far
+	 * 視錐体のfar-pointをmm単位で指定します。
+	 * 標準値は{@link #FRASTRAM_ARTK_FAR}です。
+	 * @param i_max_known_target
+	 * KnownステータスのRTターゲットの最大数を指定します。
+	 * @param i_max_unknown_target
+	 * UnKnownステータスのRTターゲットの最大数を指定します。
+	 */
 	public NyARRealityGl(NyARParam i_param,double i_near,double i_far,int i_max_known_target,int i_max_unknown_target) throws NyARException
 	{
 		super(i_param,i_near,i_far,i_max_known_target,i_max_unknown_target);
@@ -36,20 +53,23 @@ public class NyARRealityGl extends NyARReality
 		this._frustum.refMatrix().getValueT(this._gl_frustum_rh);
 	}
 	/**
-	 * 透視投影行列と視錐体パラメータを元に、インスタンスを作成します。
-	 * この関数は、樽型歪み矯正を外部で行うときに使います。
+	 * この関数は、透視投影行列と視錐体パラメータを元に、インスタンスを作成します。
+	 * 初期状態のインスタンスを生成します。
+	 * この関数は、i_prjmatにnullを指定することで、樽型歪み矯正を行わないインスタンスを生成できます。
 	 * @param i_prjmat
-	 * ARToolKitスタイルのカメラパラメータです。通常は{@link NyARParam#getPerspectiveProjectionMatrix()}から得られた値を使います。
-	 * @param i_screen_size
-	 * スクリーン（入力画像）のサイズです。通常は{@link NyARParam#getScreenSize()}から得られた値を使います。
+	 * ARToolKit形式の射影変換パラメータを指定します。
+	 * @param i_screen
+	 * スクリーン(入力画像)のサイズを指定します。
 	 * @param i_near
-	 * 視錐体のnear-pointをmm単位で指定します。
-	 * default値は{@link #FRASTRAM_ARTK_NEAR}です。
+	 * {@link #NyARReality(NyARParam i_param,double i_near,double i_far,int i_max_known_target,int i_max_unknown_target)}を参照
 	 * @param i_far
-	 * 視錐体のfar-pointをmm単位で指定します。
-	 * default値は{@link #FRASTRAM_ARTK_FAR}です。
+	 * {@link #NyARReality(NyARParam i_param,double i_near,double i_far,int i_max_known_target,int i_max_unknown_target)}を参照
+	 * @param i_dist_factor
+	 * 樽型歪み矯正オブジェクトを指定します。歪み矯正が不要な時は、nullを指定します。
 	 * @param i_max_known_target
+	 * {@link #NyARReality(NyARParam i_param,double i_near,double i_far,int i_max_known_target,int i_max_unknown_target)}を参照
 	 * @param i_max_unknown_target
+	 * {@link #NyARReality(NyARParam i_param,double i_near,double i_far,int i_max_known_target,int i_max_unknown_target)}を参照
 	 * @throws NyARException
 	 */
 	public NyARRealityGl(NyARPerspectiveProjectionMatrix i_prjmat,NyARIntSize i_screen_size,double i_near,double i_far,int i_max_known_target,int i_max_unknown_target) throws NyARException
@@ -61,8 +81,12 @@ public class NyARRealityGl extends NyARReality
 	
 	private double[] _temp=new double[16];
 	/**
-	 * NyARToolKitの姿勢変換行列をOpenGLスタックへロードします。
-	 * @throws NyARException 
+	 * この関数は、NyARToolKitの姿勢変換行列をOpenGL行列スタックへロードします。
+	 * @param i_gl
+	 * OpenGLのインスタンス
+	 * @param i_mat
+	 * NyARToolkit形式の姿勢変換行列
+	 * @throws NyARException
 	 */
 	public void glLoadModelViewMatrix(GL i_gl,NyARDoubleMatrix44 i_mat) throws NyARException
 	{
@@ -72,7 +96,9 @@ public class NyARRealityGl extends NyARReality
 	}
 	
 	/**
-	 * projection行列をOpenGLの行列スタックへロードします。
+	 * この関数は、NyARToolKitの射影変換行列をOpenGL行列スタックへロードします。
+	 * @param i_gl
+	 * OpenGLのインスタンス
 	 */
 	public void glLoadCameraFrustum(GL i_gl)
 	{
@@ -80,10 +106,12 @@ public class NyARRealityGl extends NyARReality
 		return;
 	}
 	/**
-	 * 現在のViewPortに、i_rtsourceの内容を描画します。
+	 * この関数は、現在のViewPortに、i_rtsourceの元画像の内容を描画します。
+	 * 背景画像の描画に使います。
 	 * @param i_gl
 	 * OpenGLインスタンスを指定します。
-	 * @param i_raster
+	 * @param i_rtsource
+	 * 描画するRealitySource
 	 * @throws NyARException
 	 */
 	public void glDrawRealitySource(GL i_gl,NyARRealitySource i_rtsource) throws NyARException
diff --git a/utils/jogl/src/jp/nyatla/nyartoolkit/jogl/utils/NyARGLDrawUtil.java b/utils/jogl/src/jp/nyatla/nyartoolkit/jogl/utils/NyARGLDrawUtil.java
index fbf988f..9cf55d5 100644
--- a/utils/jogl/src/jp/nyatla/nyartoolkit/jogl/utils/NyARGLDrawUtil.java
+++ b/utils/jogl/src/jp/nyatla/nyartoolkit/jogl/utils/NyARGLDrawUtil.java
@@ -15,17 +15,23 @@ import jp.nyatla.nyartoolkit.core.types.NyARIntSize;
 import com.sun.opengl.util.j2d.TextRenderer;
 
 /**
- * OpenGL向けの描画関数を提供します。
+ * このクラスには、アプリケーションの為のOpenGL用のヘルパー関数を定義します。
+ * NyARToolKitを使ったアプリケーションを実装するのに役立ちます。
+ * ほとんどの関数はstatic宣言です。このクラスのインスタンスを作る必要はありません。
+ * 
+ *
  */
 public class NyARGLDrawUtil
 {
 	private static TextRenderer _tr=new TextRenderer(new Font("SansSerif", Font.PLAIN, 10));
 	/**
-	 * 立方体を描画します。
+	 * この関数は、指定サイズの立方体を現在のビューポートへ描画します。
+	 * ARToolKitのサンプルで使われているカラーキューブを描画します。
 	 * @param i_gl
-	 * OpenGLインスタンス
+	 * OpenGLのインスタンス
 	 * @param i_size_per_mm
-	 * 立方体の辺の長さを[mm単位]
+	 * 立方体の辺の長さ。[mm単位]
+	 * ARシステムをmmオーダーで構築していない場合は、別単位になります。
 	 */
 	public static void drawColorCube(GL i_gl,float i_size_per_mm)
 	{
@@ -60,27 +66,36 @@ public class NyARGLDrawUtil
 		i_gl.glCallList(polyList); // Draw the cube.
 	}
 	/**
-	 * フォントカラーをセットします。
+	 * この関数は、{@link NyARGLDrawUtil}の描画する文字列の、フォントカラーを設定します。
+	 * フォントカラーはOpenGL固有のものではなく、{@link NyARGLDrawUtil}固有のものです。
 	 * @param i_c
+	 * 設定する色。
 	 */
 	public static void setFontColor(Color i_c)
 	{
 		NyARGLDrawUtil._tr.setColor(i_c);
 	}
 	/**
-	 * フォントスタイルをセットします。
+	 * この関数は、{@link NyARGLDrawUtil}の描画する文字列の、フォントスタイルを設定します。
+	 * フォントスタイルはOpenGL固有のものではなく、{@link NyARGLDrawUtil}固有のものです。
 	 * @param i_font_name
+	 * フォントの名前を指定します。デフォルト値は、"SansSerif"です。
 	 * @param i_font_style
+	 * フォントスタイルを指定します。デフォルト値は、{@link Font#PLAIN}です。
 	 * @param i_size
+	 * フォントサイズを指定します。デフォルト値は、10です。
 	 */
 	public static void setFontStyle(String i_font_name,int i_font_style,int i_size)
 	{
 		NyARGLDrawUtil._tr=new TextRenderer(new Font(i_font_name,i_font_style, i_size));
 	}
 	/**
-	 * 現在のフォントで、文字列を描画します。
+	 * この関数は、文字列を描画します。
+	 * この関数は、ちらつきが発生したり、あまり品質が良くありません。品質を求められる環境では、別途実装をして下さい。
 	 * @param i_str
+	 * 描画する文字列。
 	 * @param i_scale
+	 * 文字列のスケール値。
 	 */
 	public static void drawText(String i_str,float i_scale)
 	{
@@ -90,9 +105,17 @@ public class NyARGLDrawUtil
 		return;
 	}
 	/**
-	 * INyARRasterの内容を現在のビューポートへ描画します。
+	 * この関数は、{@link INyARRaster}の内容を、現在のビューポートへ描画します。
+	 * カメラ画像の背景を描画するのに使用できます。
 	 * @param i_gl
+	 * OpenGLのインスタンス
 	 * @param i_raster
+	 * 描画するラスタオブジェクト。何れかのバッファ形式である必要があります。
+	 * <ol>
+	 * <li>{@link NyARBufferType#BYTE1D_B8G8R8_24}
+	 * <li>{@link NyARBufferType#BYTE1D_R8G8B8_24}
+	 * <li>{@link NyARBufferType#BYTE1D_B8G8R8X8_32}
+	 * </ol>
 	 * @param i_zoom
 	 * @throws NyARException
 	 */
@@ -177,13 +200,18 @@ public class NyARGLDrawUtil
 		}
 	}
 	/**
-	 * スクリーン座標系をOpenGLにロードします。この関数は、PROJECTIONとMODELVIEWスタックをそれぞれ1づつpushします。
-	 * スクリーン座標系を使用し終わったら、endScreenCoordinateSystemを呼び出してください。
+	 * この関数は、スクリーン座標系をOpenGLにロードします。
+	 * スクリーンに二次元系の情報をそのまま書きこむときに使います。
+	 * この関数は、PROJECTIONとMODELVIEWスタックをそれぞれ1づつpushします。
+	 * スクリーン座標系を使用し終わったら、{@link endScreenCoordinateSystem}を必ず呼び出してください。
 	 * @param i_gl
+	 * OpenGLのインスタンス
 	 * @param i_width
+	 * スクリーンの幅
 	 * @param i_height
+	 * スクリーンの高さ
 	 * @param i_revers_y_direction
-	 * Y軸の反転フラグです。trueならばtop->bottom、falseならばbottom->top方向になります。
+	 * Y軸の反転フラグ。trueならばtop->bottom、falseならばbottom->top方向になります。
 	 */
 	public static void beginScreenCoordinateSystem(GL i_gl,int i_width,int i_height,boolean i_revers_y_direction)
 	{
@@ -201,8 +229,10 @@ public class NyARGLDrawUtil
 		return;
 	}
 	/**
-	 * ロードしたスクリーン座標系を元に戻します。{@link #beginScreenCoordinateSystem}の後に呼び出してください。
+	 * この関数は、ロードしたスクリーン座標系を元に戻します。
+	 * {@link #beginScreenCoordinateSystem}の後に呼び出してください。
 	 * @param i_gl
+	 * OpenGLのインスタンス
 	 */
 	public static void endScreenCoordinateSystem(GL i_gl)
 	{
diff --git a/utils/jogl/src/jp/nyatla/nyartoolkit/jogl/utils/NyARGLUtil.java b/utils/jogl/src/jp/nyatla/nyartoolkit/jogl/utils/NyARGLUtil.java
index 6a885ce..921e481 100644
--- a/utils/jogl/src/jp/nyatla/nyartoolkit/jogl/utils/NyARGLUtil.java
+++ b/utils/jogl/src/jp/nyatla/nyartoolkit/jogl/utils/NyARGLUtil.java
@@ -35,30 +35,32 @@ import jp.nyatla.nyartoolkit.core.param.NyARPerspectiveProjectionMatrix;
 import jp.nyatla.nyartoolkit.core.types.*;
 import jp.nyatla.nyartoolkit.core.types.matrix.*;
 /**
- * OpenGL向けの形式変換変換関数を提供します。
+ * このクラスは、NyARToolkitのデータ型と、OpenGLデータ型を変換する関数を定義します。
  * 描画系関数は{@link NyARGLDrawUtil}を参照してください。
  */
 public class NyARGLUtil
 {
 	/**
-	 * NyARToolKit 2.53以前のコードと互換性を持たせるためのスケール値。{@link #toCameraFrustumRH}のi_scaleに設定することで、
-	 * 以前のバージョンの数値系と互換性を保ちます。
+	 * NyARToolKit 2.53以前のコードと互換性を持たせるためのスケール値。
+	 * {@link #toCameraFrustumRH}のi_scaleに設定することで、以前のバージョンの数値系と互換性を保ちます。
 	 */
 	public final static double SCALE_FACTOR_toCameraFrustumRH_NYAR2=1.0;
 	/**
-	 * NyARToolKit 2.53以前のコードと互換性を持たせるためのスケール値。{@link #toCameraViewRH}のi_scaleに設定することで、
-	 * 以前のバージョンの数値系と互換性を保ちます。
+	 * NyARToolKit 2.53以前のコードと互換性を持たせるためのスケール値。
+	 * {@link #toCameraViewRH}のi_scaleに設定することで、以前のバージョンの数値系と互換性を保ちます。
 	 */
 	public final static double SCALE_FACTOR_toCameraViewRH_NYAR2=1/0.025;
 
-    private NyARGLUtil()
+	private NyARGLUtil()
     {//生成の禁止
     }	
 
 	
 	/**
-	 * ARToolKitスタイルのカメラパラメータから、 CameraFrustamを計算します。
+	 * この関数は、ARToolKitスタイルのカメラパラメータから、 CameraFrustamを計算します。
+	 * カメラパラメータの要素のうち、ProjectionMatrix成分のみを使います。
 	 * @param i_arparam
+	 * ARToolKitスタイルのカメラパラメータ。
 	 * @param i_scale
 	 * スケール値を指定します。1=1mmです。10ならば1=1cm,1000ならば1=1mです。
 	 * 2.53以前のNyARToolkitと互換性を持たせるときは、{@link #SCALE_FACTOR_toCameraFrustumRH_NYAR2}を指定してください。
@@ -67,6 +69,7 @@ public class NyARGLUtil
 	 * @param i_far
 	 * 視錐体のfarPointを指定します。単位は、i_scaleに設定した値で決まります。
 	 * @param o_gl_projection
+	 * OpenGLスタイルのProjectionMatrixです。double[16]を指定します。
 	 */
 	public static void toCameraFrustumRH(NyARParam i_arparam,double i_scale,double i_near,double i_far,double[] o_gl_projection)
 	{
@@ -74,7 +77,7 @@ public class NyARGLUtil
 		return;
 	}
 	/**
-	 * ARToolKitスタイルのProjectionMatrixから、 CameraFrustamを計算します。
+	 * この関数は、ARToolKitスタイルのProjectionMatrixから、 CameraFrustamを計算します。
 	 * @param i_promat
 	 * @param i_size
 	 * スクリーンサイズを指定します。
@@ -95,13 +98,14 @@ public class NyARGLUtil
 		return;
 	}
 	/**
-	 * NyARTransMatResultをOpenGLの行列へ変換します。
+	 * この関数は、NyARTransMatResultをOpenGLのModelView行列へ変換します。
 	 * @param mat
 	 * 変換元の行列
 	 * @param i_scale
 	 * 座標系のスケール値を指定します。1=1mmです。10ならば1=1cm,1000ならば1=1mです。
 	 * 2.53以前のNyARToolkitと互換性を持たせるときは、{@link #SCALE_FACTOR_toCameraViewRH_NYAR2}を指定してください。
 	 * @param o_gl_result
+	 * OpenGLスタイルのProjectionMatrixです。double[16]を指定します。
 	 */
 	public static void toCameraViewRH(NyARDoubleMatrix44 mat,double i_scale, double[] o_gl_result)
 	{
-- 
2.11.0