Next Previous

Retired Document

Important: Apple recommends that developers explore QTKit and Core Video for new development in this technology area. See QTKit Framework Reference and Core Video Programming Guide for more information.

QTVR Atom Containers

This chapter describes in detail the VR world and node information atom containers. These two atom containers can be obtained by calling the QuickTime VR Manager routines QTVRGetVRWorld and QTVRGetNodeInfo. Those routines are described in this chapter.

If you are unfamiliar with QuickTime atoms and atom containers, you should read the QuickTime File Format specification (see bibliography). The specification describes in detail how QuickTime uses QT atom and atom containers, which are tree-structured hierarchies of QT atoms, to provide a basic structure for storing information in QuickTime.

You need to know about the various atoms contained in the VR world and node information atom containers if you want to extract information from a QuickTime VR file that cannot be obtained using VR Manager functions. For instance, there is no QuickTime VR Manager function that returns the name of a given node; however, you can easily get a node’s name by reading the information in the atoms in the atom container returned by the QTVRGetNodeInfo function.

This chapter is divided into the following major sections:

Overview of Atom Containers describes the QuickTime atom container, a tree structured hierarchy of QT atoms used for storing information in QuickTime files.
Getting the Name of a Node discusses how you can use standard QuickTime atom container functions to retrieve the information in a node header atom.
Adding Custom Atoms in a QuickTime VR Movie describes how you can add custom atoms to either the VR world or node information atom containers.
Required Atoms for Wired Actions discusses what atoms must be included in the QuickTime VR file to support wired actions.

Overview of Atom Containers

A QuickTime atom container is a basic structure for storing information in QuickTime files. An atom container is a tree structured hierarchy of QT atoms. By definition, only the leaf atoms in the hierarchy contain data. Intermediate atoms serve as parent atoms that contain any number of child atoms, which may in turn be either leaf atoms or more parent atoms. Each parent’s child atom is uniquely identified by its atom type and atom ID. The atom container itself is considered the parent of the highest level atoms.

Many atom types contained in the VR world and node information atom containers are unique within their container. For example, each has a single header atom. Most of the parent atoms within an atom container are unique as well, such as the node parent atom in the VR world atom container or the hot spot parent atom in the node information atom container. For these one time only atoms, the atom ID is always set to 1. Unless otherwise mentioned in the descriptions of the atoms that follow, assume that the atom ID is 1.

Many of the atom structures contain two version fields, majorVersion and minorVersion. The values of these fields correspond to the constants kQTVRMajorVersion and kQTVRMinorVersion found in the header file QuickTimeVRFormat.h. For QuickTime 2.0 files, these values are 2 and 0.

QuickTime provides many routines for creating and accessing atom containers. Those are described in the QuickTime API Reference.

The String Atom and the String Encoding Atom

Some of the leaf atoms within the VR world and node information atom containers contain fields that specify the ID of string atoms that are siblings of the leaf atom. For example, the VR world header atom contains a field for the name of the scene. The string atom is a leaf atom whose atom type is kQTVRStringAtomType ('vrsg'). Its atom ID is that specified by the referring leaf atom.

A string atom contains a string. The structure of a string atom is defined by the QTVRStringAtom data type:

typedef struct QTVRStringAtom {

    UInt16                              stringUsage;

    UInt16                              stringLength;

    unsigned char                       theString[4];

} QTVRStringAtom, *QTVRStringAtomPtr;

stringUsage: The string usage. This field is unused.
stringLength: The length, in bytes, of the string.
theString: The string. The string atom structure is extended to hold this string.

Each string atom may also have a sibling leaf atom called the string encoding atom. The string encoding atom’s atom type is kQTVRStringEncodingAtomType ('vrse'). Its atom ID is the same as that of the corresponding string atom. The string encoding atom contains a single variable, TextEncoding, a UInt32, as defined in the header file TextCommon.h. The value of TextEncoding is handed, along with the string, to the routine QTTextToNativeText for conversion for display on the current machine. The routine QTTextToNativeText is found in the header file Movies.h.

