root/trunk/README.txt

maya2q3 GPL source release
==================================

HermitWorks Entertainment Corporation
Email: phill@hermitworksentertainment.com


This file contains the following sections:

LICENSE
GENERAL NOTES
COMPILING ON WIN32
COMPILING ON GNU/LINUX
USAGE

LICENSE
=======

See COPYING.txt for the GNU GENERAL PUBLIC LICENSE
-----------------------------------------------------------------------------

Some source code in this release is not covered by the GPL:

NVMeshMender.cpp
NVMeshMender.h
NvTriStrip.cpp
NvTriStrip.h
NvTriStripObjects.cpp
NvTriStripObjects.h
VertexCache.h

Copyright NVIDIA Corporation 2003
TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, THIS SOFTWARE IS PROVIDED
*AS IS* AND NVIDIA AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES, EITHER EXPRESS
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS FOR A PARTICULAR PURPOSE.  IN NO EVENT SHALL NVIDIA OR ITS SUPPLIERS
BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT, OR CONSEQUENTIAL DAMAGES
WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS,
BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR ANY OTHER PECUNIARY LOSS)
ARISING OUT OF THE USE OF OR INABILITY TO USE THIS SOFTWARE, EVEN IF NVIDIA HAS
BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

DXVec.h is also not covered under the GPL as it is copied from the DirectX SDK.
-----------------------------------------------------------------------------

GENERAL NOTES
=============

A short summary of the file layout:

maya2q3                         maya2q3 source code
glew                            GL Extension Wrangler library http://glew.sourceforge.net
physfs-1.1.0            PhysicsFS file system library http://icculus.org/physfs/

These folders will be created by the Win32 build process:

maya2q3/win32/bin/CONFIG        exporter executable binary (and debug symbols)
maya2q3/win32/obj/CONFIG        intermediate files (.obj, etc)

Release builds also generate .pdb debugging databases, however due to compiler
optimizations these are not sufficient for debugging - they will not allow you
to properly step through the code. If you're trying to debug, use a debug build.

COMPILING ON WIN32
==================

  DEPENDENCIES:

The plugin depends on the GLEW library for access to OpenGL and OpenGL extensions,
and on the PhysicsFS library for access to assets in a Quake 3 style game directory.
The source for both libraries is included in the repository to make building the
plugin easier.

You will need to build these libraries before you can build the plugin. To do this
open and build libs.sln. The project files it references have already been set up
with the correct compiler and linker settings, and will put the .lib files where
the maya2q3 project expects to find them.

You only have to do this once.

Note that neither I nor anyone else at Hermitworks Entertainment are responsible for
the development or maintenance of either project. You can find the people that *are*
responsible for them here:

    GLEW: http://glew.sourceforge.net/
    PhysicsFS: http://icculus.org/physfs/

  THE PLUGIN:

Note: You MUST have Maya (or at least the SDK components) installed on your system.

Open maya2q3.sln.

There are 4 configurations in the solution: debug for Maya 6.0, debug for
Maya 7.0, release for Maya 6.0, and release for Maya 7.0 (note that only the
Maya 7.0 configurations are being actively developed or supported). You must
match the configuration to the version of Maya you are building against.

The solution is already configured to build the exporter and copy it to the
appropriate directory, along with its supporting script(s). Note that building
a debug will overwrite an existing release build. Modify the Custom Build Step
project property's command line of you want to change this but we find it makes
it easier to debug the plugin if only one copy ever exists: going back to a
release plugin is as easy as rebuilding.

  IF MAYA IS INSTALLED TO A NON-DEFAULT DIRECTORY:

If Maya is not installed in the default folder $(Program Files)\Alias\Maya\VERSION
then you will have to edit the project's properties to get it to reference the
correct header and library files. Open up the project properties and change

C/C++ -> General -> Additional Include Directories
Linker ->General -> Additional Library Directories
Build Events -> Post-Build Event -> Command Line

  SUPPORTING OTHER MAYA VERSIONS:

If you're adding code to support another version of Maya, create new solution
configurations and update the above properties. The code automatically retargets
itself to the current Maya version based on the value of the MAYA_API_VERSION 
macro, so it is imperative that the compiler is directed to the correct version
of the headers.

COMPILING ON GNU/LINUX
==================

Download the tar.gz, and extract with tar -zxf maya2q3-VERSION.tar.gz

then run make from inside of the mata2q3-1.0/maya2q3 folder.  Once it is
done there should be a maya2q3.so in the linux/bin directory.  Copy that to
your maya plug-ins folder.  On my system it's in /usr/aw/maya7.0/bin/plug-ins/

You can also use maya to browse for the plugin if you do not have rights to
copy it into the plug-ins folder.

$ tar -zxf maya2q3-VERSION.tar.gz
$ cd maya2q3-VERSION/maya2q3
$ make
$ sudo cp linux/bin/maya2q3.so /usr/aw/maya7.0/bin/plug-ins/

