Getting started with COLLADA

Here's some information to help if you are getting started with COLLADA.

• Read the COLLADA FAQ to get a good overview.

• If you want to know more about the goals, design fundamentals and get detailed information about all the 1.4.x features, get a copy of the COLLADA book from AK Peters, or any other bookseller or library.

• Ignore anything prior to 1.4.x. Older versions of COLLADA are no longer supported, and are not compatible with the official standard release.

Learn about COLLADA

If you want to learn about the details:

• Read the specification, available on the official COLLADA standard web site: www.khronos.org/collada.

• Read the release notes. Available at the same place: www.khronos.org/collada. Release notes contain valuable information that could not be included in the documentation in time for production.

• Download the schema, from the same source

Use graphical tools such as XMLspy (free personal edition) to browse the schema in graphical form. [Note, the free XML edition will complain about the include statement, you can safely comment it on a special copy of the schema]

• Look at sample COLLADA documents in the COLLADA Test Model Bank. If you are getting samples from elsewhere, make sure you are not looking at a document for a version prior to 1.4.x. Every COLLADA document contain the version in the namespace declaration.
• Ask questions about design issues in the Design Discussions forum.

Importing and exporting COLLADA data

If you want to use COLLADA to import/export data from tools:

• Go to the " target="_blank" class="postlink">Product section and check if the tools you want to use are listed. Make sure to follow the instructions on how to install the plug-in if required.

• Check the Latest Versions post often to make sure you have the up-to-date tool. It is a good idea to subscribe (available on the bottom once you logged in the forum) to get an e-mail when updates are made to this post

• If your tool is not listed, go to the vendor's support web/e-mail and query about their COLLADA support. A lot of tools have COLLADA as work in progress and may be able to provide you with early software releases.

• If your product is listed, but lack some features you need, please make a request to the tool vendor and/or the COLLADA plug-in provider.

• Get the Feeling Viewer to look at the data you have exported

• Get Refinery, and use it to process your data further. This package also contains the Coherency Test that you want to run your exported data through to detect any potential issues.
• Report bugs ! Please ! Check the Latest Versions post to know where to post your bugs

• Ask your questions in the relevant forums, listed on the same post as above.

• Share your experience and contribute samples !

Implementing with COLLADA

If you want to implement COLLADA in your project :

First some important notes:

COLLADA is not designed as a game engine format, it is designed as an intermediate format for all the tools in your content pipeline, such as DCC tools and conditioners.

Some applications are using COLLADA as their input format, such as Google Earth, but most will have a converter from COLLADA to their highly optimized binary platform and engine specific format at the end of the COLLADA tool-chain. Consider writing such converter in a generic way so you can get data to your application from any part of the content pipeline. Likewise, consider the capability to directly load COLLADA documents in your application, at least in the development phase, to improve productivity.

COLLADA is designed to be highly flexible, it can store application specific data using its <extra> mechanism at various places in the document. You can insert this data in your DCC tool using the 'user properties' mechanism, the COLLADA import/export will carry this information for you, there is no need to change the exporter source code to carry your application/game specific data into the COLLADA format. The COLLADA schema allows this <extra> information at a lot of places, but implementations do not support all the possibilities. Make sure you do a quick experiment first, and ask the vendor/maintainer to know how this is currently supported. Note that this is often a limitation of the tool itself, not necessarily a limitation of the import/export process. The <extra> information that is supported will be saved in the tool native format as well, if imported from a COLLADA document. If you have your own plug-in for a given DCC tool, simply make sure that this plug-in puts the relevant information at the right place, and the already available COLLADA export/import will do the rest of the work for you.

• Consider using either the FCOLLADA or the COLLADA DOM library. Both libraries are open-source and can use in a commercial or non-commercial application without restrictions. COLLADA DOM is generated from the XML schema and provide access to all the COLLADA elements. FCOLLADA is used by the 3dsMax and Maya plug-ins, and provide a higher level interface. The choice of library depends on your style on programming, and how close to the schema you want to be.

• Check the Latest Versions post often to make sure you have the up-to date libary.

• If you are not using C++, or do not want to use the above libraries, there are other libraries or sample code for Java, C# and other languages available. Check the Contributions, or tools that can generate an interface in a variety of language from the Schema.

• Report bugs ! Please report bugs in the right place, as indicated in the Latest Versions post.

• Get Refinery and write your own conditionners to create your content pipeline and process the data further toward the application specific data. For instance, use this to create triangle stips, or optimized index triangle lists, out of all possible COLLADA geometries.
• Get a copy of the Feeling Viewer and use the Coherency Test (part of the Refinery package) to test out your exports, or the documents you are importing.

• Ask questions about implementation issues in the Implementation Discussions forum.

• Feel free to update the source code of the export/import, but only if you have a good reason for it, since this is extra work. Export/Import plug-ins are usually well designed and if you make your changes in additional files should be easy to merge with updates. If you want to avoid merging with future releases, consider providing your code to the maintainer/vendor so you code gets included in the next release.

I hope this information is useful. If you have ideas on how to improve this guide, please let us know at collada (at) collada.org

Most important, do not give up! COLLADA is not that hard, and it is rewarding and fun after you're through the learning curve!