VR World Atom Container

The VR world atom container (VR world for short) includes such information as the name for the entire scene, the default node ID, and default imaging properties, as well as a list of the nodes contained in the QTVR track.

A VR world can also contain custom scene information. QuickTime VR ignores any atom types that it doesn’t recognize, but you can extract those atoms from the VR world using standard QuickTime atom functions.

The structure of the VR world atom container is shown in Figure 7-1. The component atoms are defined and their structures are shown in the sections that follow.

VR World Header Atom Structure

The VR world header atom is a leaf atom. Its atom type is kQTVRWorldHeaderAtomType ('vrsc'). It contains the name of the scene and the default node ID to be used when the file is first opened as well as fields reserved for future use.

The structure of a VR world header atom is defined by the QTVRWorldHeaderAtom data type:

typedef struct QTVRWorldHeaderAtom {

    UInt16                              majorVersion;

    UInt16                              minorVersion;

    QTAtomID                            nameAtomID;

    UInt32                              defaultNodeID;

    UInt32                              vrWorldFlags;

    UInt32                              reserved1;

    UInt32                              reserved2;

} QTVRWorldHeaderAtom, *QTVRWorldHeaderAtomPtr;

majorVersion: The major version number of the file format.
minorVersion: The minor version number of the file format.
nameAtomID: The ID of the string atom that contains the name of the scene. That atom should be a sibling of the VR world header atom. The value of this field is 0 if no name string atom exists.
defaultNodeID: The ID of the default node (that is, the node to be displayed when the file is first opened).
vrWorldFlags: A set of flags for the VR world. This field is unused.
reserved1: Reserved. This field must be 0.
reserved2: Reserved. This field must be 0.

Imaging Parent Atom

The imaging parent atom is the parent atom of one or more node-specific imaging atoms. Its atom type is kQTVRImagingParentAtomType ('imgp'). Only panoramas have an imaging atom defined.

Panorama-Imaging Atom

A panorama-imaging atom describes the default imaging characteristics for all the panoramic nodes in a scene. This atom overrides QuickTime VR’s own defaults.

The panorama-imaging atom has an atom type of kQTVRPanoImagingAtomType ('impn'). Generally, there is one panorama-imaging atom for each imaging mode, so the atom ID, while it must be unique for each atom, is ignored. QuickTime VR iterates through all the panorama-imaging atoms.

The structure of a panorama-imaging atom is defined by the QTVRPanoImagingAtom data type:

typedef struct QTVRPanoImagingAtom {

    UInt16                              majorVersion;

    UInt16                              minorVersion;

    UInt32                              imagingMode;

    UInt32                              imagingValidFlags;

    UInt32                              correction;

    UInt32                              quality;

    UInt32                              directDraw;

    UInt32                              imagingProperties[6];

    UInt32                              reserved1;

    UInt32                              reserved2;

} QTVRPanoImagingAtom, *VRPanoImagingAtomPtr;

majorVersion: The major version number of the file format.
minorVersion: The minor version number of the file format.
imagingMode: The imaging mode to which the default values apply. Only kQTVRStatic and kQTVRMotion are allowed here.
imagingValidFlags: A set of flags that indicate which imaging property fields in this structure are valid.
correction: The default correction mode for panoramic nodes. This can be either kQTVRNoCorrection, kQTVRPartialCorrection, or kQTVRFullCorrection.
quality: The default imaging quality for panoramic nodes.
directDraw: The default direct-drawing property for panoramic nodes. This can be true or false.
imagingProperties: Reserved for future panorama-imaging properties.
reserved1: Reserved. This field must be 0.
reserved2: Reserved. This field must be 0.

The imagingValidFlags field in the panorama-imaging atom structure specifies which imaging property fields in that structure are valid. You can use these bit flags to specify a value for that field:

enum {

    kQTVRValidCorrection                        = 1 << 0,

    kQTVRValidQuality                           = 1 << 1,

    kQTVRValidDirectDraw                        = 1 << 2,

