# QTAtoms

This page is based on information obtained from various places at the QuickTime API website. More details about the QT Atom architecture are available here.

QuickTime stores most of its data using specialized structures, called QT Atoms. The QT atom architecture is a simple, yet powerful, way to construct arbitrarily complex hierarchical data structures.

Each QT Atom carries its own size and type information, as well as its data. There are several advantages to using QT atoms for holding and passing information:

- QT Atoms can nest indefinitely, forming hierarchies that are easy to pass from one process to another.
- QuickTime provides a single set of tools by which you can search and manipulate QT atoms of all types.

QT Atoms are stored in QT Atom Containers. You can think of a newly-created QT atom container as the root of a tree structure that contains no children.

A QT atom container contains QT atoms (Figure 1). Each QT atom contains either data or other atoms.

- A QT atom that contains other atoms is a parent atom and the atoms it contains are its child atoms.
- A QT atom that contains data is a leaf atom.

You can use the QT atoms API (part of the Movie Toolbox) to search through QT atom hierarchies until you get to leaf atoms, then read the leaf atom's data from its various fields.

Figure 1: QT atom container with parent and child atoms

Each atom has an offset that describes its position within the container. In addition, each QT atom has a type and an ID. The atom type describes the kind of information the atom represents. For example, movie atoms are type `'moov'` , while the track atoms inside them are type `'trak'`. The atom ID is used to differentiate child atoms of the same type with the same parent; an atom's ID must be unique for a given parent and type. In addition to the atom ID, each atom has a 1-based index that describes its order relative to other child atoms of the same type and parent. You can uniquely identify a QT atom in three ways:

- by its offset within the container
- by its parent atom, type, and index
- by its parent atom, type, and ID

You can store and retrieve atoms in a QT atom container by index, ID, or both. For example:

- to use a QT atom container as a dynamic array or tree structure, you can store and retrieve atoms by index
- to use a QT atom container as a database, you can store and retrieve atoms by ID.

You can also create, store, and retrieve atoms using both ID and index to create an arbitrarily complex, extensible data structure.

Warning: Since QT atoms are offsets into a data structure, they can be changed during editing operations on QT atom containers, such as inserting or deleting atoms. For a given atom, editing child atoms is safe, but editing sibling or parent atoms invalidates that atom's offset.

Note: For cross-platform purposes, all data in a QT atom is expected to be in big-endian format.

Parsing the QT atom container

As a developer, you do not need to parse the QT atom container format yourself. Instead, you can use the QT atom functions to:

- create atom containers
- add atoms to and remove atoms from atom containers
- search for specific atoms in atom containers, and
- retrieve data from atoms in atom containers.

Most QT atom functions take two parameters to specify a particular atom: the atom container that contains the atom and the offset of the atom in the atom container data structure. You obtain an atom's offset by calling either QT_FindChildByID or QT_FindChildByIndex.

When calling any QT atom function for which you specify a parent atom as a parameter, you can pass 0 as an atom offset to indicate that the specified parent atom is the atom container itself. For example, you would call the QT_FindChildByIndex command and pass 0 for the parent atom parameter to indicate that the requested child atom is a child of the atom container itself.

- QT Atom commands

- Constants

QTAtoms © Escape
Generated by QDoc 2.8 on Wed, Jan 28, 2009 18:57:07