General Tween Atoms

The kTweenEntry atom specifies a tween that can be either a single tween, a tween in a tween sequence, or an interpolation tween. 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. 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 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 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 this 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.

If a kTweenEntry atom specifies an interpolation tween, it must contain the following child atom(s):

• 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 to use for the kTweenData atom.

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

• A kTweenOutputMin atom that specifies the minimum output value of the interpolation tween. 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.

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

• A kTweenStartOffset atom. For a tween in a tween track of a QuickTime movie, this atom specifies a time offset from the start of the tween media sample to the start of the tween. 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.

The kTweenDuration atom 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 is the duration of the media sample that contains it.

The kTweenData atom contains data for a tween. Its parent atom is a kTweenEntry atom.

A kTweenEntry atom can contain any number of kTweenData atoms. 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 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 would contain three kTweenData atoms, one for each data set. The application would specify the desired data set by specifying the ID of the kTweenData atom to use.

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 tweens, a kTweenData atom is a leaf atom. It can contain data of any type.

For polygon tweens, a kTweenData atom is a leaf atom. The data type of its data is Fixed[27], which specifies three polygons as described in Using Path Tween Components.

For path tweens, a kTweenData atom is a leaf atom. The data type of its data is Handle, which contains a QuickTime vector as described in Using Path Tween Components.

In interpolation tweens, a kTweenData atom is a leaf atom. It can contain data of any type. An interpolation tween can be any tween other than a list tween that returns a time value, as described in Interpolation Tweens.

In list tweens, 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 iof the tween.

• 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, as described in Using a List Tween Component.

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

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 StringPtr.

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

The kTweenType atom 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

The kTweenFlags atom contains flags that control the tween operation. Its parent atom is a kTweenEntry atom. One flag that controls path tweens is defined: the kTweenReturnDelta flag. It applies only to path tweens (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.

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.

The kInitialRotationAtom atom specifies an initial angle of rotation for a path tween 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 is performed.

List Tween Atoms

The kListElementType atom specifies the atom type of the elements in a list tween. 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.

Interpolation Tween Atoms

The kTweenOutputMax atom specifies the maximum output value of an interpolation tween. Its parent atom is a kTweenEntry atom.

If a kTweenOutputMax atom is included for an interpolation tween, output values for the tween 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 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).

A kTweenEntry atom can contain only on e 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.

The kTweenOutputMin atom specifies the minimum output value of an interpolation tween. Its parent atom is a kTweenEntry atom.

If both kTweenOutputMin and kTweenOutputMax atoms are included for an interpolation tween, output values for the tween are scaled to be within the minimum and maximum values. For example, if an interpolation tween 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.

A kTweenEntry atom can contain only on e 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.

The kTweenInterpolationID atom specifies an interpolation tween to use for a specified kTweenData atom. Its parent atom is a kTweenEntry atom. There can be any number of kTweenInterpolationID atoms for a tween, one for each kTweenData atom to be interpolated.

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 (1) match the atom ID of the kTweenData atom to be interpolated, and (2) 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.

Sequence Tween Atoms

The kTweenSequenceElement atom specifies an entry in a tween sequence. Its parent is the tween QT atom container (which you specify with the constant kParentAtomIsContainerTween Components and Tween Media).

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.

kTweenTypeFixed

Input data: Two 32-bit fixed-point values.

Output data: A 32-bit fixed-point value.

kTweenTypeFixedPoint

Input data: Two structures of type FixedPoint that describe QuickDraw points.

Output data: A structure of type FixedPoint that describes a QuickDraw point.

How interpolation is performed: Each of the two coordinate values used to specify a fixed point is interpolated separately from the other.

kTweenTypeGraphicsModeWithRGBColor

Input data: Two ModifierTrackGraphicsModeRecord data structures.

Output data: A ModifierTrackGraphicsModeRecord data structure.

How interpolation is performed: Only the RGBColor fields of the ModifierTrackGraphicsModeRecord data structures are interpolated. The graphic mode used is the first graphic mode that is specified in the modifier track.

kTweenTypeLong

Input data: Two signed 32-bit integers.

Output data: A signed 32-bit integer.

kTweenTypeMatrix

Input data: Two QuickTime 3X3 matrices (data structures of type MatrixRecord).

Output data: A QuickTime 3X3 matrix (a data structure of type MatrixRecord).

How interpolation is performed: Each of the individual matrix elements is interpolated separately from the other.

kTweenTypePoint

