Advanced Search

Log In | Not a Member?

Contact ADC

< Previous PageNext Page > Hide TOC

VR Media

This section describes the QuickTime VR world and node information atom containers, which can be obtained by calling the QuickTime VR Manager routines QTVRGetVRWorld and QTVRGetNodeInfo. Those routines, as well as a complete discussion of QuickTime VR and how your application can create QuickTime VR movies, are described in detail in QuickTime VR.

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

Note that many 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 a number of routines for both creating and accessing atom containers.

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;

Field descriptions

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 3-16. The component atoms are defined and their structures are shown in the sections that follow.

Figure 3-16  Structure of the VR world atom container

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 VRWorldHeaderAtom {

    UInt16                              majorVersion;

    UInt16                              minorVersion;

    QTAtomID                            nameAtomID;

    UInt32                              defaultNodeID;

    UInt32                              vrWorldFlags;

    UInt32                              reserved1;

    UInt32                              reserved2;

} VRWorldHeaderAtom, *QTVRWorldHeaderAtomPtr;

QT

QT

Field descriptions

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;

Field descriptions

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

};

Constant descriptions

kQTVRValidCorrection

The default correction mode for panorama-imaging properties. If this bit is set, the correction field holds a default correction mode.

kQTVRValidQuality

The default imaging quality for panorama-imaging properties. If this bit is set, the quality field holds a default imaging quality.

kQTVRValidDirectDraw

The default direct-draw quality for panorama-imaging properties. If this bit is set, the directDraw field holds a default direct-drawing property.

kQTVRValidFirstExtraProperty

The default imaging property for panorama-imaging properties. If this bit is set, the first element in the array in the imagingProperties field holds a default imaging property. As new imaging properties are added, they will be stored in this array.

< Previous PageNext Page > Hide TOC

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. | Terms of use | Privacy Notice