LightWave Data Loader

NyaRuRu

First Version : October 11, 2003

0. Index

  1. Introduction
  2. Specifications
  3. Implementations
  4. Conclusion
  5. Bibliography

1. Introduction

LightWaveのデータファイルからの直接ロードをロードをサポートするライブラリとして，Object, Scene Library（資料[1]），Teddy 3D（資料[2]），Luna（資料[3]）などがあります．P/Invokeを用いれば，.NET Frameworkからこれらのライブラリを利用することも出来るでしょう．しかしStreamとの親和性やシリアライズサポート，セキュリティ保護の点で，新たにC#でネイティブ実装するに足るメリットがあると考えました．Surface，Texture，Clip周りのロードはフォーマットが複雑なため実装を後回しにし，まずはVer.0.1として最低限の情報のロードに対応したものをリリースします．

特徴は以下の通りです．

ロード段階で失われる情報としては以下のものがあります．

またサンプルとして，Xファイル形式にコンバートを行いStreamで返すライブラリを添付しました．アニメーション付き階層構造のデータを出力します．アニメーションデータは元データのキーフレームの時刻及びその中間点時刻の姿勢情報を出力しています．本来出力時に計算すべきデータで，出力に対応していないデータは以下の通りです．

2. Specifications

ここでは LightWave のアニメーションデータの構造の説明と，LightWave Animation Templates の定義を行います．

このような各階層の姿勢制御パラメータ全体に関わる情報を記述するのが，LWAnimation テンプレートです．以下にテキストタイプの X ファイル用のテンプレートヘッダを示します．

template LWAnimation {
 <897be58b-8f05-496f-8b17-b7f126b059b8>
 DWORD headController;
 DWORD pitchController;
 DWORD bankController;
 FLOATKEYS pivotRotation; 
 STRING targetObjectName;
 FLOAT lookAheadTime;
 [ LWAnimationChannel<d01c52a9-2084-457c-87e3-b45fb521981d>, Frame<3D82AB46-62DA-11CF-AB39-0020AF71E433> ]
}
LWLoader

LWLoaderネームスペースには．

LWLoader.ObjectFile

LWLoader.ObjectFileネームスペースには．

LWLoader.SceneFile

LWLoader.SceneFileネームスペースには．

Type Parameter Name Control
 KeyFrame   Target  PathAlignment  IK 
Pivot Translate X
Y
Z
Scale X ○
Y ○
Z ○
Rotate Head ○ ○ ○ ○
Pitch ○ ○ ○ ○
Bank ○ ○
Pivot Rotate Head
Pitch
Bank
Translate X ○
Y ○
Z ○

注）上から順にローカル座標に作用する

表1 LightWave の姿勢表現

pivotRotation

pivotRotation には Pivot Rotate をクオータニオンで表現したものを格納します．ただし慣例に従って，以下のようにパラメータの順序と符号を変えて記述することとします．

D3DXQUATERNION q;

// q に対応する X ファイルでの FLOATKEYS 表現は以下のようになる
"4;q.w,-q.x,-q.y,-q.z;"
lookAheadTime

LightWave Scene での LookAheadFrames に対応する値を秒単位に変換して格納します．回転コントローラが PathAlign のときに使用します．

以上が LWAnimation の持つパラメータの全てです．Pivot Translate に対応するパラメータを持たないのは，D3DX が姿勢情報を SRT(Scale×Rotate×Transtale) の形で扱うため，それと適合しないからです．Pivot Translate が存在する場合はダミーフレームを新たに作成し，FrameTransformMatrix に繰り込んでしまうことで解決してください．

また，LWAnimation は子要素を持つことが出来ます．子要素として持つことが出来るのは，Frame テンプレート，LWAnimationChannel テンプレートです．Frame テンプレートまたは Frame テンプレートへの参照を 1 つだけ持たせることで，この LWAnimation の作用するフレームを決めることとします．また，LWAnimationChannel は KeyFrame タイプの姿勢パラメータを記述します．以下に LWAnimationChannel のテンプレートヘッダを示します．LWAnimationChannel テンプレートの各パラメータは，資料[2]の『エンベロープ』の項に詳しいです．

template LWAnimationChannel {
 <d01c52a9-2084-457c-87e3-b45fb521981d>
 DWORD channelNumber;
 DWORD preBehavior;
 DWORD postBehavior;
 DWORD nKeys;
 array LWAnimationChannelKey keys[nKeys];
}
channelNumber

LightWave Scene ファイルでの Channel nindex と対応しています．

  1. 0 - Translate X
  2. 1 - Translate Y
  3. 2 - Translate Z
  4. 3 - Head
  5. 4 - Pitch
  6. 5 - Bank
  7. 6 - Scale X
  8. 7 - Scale Y
  9. 8 - Scale Z
preBehavior, postBehavior

LightWave Scene ファイルでの Behaviors pre post と対応しています．

  1. 0 - Reset
  2. 1 - Constant
  3. 2 - Repeat
  4. 3 - Oscillate
  5. 4 - Offset
  6. 5 - Linear
