#
# Copyright (C) 2004 Mekensleep
#
# Mekensleep
# 24 rue vieille du temple
# 75004 Paris
#       licensing@mekensleep.com
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
#
#
----------------------------------------------------------------------------
--------------------
----------------------------------------------------------------------------
--------------------
----------------------------------------------------------------------------
--------------------
Exportcalskel <string:filepathname> <node_array:bones list(bone root)>
<boolean:bShowUI>

Description :
-------------
This function is used to export a skeleton from 3D Studio Max to the Cal3D
0.9 skeleton file format.
The skeleton is a hierarchy of nodes that can be any type of nodes (cameras,
meshes, bones, Biped bones.) or a mix of nodes types.
Remark : All nodes from the hierarchy are exported. While when using the
exporter without Maxscript, that is manually, dummies nodes that are part of
the hierarchy are not exported by default, you have to select them in the
user interface.

Parameters :
------------
1) The first parameter is a Maxscript string that contains the full path
name of the file where to write the skeleton information. This string must
end with the file extension. Two file extensions are supported : .CSF or
.XSF. If you set an extension of .CSF, the file exported will be written in
a binary format. If you use the .XSF extension, the file exported will be
written in an XML format. If you don't set an extension, by default, the XML
file format is chosen.
If the string doesn't contain a full path name but a name such as
"myskeletonfile.xsf", the file will be written on your hard drive in the
current directory which is the last directory used by 3D Studio Max.

Remark : Invalid characters are removed from this string when writing the
file.

2) The 2nd parameter is a Maxscript array of nodes. It can contain any type
of nodes. Only the highest node of the skeleton hierarchy must be set in
this array, if you have several skeletons to export in the same file, you
should set in this array the highest bones of your nodes hierarchies. If you
have only one skeleton, just set the highest bone of your skeleton hierarchy
in the array.

3) The 3rd parameter is a Maxscript boolean to tell if you want to use the
user interface to select nodes to be exported as the skeleton. If so, you
will be able to select manually the nodes to be exported.

Return value :
--------------
If the function worked fine it returns the Maxscript integer value of 0. If
it returns a Maxscript non-zero integer value then something went wrong.
Detail of the return values as Maxscript integers:
-2 : An exception occurred in the ExportCalSkel_cf C++ function.
-1 : The C++ function ExportSkeletonFromMaxscriptCall didn't worked.
 0 : Everything went right.
 1 : the first parameter : <string:filepathname> is a null string.
 2 : the second parameter : <node_array:bones list(bone root)> is an empty
array.
 3 : One of the component of the second parameter : <node_array:bones
list(bone root)>
     is not an instance of the Node class.

Usage :
-------
--Maxscript code snippet : We suppose we have a Biped skeleton (using
Character Studio plugin from Discreet) whose bone root, highest in the
hierarchy is named "Bip01".

--Set the full path name of the skeleton file (set extension .XSF to let the
file be in XML format)
SkeletonFile = "c:/3dsmax6/mesh/cal3D/Character01/skeletonfile.xsf"

--Create an array named "tab" with the node named bip01 inside
tab = #($Bip01)

--Call the export skeleton function with no UI
errorcode = exportcalskel SkeletonFile tab false
if (errorcode != 0) then messagebox("error in exportcalskel")


----------------------------------------------------------------------------
--------------------
----------------------------------------------------------------------------
--------------------
----------------------------------------------------------------------------
--------------------
ExportCalMesh <string:filepath> <string:Skeleton filepath>
<mesh_node:meshnode> <int:Max number of bones by vertex> <float:Weight
threshold> <bool: LOD creation> <bool:Spring system>
Description :
-------------
This function is used to export a mesh from 3D Studio Max to the Cal3D 0.9
mesh file format. The mesh is always linked to a skeleton and can't be
exported separately because the mesh Cal3D file format contains the skinning
vertices weights information.

Warnings :
-        We need to have exported the Cal3D skeleton file first !

Parameters :
------------
1) The first parameter is a Maxscript string that contains the full path
name of the file where to write the mesh information. This string must end
with the file extension. Two file extensions are supported for mesh files:
.CMF or .XMF. If you set an extension of .CMF, the file exported will be
written in a binary format. If you use the .XMF extension, the file exported
will be written in an XML format. If you don't set an extension, by default,
the XML file format is chosen.
If the string doesn't contain a full path name but a name such as
"mymeshfile.xmf", the file will be written on your hard drive in the current
directory which is the last directory used by 3D Studio Max.
Remark : Invalid characters are removed from this string when writing the
file.

