Initial commit

Torque/SDK/tools/ms2dtsExporter/readme.txt

@@ -0,0 +1,166 @@
+==============================================================================
+
+This is the exporter DLL for the MilkShape 3D modeler available
+from chUmbaLum sOft : //www.swissquake.ch/chumbalum-soft/
+
+The original version of this code was written be Jos<6F> Luis Cebri<72>n who
+has graciously allowed us to integrate his code into the Torque SDK.
+Jos<EFBFBD> did an awesome job of putting this tool together and the GG staff
+is very gratefull for the work he's put in to it.
+
+If you look through the code, you'll notice a little complexity in the
+DTS file format. A little background is in order... the dts format was
+originally designed to reduce load time processing. This means that the
+DTS format is almost a direct representation of how the TS engine stores
+data in memory.   This does reduce load times, but also ties the file
+format to the run-time implementation, which is not really a good idea.
+Changes in run-time implementation, and the pre-processing needed for
+the run-time data, resulted in un-planned changes and re-structuring of
+the DTS file format. These changes leave us with a file format which
+leaves much to be desired.
+
+To help reduce the complications involved in writing new exporters,
+the MilkShape exporter is divided into a base DTS "SDK", which provides
+the core support needed to deal with DTS files, and a small set of
+MilkShape specific files which do the actual conversion.  The long term
+goal is split this DTS SDK into a seperate library to be shared between
+exporter projects.
+
+
+Current Functionality
+---------------------
+
+The exporter is currently in it's 1.0 "beta" phase. Which means it's
+usable. Though there is much functinality to add, and several outstanding
+issues.  Maybe "alpha" might be more appropriate :)
+
+- The exporter only exports diffuse texture materials.
+- Multi-sequence animations
+- Animation only supports bone animation (no texture, texture coor,
+  vertex morphing or mesh visibility)
+- Support for single collision mesh
+- Named nodes.
+
+
+Exporter Flags & Animation Sequences
+------------------------------------
+
+Since MilkShape does not directly support a number of Torque engine features
+so the tool has been extended through the use of "hacks".  These are described
+more fully below but essentially fall into two categories: mesh flags embeded
+in the mesh's name, and specially named materials which are used to declare
+animation sequences and exporter options.
+
+
+Multi-Sequence Animations
+-------------------------
+
+Material with special names can be used to declare sequence information.
+These materials are ignored during export and are solely used to declare
+animation sequences.  Sequence materials are named as follows:
+
+	seq: option, option, ...
+
+All other properties of the material are ignored.  The following options are recognized:
+
+        name=start-end This declares the name of the sequence followed by
+                       the starting and ending key frames.  This option must
+                       exist for the sequence declaration to be valid. 
+        fps=n          The number of frames/second. This value affects the
+                       duration and playback speed of the sequence.
+        cyclic         Sequences are non-cyclic by default. Cyclic animations
+                       automatically loop back to the start and never end.
+
+Examples of valid sequence declarations:
+ 
+        "seq: fire=1-4"
+        "seq: rotate=5-8, cyclic, fps=2"
+	"seq: reload=9-12, fps=5"
+
+
+Setting Export Options
+----------------------
+
+Materials with special names can be used to set several export options.
+These materials are ignored during export and are solely used to set otoins.  Option materials are named as follows:
+
+	opt: option, option, ...
+
+All other properties of the material are ignored.  The following options are recognized:
+
+	scale=n         Shape scale factor, where n is a floating point value.
+                        The default scale value is 0.1
+        size=n          The minimum visible pixel size, default is 0
+        fps=n           The default frames/second value for animations. Each
+                        animation sequence may set this value, but if it's
+                        not defined by the sequence, this default value is used.
+        cyclic          The default animation looping flag.  Each animation
+                        sequence may set this value, but if it's not defined
+                        by the sequence, this default value is used.
+
+There may be more than one option material.  If the same options are set on mulitple materials, then the last one in the material list is the value used.
+Examples of valid material names:
+
+        "opt: fps=10, cyclic"
+        "opt: scale=1"
+
+
+Mesh Option Flags
+-----------------
+
+Mesh may have additional flags embedded in the mesh (or group) name. The mesh name follows the following format:
+
+        name: flag, flag, ...
+
+where the : and flags are optional.  The following flags are recognized:
+
+        Billboard       The mesh always faces the viewer
+        BillboardZ      The mesh faces the viewer but is only rotated around
+                        the mesh's Z axis.
+        ENormals        Encodes vertex normals. This flag is deprecated and
+                        should not be used, unless you know what your doing.
+
+Examples of legal mesh/group names:
+        "box"                   Just called box
+        "leaf: Billboard"       Leaf that always faces the viewer
+        "leaf: BillboardZ"	Z axis rotated facing leaf
+
+Meshes by defualt do not have any of these flags set.
+
+
+Issues & Future Developement
+----------------------------
+
+- Split off the DTS SDK into it's own library and continue to refine
+  it's functionality and API.
+
+- Triangle strips. This is probably the biggest outstanding issue.
+  Every mesh triangle is emitted as it's own triangle strip. This is
+  very bad :( Triangles need to be stripped by material.  Support
+  should be added to the DTSMesh class. 
+
+- Detail support.  Need to add support for progressive meshes. The
+  DTSMesh class should automatically produce decimated sub-details
+  based off the original art.
+
+- DSQ exporting.  DSQ files are essentially animation sequence files.
+  They only contain animation sequence information and can be loaded into
+  a shape at run-time.  The same DSQ can be loaded into multiple shapes
+  allowing animations to be shared.
+
+- Multiple collision meshes.  The exporter currently selects the first
+  mesh named "collision" as a collision mesh.  The torque engine actually
+  allows multiple collision meshes per shape and the exporter should
+  export all meshes named "collision" as collision meshes.
+
+- Billboard meshes are mesh which the Torque engine automatically
+  rotates at run time to face the camera.  There needs to be some way
+  of marking meshes.  This could be as simple as naming them "billboard".
+
+- Alpha BSP (or ordered) meshes.  Alpha textured triangles need to be
+  rendered in back to front order at run-time for them to render correctly.
+  The dts file can contain BSP tree meshes used for this purpose.
+
+- Better material support. There are number of material features (besides
+  animation) which MS doesn't support, these include multiple UV mapping
+  options, environment mapping flags, addative vs. blended alpha, etc.