    kQTVRValidFirstExtraProperty                = 1 << 3

};

kQTVRValidCorrection: If this bit is set, the field holds a default correction mode.
kQTVRValidQuality: If this bit is set, the field holds a default imaging quality.
kQTVRValidDirectDraw: If this bit is set, the field holds a default direct-drawing property.
kQTVRValidFirstExtraProperty: If this bit is set, the first element in the array in the field holds a default imaging property. As new imaging properties are added, they will be stored in this array.

Node Parent Atom

The node parent atom is the parent of one or more node ID atoms. The atom type of the node parent atom is kQTVRNodeParentAtomType ('vrnp') and the atom type of the each node ID atom is kQTVRNodeIDAtomType ('vrni').

There is one node ID atom for each node in the file. The atom ID of the node ID atom is the node ID of the node. The node ID atom is the parent of the node location atom. The node location atom is the only child atom defined for the node ID atom. Its atom type is kQTVRNodeLocationAtomType ('nloc').

Node Location Atom Structure

The node location atom is the only child atom defined for the node ID atom. Its atom type is kQTVRNodeLocationAtomType ('nloc'). A node location atom describes the type of a node and its location.

The structure of a node location atom is defined by the QTVRNodeLocationAtom data type:

typedef struct QTVRNodeLocationAtom {

    UInt16                              majorVersion;

    UInt16                              minorVersion;

    OSType                              nodeType;

    UInt32                              locationFlags;

    UInt32                              locationData;

    UInt32                              reserved1;

    UInt32                              reserved2;

} QTVRNodeLocationAtom, *QTVRNodeLocationAtomPtr;

majorVersion: The major version number of the file format.
minorVersion: The minor version number of the file format.
nodeType: The node type. This field should contain either kQTVRPanoramaType or kQTVRObjectType.
locationFlags: The location flags. This field must contain the value kQTVRSameFile, indicating that the node is to be found in the current file. In future, these flags may indicate that the node is in a different file or at some URL location.
locationData: The location of the node data. When the locationFlags field is kQTVRSameFile, this field should be 0. The nodes are found in the file in the same order that they are found in the node list.
reserved1: Reserved. This field must be 0.
reserved2: Reserved. This field must be 0.

Custom Cursor Atoms

The hot spot information atom, discussed in Hot Spot Information Atom, allows you to indicate custom cursor IDs for particular hot spots that replace the default cursors used by QuickTime VR. QuickTime VR allows you to store your custom cursors in the VR world of the movie file.

The cursor parent atom is the parent of all of the custom cursor atoms stored in the VR world. Its atom type is kQTVRCursorParentAtomType ('vrcp'). The child atoms of the cursor parent are either cursor atoms or color cursor atoms. Their atom types are kQTVRCursorAtomType ('CURS') and kQTVRColorCursorAtomType ('crsr'). These atoms are stored exactly as cursors or color cursors would be stored as a resource.

Node Information Atom Container

The node information atom container includes general information about the node such as the node’s type, ID, and name. The node information atom container also contains the list of hot spot atoms for the node. A QuickTime VR movie contains one node information atom container for each node in the file. The routine QTVRGetNodeInfo allows you to obtain the node information atom container for the current node or for any other node in the movie.

Figure 7-2 shows the structure of the node information atom container.

Node Header Atom Structure

A node header atom is a leaf atom that describes the type and ID of a node, as well as other information about the node. Its atom type is kQTVRNodeHeaderAtomType ('ndhd').

The structure of a node header atom is defined by the QTVRNodeHeaderAtom data type:

typedef struct QTVRNodeHeaderAtom {

    UInt16                              majorVersion;

    UInt16                              minorVersion;

    OSType                              nodeType;

    QTAtomID                            nodeID;

    QTAtomID                            nameAtomID;

    QTAtomID                            commentAtomID;

    UInt32                              reserved1;

    UInt32                              reserved2;

} QTVRNodeHeaderAtom, *VRNodeHeaderAtomPtr;