2) The second parameter is a Maxscript string that contains the full path
name of the cal3D skeleton file linked to this mesh. This string must be the
exact full path name of the skeleton file with its path and extension. If
the file is not a valid Cal3D skeleton file, you get an error message
telling "Invalid file format".

3) The third parameter <mesh_node:meshnode> is the node of the mesh to
export.

4)The fourth parameter is a Maxscript integer which represents the maximum
number of bones per vertex for the skinning operation (same as in the user
interface of the exporter dialog box). It must be strictly positive.

5)The fifth parameter is a Maxscript float that represents the Weight
threshold (same as in the user interface of the exporter dialog box). It
must be positive.

6) The sixth parameter is a Maxscript Boolean. It is true if we want to
create the Cal3D LOD or false if we do not.

7) The seventh parameter is a Maxscript Boolean. It is true if we want to
use the Cal3D spring system or false if we o not.

Return value :
--------------
If the function worked fine it returns the Maxscript integer value of 0. If
it returns a Maxscript non-zero integer value then something went wrong.
Detail of the return values as Maxscript integers:
-2  : An exception occurred in the ExportCalMesh_cf C++ function.
-1  : The C++ function ExportMeshFromMaxscriptCall didn't worked.
 0  : Everything went right.
 1  : the first parameter : <string:filepath> is a null string.
 2  : the second parameter : <string:Skeleton filepath> is a null string.
 3  : the second parameter : <string:Skeleton filepath> is not an existing
file.
 4  : the fourth parameter <int:Max number of bones by vertex> is negative
or null.
5        : the fifth parameter <float:Weight threshold> is negative.
6        : the third parameter <mesh_node:meshnode> is a null pointer.
 7  : the third parameter <mesh_node:meshnode> is not a mesh /editable mesh
pointer.

Usage :
-------
--Maxscript code snippet : We suppose we have exported a skeleton file and
our mesh node to be exported is called MyMesh.

--This is the name of the skeleton file already exported
SkeletonFile = "c:/3dsmax6/mesh/cal3D/Character01/skeletonfile.xsf"

--We suppose we have a mesh node called "MyMesh"
--Call the function to export the mesh
errorcode = exportcalmesh "c:/3dsmax6/mesh/cal3D/Character01/mesh.xmf"
skeletonfile $MyMesh
 3 0.001 false false
if (errorcode != 0) then messagebox("error in exportcalmesh ")


----------------------------------------------------------------------------
--------------------
----------------------------------------------------------------------------
--------------------
----------------------------------------------------------------------------
--------------------
ExportCalMat <string:filepath> <standard_material: material>
Description :
-------------
This function is used to export a material from 3D Studio Max to the Cal3D
0.9 material file format.

Parameters :
------------
1) The first parameter is a Maxscript string that contains the full path
name of the file where to write the material information. This string must
end with the file extension. Two file extensions are supported : .CRF or
.XRF. If you set an extension of .CRF, the file exported will be written in
a binary format. If you use the .XRF extension, the file exported will be
written in an XML format. If you don't set an extension, by default, the XML
file format is chosen.
If the string doesn't contain a full path name but a name such as
"mymaterial.xrf", the file will be written on your hard drive in the current
directory which is the last directory used by 3D Studio Max.

Remark : Invalid characters are removed from this string when writing the
file.

2) The 2nd parameter is a Maxscript standard material. You pass a standard
material as this parameter(not necessarily coming from the material editor,
it can be the material of the selected node or any other material)


Return values :
--------------
If the function worked fine it returns the Maxscript integer value of 0. If
it returns a Maxscript non-zero integer value then something went wrong.
Detail of the return values as Maxscript integers:
-2 : An exception occurred in the ExportCalMat_cf C++ function.
-1 : The C++ function ExportMaterialFromMaxscriptCall didn't worked.
 0 : Everything went right.
 1 : the first parameter : <string:filepath> is a null string.
 2 : the second parameter : <standard_material: material> is a null pointer.
 3 : the second parameter : <standard_material: material> is not an instance
of a standard material class.

Usage :
-------
--Maxscript code snippet : We suppose we have a mesh named "MyMesh" with a
standard material applied on it.
--Call our function and pass as a second parameter the material of mesh
node.
errorcode = exportcalmat
 "c:/3dsmax6/mesh/cal3D/Character01/materialfile.xmf" ($MyMesh.material)
