src/main/java/jp/sfjp/mikutoga/vmd/parser/VmdCameraHandler.java

   1 /*
   2  * VMD camerawork handler
   3  *
   4  * License : The MIT License
   5  * Copyright(c) 2011 MikuToga Partners
   6  */
   7
   8 package jp.sfjp.mikutoga.vmd.parser;
   9
  10 import jp.sfjp.mikutoga.bin.parser.LoopHandler;
  11 import jp.sfjp.mikutoga.bin.parser.MmdFormatException;
  12 import jp.sfjp.mikutoga.bin.parser.ParseStage;
  13
  14 /**
  15  * VMDモーションファイルのカメラワーク情報の通知用ハンドラ。
  16  *
  17  * <p>フレーム番号は相対的なものとなる。
  18  * カメラ・照明・シャドウのうち
  19  * 一番若いモーションのフレーム番号が0となる模様。
  20  *
  21  * <p>ターゲット位置、カメラ回転量とも、座標基準はワールド座標。
  22  *
  23  * <p>カメラターゲットの座標は左手系で表される。
  24  *
  25  * <p>ターゲットに対するカメラ位置は極座標で表される。
  26  *
  27  * <p>補間情報は直前カメラ情報との差分に関するもの。
  28  */
  29 public interface VmdCameraHandler extends LoopHandler {
  30
  31     /** カメラデータ抽出ループ識別子。 */
  32     public static final ParseStage CAMERA_LIST = new ParseStage();
  33
  34
  35     /**
  36      * カメラモーションのキーフレーム番号に関する情報を通知する。
  37      *
  38      * <p>{@link #CAMERA_LIST}ループの構成要素。
  39      *
  40      * @param keyFrameNo キーフレーム番号
  41      * @throws MmdFormatException
  42      *     不正フォーマットによるパース処理の中断をパーサに指示
  43      */
  44     public abstract void vmdCameraMotion(int keyFrameNo)
  45             throws MmdFormatException;
  46
  47     /**
  48      * ターゲットとカメラ間の距離情報を通知する。
  49      *
  50      * <p>球座標(極座標)の動径に相当する。
  51      * 通常はターゲットより手前に位置するカメラまでの距離が負の値で渡される。
  52      *
  53      * <p>カメラ位置がターゲットを突き抜けた場合は正の値もとりうる。
  54      * ※MMDのUIと符号が逆なので注意。
  55      *
  56      * <p>{@link #CAMERA_LIST}ループの構成要素。
  57      *
  58      * @param range 距離
  59      * @throws MmdFormatException 不正フォーマットによる
  60      *     パース処理の中断をパーサに指示
  61      */
  62     public abstract void vmdCameraRange(float range)
  63             throws MmdFormatException;
  64
  65     /**
  66      * カメラのターゲット位置情報を通知する。
  67      *
  68      * <p>{@link #CAMERA_LIST}ループの構成要素。
  69      *
  70      * @param xPos ターゲットのX座標
  71      * @param yPos ターゲットのY座標
  72      * @param zPos ターゲットのZ座標
  73      * @throws MmdFormatException 不正フォーマットによる
  74      *     パース処理の中断をパーサに指示
  75      */
  76     public abstract void vmdCameraPosition(float xPos, float yPos, float zPos)
  77             throws MmdFormatException;
  78
  79     /**
  80      * カメラの回転および回転量情報を通知する。
  81      *
  82      * <p>極座標(球座標)が用いられる。
  83      *
  84      * <p>180度を超える値も回転量として意味を持つ。
  85      *
  86      * <p>{@link #CAMERA_LIST}ループの構成要素。
  87      *
  88      * @param latitude ターゲットから見たカメラの仰俯角(≒緯度)。
  89      *     単位はラジアン。
  90      *
  91      *     <p>Y軸回転量が0の時のZ正軸がY正軸へ倒れる方向が正回転。
  92      *     (MMDのUIとは符号が逆になるので注意)</p>
  93      *
  94      *     <p>仰俯角が0の場合、
  95      *     カメラはターゲットに対しXZ平面(水平)と平行な箇所に位置する。</p>
  96      *
  97      * @param longitude Y軸周りの回転量(≒経度)。単位はラジアン。
  98      *
  99      *     <p>X正軸がZ正軸へ倒れる方向が正回転。(ボーン回転と逆)</p>
 100      *
 101      *     <p>仰俯角およびY軸回転量が0の場合、
 102      *     カメラレンズはZ軸-∞方向からZ軸+∞方向を向く。</p>
 103      *
 104      * @param roll レンズをターゲットを向けたカメラのロール回転量。
 105      *
 106      *     <p>仰俯角とY軸回転量が0の時に
 107      *     Y正軸がX正軸に倒れる方向が正回転。</p>
 108      *
 109      *     <p>仰俯角およびロール回転量が0の場合、
 110      *     カメラ上部はY軸+∞の方を向く。</p>
 111      *
 112      * @throws MmdFormatException 不正フォーマットによる
 113      *     パース処理の中断をパーサに指示
 114      */
 115     public abstract void vmdCameraRotation(
 116             float latitude, float longitude, float roll)
 117             throws MmdFormatException;
 118
 119     /**
 120      * カメラを通じたスクリーン座標への投影に関する情報を通知する。
 121      *
 122      * <p>{@link #CAMERA_LIST}ループの構成要素。
 123      *
 124      * @param angle 縦画角。単位は度数法。MMDのUIでは1から125が指定可能。
 125      * @param hasPerspective パースペクティブスイッチがONならtrue。
 126      *     スイッチがOFFの場合、画角は無視され遠近感処理が行われなくなる。
 127      *     (平行投影?)
 128      * @throws MmdFormatException 不正フォーマットによる
 129      *     パース処理の中断をパーサに指示
 130      */
 131     public abstract void vmdCameraProjection(
 132             int angle, boolean hasPerspective)
 133             throws MmdFormatException;
 134
 135     /**
 136      * カメラターゲットX軸移動補間情報の通知を受け取る。
 137      * 三次ベジェ曲線のP1,P2点に関する情報を受け取る。
 138      *
 139      * <p>{@link #CAMERA_LIST}ループの構成要素。
 140      *
 141      * @param p1x P1点のX座標
 142      * @param p1y P1点のY座標
 143      * @param p2x P2点のX座標
 144      * @param p2y P2点のY座標
 145      * @throws MmdFormatException 不正フォーマットによる
 146      *     パース処理の中断をパーサに指示
 147      */
 148     public abstract void vmdCameraIntpltXpos(
 149             byte p1x, byte p1y, byte p2x, byte p2y)
 150             throws MmdFormatException;
 151
 152     /**
 153      * カメラターゲットY軸移動補間情報の通知を受け取る。
 154      * 三次ベジェ曲線のP1,P2点に関する情報を受け取る。
 155      *
 156      * <p>{@link #CAMERA_LIST}ループの構成要素。
 157      *
 158      * @param p1x P1点のX座標
 159      * @param p1y P1点のY座標
 160      * @param p2x P2点のX座標
 161      * @param p2y P2点のY座標
 162      * @throws MmdFormatException 不正フォーマットによる
 163      *     パース処理の中断をパーサに指示
 164      */
 165     public abstract void vmdCameraIntpltYpos(
 166             byte p1x, byte p1y, byte p2x, byte p2y)
 167             throws MmdFormatException;
 168
 169     /**
 170      * カメラターゲットZ軸移動補間情報の通知を受け取る。
 171      * 三次ベジェ曲線のP1,P2点に関する情報を受け取る。
 172      *
 173      * <p>{@link #CAMERA_LIST}ループの構成要素。
 174      *
 175      * @param p1x P1点のX座標
 176      * @param p1y P1点のY座標
 177      * @param p2x P2点のX座標
 178      * @param p2y P2点のY座標
 179      * @throws MmdFormatException 不正フォーマットによる
 180      *     パース処理の中断をパーサに指示
 181      */
 182     public abstract void vmdCameraIntpltZpos(
 183             byte p1x, byte p1y, byte p2x, byte p2y)
 184             throws MmdFormatException;
 185
 186     /**
 187      * カメラ回転量補間情報の通知を受け取る。
 188      * 三次ベジェ曲線のP1,P2点に関する情報を受け取る。
 189      *
 190      * <p>{@link #CAMERA_LIST}ループの構成要素。
 191      *
 192      * <p>カメラ回転でクォータニオン補間は使われない。
 193      *
 194      * @param p1x P1点のX座標
 195      * @param p1y P1点のY座標
 196      * @param p2x P2点のX座標
 197      * @param p2y P2点のY座標
 198      * @throws MmdFormatException 不正フォーマットによる
 199      *     パース処理の中断をパーサに指示
 200      */
 201     public abstract void vmdCameraIntpltRotation(
 202             byte p1x, byte p1y, byte p2x, byte p2y)
 203             throws MmdFormatException;
 204
 205     /**
 206      * カメラ-ターゲット間距離補間情報の通知を受け取る。
 207      * 三次ベジェ曲線のP1,P2点に関する情報を受け取る。
 208      *
 209      * <p>{@link #CAMERA_LIST}ループの構成要素。
 210      *
 211      * @param p1x P1点のX座標
 212      * @param p1y P1点のY座標
 213      * @param p2x P2点のX座標
 214      * @param p2y P2点のY座標
 215      * @throws MmdFormatException 不正フォーマットによる
 216      *     パース処理の中断をパーサに指示
 217      */
 218     public abstract void vmdCameraIntpltRange(
 219             byte p1x, byte p1y, byte p2x, byte p2y)
 220             throws MmdFormatException;
 221
 222     /**
 223      * スクリーン投影補間情報の通知を受け取る。
 224      * 三次ベジェ曲線のP1,P2点に関する情報を受け取る。
 225      *
 226      * <p>{@link #CAMERA_LIST}ループの構成要素。
 227      *
 228      * @param p1x P1点のX座標
 229      * @param p1y P1点のY座標
 230      * @param p2x P2点のX座標
 231      * @param p2y P2点のY座標
 232      * @throws MmdFormatException 不正フォーマットによる
 233      *     パース処理の中断をパーサに指示
 234      */
 235     public abstract void vmdCameraIntpltProjection(
 236             byte p1x, byte p1y, byte p2x, byte p2y)
 237             throws MmdFormatException;
 238
 239 }