---

Tween Media

Tween media is used to store pairs of values to be interpolated between in QuickTime movies. These interpolated values modify the playback of other media types by using track references and track input maps. For example, a tween media could generate gradually changing relative volume levels to cause an audio track to fade out. It has a media type of 'twen'.

Every tween operation is based on a collection of one or more values from which a range of output values can be algorithmically derived. Each tween is assigned a time duration, and an output value can be generated for any time value within the duration. In the simplest kind of tween operation, a pair of values is provided as input and values between the two values are generated as output.

A tween track is a special track in a movie that is used exclusively as a modifier track. The data it contains, known as tween data, is used to generate values that modify the playback of other tracks, usually by interpolating values. The tween media handler sends these values to other media handlers; it never presents data.

In this section:

Tween Sample Description
Tween Sample Data
Tween Type Categories
Tween QT Atom Container

Tween Sample Description

The tween sample description uses the standard sample description header, as described in “Sample Table Atoms.”

The data format field in the sample description is always set to 'twen'. The tween media handler adds no additional fields to the sample description.

Tween Sample Data

Tween sample data is stored in QT atom structures.

At the root level, there are one or more tween entry atoms; these atoms have an atom type value of 'twen'. Each tween entry atom completely describes one interpolation operation. These atoms should be consecutively numbered starting at 1, using the atom ID field.

Each tween entry atom contains several more atoms that describe how to perform the interpolation. The atom ID field in each of these atoms must be set to 1.

• Tween start atom (atom type is 'twst'). This atom specifies the time at which the interpolation is to start. The time is expressed in the media’s time coordinate system. If this atom is not present, the starting offset is assumed to be 0.

• Tween duration atom (atom type is 'twdu'). This atom specifies how long the interpolation is to last. The time is expressed in the media’s time coordinate system. If this atom is not present, the duration is assumed to be the length of the sample.

• Tween data atom (atom type is 'twdt'). This atom contains the actual values for the interpolation. The contents depend on the value of the tween type atom.

• Tween type atom (atom type is 'twnt'). Describes the type of interpolation to perform.

Table 3-11 shows all currently defined tween types. All tween types are currently supported using linear interpolation.

Each tween type is distinguished from other types by these characteristics:

• Input values or structures of a particular type

• A particular number of input values or structures (most often one or two)

• Output values or structures of a particular type

• A particular algorithm used to derive the output values

Tween operations for each tween type are performed by a tween component that is specific to that type or, for a number of tween types that are native to QuickTime, by QuickTime itself. Movies and applications that use tweening do not need to specify the tween component to use; QuickTime identifies a tween type by its tween type identifier and automatically routes its data to the correct tween component or to QuickTime.

When a movie contains a tween track, the tween media handler invokes the necessary component (or built-in QuickTime code) for tween operations and delivers the results to another media handler. The receiving media handler can then use the values it receives to modify its playback. For example, the data in a tween track can be used to alter the volume of a sound track.

Tweening can also be used outside of movies by applications or other software that can use the values it generates.

Tween Type Categories

Each of the tween types supported by QuickTime belongs to one of these categories:

• Numeric tween types, which have pairs of numeric values, such as long integers, as input. For these types, linear interpolation is used to generate output values.

• QuickDraw tween types, most of which have pairs of QuickDraw structures, such as points or rectangles, as input. For these types, one or more structure elements are interpolated, such as the h and v values for points, and each element that is interpolated is interpolated separately from others.

• 3D tween types, which have a QuickDraw 3D structure such as TQ3Matrix4x4 or TQ3RotateAboutAxisTransformData as input. For these types, a specific 3D transformation is performed on the data to generate output.

• The polygon tween type, which takes three four-sided polygons as input. One polygon (such as the bounds for a sprite or track) is transformed, and the two others specify the start and end of the range of polygons into which the tween operation maps it. You can use the output (a MatrixRecord data structure) to map the source polygon into any intermediate polygon. The intermediate polygon is interpolated from the start and end polygons for each particular time in the tween duration.

