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 detailed information about 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 COLLADA 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 to browse the schema in graphical form. [Note: XML edition might complain about the include statement; you can safely comment it out 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 that 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 format to import data into or export data from tools:
- Go to Portal:Products directory and check whether the tool that you want is listed. Follow the instructions on how to install the plug-in if required.
- Check the Portal:Products directory often to make sure that you have the most up-to-date tool. It is a good idea to subscribe to each product of interest to get an e-mail when updates are made to the product's page.
- If your tool is not listed, go to the vendor's support web/e-mail and query about their COLLADA support. Many tools have COLLADA as a work in progress and may be able to provide you with early software releases.
- If your product is listed, but lacks some features you need, please make a request to the tool vendor and/or the COLLADA plug-in provider.
- Get COLLADA Refinery and use it to process your data further. This package also contains the COLLADA Coherency Test; you can run your exported data through these tests to detect any potential issues.
- Report bugs! Please! Check reporting bugs or requests to know where to post your bugs.
- Ask your questions in the relevant COLLADA forums (use the Forum link in left navigation bar at any time).
- 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 use COLLADA as their input format, such as Google Earth, but most 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 a 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 into 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 then carry this information for you, so 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 for information about 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.
Also see the Extensions directory for details about the syntax of these <extra> extensions provided by various vendors. If you are a vendor with extensions, please consider adding to the extensions directory.
Developer tools and resources
- Consider using either the FCollada or the COLLADA DOM library. Both libraries are open-source and can be used in a commercial or noncommercial application without restrictions. COLLADA DOM is generated from the XML COLLADA schema and provides access to all the COLLADA elements. FCOLLADA is used by the ColladaMax and ColladaMaya plug-ins, and provides a higher-level interface. The choice of library depends on your style of programming, and how close to the schema you want to be.
- Check Portal:Products directory often to make sure you have the most up-to-date library.
- If you are not using C++, or do not want to use the preceding libraries, there are other libraries or sample code for Java, C#, and other languages available. Check the Contributions forum, for 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 reporting bugs or requests.
- Get COLLADA Refinery and write your own conditioners to create your content pipeline and process the data further toward the application-specific data. For instance, use this to create triangle strips, or optimized index triangle lists, out of all possible COLLADA geometries.
- Use the Coherency Test (part of the Refinery package) to test your exports or the documents that 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 that your code gets included in the next release.
If you have ideas on how to improve this guide, please sign in and edit this article or post suggestions on this article's discussion/talk page, or 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!