if (errorcode != 0) then messagebox("error in exportcalmat ")

----------------------------------------------------------------------------
--------------------
----------------------------------------------------------------------------
--------------------
----------------------------------------------------------------------------
--------------------
ExportCalAnim <string:filepath> <string:Skeleton filepath> <node_array:Bones
list> <int:start frame> <int:end frame> <int:frame offset>
list> <int:framerate>

Description :
-------------
This function is used to export an animation from 3D Studio Max to the Cal3D
0.9 animation file format.

Warning :
-        We need to have exported the Cal3D skeleton file first !

Parameters :
------------
1) The first parameter is a Maxscript string that contains the full path
name of the file where to write the animation information. This string must
end with the file extension. Two file extensions are supported : .CAF or
.XAF. If you set an extension of .CAF, the file exported will be written in
a binary format. If you use the .XAF extension, the file exported will be
written in an XML format. If you don't set an extension, by default, the XML
file format is chosen.
If the string doesn't contain a full path name but a name such as
"myanimationfile.xaf", the file will be written on your hard drive in the
current directory which is the last directory used by 3D Studio Max.

Remark : Invalid characters are removed from this string when writing the
file.

2) The second parameter is a Maxscript string that contains the full path
name of the cal3D skeleton file linked to this aniamtion. This string must
be the exact full path name of the skeleton file with its path and
extension. If the file is not a valid Cal3D skeleton file, you get an error
message telling "Invalid file format".

3) The third parameter is a Maxscript array of nodes. It can contain any
type of nodes. The nodes contained in this array should be part of the
skeleton nodes written in the skeleton file. If not, they will be ignored.
The array should contain only the nodes of the skeleton that you want to get
their animation written in the animation file.
For example : you only want to get the animation of 2 nodes of the skeleton,
set these 2 nodes in this array and only their 2 animation will be exported.

4) The fourth parameter is a Maxscript integer that represents the start
frame number to get animation from. If you want to start getting the
animation from frame number 60, set 60 in this parameter. It should always
be a positive or null number.

5) The fifth parameter is a Maxscript integer that represents the end frame
number to stop getting animation. If you want to stop getting the animation
from frame number 90, set 90 in this parameter. It should always be a
positive or null number and superior to the StartFrame previous parameter.

6) The sixth parameter is a Maxscript integer that represents the frame
offset number. It is the number that represents the step set to get from
startFrame number to endframe number. It should always be a strictly
positive.
For example, you want to export the animation from time 60 to 90 but only
every 10 frame, so set 10 in this parameter.

7) The seventh parameter is a Maxscript integer that represents the frame
rate number. It is the number of frame per second to consider.
It should always be a strictly positive.

Return value :
--------------
If the function worked fine it returns the Maxscript integer value of 0. If
it returns a Maxscript non-zero integer value then something went wrong.
Detail of the return values as Maxscript integers:
 -2 : An exception occurred in the ExportCalAnim_cf C++ function.
 -1 : The C++ function ExportAnimationFromMaxscriptCall didn't worked.
 0  : Everything went right.
 1  : the first parameter : <string:filepath> is a null string.
 2  : the second parameter : <string:Skeleton filepath> is a null string.
 3  : the second parameter : <string:Skeleton filepath> is not an existing
file.
 4  : the third parameter <node_array:Bones list> is an empty array.
 5  : the fourth parameter <int:start frame> is negative.
 6  : The fifth parameter <int:end frame> is negative.
 7  : The "start frame" parameter is superior to the "end frame" parameter
 8  : The sixth parameter <int:frame offset> is negative.
 9  : The seventh parameter <int:framerate> is negative.
 10 : One of the node of the third parameter <node_array:Bones list> is a
null node pointer.


Usage :
-------
--Maxscript code snippet : We suppose we have a cal3D skeleton file already
written at the following path :
SkeletonFile = "c:/3dsmax6/mesh/cal3D/Character01/skeletonfile.xsf"

--This is the name of the skeleton file already exported
SkeletonFile = "c:/3dsmax6/mesh/cal3D/Character01/skeletonfile.xsf"

-- Set all Biped nodes in an array (all their names start with "bip")
tab = #($bip*)

--call our function
errorcode = exportcalanim animationFile skeletonfile tab 60 90 10 30
if (errorcode != 0) then messagebox("error in exportcalanim ")