• Path tween types, whichhave as input a QuickTime vector data stream for a path. Four of the path tween types also have as input a percentage of path’s length; for these types, either a point on the path or a data structure is returned. Two other path tween types treat the path as a function: one returns the y value of the point on the path with a given x value, and the other returns the x value of the point on the path with a given y value.

• The list tween type, which has as input a QT atom container that contains leaf atoms of a specified atom type. For this tween type category, the duration of the tween operation is divided by the number of leaf atoms of the specified type. For time points within the first time division, the data for the first leaf atom is returned; for the second time division, the data for the second leaf atom is returned; and so on. The resulting tween operation proceeds in discrete steps (one step for each leaf atom), instead of the relatively continuous tweening produced by other tween type categories.

Tween QT Atom Container

The characteristics of a tween are specified by the atoms in a tween QT atom container.

A tween QT atom container can contain the atoms described in the following sections.

General Tween Atoms

• kTweenEntry

  Specifies a tween atom, which can be either a single tween atom, a tween atom in a tween sequence, or an interpolation tween atom.

  Its parent is the tween QT atom container (which you specify with the constant kParentAtomIsContainer).

  The index of a kTweenEntry atom specifies when it was added to the QT atom container; the first added has the index 1, the second 2, and so on. The ID of a kTweenEntry atom can be any ID that is unique among the kTweenEntry atoms contained in the same QuickTime atom container.

  This atom is a parent atom. It must contain the following child atoms:

  • A kTweenType atom that specifies the tween type.

  • One or more kTweenData atoms that contain the data for the tween atom. Each kTweenData atom can contain different data to be processed by the tween component, and a tween component can process data from only one kTweenData atom a time. For example, an application can use a list tween to animate sprites. The kTweenEntry atom for the tween atom could contain three sets of animation data, one for moving the sprite from left to right, one for moving the sprite from right to left, and one for moving the sprite from top to bottom. In this case, the kTweenEntry atom for the tween atom would contain three kTweenData atoms, one for each data set. The application specifies the desired data set by specifying the ID of the kTweenData atom to use.

    A kTweenEntry atom can contain any of the following optional child atoms:

  • A kTweenStartOffset atom that specifies a time interval, beginning at the start of the tween media sample, after which the tween operation begins. If this atom is not included, the tween operation begins at the start of the tween media sample.

  • A kTweenDuration atom that specifies the duration of the tween operation. If this atom is not included, the duration of the tween operation is the duration of the media sample that contains it.

    If a kTweenEntry atom specifies a path tween, it can contain the following optional child atom:

  • A kTweenFlags atom containing flags that control the tween operation. If this atom is not included, no flags are set.

    Note that interpolation tween tracks are tween tracks that modify other tween tracks. The output of an interpolation tween track must be a time value, and the time values generated are used in place of the input time values of the tween track being modified.

    If a kTweenEntry atom specifies an interpolation tween track, it must contain the following child atoms:

  • A kTweenInterpolationID atom for each kTweenData atom to be interpolated. The ID of each kTweenInterpolationID atom must match the ID of the kTweenData atom to be interpolated. The data for a kTweenInterpolationID atom specifies a kTweenEntry atom that contains the interpolation tween track to use for the kTweenData atom.

    If this atom specifies an interpolation tween track, it can contain either of the following optional child atoms:

  • A kTweenOutputMin atom that specifies the minimum output value of the interpolation tween atom. The value of this atom is used only if there is also a kTweenOutputMax atom with the same parent. If this atom is not included and there is a kTweenOutputMax atom with the same parent, the tween component uses 0 as the minimum value when scaling output values of the interpolation tween track.

  • A kTweenOutputMax atom that specifies the maximum output value of the interpolation tween atom. If this atom is not included, the tween component does not scale the output values of the interpolation tween track.