Input data: Two QuickDraw points (data structures of type Point.

Output data: A QuickDraw point (a data structure of type Point).

How interpolation is performed: Each of the two coordinate values used to specify a QuickDraw point (h and v ) is interpolated separately from the other.

kTweenTypeQTFloatDouble

Input data: Two double-precision (64-bit) IEEE floating-point numbers of type double.

Output data: A double-precision (64-bit) IEEE floating-point number of type double.

kTweenTypeQTFloatSingle

Input data: Two single-precision floating-point numbers of type float.

Output data: A single-precision floating-point number of type float.

kTweenTypeRGBColor

Input data: Two RGB colors (data structures of type RGBColor).

Output data: An RGB color (a data structure of type RGBColor).

How interpolation is performed: Each of the three values used to specify an RGB color (red, green, blue ) is interpolated separately from the others.

kTweenTypeShort

Input data: Two signed 16-bit integers.

Output data: A signed 16-bit integer.

List Tweener Components

A component of type kTweenTypeAtomList is the component that processes list tweens. For an introduction to list tweens, see Using a List Tween Component.

Input data: A QT atom list. This is a kTweenData atom that contains

• a kListElementType atom that specifies the atom type of the elements and the output

• one or more leaf atoms, ordered by their index values, of the type specified by the kListElementType atom

• atoms of other types, which are optional and ignored by the component; these optional atoms can be used by an application, such as atoms that specify a name for each element.

Output data: The data for one of the list element atoms. How this atom is determined is described in Using a List Tween Component.

How interpolation is performed: The duration of the tween is divided by the number of elements in the list. At the time point for which a result is to be returned, the component determines the list element for which to return data. If (0 <= time value <= (1 * (tween duration / number of list elements)), the component returns the data for the first list element; if ((1 * (tween duration / number of list elements < time value <= (2 * (tween duration / number of list elements)), the component returns the data for the second list element, and so on. For example, if the tween duration is 100 and there are 10 elements in the list, the component returns the value of the first element for a time from 0 to 10, the value of the second element is returned for a time greater than 10 and less than or equal to 20, and so on. The total time for the tween is divided equally among the list elements.

The kTweenTypeAtomList container description is the following:

[(QTAtomListTweenEntryAtoms)] =

    kListElementType, 1, 1

    // a QTAtomType specifying the type of atoms that make up the list

    kListElementDataType, 1, 1

    // a UInt32 that contains one of the allowed kTweenType flags.

    // kTweenTypeShort through kTweenTypeFixedPoint are allowed]

    kTweenData, 1, 1

        kTweenType, 1, 1

        // QTAtomType for elements in list, for example 'pcid'

        'pcid', anyUniqueID, 1

            [data for first element]

        'pcid', anyUniqueID, 2

        // data for second element

        ...

        'pcid', anyUniqueID, n

        // data for nth element

<kTweenStartOffset>, 1, 1

[TimeValue] = starting offset

<kTweenDuration>, 1, 1

[TimeValue] = duration

<kTweenOutputMinValue>, 1, 1

[Fixed] = minimum output value

<kTweenOutputMaxValue>, 1, 1

[Fixed] = maximum output value

<kTweenSequenceElement>, (anyUniqueIDs), (1..numElementsInSequence)

[TweenSequenceEntryRecord]

<kTweenInterpolationID>, (a kTweenData ID), (1.. numInterpolationIDAtoms)

[QTAtomID] = the id of a kTweenEntry (child of [(TweenContainerFormat)]

       describing the tween to be used to interpolate time values).

Multimatrix Tweener Component

The multimatrix tweener, of type kTweenTypeMultiMatrix, returns a MatrixRecord that is a concatenation of several matrix tweeners. This record can be applied to a sprite or track.

An example of using the multimatrix tweener would be to make a sprite follow a path using the path tweener and at the same time apply a distortion effect using the polygon tweener.

Input data: A list of kTweenEntry atoms.

Output data: a matrix record

How interpolation is performed: The data for the tweener consists of a list of kTweenEntry atoms, each containing [(QTAtomListEntryAtomsTween Components and Tween Media)] for any type of tweener that returns a matrix. The order of matrix concatenation is important; the matrices are applied in the order determined by index of the kTweenEntry child atoms of the multimatrix tweener’s data atom.

Path Tweener Components

A path tweener component returns a point along a path depending on the current time value. The point is either returned as a FixedPoint value or a MatrixRecord with x and y offsets corresponding to the point. There are six component subtypes:

• Subtype kTweenTypePathToFixedPoint returns a tweenResult of type FixedPoint.

• Subtype kTweenTypePathToMatrixTranslation returns a tweenResult of type MatrixRecord and performs translation tweening.

• Subtype kTweenTypePathToMatrixRotation returns a tweenResult of type MatrixRecord and performs rotation tweening.

• Subtype kTweenTypePathToMatrixTranslationAndRotation returns a tweenResult of type MatrixRecord and performs both translation and rotation tweening.

• Subtype kTweenTypePathXtoY returns a tweenResult of type FixedPoint that specifies the y-coordinate value for a given x-coordinate value.

• Subtype kTweenTypePathYtoX returns a tweenResult of type FixedPoint that specifies the x-coordinate value for a given y-coordinate value.

An example of using a path tweener would be to store a path that you want a sprite to follow. The MatrixRecord returned could be used to determine the offset of the sprite.

The path tweener’s path format is the one used by the QuickTime vector codec. A transcoder exists that converts a QuickDraw GX shape into this format.

This component uses only the first contour of the first path in the vector data when determining the output. It ignores any additional atoms and paths in the vector data.

Polygon Tweener Component

A component of type kTweenTypePolygon tweens one polygon into another. All input polygons must be convex and not self-intersecting.

Input data: An array of 27 fixed-point values (Fixed[27]Tween Components and Tween Media) that specifies three four-sided polygons. Each polygon is specified by 9 consecutive array elements. The first element in each set of 9 contains the number of points used to specify the polygon; this value is coerced to a long integer, and it must always be 4 after coercion. The following 8 values in each set of nine are four x, y pairs that specify the corners of the polygon.

The first set of 9 elements specifies the dimensions of a sprite or track to be mapped. For example, if the object is a sprite, the four points are (0,0), (spriteWidth, 0), (spriteWidth, spriteHeight), (0, spriteHeight). The next set of 9 elements specifies the initial polygon into which the sprite or track is mapped. The next set of 9 elements specifies the ending polygon into which the sprite or track is mapped.

Output data: A MatrixRecord structure that can be used to map the sprite or track into a four-sided polygon. During the duration of the tween, the shape of this polygon is transformed linearly from that of the initial polygon specified in the input data to that of the ending polygon specified in the input data.

Spin Tweener Component

A component of type kTweenTypeSpin returns a MatrixRecord that can be applied to a sprite or a track. The matrix returned causes a rotation based on a given number of rotations over the duration of the tween. The data for the tweener consists of an array of two Fixed numbers. The first Fixed number is the intialRotation value, specified as a fraction of one rotation. A number between 0 and 1 is expected; for instance, a value of 0.25 represents a rotation of 90 degrees. The second Fixed number is the number of rotations that should occur over the durationof the tween. For instance, to spin a sprite four and a half times this number should be 4.5.

The spin tweener container description is the following:

[SpinTweenEntryAtoms)] =

    kTweenType, 1, 1

        [kTweenTypeSpin]

    kTweenData, 1, 1

        Fixed[2]

<kTweenStartOffset>, 1, 1

[TimeValue] = starting offset

<kTweenDuration>, 1, 1

[TimeValue] = duration

<kTweenSequenceElement>, (anyUniqueIDs), (1..numElementsInSequence)

[TweenSequenceEntryRecord]

<kTweenInterpolationID>, (a kTweenData ID), (1.. numInterpolationIDAtoms)

[QTAtomID] = the id of a kTweenEntry (child of [(TweenContainerFormat)]

              describing the tween to be used to interpolate time values).

Tween Component Constant

The TweenComponentType constant specifies that the component is a tween component.

enum {

    TweenComponentType  = 'twen'

};

Tween Type and Tween Component Subtype Constants

The following constants specify tween types. If a tween type is identified by a four-character code, the four-character code is also the component subtype of the tween component that is invoked for the tween. If a tween type is identified by a numeric constant, such as kTweenTypeShort, tweens of that type are processed by QuickTime rather than by a tween component.

enum {

    kTweenTypeShort = 1,

    kTweenTypeLong = 2,

    kTweenTypeFixed = 3,

    kTweenTypePoint = 4,

    kTweenTypeQDRect = 5,

    kTweenTypeQDRegion = 6,

    kTweenTypeMatrix = 7,

    kTweenTypeRGBColor = 8,

    kTweenTypeGraphicsModeWithRGBColor = 9,

    kTweenTypeQTFloatSingle = 10,

    kTweenTypeQTFloatDouble = 11,

    kTweenTypeFixedPoint = 12,

    kTweenType3dScale = FOUR_CHAR_CODE('3sca'),

    kTweenType3dTranslate = FOUR_CHAR_CODE('3tra'),

    kTweenType3dRotate = FOUR_CHAR_CODE('3rot'),

    kTweenType3dRotateAboutPoint = FOUR_CHAR_CODE('3rap'),

    kTweenType3dRotateAboutAxis = FOUR_CHAR_CODE('3rax'),

    kTweenType3dRotateAboutVector = FOUR_CHAR_CODE('3rvc'),

    kTweenType3dQuaternion = FOUR_CHAR_CODE('3qua'),

    kTweenType3dMatrix = FOUR_CHAR_CODE('3mat'),

    kTweenType3dCameraData = FOUR_CHAR_CODE('3cam'),

    kTweenType3dSoundLocalizationData = FOUR_CHAR_CODE('3slc'),

    kTweenTypePathToMatrixTranslation = FOUR_CHAR_CODE('gxmt'),

    kTweenTypePathToMatrixTranslationAndRotation =FOUR_CHAR_CODE('gxmr'),

    kTweenTypePathToFixedPoint = FOUR_CHAR_CODE('gxfp'),

    kTweenTypePathXtoY = FOUR_CHAR_CODE('gxxy'),

    kTweenTypePathYtoX = FOUR_CHAR_CODE('gxyx'),

    kTweenTypeAtomList = FOUR_CHAR_CODE('atom'),

    kTweenTypePolygon = FOUR_CHAR_CODE('poly')

    kTweenTypePathToMatrixRotation = FOUR_CHAR_CODE('gxpr'),

    kTweenTypeMultiMatrix = FOUR_CHAR_CODE('mulm'),

    kTweenTypeSpin = FOUR_CHAR_CODE('spin'),

    kTweenType3dMatrixNonLinear = FOUR_CHAR_CODE('3nlr'),

    kTweenType3dVRObject = FOUR_CHAR_CODE('3vro')

    };

Tween Atom Constants

The following constants are defined for tween-related atoms. These atom types are described in Tween QT Atom Container.

enum {

    kTweenEntry                 = FOUR_CHAR_CODE('twen'),

    kTweenData                  = FOUR_CHAR_CODE('data'),

    kTweenType                  = FOUR_CHAR_CODE('twnt'),

    kTweenStartOffset           = FOUR_CHAR_CODE('twst'),

    kTweenDuration              = FOUR_CHAR_CODE('twdu'),

    kTweenFlags                 = FOUR_CHAR_CODE('flag'),

    kTweenOutputMin             = FOUR_CHAR_CODE('omin'),

    kTweenOutputMax             = FOUR_CHAR_CODE('omax'),

    kTweenSequenceElement       = FOUR_CHAR_CODE('seqe'),

    kTween3dInitialCondition    = FOUR_CHAR_CODE('icnd'),

    kTweenInterpolationID       = FOUR_CHAR_CODE('intr'),

    kTweenRegionData            = FOUR_CHAR_CODE('qdrg'),

    kTweenPictureData           = FOUR_CHAR_CODE('PICT'),

    kListElementType            = FOUR_CHAR_CODE('type'),

    kNameAtom                   = FOUR_CHAR_CODE('name'),

    kInitialRotationAtom        = FOUR_CHAR_CODE('inro')

};

Tween Flag

The following flag modifies the characteristics of a tween.

enum {

    kTweenReturnDelta= 1L << 0

};

The kTweenReturnDelta flag applies only to path tweens (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.

Tween Sequence Entry Record

A tween sequence entry record specifies when a tween in a tween sequence ends. Each tween in a tween sequence begins after the previous tween ends or, for the first tween in the sequence, at the beginning of the tween duration.

Because there can be more than one data set for a tween, the data structure includes a field for the data atom ID as well as the tween atom ID.

struct TweenSequenceEntryRecord {

    Fixed                   endPercent;

    QTAtomID                tweenAtomID;

    QTAtomID                dataAtomID;

};

typedef struct TweenSequenceEntryRecord TweenSequenceEntryRecord;

Component Instance

The component instance for a tween component, TweenerComponent, identifies an application’s use of a component.

typedef ComponentInstance TweenerComponent;

Tween Record

QuickTime maintains a tween record structure that is provided to your tween component’s TweenDoTween method. The TweenRecord structure is defined as follows.

typedef struct TweenRecord TweenRecord;

struct TweenRecord {

    long                    version;

    QTAtomContainer         container;

    QTAtom                  tweenAtom;

    QTAtom                  dataAtom;

    Fixed                   percent;

    TweenerDataUPP          dataProc;

    void *                  private1;

    void *                  private2;

};

Value Setting Function

The function that you call to send the interpolated value to the receiving track is defined as a universal procedure in systems that support the Macintosh Code Fragment Manager (CFM) or is defined as a data procedure for non-CFM systems:

typedef UniversalProcPtr TweenerDataUPP;    /* CFM */

typedef TweenerDataProcPtr TweenerDataUPP;  /* non-CFM */

The TweenerDataUPP function pointer specifies the function the tween component calls with the value generated by the tween operation. A tween component calls this function from its implementation of the TweenerDoTween function.

typedef pascal ComponentResult (*TweenerDataProcPtr)(

                     TweenRecord *tr,

                     void *tweenData,

                     long tweenDataSize,

                     long dataDescriptionSeed,

                     Handle dataDescription,

                     ICMCompletionProcRecordPtr asyncCompletionProc,

                     ProcPtr transferProc,

                     void *refCon);

You call this function by invoking the function specified in the tween record’s dataProc field. The following errors are returned: