User:Chingachgook/Gsoc2009/End-User Specification

From BlenderWiki

Note: This is an archived version of the Blender Developer Wiki. The current and active wiki is available on wiki.blender.org.

Introduction

This plugin is made for Blender 2.5, using Collada spec 1.5.0 and OpenCOLLADA.

Non-Standard extensions which need to be defined

As said, COLLADA has no specific support for normal maps. The FCollada plugin does this for Maya and 3ds Max with the "<extra>" tag.

What do we choose?
Blender Tag-Set (used by no-one till now)
FCollada
A way which will be standard in (coming standard) COLLADA 1.6 (I don't think that exists)

I suggest we take the FCollada implementation, since it seems to be already widely used.

About the COLLADA module

OPENCOLLADA

Erwin Cowmans recommended to use this library because NextGen were sponsored by Sony to develop OpenCollada.

OpenCollada differs from a regular DOM in that it writes/reads data "on the fly".

This is done for memory and speed efficiency.

OpenCollada depends on two libraries: pcre (217K on linux) and expat (202K).

EXPORT

File is written just as new elements are added.

The following steps are repeated:

prepare element, or element hierarchy
write it

Collada allows multiple scene storage, this fits nicely with Blender database.

Currently the exporter writes active scene taken from context. It exports scene graph by looping through scene->base linked list. Inside scene graph, nodes link to geometry and material data by ids (XML referencing method). The geometry and material data is defined separately. For example geometries are stored in <library_geometries>.

For each <library_...> we create a class. Here is a simple sample of exporter's code:

class ImagesExporter: COLLADASW::LibraryImages
{
	const char *mfilename;
       // contains list of written images, to avoid duplicates
	std::vector<std::string> mImages;
public:
	ImagesExporter(COLLADASW::StreamWriter *sw, const char* filename) :
COLLADASW::LibraryImages(sw), mfilename(filename)
	{}
	
	void exportImages(Scene *sce)
	{
		openLibrary();
               // we take images from textures to avoid exporting unused images
		forEachMaterialInScene(sce, *this);

		closeLibrary();
	}

	void operator()(Material *ma, Object *ob)
	{
        // some code...
       }
};

IMPORT

Similar approach: "catch things on the fly".

Importer implements an interface which defines callbacks that are called by OpenCollada as it reads DAE.

Some callback examples:

writeGeometry - geometry data is passed
writeVisualScene - scene graph is passed
writeMaterial

These can be called by SAX parser in any order.

Each callback is passed a pointer to data which is OpenCollada frees once callback returns.

So what we're going to do here:

create a Mesh, fill it's geometry data and add it to Blender database in writeGeometry
create Objects in writeVisualScene. Here we get node info: parenting, transforms and data links (material, geometry)
link Object with Mesh in the "end" callback which is called when DAE reading finishes

Although it is possible to read DAE in two passes:

first pass: read scene graph info
second pass: read data (geometry, etc.) and link nodes to data

ColladaMaya importer does so, but for now doing this seems redundant.

File format support completeness

The end target is to make Blender understand COLLADA files as completely as possible.

The list of features planned to support:

geometry: vertices, normals, uvs, vertex colors
materials & textures
object transform animation: meshes, cameras, lamps, etc.
skinned animation

Not planned features:

kinematics - don't know how complex this is
physics - should be simple?
shaders

If some advanced features cannot be implemented at the moment, focus on those I can do and they will include most commonly used data.

Make good code structure so that new developers can jump in easily.

COLLADA spec defines requirements for exporters and importers - follow them.

User interface

The rule I'll follow is "keep the UI as simple as possible".

If unsupported data is being imported, inform a user clearly that it is not supported and, if possible, add what can be done to solve the problem.

Instructions

There are two submenus "Import" and "Export" in "File" menu. Each of them contains a list of importers/exporters. Find "COLLADA", press it, a pop-up menu should open, here you can choose a file you want to import (if you import) or create a dae file (if you export).

NOTE: Don't forget to add the ".dae" file format at the end while exporting.

End-user documentation

Supported features

Exporter

Scenes
- only current scene
Geometry
- only meshes
- vertices, faces, normals
Materials
- shaders: lambert, phong, blinn, others are exported as lambert
- shader options: emission, ambient, diffuse, specular, shininess, reflective, reflectivity, transparency, index of refraction.
- per-face materials
Textures
- mapped to: diffuse, ambient, specular, emission and reflective colors, there is no normal map in Collada but we can support it through <extra> as FCollada plugin for Maya does. Not sure if it's neccessary for exporter but importer should support this - creatures exported from Spore have such maps.
- NOTE: input is always assumed to be UV - if textures input is not UV it won't be exported
UVs
- multiple UV layers
Cameras
- camera options unfinished
Lights
- area lamp is not supported - accoding to Collada spec there is no such element - so it will be exported as a local lamp
Skinning
- NOTE: Armatures not assigned to geometry won't be exported properly.
Animation
- object animation
- skinned animation(linear)
Objects hierarchy
Empties

Importer

Should provide inverse functions of everything that exporter does.

Scenes
- scenes are imported in the current scene
Geometry
- only meshes
- vertices, faces, normals
- NOTE: polygons with less than 3 vertices are not supported, polygons with more than 4 verts will be triangulated
Materials
- shaders: lambert, blinn, phong, constant is imported as lambert
- shader options: diffuse, emission, ambient, reflective, reflectivity, index of refraction, specular
- per-face materials
Textures
- mapped to: diffuse, emission, ambient, reflective, specular
UVs
- multiple UV channels
Cameras
- camera options unfinished
Lights
Empties
Objects hierarchy
Skinning
Animation
- object animation
- skinned animation unfinished

Missing

The following features are missing but they could be added later:

COLLADA supports lots of different material profiles - such as - profile CG, Open GL ES, Open GL ES 2.0, GLSL, and others. Maybe once someone would like to add support for them. Currently plugin supports only profile COMMON.
Splines, lines, nurbs.
Kinematics
Physics
...