• kTweenStartOffset

  For a tween atom in a tween track of a QuickTime movie, specifies a time offset from the start of the tween media sample to the start of the tween atom. The time units are the units used for the tween track.

  Its parent atom is a kTweenEntry atom.

  A kTweenEntry atom can contain only one kTweenStartOffset atom. The ID of this atom is always 1. The index of this atom is always 1.

  This atom is a leaf atom. The data type of its data is TimeValue.

  This atom is optional. If it is not included, the tween operation begins at the start of the tween media sample.

• kTweenDuration

  Specifies the duration of a tween operation. When a QuickTime movie includes a tween track, the time units for the duration are those of the tween track. If a tween component is used outside of a movie, the application using the tween data determines how the duration value and values returned by the component are interpreted.

  Its parent atom is a kTweenEntry atom.

  A kTweenEntry atom can contain only one kTweenDuration atom. The ID of this atom is always 1. The index of this atom is always 1.

  This atom is a leaf atom. The data type of its data is TimeValue.

  This atom is optional. If it is not included, the duration of the tween operation is the duration of the media sample that contains it.

• kTweenData

  Contains data for a tween atom.

  Its parent atom is a kTweenEntry atom.

  A kTweenEntry atom can contain any number of kTweenData atoms.

  The index of a kTweenData atom specifies when it was added to the kTweenEntry atom; the first added has the index 1, the second 2, and so on. The ID of a kTweenData atom can be any ID that is unique among the kTweenData atoms contained in the same kTweenEntry atom.

  At least one kTweenData atom is required in a kTweenEntry atom.

  For single tween atoms, a kTweenData atom is a leaf atom. It can contain data of any type.

  For polygon tween atoms, a kTweenData atom is a leaf atom. The data type of its data is Fixed[27], which specifies three polygons.

  For path tweens, a kTweenData atom is a leaf atom. The data type of its data is Handle, which contains a QuickTime vector.

  In interpolation tween atoms, a kTweenData atom is a leaf atom. It can contain data of any type. An interpolation tween atom can be any tween atoms other than a list tween atom that returns a time value.

  In list tween atoms, a kTweenData atom is a parent atom that must contain the following child atoms:

  • A kListElementType atom that specifies the atom type of the elements of the tween atom.

  • One or more leaf atoms of the type specified by the kListElementType atom. The data for each atom is the result of a list tween operation.

• kNameAtom

  Specifies the name of a tween atom. The name, which is optional, is not used by tween components, but it can be used by applications or other software.

  Its parent atom is a kTweenEntry atom.

  A kTweenEntry atom can contain only one kNameAtom atom. The ID of this atom is always 1. The index of this atom is always 1.

  This atom is a leaf atom. Its data type is String.

  This atom is optional. If it is not included, the tween atom does not have a name.

• kTweenType

  Specifies the tween type (the data type of the data for the tween operation).

  Its parent atom is a kTweenEntry atom.

  A kTweenEntry atom can contain only one kTweenType atom. The ID of this atom is always 1. The index of this atom is always 1.

  This atom is a leaf atom. The data type of its data is OSType.

  This atom is required.

Path Tween Atoms

• kTweenFlags

  Contains flags that control the tween operation. One flag that controls path tween atoms is defined:

  • The kTweenReturnDelta flag applies only to path tween atoms (tweens of type kTweenTypePathToFixedPoint, kTweenTypePathToMatrixTranslation, kTweenTypePathToMatrixTranslationAndRotation, kTweenTypePathXtoY, or kTweenTypePathYtoX). If the flag is set, the tween component returns the change in value from the last time it was invoked. If the flag is not set, or if the tween component has not previously been invoked, the tween component returns the normal result for the tween atom.

    Its parent atom is a kTweenEntry atom.

    A kTweenEntry atom can contain only one kTweenFlags atom. The ID of this atom is always 1. The index of this atom is always 1.

    This atom is a leaf atom. The data type of its data is Long.

    This atom is optional. If it is not included, no flags are set.

