DOM guide: Setting up
This article describes how to set up your software and system to use the COLLADA DOM.
To use the COLLADA DOM in a client application, you must:
- Download the DOM
- Download the external libraries that the DOM uses
- Build the DOM
- Build your client application
((EDITOR: This page needs the following improvement: Include a discussion of how to build on Linux. ))
Downloading the COLLADA DOM
The COLLADA DOM is available royalty free and open source for download from SourceForge at http://sourceforge.net/projects/collada-dom.
The COLLADA 1.4.1 DOM 1.3.0 is the latest release package. It comes in three varieties:
- A source-code-only distribution
- A binary installer for Visual Studio .NET 2005 (VC8)
- A binary installer for Visual Studio .NET 2003 (VC7)
The COLLADA DOM is packaged for release only a few times a year. The latest COLLADA DOM code, containing the most recent bug fixes and features, can be downloaded directly from the Subversion repository on SourceForge. To grab the code from Subversion, you'll first need to download and install a Subversion client for your platform from http://subversion.tigris.org/project_packages.html. Then, open a console and run the command:
svn co https://collada-dom.svn.sourceforge.net/svnroot/collada-dom/COLLADA_DOM/trunk COLLADA_DOM
That downloads the latest copy of the COLLADA DOM to the COLLADA_DOM subdirectory (as specified by the last parameter).
The COLLADA DOM and all client applications have three external dependencies, libxml2, zlib, and iconv. The most current Windows binaries for these libraries can be downloaded from http://www.zlatkovic.com/libxml.en.html. For convenience, these libraries are packaged together in the "External Libaries" package available from the COLLADA DOM SourceForge download page.
Building the COLLADA DOM requires that the files for the external libraries on which it depends be in a specific directory structure. An environment variable,
COLLADA_EXTERNAL_LIBS_LOCATION, needs to be set to the directory that contains the following files:
libxml2/win32/include/libxml/* - The libxml2 headers from the distribution libxml2/win32/include/iconv.h libxml2/win32/include/zlib.h libxml2/win32/lib/iconv_a.lib libxml2/win32/lib/libxml2_a.lib libxml2/win32/lib/zlib.lib
On Linux you need to make sure the libxml2 headers and libs are installed. On Debian based systems you can install the package libxml2-dev:
apt-get install libxml2-dev
Building the COLLADA DOM
The Windows installers include prebuilt binaries (both DLLs and static libraries), so if you used the installers it isn't actually necessary to build the DOM yourself. Otherwise you'll have to build the DOM manually.
Project and solution files for Visual Studio .NET 2003 can be found in
Project and solution files for Visual Studio .NET 2005 can be found in
Open the .sln file for your version of Visual Studio and build whatever configurations you're interested in.
There are no prebuilt binaries available for Linux, so you'll have to build the DOM yourself. Also, currently there is no shared library version of the COLLADA DOM on Linux. Only static libs are available.
Go to the COLLADA DOM directory and run
for a debug build or
for a release build.
Building Client Applications
Visual Studio requires additional path and dependency information to properly compile and link applications using the COLLADA DOM.
Setting up include directories
Add the following information to your project:
- Add the following lines to the Additional include directories field in the General tab for the C/C++ project configuration settings:
Linking with the static COLLADA DOM libararies
The COLLADA DOM is provided as both static and dynamic link libraries.
To link with the static COLLADA DOM libraries:
- Add the following lines to the Additional library directories field in the General tab for the Linker project configuration settings:
<COLLADA_DOM-path>\lib\vc8\1.4 <libxml2, zlib, and iconv lib directory-path>
- Add the following lines to the Additional Dependencies field in the Input tab for the Linker project configuration settings:
libcollada_dae.lib libcollada_dom.lib libcollada_STLDatabase.lib libcollada_LIBXMLPlugin.lib libcollada_stdErrPlugin.lib libxml2_a.lib iconv_a.lib zlib.lib wsock32.lib
Linking with the dynamic COLLADA DOM library
To link with the dynamic COLLADA DOM library:
- Add the following line to the Preprecessor Definitions field in the Preprocessor tab for the C/C++ project configuration settings:
- Add the following line to the Additional library directories field in the General tab for the Linker project configuration settings:
- Add the following line to the Additional Dependencies field in the Input tab for the Linker project configuration settings:
Additional configuration options
- If you are using Visual Studio .NET 2003, substitute vc7 for vc8 in the Additional library directories field.
- To use the debug version of the libraries:
- Append "_d" to the end of the COLLADA DOM library names, for example, libcollada_dae_d.lib.
- Replace "lib" with "lib-dbg" in the library path.
- Make sure that your application is using the correct runtime libraries. The Runtime Library field in the Code Generation tab for the C/C++ configuration options should be set to:
- "Multi-threaded DLL" if using the release builds of the library
- "Multi-threaded Debug DLL" if using the debug builds
Currently there is no shared library version of the COLLADA DOM on Linux. Only static libs are available.
Install the COLLADA DOM
When building client applications on Linux, it's convenient to install the DOM headers and libs to /usr/include and /usr/lib, respectively. To install, go to the COLLADA DOM directory and run
to install the debug COLLADA DOM or
make install RELEASE=1
to install the release version of the DOM. You can uninstall by running
Building the Client App
If you have a file test.cpp that works with the COLLADA DOM, you can build it with g++ like this:
g++ -Wall -I/usr/include/collada test.cpp -lcollada_dae -lcollada_dom -lcollada_dae -lcollada_STLDatabase -lcollada_stdErrPlugin -lcollada_LIBXMLPlugin -lxml2 -o test
The fact that
collada_dae shows up twice isn't a mistake. It's necessary to resolve all the dependencies between the DAE and the DOM libraries.
|COLLADA DOM - Version 2.4 Historical Reference|
|List of main articles under the DOM portal.|
|User Guide chapters: • Intro • Architecture • Setting up • Working with documents • Creating docs • Importing docs • Representing elements • Working with elements • Resolving URIs • Resolving SIDs • Using custom COLLADA data • Integration templates • Error handling|
Systems: • URI resolver • Meta • Load/save flow • Runtime database • Memory • StringRef • Code generator