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     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     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     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     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     void vmdCameraRotation(float latitude, float longitude, float roll)
 116             throws MmdFormatException;
 117
 118     /**
 119      * カメラを通じたスクリーン座標への投影に関する情報を通知する。
 120      *
 121      * <p>{@link #CAMERA_LIST}ループの構成要素。
 122      *
 123      * @param angle 縦画角。単位は度数法。MMDのUIでは1から125が指定可能。
 124      * @param hasPerspective パースペクティブスイッチがONならtrue。
 125      *     スイッチがOFFの場合、画角は無視され遠近感処理が行われなくなる。
 126      *     (平行投影?)
 127      * @throws MmdFormatException 不正フォーマットによる
 128      *     パース処理の中断をパーサに指示
 129      */
 130     void vmdCameraProjection(int angle, boolean hasPerspective)
 131             throws MmdFormatException;
 132
 133     /**
 134      * カメラターゲットX軸移動補間情報の通知を受け取る。
 135      * 三次ベジェ曲線のP1,P2点に関する情報を受け取る。
 136      *
 137      * <p>{@link #CAMERA_LIST}ループの構成要素。
 138      *
 139      * @param p1x P1点のX座標
 140      * @param p1y P1点のY座標
 141      * @param p2x P2点のX座標
 142      * @param p2y P2点のY座標
 143      * @throws MmdFormatException 不正フォーマットによる
 144      *     パース処理の中断をパーサに指示
 145      */
 146     void vmdCameraIntpltXpos(byte p1x, byte p1y, byte p2x, byte p2y)
 147             throws MmdFormatException;
 148
 149     /**
 150      * カメラターゲットY軸移動補間情報の通知を受け取る。
 151      * 三次ベジェ曲線のP1,P2点に関する情報を受け取る。
 152      *
 153      * <p>{@link #CAMERA_LIST}ループの構成要素。
 154      *
 155      * @param p1x P1点のX座標
 156      * @param p1y P1点のY座標
 157      * @param p2x P2点のX座標
 158      * @param p2y P2点のY座標
 159      * @throws MmdFormatException 不正フォーマットによる
 160      *     パース処理の中断をパーサに指示
 161      */
 162     void vmdCameraIntpltYpos(byte p1x, byte p1y, byte p2x, byte p2y)
 163             throws MmdFormatException;
 164
 165     /**
 166      * カメラターゲットZ軸移動補間情報の通知を受け取る。
 167      * 三次ベジェ曲線のP1,P2点に関する情報を受け取る。
 168      *
 169      * <p>{@link #CAMERA_LIST}ループの構成要素。
 170      *
 171      * @param p1x P1点のX座標
 172      * @param p1y P1点のY座標
 173      * @param p2x P2点のX座標
 174      * @param p2y P2点のY座標
 175      * @throws MmdFormatException 不正フォーマットによる
 176      *     パース処理の中断をパーサに指示
 177      */
 178     void vmdCameraIntpltZpos(byte p1x, byte p1y, byte p2x, byte p2y)
 179             throws MmdFormatException;
 180
 181     /**
 182      * カメラ回転量補間情報の通知を受け取る。
 183      * 三次ベジェ曲線のP1,P2点に関する情報を受け取る。
 184      *
 185      * <p>{@link #CAMERA_LIST}ループの構成要素。
 186      *
 187      * <p>カメラ回転でクォータニオン補間は使われない。
 188      *
 189      * @param p1x P1点のX座標
 190      * @param p1y P1点のY座標
 191      * @param p2x P2点のX座標
 192      * @param p2y P2点のY座標
 193      * @throws MmdFormatException 不正フォーマットによる
 194      *     パース処理の中断をパーサに指示
 195      */
 196     void vmdCameraIntpltRotation(byte p1x, byte p1y, byte p2x, byte p2y)
 197             throws MmdFormatException;
 198
 199     /**
 200      * カメラ-ターゲット間距離補間情報の通知を受け取る。
 201      * 三次ベジェ曲線のP1,P2点に関する情報を受け取る。
 202      *
 203      * <p>{@link #CAMERA_LIST}ループの構成要素。
 204      *
 205      * @param p1x P1点のX座標
 206      * @param p1y P1点のY座標
 207      * @param p2x P2点のX座標
 208      * @param p2y P2点のY座標
 209      * @throws MmdFormatException 不正フォーマットによる
 210      *     パース処理の中断をパーサに指示
 211      */
 212     void vmdCameraIntpltRange(byte p1x, byte p1y, byte p2x, byte p2y)
 213             throws MmdFormatException;
 214
 215     /**
 216      * スクリーン投影補間情報の通知を受け取る。
 217      * 三次ベジェ曲線のP1,P2点に関する情報を受け取る。
 218      *
 219      * <p>{@link #CAMERA_LIST}ループの構成要素。
 220      *
 221      * @param p1x P1点のX座標
 222      * @param p1y P1点のY座標
 223      * @param p2x P2点のX座標
 224      * @param p2y P2点のY座標
 225      * @throws MmdFormatException 不正フォーマットによる
 226      *     パース処理の中断をパーサに指示
 227      */
 228     void vmdCameraIntpltProjection(byte p1x, byte p1y, byte p2x, byte p2y)
 229             throws MmdFormatException;
 230
 231 }