• kInitialRotationAtom

  Specifies an initial angle of rotation for a path tween atom of type kTweenTypePathToMatrixRotation, kTweenTypePathToMatrixTranslation, or kTweenTypePathToMatrixTranslationAndRotation.

  Its parent atom is a kTweenEntry atom.

  A kTweenEntry atom can contain only one kInitialRotationAtom atom. The ID of this atom is always 1. The index of this atom is always 1.

  This atom is a leaf atom. Its data type is Fixed.

  This atom is optional. If it is not included, no initial rotation of the tween atom is performed.

List Tween Atoms

• kListElementType

  Specifies the atom type of the elements in a list tween atom.

  Its parent atom is a kTweenData atom.

  A kTweenEntry atom can contain only one kListElementType atom. The ID of this atom is always 1. The index of this atom is always 1.

  This atom is a leaf atom. Its data type is QTAtomType.

  This atom is required in the kTweenData atom for a list tween atom.

3D Tween Atoms

• kTween3dInitialCondition

  Specifies an initial transform for a 3D tween atom whose tween type is one of the following: kTweenType3dCameraData, kTweenType3dMatrix, kTweenType3dQuaternion, kTweenType3dRotate, kTweenType3dRotateAboutAxis, kTweenType3dRotateAboutAxis, kTweenType3dRotateAboutPoint, kTweenType3dRotateAboutVector, kTweenType3dScale, or kTweenType3dTranslate.

  Its parent atom is a kTweenEntry atom.

  A kTweenEntry atom can contain only one kTween3dInitialCondition atom. The ID of this atom is always 1. The index of this atom is always 1.

  This atom is a leaf atom. The data type of its data is as follows:

  • For a kTweenType3dCameraData tween, its data type is TQ3CameraData.

  • For a kTweenType3dMatrix tween, its data type is TQ3Matrix4x4.

  • For a kTweenType3dQuaternion tween, its data type is TQ3Quaternion.

  • For a kTweenType3dRotate tween, its data type is TQ3RotateTransformData.

  • For a kTweenType3dRotateAboutAxis tween, its data type is TQ3RotateAboutAxisTransformData.

  • For a kTweenType3dRotateAboutPoint tween, its data type is TQ3RotateAboutPointTransformData.

  • For a kTweenType3dRotateAboutVector tween, its data type is TQ3PlaneEquation.

  • For a kTweenType3dScale tween, its data type is TQ3Vector3D.

  • For a kTweenType3dTranslate tween, its data type is TQ3Vector3D.

    This atom is optional. For each tween type, the default value is the data structure that specifies an identity transform, that is, a transform that does not alter the 3D data.

Interpolation Tween Atoms

• kTweenOutputMax

  Specifies the maximum output value of an interpolation tween atom. If a kTweenOutputMax atom is included for an interpolation tween, output values for the tween atom are scaled to be within the minimum and maximum values. The minimum value is either the value of the kTweenOutputMin atom or, if there is no kTweenOutputMin atom, 0. For example, if an interpolation tween atom has values between 0 and 4, and it has kTweenOutputMin and kTweenOutputMax atoms with values 1 and 2, respectively, a value of 0 (the minimum value before scaling) is scaled to 1 (the minimum specified by the kTweenOutputMin atom), a value of 4 (the maximum value before scaling) is scaled to 2 (the maximum specified by the kTweenOutputMax atom), and a value of 3 (three-quarters of the way between the maximum and minimum values before scaling) is scaled to 1.75 (three-quarters of the way between the values of the kTweenOutputMin and kTweenOutputMax atoms).

  Its parent atom is a kTweenEntry atom.

  A kTweenEntry atom can contain only one kTweenOutputMax atom. The ID of this atom is always 1. The index of this atom is always 1.

  This atom is a leaf atom. The data type of its data is Fixed.

  This atom is optional. If it is not included, QuickTime does not scale interpolation tween values.

