Feeling ColladaMax

ColladaMax is a COLLADA importer and exporter plug-in for 3ds Max. It supports all COLLADA 1.4 core features (e.g. animation and skinning) and a subset of ColladaFX. There is no support for ColladaPhysics at the moment. Backward compatibility is also considered important: COLLADA 1.3 documents can generally be imported without problem, and in the future we plan to continue supporting older versions.

Depending on our availability, we offer free support to qualifying game developers. For your report to be taken in consideration, make sure to use a corporate email (i.e. no hotmail account), include your full name and tell us a bit about how your team or studio uses COLLADA.

If you have feature requests or would like to report problems, visit the Feeling Software Bugzilla. Make sure that someone else hasn't already reported the issue. If you want, you can vote on an issue to increase its relative priority.

If you have specific needs, feel free to contact us through colladamax@feelingsoftware.com

To install ColladaMax, you will need 3ds Max 9, 3ds Max 8 or 3ds Max 7 SP1 (Service pack 1). Service packs for 3ds Max can be downloaded from the Autodesk support website. Make sure to install the right service pack for your system language. Note that service packs are not compatible with the debug builds of 3ds Max.

ColladaMax does not rely anymore on external libraries. The installer you download should set-up everything correctly and will delete Autodesk's own COLLADA plug-in.

The installation of ColladaMax is automatic using the installer you can download from our website.

To export a scene from the UI, click on File → Export…, then select the “COLLADA (*.DAE)” file type. You can then select which export options to use. Please see the Export options section for more information. You can also use the File → Export Selected… menu item to export only the selected objects and their dependencies.

To export a scene from within MaxScript, use the exportFile command:

            exportFile <filename>.DAE #noprompt

Please consult the 3ds Max documentation for more information on automating 3ds Max.

To import a COLLADA document from the UI, click on File → Import…, then select the “COLLADA (*.DAE)” file type. There are no import options. If there is an error in the COLLADA document, no data will be imported and an error message will be displayed. Otherwise, your COLLADA document should be imported silently after a short moment.

To import a scene from within MaxScript, use the importFile command:

            importFile <filename >.DAE #noprompt

Some popular features of 3ds Max are not currently supported by COLLADA. At the request of our users, we added many parameters to the export, through additional XML stored inside <extra><technique profile=”MAX3D”> blocks.

Extension parameter	3ds Max equivalent	Default value	Comment
<node><user_properties>	User-defined properties of an object.	“”	Within the UI: menu: Edit → Object Properties… → User Defined → User Defined Properties textbox, with a give object selected.
<camera><…><target>	Target node for a light or camera.	“”	The presence of this element indicates that the camera/light is targeted. The string contained by the element indicated the ‘id’ of the COLLADA scene node which is targeted.
<light><…><intensity>	Intensity for the color of a light.	1.0	Within the Modify tab for a selected light: Intensity/Color/Attenuation → Multiplier. Can be animated.
<light><…><aspect_ratio>	Aspect ratio for rectangular directional/spot lights.	1.0	Within the Modify tab for a selected light: Spotlight Parameters (or Directional Parameters) → Aspect.
<light><…><outer_cone>	Falloff for directional/spot lights.	Hotspot – 2.0	Within the Modify tab for a selected light: Spotlight Parameters (or Directional Parameters) → Falloff/Field. Can be animated.
<phong><spec_level>	Specular level of a Phong or Blinn  material.	100	In the COLLADA document, this value is held in percent. Within the Material Editor for a standard material: Blinn Basic Parameters → Specular Highlights → Specular Level. Can be animated.
<phong><emission_level>	Self-Illumination level of a Phong or Blinn.	100	In the COLLADA document, this value is held in percent. Within the Material Editor for a standard material: Blinn Basic Parameters → Self-Illumination textfield, when the “Color” checkbox is off. Can be animated.
<phong><displacement> <phong><filter_color> <phong><shininess> <phong>      <index_of_refraction> <phong><bump>	Extra map channels of a common material.	none	These extra map channels are available for export, within the MAX3D extension. Within the Material Editor for a standard material: Maps → Displacement, Maps → Filter Color …
<phong><wireframe> <phong><double_sided> <phong><face_map> <phong><faceted>	Material flags for common materials.	false	Within the Material Editor for a standard material: Shader Basic Parameters → Wire, Shader Basic Parameters → 2-Sided …
<phong>     <…>        <texture>          <amount>	Multiplier value for a map channel for common materials.	100	This parameter is exported for all the textured map channels, represented as a percentage in the COLLADA document. Within the Material Editor for a standard material: Maps → Amount column (for all the map channels). Can be animated.

