Luxinia F3D Tool
================
by Christoph 'CrazyButcher' Kubisch

DESCRIPTION:
------------

Conversion to F3D model format
Or changing data in F3D
Optimization of triangle and vertex indices, NvTriStrip
Generation of tangents and mesh rebuilding, NvMeshMender

Never move the OPENGL32.DLL somewhere else, it is a special
software implementation of OpenGL (MESA-3D)

USEAGE:
-------

luxf3d.exe FILENAME OUTNAME TEXNAME OPTIONS...

Alternatively store the arguments in a plain ascii file called 
luxf3d_args.cfg
Lines starting with # will be ignored
Each line serves as argument and will be used after the 
arguments directly passed.

  FILENAME:
    modelfile.mm/f3d/md3/3ds/ms3d/bsp
  OUTNAME:
    If set this outputname will be used, no checking if directories exist
    If not set then output will be into /out/modelfile.f3d
  TEXNAME:
    for special conversion/generation of textures
    renders first mesh with the texture bound using the
    given render programs (totangentspace is default)
	Only .tga is supported. Alternatively you can pass a .txt
	file that is formated like:<meshname>,<texturename><newline>
	which will render every mesh.
  OPTIONS:
    -noma: animation wont be exported
    -nof3d: geometry wont be exported
    -nthframe<INT>: every nth animation frame will be exported
      (useful whenn too many keys exist) only used for .3ds
    -frametime<FLOAT>: for animation export this value is multiplied with
      frametimes as those are stored in milliseconds.(default 33.33 ms == 30 FPS)
      only used for .3ds
    -tangents: create tangents for the mesh
      optionally:
      -cbin<FLOAT>: binormal crease in cosine
      -ctan<FLOAT>: tangent crease in cosine
      -fixcyl: fix cylindrical mapping
    -render(<STRING program>|<STRING postfix>|<INT padding>|<INT backfacefirst>): 
      renders the model with the given texture (TGA) (texture list .txt) into a texture 
      of same size using the program.vp/.fp combo in the "renderprograms/" directory.
      Textures outname is TEXNAMEpostfix.tga
      Programs are rendered with CPU so there is no hardware dependency.
      currently we do some padding and also fill rest with 128,128,256,0
      backfacefirst should be 0 or 1 (default is 1)
    -optimize: optimize indices and vertices
      optionally:
      -cache16: optimized for vertexcache of size 16, default 24
      -strip: creates triangle strips, default off
      -nostitch: creates many strips instead of one big, default off
    -odir<STRING>: out directory for models (default is out/)
    -memsize<INT>: buffer memory size in MB (default is 32)
    -swizzle(<INT X>,<INT Y>,<INT Z>,<INT reversetris>,<INT flipnormals>,<float Wdir>):
       Sometimes the outcome of your model might not have the optimal axis orientations
       with swizzle you can change it (or rotate models in luxinia), however doing it
       here should be better.
       you can change orders of axis and invert them if needed.
       X,Y,Z can be -+ 1,2,3 (1 = X, 2 = Y ...)
       Wdir should be 1 or -1 (quaternion W) (default is 1), just in case rotations
         are wrong.
       reversetris and flipnormals can be 0 or 1 (default is 0) use them if you run into
         problems with the polygon winding or the normals
       order 3,1,2 is typical for Maya, XSI,... (Y-up systems) while 3dstudio like
          systems should require no swizzling at all
    for quake3 .bsp:
     -lmdir<STRING>: out directory for textures (default is out/)
     -lmscale<FLOAT>: .bsp contains lightmaps that can be brightened/darkened
     -lmoffset<FLOAT>: Output values will be 0-255
     -keepsky: sky surfaces will be exported
	

Examples:

for conversion, tangents and triangle strips
  luxf3d test.mm -tangents -cbin0.1 -ctan0.1 -optimize -strip

for simple conversion
  luxf3d model.md3

for creating tangents and converting localspace normalmap to tangentspace:
  luxf3d model.f3d mynormalmap.tga -render(totangentspace) -tangents

FILEFORMATS:
------------

  .f3d: full support
  .mm: full support
  .md3: simple meshes, tags become bones, frame 0 as reference
  .obj: simple meshes, material support
  .3ds: simple meshes, animation ,material & matrix support, frame 0 as reference for geometry
        animation commands: -nof3d, -nthframe,-frametime
  .bsp: simple meshes, lightmaps split to tgas, and saved in mesh texturestring. 
        Lightmaps can be color manipulated with -lmscale and -lmoffset.
  .ms3d: full support & animation. currently only single weight per vertex weight
  .b3d: full support, mesh & animation. No subanimations allowed. 
        Extra material info stored to .lua file. 
  .dae (collada 1.4),
  .fbx: meshes, skin (non-additive), animation. simple textures as material 
        (no perpolygon textures). 
        UV channels are looked for like this: diffuse,emissive,normal,specular
        so in case you want to make use of other uv channels, bind some texture
        to those slots and set the appropriate uv channel for it
        If your FBX exporter allows "Z up" option use it, else experiment with -swizzle
        command
        use -swizzle(3,1,2) when converting Maya,XSI... stuff, sometimes
        it is needed to add 3 more 1s ...1,1,1) 


CHANGELOG:
----------
2.2: exports F3D 260
2.1: improved .fbx and .dae via FBX SDK 2006.11 
     added -swizzle option
     always logs to luxf3d.log in the same directory as .exe
2.0: bugfix with ms3d texcoordflip, 
	 .b3d (Blitz3D) added
	 .fbx and .dae (collada 1.4 thru FBX) support added (basic stuff)
	 
1.9: bugfix with ms3d direct linked meshes, render order added
1.8: render function added (local normalmap to tangentspace)
     luxf3d_args.cfg added
1.7: 3ds animation support, milkshape 3d support & bugfixes with optional arguments
     removed dependency on dx9
     md3 bugfix
1.6: quake3 bsp conversion & bugfixes with optimize
     now compilable as LUA lib, directly pluggable in luxinia
1.5: bugfix
1.4: converts .3ds and .obj
1.3: outputs f3d v250
1.2: bugfixes with md3 textures

Third Party:
------------

for FBX/.DAE
http://www.autodesk.com
http://usa.autodesk.com/adsk/servlet/index?siteID=123112&id=6839916

for NvTriStrip and NvMeshMender
http://developer.nvidia.com
http://developer.nvidia.com/object/nvtristrip_library.html
http://developer.nvidia.com/object/NVMeshMender.html


lib3ds for 3DS loading
http://lib3ds.sourceforge.net


q3 .bsp, .obj basic, .b3d, .ms3d conversion
http://irrlicht.sourceforge.net


MESA-OpenGL:
http://www.mesa3d.org

LICENSE:
--------

NO WARRANTIES, USE AT YOUR OWN RISK