majorVersion: The major version number of the file format.
minorVersion: The minor version number of the file format.
nodeType: The node type. This field should contain either kQTVRPanoramaType or kQTVRObjectType.
nodeID: The node ID.
nameAtomID: The ID of the string atom that contains the name of the node. This atom should be a sibling of the node header atom. The value of this field is 0 if no name string atom exists.
commentAtomID: The ID of the string atom that contains a comment for the node. This atom should be a sibling of the node header atom. The value of this field is 0 if no comment string atom exists.
reserved1: Reserved. This field must be 0.
reserved2: Reserved. This field must be 0.

Hot Spot Parent Atom

The hot spot parent atom is the parent for all hot spot atoms for the node. The atom type of the hot spot parent atom is kQTVRHotSpotParentAtomType ('hspa') and the atom type of the each hot spot atom is kQTVRHotSpotAtomType ('hots'). Note that the atom ID of each hot spot atom is not the hot spot ID for the corresponding hot spot. The hot spot ID is determined by its color index value as it is stored in the hot spot image track.

The hot spot track is an 8-bit video track which contains color information that indicates hot spots.

Each hot spot atom is the parent of a number of atoms that contain information about each hot spot.

Hot Spot Information Atom

The hot spot information atom contains general information about a hot spot. Its atom type is kQTVRHotSpotInfoAtomType ('hsin'). Every hot spot atom should have a hot spot information atom as a child.

The structure of a hot spot information atom is defined by the QTVRHotSpotInfoAtom data type:

typedef struct QTVRHotSpotInfoAtom {

    UInt16                              majorVersion;

    UInt16                              minorVersion;

    OSType                              hotSpotType;

    QTAtomID                            nameAtomID;

    QTAtomID                            commentAtomID;

    SInt32                              cursorID[3];

    Float32                             bestPan;

    Float32                             bestTilt;

    Float32                             bestFOV;

    FloatPoint                          bestViewCenter;

    Rect                                hotSpotRect;

    UInt32                              flags;

    UInt32                              reserved1;

    UInt32                              reserved2;

} QTVRHotSpotInfoAtom, *QTVRHotSpotInfoAtomPtr;

majorVersion: The major version number of the file format.
minorVersion: The minor version number of the file format.
hotSpotType: The hot spot type. This type specifies which other information atoms—if any—are siblings to this one. QuickTime VR recognizes three types: kQTVRHotSpotLinkType, kQTVRHotSpotURLType, and kQTVRHotSpotUndefinedType.
nameAtomID: The ID of the string atom that contains the name of the hot spot. This atom should be a sibling of the hot spot information atom. This string is displayed in the QuickTime VR control bar when the mouse is moved over the hot spot.
commentAtomID: The ID of the string atom that contains a comment for the hot spot. This atom should be a sibling of the hot spot information atom. The value of this field is 0 if no comment string atom exists.
cursorID: An array of three IDs for custom hot spot cursors (that is, cursors that override the default hot spot cursors provided by QuickTime VR). The first ID (cursorID[0]) specifies the cursor that is displayed when it is in the hot spot. The second ID (cursorID[1]) specifies the cursor that is displayed when it is in the hot spot and the mouse button is down. The third ID (cursorID[2]) specifies the cursor that is displayed when it is in the hot spot and the mouse button is released. To retain the default cursor for any of these operations, set the corresponding cursor ID to 0. Custom cursors should be stored in the VR world atom container, as described in VR World Atom Container.
bestPan: The best pan angle for viewing this hot spot.
bestTilt: The best tilt angle for viewing this hot spot.
bestFOV: The best field of view for viewing this hot spot.
bestViewCenter: The best view center for viewing this hot spot; applies only to object nodes.
hotSpotRect: The boundary box for this hot spot, specified as the number of pixels in full panoramic space. This field is valid only for panoramic nodes.
flags: A set of hot spot flags. This field is unused.
reserved1: Reserved. This field must be 0.
reserved2: Reserved. This field must be 0.