nKeys

LightWave Scene での nkeys と対応しています．keys パラメータの配列の要素数を表します．

keys

LightWave Scene での Key value time spantype p1 p2 p3 p4 p5 p6 に対応しています．要素数が nKeys の配列構造になっています．

最後に LWAnimationChannelKey テンプレートヘッダを示します．

template LWAnimationChannelKey {
 <942ae4f8-5e7a-4813-a19f-278c3c921463>
 FLOAT value;
 FLOAT time;
 DWORD shapeType;
 FLOATKEYS pamams;
}
value

LightWave Scene ファイルでの Key value に対応しています．

time

LightWave Scene ファイルでの Key time に対応しています．

shapeType

LightWave Scene での Key shapeType に対応しています．

  1. 0 - TCB
  2. 1 - Hermite
  3. 2 - Bezier
  4. 3 - Line
  5. 4 - Offset
  6. 5 - Linear
pamams

LightWave Scene での Key p1 p2 p3 p4 p5 p6 に対応しています．

float p1, p2, p3, p4, p5, p6

// 対応する X ファイルでの FLOATKEYS 表現は以下のようになる
"6; p1, p2, p3, p4, p5, p6;"

LWAnimation，LWAnimationChannel，LWAnimationChannelKey テンプレートはそれぞれ，Animation，AnimationKey，TimedFloatKeys に対応しています．
そして，AnimationSet に対応する LWAnimationSet をトップレベルに記述し，各 LWAnimation はその子要素となるようにします．最後に LWAnimation のテンプレートヘッダを示します．

template LWAnimationSet {
 <1fc4c2bf-4e12-4b71-8741-7d6fbbd6c6cc>
 [ LWAnimation<897be58b-8f05-496f-8b17-b7f126b059b8> ]
}

3. Implementations

LightWave Scene Exporter .NET

LightWave Animation Templates に対応した Scene ファイルエクスポータを実際に作成しました．Scene ファイルを指定し，参照する Object データを含んだ X ファイルを出力します．ボーンウェイトの出力にも対応しています．実行には .NET Framework 1.1，DirectX 9.0b，Managed DirectX (Assembly Version 1.0.1901.0) が必要です．

LoadLWAnimationSet

C++ 用のユーティリティー関数です．ID3DXLoadUserData::LoadTopLevelDataから呼び出されることを想定しています．引数に LWAnimationSet テンプレートを指す IDirectXFileData を渡すと，この LWAnimationSet を解釈する専用のインターポレータを ID3DXAnimationSet インターフェイスの形で返します． 得られた AnimationSet をD3DXLoadMeshHierarchyFromX が返す ID3DXAnimationController にセットするには，例えば以下のような方法があります．

// D3DXLoadMeshHierarchyFromX が返したもの
LPD3DXANIMATIONCONTROLLER controller;

// LoadLWAnimationSet が返したもの
LPD3DXANIMATIONSET        lwAnimation;

// 元々あったアニメーションの解除
LPD3DXANIMATIONSET        originalAnimation;
controller->GetAnimationSet( 0, &originalAnimation );
controller->UnregisterAnimationSet( originalAnimation );
originalAnimation->Release();
originalAnimation = NULL;

controller->RegisterAnimationSet( lwAnimation );
controller->SetTrackAnimationSet( 0, lwAnimation );
lwAnimation->Release();
lwAnimation = NULL;

ただしこの ID3DXAnimationSet にはいくつか制限があります．

  1. マルチスレッドには対応していません．
  2. 回転コントローラの Target，IK には対応していません．
  3. ID3DXAnimationSet::GetCallback は実装されていません．
  4. ID3DXAnimationSet::GetPeriod は常に 0.0 を返します．ループは LightWave 側で設定してください．

4. Conclusion

LightWave のアニメーションデータを直接 X ファイルに出力することにより，デザイン時のアニメーションをそのままゲームで利用することが可能になりました．この方法は，従来の X ファイルで用いられていたキーフレーム方式に比べ，データ量，データ自由度の点で優れています．また C++ で利用する場合は，専用の ID3DXAnimationSet を用いれば，既存コードに対するごくわずかな修正で LightWave Animation Templates によるオリジナルのアニメーションを利用することが可能となりました．

5. Bibliography

参考資料

  1. ウマイハナシ ―Xファイルにユーザーデータな話―[highway.ne.jp]
    →X ファイルにカスタムテンプレートを追加するハナシです．
  2. LWS version 3ファイルフォーマット[dstorm.co.jp]
    →DSTORM社による日本語訳です．
  3. LWO version 2ファイルフォーマット[dstorm.co.jp]
    →DSTORM社による日本語訳です．
  4. Adding Frames and Animations[microsoft.com]
    → X ファイルに通常のアニメーションを手で追加する方法についてです．

Copyright © 2003 NyaRuRu