How to create a COLLADA Extension

This document outlines the steps to create, define, and use an extension for COLLADA.

Overview

This document contains the following sections:

• Specification: How to specify an extension prior to coding it.
• Implementing and advertising extensions: How to implement an extension (this discusses only aspects of the implementation that are visible to users - primarily determining whether the extension is available and defining its interface).
• Use of extensions in an application (this discusses the mechanics of using an extension if and only if it's supported by an implementation).

Specification

When initially creating an extension, take the following steps:

1. Does COLLADA already support the feature that does what I want?
2. Is there already an extension that does what I want? Or can one be reused?
3. If no suitable extension already exists, should the extension be Khronos-approved, multi-vendor, or specific to a single vendor?
4. Develop and write an extension specification as described in How do I write a specification?, following the naming conventions.
5. When you're ready to release the extension, freeze the specification and add it to the extension registry maintained by Khronos. At this time (but not before), you can receive, and be notified of, your permanent token (profile name) assignments from the COLLADA work group.
6. When shipping an extension, make sure that it is defined in XML Schema files accessible to ISVs. If the extension is Khronos-approved, use the Khronos-provided schema.

Note: The COLLADA schema enforces "lax" validation of extensions so use of qualified element names is recommended.

Does COLLADA already support the feature that does what I want?

Have you checked every COLLADA specification (e.g. 1.4 and 1.5) for the feature that you want? If the feature exists then you should use it. If the feature doesn't do everything that you want, then extend it using this process rather then create a new extension that replaces the feature.

It's possible, though unlikely, that the feature in COLLADA is not extensible. In this case, report a bug in the Khronos Bugzilla.

Is there already an extension that does what I want?

Can it be used instead of writing a new one? This may involve reuse of an existing specification, or promoting single-vendor COLLADA extensions to multi-vendor or Khronos-approved status. In either case, coordinate this use with the vendor(s) defining and shipping the existing extension.

Specifications for extensions that have already been developed can be obtained from the extension registry maintained by Khronos.

It's possible that additional extensions may have been submitted to the registry but not yet updated on the website, or that another licensee may be working on a similar extension but have not yet released the specification. So it's worth asking the COLLADA Working Group chair whether anyone has already defined related functionality.

Should the extension be Khronos-approved, multi-vendor, or specific to a single vendor?

Lesson learned from OpenGL - OpenGL's history has made clear that vendors do not want to deal with vendor-specific extensions if they can possibly avoid it. So if the functionality being designed is going to be expressed in COLLADA documents that are used by multiple applications - as most will - it's a good idea to agree on a single extension with other developers providing that functionality in their products. This makes it easier for vendors to justify development of the extensions.

If the functionality is well-understood, it may be appropriate to define a Khronos-approved extension. This is the most "blessed" category of extension; it goes through the entire standards process, and is approved by the working group, but remains optional functionality.

If Khronos as a whole isn't ready to deal with the extension, but other vendors are, then it should be defined as a multi-vendor extension. The interested parties can develop the specification entirely among themselves, outside the standards process.

In some cases, vendors may share a common core of functionality, with vendor-specific additional features. Here, it may make sense to agree on a multi-vendor extension to access the core functionality, with additional vendor-specific extensions layered on the core exposing unique features.

Finally, some extensions may have to remain proprietary and would therefore not be published. This process is still useful to designers of proprietary extensions however.

How do I write a specification?

Start with the template for writing extension specifications and also see this explanation of COLLADA extension mechanisms. General considerations include:

• It's important to think about all the different areas of the COLLADA specification(s) that are affected. The template helps with these questions by at least reminding you to consider each part of the core language specification.
  • What elements do new elements and attributes belong in?
  • What conformance badge would it belong to once it is formalized in the specification (Baseline, Superior, Exemplary, etc.)?
  • How are existing objects (elements) affected by use of the extension?

• Extension specifications may be written against multiple versions of the COLLADA specification. "Written against" means that new language must be written as well-defined modifications to the Specification being referenced (as listed in the Dependencies section).
  • If possible, it's highly preferable to write against the most recent public version.
  • It should be possible for someone not involved with the development of an extension to sit down with a copy of the Specification and the extension and produce a merged document identical to what you intended.

One complete, published example to refer to is the EXT_Morph_Weights_Extension.

Naming conventions

Naming convention details are described on the Syntax_rules_for_COLLADA_Extensions page.

All extensions must be named and the name is included in the extension specification page. The extension name is of the form "category element profile" where:

• "category" identifies the extension category.
  • For a single-vendor extension, the category is the vendor name: "Autodesk", "NVIDIA", etc..
  • For a multi-vendor extension, the category is "EXT".
  • For Khronos-approved extensions, the category is "KHR".
• "element" identifies the name of the element in the COLLADA specification that is being extended.
• "profile" is the name used in the profile attribute of the <technique> element that implements the extension.

For example, the extension name "Luxology light modo401" is used for a single-vendor
extension adding support for custom light settings for the modo (version 401) application.

Choose extension names that are:

• Short.
• Meaningful.
• Have a unique profile name. Naming conventions for profiles are described in the Syntax_rules_for_COLLADA_Extensions page.

The goal is for names to be concise, but not at the cost of confusion or ambiguity.

Advertising extension names to Implementations

The COLLADA specification and schema provide several ways of indicating (advertising) that a document contains extensions. The following elements signal to an Implementation that is importing the document that an extension is present:

• by <technique profile="value"> element and attribute
  • this allows you to have sub-schemas
  • these are profile dependent
• by <extra> element
  • a bag of techniques
• by <input semantic="value"> element attribute
  • these are profile independent

See COLLADA Extensibility.

Example

See EXT_Morph_Weights_Extension.

Extension Registry

Khronos keeps a registry of extensions for its specifications. The COLLADA extensions are described in the collada.org extensions directory.

The Extensions Directory is organized as follows:

• Top level page provides links to extensions sorted by either:
  • The Vendor name
  • The profile name
  • The extended element

Each of these pages contains a table with links to details documentation about each extension. Each pages contains information organized in a specification chapter template. Please follow these instructions on how to fill out these pages that explain how to add to the extensions directory

If an extension depends on another extension, the other extension must be referenced by the dependent one.

Once you have completed the extension, indicated your finished status in the appropriate section and notify the COLLADA work group chair person. The COLLADA work group will review the draft. Upon successful review, the work group will set the status to Published and application developers can then use the extension with confidence.

Implementing and advertising extensions

Errors

As COLLADA documents are content, there are no standard API or application error codes.

The handling of error conditions while parsing standard COLLADA is defined by the specification and conformance documents.

The handling of error conditions while parsing extensions is specified on an per-extension basis. The wiki template includes a section that describes the behavior for each version of the schema that the extension is designed to work with.

Use of extensions

Advertising is located on the wiki at collada.org. Pages and templates for vendors to self-declare extensions they support for specific tools are provided.