The ColladaMax exporter provides a number of options, which are detailed in this section. The options can be modified from the export UI or by editing the ColladaMax.ini file located in the “3dsmax[7,8,9]\plugcfg\” folder. This configuration file is loaded in before every export, and saved to if when the user clicks Ok in the export options dialog. This configuration file is particularly useful when automating exports, to set per-scene options.

Bake Matrices: The transforms of each scene node and their animations will be exported as matrices. This is used mostly for interoperability, e.g. with another DCC tool. Note that Bipeds automatically have their matrices baked. Default: off. 

Relative Paths: Whether the absolute or relative file path will be written to the COLLADA document. Mostly impacts texture and shader filenames. Default: on.

Normals: Whether to export the normals of meshes. Default: on. 

Triangles: Whether to export the tessellation of a mesh as triangles or N-sided polygons. In the COLLADA document, this will generate either the <triangles> or the <polylist> element. Since 3ds Max doesn’t support holes, the 3ds Max exporter will never write the <polygons> element. It is recommended to keep this option on, as N-sided polygon export is still experimental. Defaults: this option is disabled and always on.

XRefs: Whether externally referenced meshes will be exported as external references. If this option is checked off, they will simply be dropped. Defaults: on.

Tangents/Binormals: Exports the texture tangents and binormals for all given map channels of meshes, as well as their indices within the mesh tessellation.

Sample animation: Enables time-sampling the animated parameters, within the Start and End time interval. One sample is taken per time unit. If this option is disabled, ColladaMax will attempt to export the animated parameters as key-frames. Animated bipeds or objects involving IK are automatically sampled, since COLLADA doesn’t have direct support for these features yet. Defaults: off.

Single <animation>: Whether the <animation> elements within the exported COLLADA document will be placed under a single root <animation> element, named after the scene. This is especially useful when exporting animation clips for 3dsMax 7. Defaults: on.

Create Clip: After all the animations are exported, one animation clip will be created to hold these animations.

8. Collada FX

IMPORTANT: The ColladaEffect material is at an experimental stage. You are free to use/extend it. We appreciate any feedback you have on its usage.

Overview 

The Collada FX specification comes to life within 3ds Max 8.0 and above by using the ColladaEffect material plugin provided by ColladaMax. The plugin gives you the possibility to integrate complex shaders in your scene using the Cg high-level shading language, including both standard NVIDIA Cg programs and CgFX effects. The effects are displayed in real-time in Max's DirectX 9 viewports, and you can edit and animate your effect parameters.

 

Figure 1. The ColladaEffect plugin in action. Shown: a sphere with bump and environment mapping, a cone shaded with split-tone Durer style shader, and a cylinder with a metal shader. Some parameters are animated, while some are bound to scene node positions (for example a point light). Click on the image for a larger view.

 

ColladaEffect Material 

 To use the ColladaEffect plugin, you must first instantiate it in the Material Editor.

Figure 2. ColladaEffect in Max's Material browser. 

 

After selecting the material, can modify it in the Material Editor. 

 

 