Specific Information Atoms

Depending on the value of the hotSpotType field in the hot spot info atom there may also be a type specific information atom. The atom type of the type-specific atom is the hot spot type.

Link Hot Spot Atom

The link hot spot atom specifies information for hot spots of type kQTVRHotSpotLinkType ('link'). Its atom type is thus 'link'. The link hot spot atom contains specific information about a link hot spot.

The structure of a link hot spot atom is defined by the QTVRLinkHotSpotAtom data type:

typedef struct VRLinkHotSpotAtom {

    UInt16                              majorVersion;

    UInt16                              minorVersion;

    UInt32                              toNodeID;

    UInt32                              fromValidFlags;

    Float32                             fromPan;

    Float32                             fromTilt;

    Float32                             fromFOV;

    FloatPoint                          fromViewCenter;

    UInt32                              toValidFlags;

    Float32                             toPan;

    Float32                             toTilt;

    Float32                             toFOV;

    FloatPoint                          toViewCenter;

    Float32                             distance;

    UInt32                              flags;

    UInt32                              reserved1;

    UInt32                              reserved2;

} QTVRLinkHotSpotAtom, *VRLinkHotSpotAtomPtr;

majorVersion: The major version number of the file format.
minorVersion: The minor version number of the file format.
toNodeID: The ID of the destination node (that is, the node to which this hot spot is linked).
fromValidFlags: A set of flags that indicate which source node view settings are valid.
fromPan: The preferred from-pan angle at the source node (that is, the node containing the hot spot).
fromTilt: The preferred from-tilt angle at the source node.
fromFOV: The preferred from-field of view at the source node.
fromViewCenter: The preferred from-view center at the source node.
toValidFlags: A set of flags that indicate which destination node view settings are valid.
toPan: The pan angle to use when displaying the destination node.
toTilt: The tilt angle to use when displaying the destination node.
toFOV: The field of view to use when displaying the destination node.
toViewCenter: The view center to use when displaying the destination node.
distance: The distance between the source node and the destination node.
flags: A set of link hot spot flags. This field is unused and should be set to 0.
reserved1: Reserved. This field must be 0.
reserved2: Reserved. This field must be 0.

Certain fields in the link hot spot atom are not used by QuickTime VR. The fromValidFlags field is generally set to 0 and the from fields are not used. However, these fields could be quite useful if you have created a transition movie from one node to another. The from angles can be used to swing the current view of the source node to align with the first frame of the transition movie. The distance field is intended for use with 3D applications, but is also not used by QuickTime VR.

Link Hot Spot Valid Flags

The toValidFlags field in the link hot spot atom structure specifies which view settings are to be used when moving to a destination node from a hot spot. You can use these bit flags to specify a value for that field:

enum {

    kQTVRValidPan                               = 1 << 0,

    kQTVRValidTilt                              = 1 << 1,

    kQTVRValidFOV                               = 1 << 2,

    kQTVRValidViewCenter                        = 1 << 3

};

kQTVRValidPan: If this bit is set, the destination pan angle is used.
kQTVRValidTilt: If this bit is set, the destination tilt angle is used.
kQTVRValidFOV: If this bit is set, the destination field of view is used.
kQTVRValidViewCenter: If this bit is set, the destination view center is used.

URL Hot Spot Atom