The Makefile assumes that the environment variable MAYA_LOCATION is properly
defined in your environment, on my system is is set to /usr/aw/maya7.0/

If you have any problems with the linux build, contact 
scott@hermitworksentertainment.com

USAGE
=====
  MODELLING GUIDE:
  
The exporter only outputs geometry from meshes. That said, it can handle ANY mesh
geometry. It supports parenting, instancing, N-sided polygons, and isn't even
picky about non-manifold geometry. If you create more than one UV mapping for an
object, the exporter will use the first one Maya gives it, whichever that may be.

The MD3 format includes a surface name and a default shader name. These are
derived from Maya as follows:

  A surface is basically a set of polygons that share the same material. It is
  named after the shading group that it belongs to. To access this, select the
  material and press Go to Output Connection in the attribute editor (this will
  take you to the shading group).
  
  NEW (version 2) WAY:
  Each surface is connected to a default Q3 shader. The shader is specified by
  applying a Q3Shader material to the object and setting the shaderName attribute.
  If a non-Q3Shader material is assigned to an object, it will export using the
  old rules (below).
  
  NOTE: the Q3Shader material understands Quake 3 shader rules and can accept the
    name of a shader or the path of a texture, in game notation. In order for it
    to be able to load the shader, you must configure your Maya project to include
    your game data search paths. To create the appropriate entry execute this MEL
    script at the command line (after that the entry will appear in the project
    settings GUI and you can modify it from there).
    
    workspace -rt "Q3GameData" "GAME_DATA_PATHS" ;
    
    The GAME_DATA_PATHS may be absolute or relative to the project folder. To
    maintain a cross-platform project, use forward slashes (/) and let the plugin
    convert them. Multiple paths must be seperated by semicolons. PK3 files in
    these folders are automatically added to the search as well, in Q3 order.
    
    If you are using Maya 6.x you must do this before creating the first Q3Shader
    node in your scene, and you must restart Maya if you change this variable.
    The Maya 7.0 build automatically refreshes the nodes when the path changes.
    This is due to a limitation in the Maya 6.x API.
    
    When editing a Q3Shader-bound object's UVs in the UV Texture Editor, use the
    Image -> Selected Images -> SHADER_IMAGE_NAME to display any texture referenced
    by the shader in the UV Texture Editor window.
    
    Bear in mind that as this is an early release, the plugin only supports DDS and
    TGA images. BMP and PCX support may be added later. There are no plans to add JPG.
    
    For more info on MEL or Maya's project system, check your Maya documentation.
  
  OLD WAY:
  Each surface is connected to a default Q3 shader. The shader is named after
  the material assigned to the object. In order to maintain compatibility with
  Q3, this name is mangled (a little bit). The default shader is the material
  name, with all underscores converted to forward slashes, except if a pair of 
  underscores is found near the end of a name it will be converted to a period.
  
  So:
  
  sample_shader_name            becomes         sample/shader/name
  sample_shader_name__tga       becomes         sample/shader/name.tga
  
  BOTH CASES:
  NOTE: polygons assigned to the default shader "lambert1" will never be exported.
    You can use this to your advantage: if you need reference geometry that you
    don't want to export, simply stick lambert1 on it and leave it in your scene.
    This is handled on a per-face basis, so you can also use it to create holes
    in the exported object, while keeping the geometry solid in Maya (which helps
    with certain tools).
    
Any shape who's name starts with "tag_" (case insensitive) will have its world
transform exported as a tag of the same name. If you use polygon shapes for your
tags, keep in mind that they will also be exported as geometry, unless you leave
lambert1 on them.

  WIN32 INSTALLATION:
  
1. Copy maya2q3.mll into MAYA_INSTALL_DIR\bin\plug-ins
   NOTE: if you are building from Visual Studio and already have your project
     set up with Maya's installation directory you should skip this step.
     
2. Copy AEQ3ShaderTemplate.mel into MAYA_INSTALL_DIR\scripts\AETemplates
   Note: if you are buliding from Visual Studio and already have your project
     set up with Maya's installation directory you should skip this step.
     
3. Start up Maya, go to Window -> Settings/Preferences -> Plug-in Manager.

4. Check "loaded" and "auto-load" next to the maya2q3 entry.
   Note: if checking loaded makes Maya pause briefly but not load the plugin, make sure you have
     the new version of the MS CRT libraries installed (see step 2).

  EXPORTING:
1. Set your project and point it to your game data (see modelling guide notes).

2. Model your object. Make sure you give it a Q3Shader material with a meaningful name
   (see modelling guide).

3. Animate it (if you want).

4. Set the range slider to include the exact frames you want to export (this is
   important!).

5. Go File -> Export All or File -> Export Selected.
   NOTE: When exporting a selection, you must select all instances of the
     geometry you want to expect (even though Maya makes it look like they're
     all selected when you click on one, you still need to SHIFT-click on the
     others) AS WELL AS all tags you want to export. Otherwise the exporter
     won't export everything you intended.

6. Select Export MD3 from the file types list.

7. Type in a file name.

8. Hit Export.