• kTweenOutputMin

  Specifies the minimum output value of an interpolation tween atom. If both kTweenOutputMin and kTweenOutputMax atoms are included for an interpolation tween atom, output values for the tween atom are scaled to be within the minimum and maximum values. For example, if an interpolation tween atom has values between 0 and 4, and it has kTweenOutputMin and kTweenOutputMax atoms with values 1 and 2, respectively, a value of 0 (the minimum value before scaling) is scaled to 1 (the minimum specified by the kTweenOutputMin atom), a value of 4 (the maximum value before scaling) is scaled to 2 (the maximum specified by the kTweenOutputMax atom), and a value of 3 (three-quarters of the way between the maximum and minimum values before scaling) is scaled to 1.75 (three-quarters of the way between the values of the kTweenOutputMin and kTweenOutputMax atoms).

  If a kTweenOutputMin atom is included but a kTweenOutputMax atom is not, QuickTime does not scale interpolation tween values.

  Its parent atom is a kTweenEntry atom.

  A kTweenEntry atom can contain only one kTweenOutputMin atom. The ID of this atom is always 1. The index of this atom is always 1.

  This atom is a leaf atom. The data type of its data is Fixed.

  This atom is optional. If it is not included but a kTweenOutputMax atom is, the tween component uses 0 as the minimum value for scaling values of an interpolation tween atom.

• kTweenInterpolationID

  Specifies an interpolation tween atom to use for a specified kTweenData atom. There can be any number of kTweenInterpolationID atoms for a tween atom, one for each kTweenData atom to be interpolated.

  Its parent atom is a kTweenEntry atom.

  The index of a kTweenInterpolationID atom specifies when it was added to the kTweenEntry atom; the first added has the index 1, the second 2, and so on. The ID of a kTweenInterpolationID atom must match the atom ID of the kTweenData atom to be interpolated, and be unique among the kTweenInterpolationID atoms contained in the same kTweenEntry atom.

  This atom is a leaf atom. The data type of its data is QTAtomID.

  This atom is required for an interpolation tween atom.

Region Tween Atoms

• kTweenPictureData

  Contains the data for a QuickDraw picture. Used only by a kTweenTypeQDRegion atom.

  Its parent atom is a kTweenEntry atom.

  A kTweenEntry atom can contain only one kTweenPictureData or kTweenRegionData atom. The ID of this atom is always 1. The index of this atom is always 1.

  This atom is a leaf atom. The data type of its data is Picture.

  Either a kTweenPictureData or kTweenRegionData atom is required for a kTweenTypeQDRegion atom.

• kTweenRegionData

  Contains the data for a QuickDraw region. Used only by a kTweenTypeQDRegion atom.

  Its parent atom is a kTweenEntry atom.

  A kTweenEntry atom can contain only one kTweenRegionData or kTweenPictureData atom. The ID of this atom is always 1. The index of this atom is always 1.

  This atom is a leaf atom. The data type of its data is Region.

  Either a kTweenPictureData or kTweenRegionData atom is required for a kTweenTypeQDRegion tween.

Sequence Tween Atoms

• kTweenSequenceElement

  Specifies an entry in a tween sequence.

  Its parent is the tween QT atom container (which you specify with the constant kParentAtomIsContainer).

  The ID of a kTweenSequenceElement atom must be unique among the kTweenSequenceElement atoms in the same QT atom container. The index of a kTweenSequenceElement atom specifies its order in the sequence; the first entry in the sequence has the index 1, the second 2, and so on.

  This atom is a leaf atom. The data type of its data is TweenSequenceEntryRecord, a data structure that contains the following fields:

endPercent

A value of type Fixed that specifies the point in the duration of the tween media sample at which the sequence entry ends. This is expressed as a percentage; for example, if the value is 75.0, the sequence entry ends after three-quarters of the total duration of the tween media sample have elapsed. The sequence entry begins after the end of the previous sequence entry or, for the first entry in the sequence, at the beginning of the tween media sample.

tweenAtomID

A value of type QTAtomID that specifies the kTweenEntry atom containing the tween for the sequence element. The kTweenEntry atom and the kTweenSequenceElement atom must both be a child atoms of the same tween QT atom container.

dataAtomID

A value of type QTAtomID that specifies the kTweenData atom containing the data for the tween. This atom must be a child atom of the atom specified by the tweenAtomID field.

---