The URL hot spot atom has an atom type of kQTVRHotSpotURLType ('url '). The URL hot spot atom contains a URL string for a particular Web location (for example, http://quicktimevr.apple.com). QuickTime VR automatically links to this URL when the hot spot is clicked.

Getting the Name of a Node

You can use standard QuickTime atom container functions to retrieve the information in a node header atom. For example, the MyGetNodeName function defined in Listing 7-1 returns the name of a node, given its node ID.

Listing 7-1 Getting a node’s name

OSErr MyGetNodeName (QTVRInstance theInstance, UInt32 theNodeID,

                        StringPtr theStringPtr)

    OSErr                   theErr = noErr;

    QTAtomContainer         theNodeInfo;

    VRNodeHeaderAtomPtr     theNodeHeader;

    QTAtom                  theNodeHeaderAtom = 0;

    //Get the node information atom container.

    theErr = QTVRGetNodeInfo(theInstance, theNodeID, &theNodeInfo);

    //Get the node header atom.

    if (!theErr)

        theNodeHeaderAtom = QTFindChildByID(theNodeInfo,

                                            kParentAtomIsContainer,

                                            kQTVRNodeHeaderAtomType, 1,

                                            nil);

    if (theNodeHeaderAtom != 0) {

        QTLockContainer(theNodeInfo);

        //Get a pointer to the node header atom data.

        theErr = QTGetAtomDataPtr(theNodeInfo, theNodeHeaderAtom, nil,

                                    (Ptr *)&theNodeHeader);

        //See if there is a name atom.

        if (!theErr && theNodeHeader->nameAtomID != 0) {

            QTAtom theNameAtom;

            theNameAtom = QTFindChildByID(theNodeInfo,

                                         kParentAtomIsContainer,

                                         kQTVRStringAtomType,

                                         theNodeHeader->nameAtomID, nil);

            if (theNameAtom != 0) {

                VRStringAtomPtr theStringAtomPtr;

            //Get a pointer to the name atom data; copy it into the string.

                theErr = QTGetAtomDataPtr(theNodeInfo, theNameAtom, nil,

                                         (Ptr *)&theStringAtomPtr);

                if (!theErr) {

                    short theLen = theStringAtomPtr->stringLength;

                    if (theLen > 255)

                        theLen = 255;

                    BlockMove(theStringAtomPtr->string, &theStringPtr[1],

                                theLen);

                    theStringPtr[0] = theLen;

        QTUnlockContainer(theNodeInfo);

    QTDisposeAtomContainer(theNodeInfo);

    return(theErr);

The MyGetNodeName function defined in Listing 7-1 retrieves the node information atom container (by calling QTVRGetNodeInfo) and then looks inside that container for the node header atom with atom ID 1. If it finds one, it locks the container and then gets a pointer to the node header atom data. The desired information, the node name, is contained in the string atom whose atom ID is specified by the nameAtomID field of the node header structure.

Accordingly, the MyGetNodeName function then calls QTFindChildByID once again to find that string atom. If the string atom is found, MyGetNodeName calls QTGetAtomDataPtr to get a pointer to the string atom data. Finally, MyGetNodeName copies the string data into the appropriate location and cleans up after itself before returning.

Adding Custom Atoms in a QuickTime VR Movie

If you author a QuickTime VR movie, you may choose to add custom atoms to either the VR world or node information atom containers. Those atoms can be extracted within an application to provide additional information that the application may use.

Information that pertains to the entire scene might be stored in a custom atom within the VR world atom container. Node-specific information could be stored in the individual node information atom containers or as sibling atoms to the node location atoms within the VR world.

Custom hot spot atoms should be stored as siblings to the hot spot information atoms in the node information atom container. Generally, its atom type is the same as the custom hot spot type. You can set up an intercept procedure in your application in order to process clicks on the custom hot spots.

If you use custom atoms, you should install your hot spot intercept procedure when you open the movie. Listing 7-2 is an example of such an intercept procedure.

Listing 7-2 Typical hot spot intercept procedure

QTVRInterceptProc MyProc = NewQTVRInterceptProc (MyHotSpot);

QTVRInstallInterceptProc (qtvr, kQTVRTriggerHotSpotSelector, myProc, 0, 0);

pascal void MyHotSpot (QTVRInstance qtvr, QTVRInterceptPtr qtvrMsg,

                        SInt32 refCon, Boolean *cancel)

    UInt32 hotSpotID = (UInt32) qtvrMsg->parameter[0];

    QTAtomContainer nodeInfo = (QTAtomContainer) qtvrMsg->parameter[1];

    QTAtom hotSpotAtom = (QTAtom) qtvrMsg->parameter[2];

    OSType hotSpotType;

    CustomData myCustomData;

    QTAtom myAtom;

    QTVRGetHotSpotType (qtvr, hotSpotID, &hotSpotType);

    if (hotSpotType != kMyAtomType) return;

    // It's our type of hot spot - don't let anyone else handle it

    *cancel = true;

    // Find our custom atom

    myAtom = QTFindChildByID (nodeInfo, hotSpotAtom, kMyAtomType, 1, nil);

    if (myAtom != 0) {

        OSErr err;

        // Copy the custom data into our structure

        err = QTCopyAtomDataToPtr (nodeInfo, myAtom, false,

                                 sizeof(CustomData), &myCustomData, nil);

        if (err == noErr)

            // Do something with it

            DoMyHotSpotStuff (hotSpotID, &myCustomData);

Your intercept procedure is called for clicks on any hot spot. You should check to see if it is your type of hot spot and if so, extract the custom hot spot atom and do whatever is appropriate for your hot spot type (DoMyHotSpotStuff).

When you no longer need the intercept procedure you should call QTVRInstallInterceptProc again with the same selector and a nil procedure pointer and then call DisposeRoutineDescriptor on myProc.

Required Atoms for Wired Actions

Certain actions on a QuickTime VR movie can trigger wired actions if the appropriate event handler atoms have been added to the file. This section discusses what atoms must be included in the QuickTime VR file to support wired actions.

As with sprite tracks, the presence of a certain atom in the media property atom container of the QTVR track enables the handling of wired actions. This atom is of type kSpriteTrackPropertyHasActions, which has a single Boolean value that must be set to true.

When certain events occur and the appropriate event handler atom is found in the QTVR file, then that atom is passed to QuickTime to perform any actions specified in the atom. The event handler atoms themselves must be added to the node information atom container in the QTVR track. There are two types of event handlers for QTVR nodes: global and hot spot specific. The currently supported global event handlers are kQTEventFrameLoaded and kQTEventIdle. The event handler atoms for these are located at the root level of the node information atom container. A global event handler atom’s type is set to the event type and its ID is set to 1.

Hot spot–specific event handler atoms are located in the specific hot spot atom as a sibling to the hot spot info atom. For these atoms, the atom type is always kQTEventType and the ID is the event type. Supported hot spot–specific event types are kQTEventMouseClick, kQTEventMouseClickEnd, kQTEventMouseClickEndTriggerButton, and kQTEventMouseEnter, kQTEventMouseExit.

The specific actions that cause these events to be generated are described as follows:

kQTEventFrameLoaded ('fram'): Generated when a node is entered, before any application-installed entering-node procedure is called (this event processing is considered part of the node setup that occurs before the application’s routine is called).
kQTEventIdle ('idle'): Generated every n ticks, where n is defined by the contents of the
kSpriteTrackPropertyQTIdleEventsFrequency: atom (
SInt32: ) in the media property atom container. When appropriate, this event is triggered before any normal idle processing occurs for the QuickTime VR movie.
kQTEventMouseClick ('clik'): Generated when the mouse goes down over a hot spot.
kQTEventMouseClickEnd ('cend'): Generated when the mouse goes up after a kQTEventMouseClick is generated, regardless of whether the mouse is still over the hot spot originally clicked. This event occurs prior to QuickTime VR’s normal mouse-up processing.
kQTEventMouseClickEndTriggerButton ('trig'): Generated when a click end triggers a hot spot (using the same criterion as used by QuickTime VR in 2.1 for link/url hot spot execution). This event occurs prior to QuickTime VR’s normal hot spot–trigger processing.
kQTEventMouseEnter ('entr'), kQTEventMouseExit ('exit'): These two events are generated when the mouse rolls into or out of a hot spot, respectively. These events occur whether or not the mouse is down and whether or not the movie is being panned. These events occur after any application-installed MouseOverHotSpotProc is called, and will be cancelled if the return value from the application’s routine indicates that QuickTimeVR’s normal over-hotspot processing should not take place.

Next Previous