Figure 3. The ColladaEffect static UI in the Material Editor.

 

 The Material Editor UI for the ColladaEffect plugin has 3 main static panels: Techniques, Passes, and Shaders. Explaining the concept of creating effects built from multiple techniques and multiple rendering passes is out of the scope of this documentation, and you may want to refer to the Cg Toolkit documentation for further details. To add a technique you must fill the Name field and then press the Add button in the Techniques panel. You can change the current technique name by pressing the Replace button, and you can remove the current technique by pressing the Remove button. The same operations can be done for passes in the Passes panel. The chosen technique will display its passes in the Passes panel, and the currently selected pass will display its shaders in the Shaders panel. To load a vertex or fragment shader, you must have a technique and a pass selected, then press the Load button and select the Cg source file for your shader.

If the file is a standard Cg file (.cg), the load operation will only affect the selected shader, either vertex or fragment. The shader entry point defaults to "main" (see "Known limitations, item 1"), and the Cg profile and compiler options are determined automatically (the latest available for your graphics hardware).

In the event of a CgFX file (.cgfx) being chosen, the plugin will load the vertex and fragment shaders found in the first pass of the first technique in the effect file (see "Known limitations, item 2"). Render states will not be loaded (see "Known limitations, item 3").

 

Figure 4. Uniforms Parameters panel added after loading a shader.

 

Once a shader is successfully loaded (if an error has occured, it'll be displayed in the Messages panel), you will notice that a new panel is in the Material Editor: Uniform Parameters. This panel is dynamically created and holds the "tweakables", which are Cg uniform parameters not automatically handled by specific Cg binding semantics. The most commonly used Cg parameter types are supported by the plugin, see Table 1 for the exhaustive list, and Table 2 for the list of supported Cg semantics. The parameters displayed in this panel are held by Max's parameter block structures. They can thus be animated just like any other Max attribute. You can edit the animation curves in the Track View editor, but the name of the parameter will not appear (see "Known limitations", item 4). Note that loading a different shader, or re-loading the same shader, will remove any operation made to the parameter (value, animation) (see "Known limitations, item 5).

 

Cg Parameter Type	Cg Semantic	CgFX Annotation	ColladaEffect Support
bool			Yes. Checkbox, not animatable
float, half			Yes. Spinner, animatable.
	TIME		Yes. No UI, bound to Max time.
float2, half2			No Support (See "Known limitations, item 6)
float3, half3  float4, half4		UIWidget = "Color"	Yes. Color picker, animatable.
	COLOR0, COLOR1
		[Object]	Yes. Node picker, 3D position.
float4x4, half4x4	(see Table 2)		Yes. NO UI, updates with matrix  binding semantics.
texture			Yes. NO UI. Supported through  sampler parameters.
sampler1D			No support.
sampler2D			Yes. Bitmap picker. (Only one texture  parameter supported per sampler)
samplerCUBE
sampler3D			No support.

Table 1. ColladaEffect support for Cg parameters. 

 

Cg Semantic	ColladaEffect binding
WORLDVIEWPROJ WORLDVIEWPROJECTION	W * V * P
WORLDVIEWPROJI WORLDVIEWPROJECTIONI WORLDVIEWPROJECTIONINVERSE	Inverse(W * V * P)
WORLDVIEWPROJIT WORLDVIEWPROJECTIONIT WORLDVIEWPROJECTIONINVERSETRANSPOSE	Transpose(Inverse(W * V * P))
VIEWPROJ VIEWPROJECTION	V * P
VIEWPROJI VIEWPROJECTIONI VIEWPROJECTIONINVERSE	Inverse(V * P)
VIEWPROJIT VIEWPROJECTIONIT VIEWPROJECTIONINVERSETRANSPOSE	Transpose(Inverse(V * P))
VIEW	V
VIEWI VIEWINVERSE	Inverse(V)
VIEWIT VIEWINVERSETRANSPOSE	Transpose(Inverse(V))
PROJECTION	P
PROJECTIONI PROJECTIONINVERSE	Inverse(P)
PROJECTIONIT PROJECTIONINVERSETRANSPOSE	Transpose(Inverse(P))
OBJECT	O
OBJECTI OBJECTINVERSE	Inverse(O)
OBJECTIT OBJECTINVERSETRANSPOSE	Transpoese(Inverse(O))
WORLD	W
WORLDI WORLDINVERSE	Inverse(W)
WORLDIT WORLDINVERSETRANSPOSE	Transpose(Inverse(W))
WORLDVIEW	W * V
WORLDVIEWI WORLDVIEWINVERSE	Inverse(W * V)
WORLDVIEWIT WORLDVIEWINVERSETRANSPOSE	Transpose(Inverse(W * V))

 Table 2. ColladaEffect support for matrix bindings.

 

Varying Parameters

There is no support for editable varying input. The channels sent to the shader are: POSITION, NORMAL and TEXCOORD[0-7] only. These are the only semantics supported by the ColladaEffect plugin.

The way the TEXCOORD[0-7] channels are bound to the shader needs further explanation. Max users are familiar with "map channels" for assigning extra mapping information to a geometry. The ColladaEffect plugin uses the valid map channels data and sends it to the shader using the TEXCOORD[0-7] semantic. It is important to note that Max ALWAYS defines the map channel #1 as an unmodified UVW unwrap modifier. As a consequence, TEXCOORD0 will always be valid and will contain UVW coordinates if a node has no map channel modifier applied.

Example 1. If you assign a VertexPaint modifier, using the map channel #0 or "vertex color channel", on a Sphere node, then TEXCOORD0 will contain the vertex color information, and TEXCOORD1 will contain the UVW coordinates.

Example 2. You can also add a UVW modifier that uses the map channel #47 to a node, and the result on the shader side will be TEXCOORD0 for Max's UVW coordinates, and TEXCOORD1 for the modifier. The unassigned map channel numbers will be skipped.

 

Real-Time Display

The ColladaEffect material plugin is only supported by DirectX 9 display. The viewports display the geometries having a ColladaEffect assigned for material using Cg's D3D9 extended interface. The viewports will update on any time change event.

 

Collada Translation

The plugin supports for Collada export and import through ColladaMax following its specific capabilities. A <material> element will be exported for each ColladaEffect instance. Each material instances an <effect> element having a <profile_CG platform="PC-DX9"> profile. The profile contains all the effect information: <include> elements (up to two) for the shader sources, <newparam> to generate the effect parameters and a list of <technique> elements. Each technique contains a list of <pass> elements, which in turn contain two <shader> elements, each having a different stage (either VERTEX or FRAGMENT). The <compiler_target> and <name> elements are exported for each shader, as well as accurate parameter bindings using the <bind> elements.

All these elements can be imported back into Max using the ColladaMax plugin. 

 

Known Limitations

The following limitations of the plugin are known to us and will be addressed in a later ColladaMax release. 

1. Entry point for Cg shaders is fixed to "main".
2. CgFX files are loaded by using only the first pass of the first technique.
3. Render states are not supported.
4. Parameter names do not appear in the Track View editor.
5. Modifications are lost when re-loading the same shader.
6. There is no support for floating point vector parameters.
7. Incomplete support for D3D lost device events.
8. Transparency is not supported in viewports due to Max's rendering pipeline.
9. Editable varying parameters are not supported.

 

There is no support for COLLADA Physics yet. The support for ColladaFX is still very experimental.

Autodesk Media and Entertainment developed the first versions of the COLLADA translators for 3ds Max. Feeling Software was contracted in 2005 to redesign and rewrite it to make it conform with COLLADA 1.3 and 1.4. The final result was called the COLLADA tools for 3ds Max, and was copyright Autodesk Media and Entertainment, Feeling Software and distributed under the MIT license.

Feeling Software is now the official developer of ColladaMax.

We would like to thank Autodesk Media and Entertainment (especially Jean-Luc Corenthin and his team), for starting this plug-in; Igor Kravtchenko for his patch on materials and Kevin Thacker for his work on sampling/baking matrices and his many generous fixes.