< Previous PageNext Page >

Hide TOC

Movie Toolbox Constants, Data Types, and Functions

This chapter describes some of the constants, data types, and functions in the Movie Toolbox that you can use in your application development. It also discusses media and data handler support in QuickTime.

In this section:

Movie Exporting Flags
Movie Importing Flags
Flattening Flags
Interesting Times Flags
Full Screen Flags
Text Sample Display Flags
Data Types
Constants
Result Codes

Movie Exporting Flags

The flags parameter for the ConvertMovieToFile function specifies a set of movie conversion flags. QuickTime provides this flag:

enum {

    showUserSettingsDialog  = 2,

    movieToFileOnlyExport   = 4,

    movieFileSpecValid      = 8

};

Term	Definition
`showUserSettingsDialog`	If this flag is set, the Save As dialog box will be displayed to allow the user to choose the type of file to export to, optional export settings, and the file name to export to.
`movieToFileOnlyExport`	If this flag is set and the `showUserSettingsDialog` flag is set, the Save As dialog box restricts the user to those file formats that are supported by movie data export components. If this flag is not set, the user will also be able to save the movie either as a self-contained movie or as a reference movie.
`movieFileSpecValid`	If this flag is set and the `showUserSettingsDialog` flag is set, the `name` field of the `outputFile` parameter is used as the default name of the exported file in the Save As dialog box.

Movie Importing Flags

The flags parameter for the ConvertFileToMovieFile and PasteHandleIntoMovie functions specifiy a set of movie conversion flags. QuickTime provides one additional flag:

enum {

    showUserSettingsDialog  = 2

};

Term	Definition
`showUserSettingsDialog`	If this flag is set, the user settings dialog box for that import operation can be displayed. For example, when importing a picture, this flag would display the standard compression dialog box so that the user could select a compression method.

Flattening Flags

The flags parameter for the FlattenMovieData function specifies a set of movie flattening flags. QuickTime provided one new flag that you must set when specifying a data reference to flatten a movie to, instead of a file:

enum {

    flattenFSSpecPtrIsDataRefRecordPtr  = 1L << 4

};

Term	Definition
`flattenFSSpecPtrIsDataRefRecordPtr`	Set this flag to 1 if the `FSSpec` pointer is a `DataReferencePtrMovie` Data Types. This capability enables you to flatten movies for devices other than file systems.

Interesting Times Flags

The interestingTimeFlags parameter for the interesting time functions (GetMovieNextInterestingTime, GetTrackNexttInterestingTime, and GetMediaNextInterestingTime ) specifies a set of bit flags that specify search criteria. Normally, you use one of the interesting time functions to step forward to the next frame.

These functions work well for most media types, including video and text. However, because QuickTime stores an entire MPEG stream as a single sample, stepping to the next sample skips to the end of the sequence. To solve this problem, QuickTime introduced a new flag for the interesting time calls: nextTimeStep. This flag returns the time of the next frame, even if there are multiple frames per sample, for all media types including video, text, and MPEG. Applications that implement single stepping capabilities should always use this flag instead of nextTimeMediaSample.

enum {

    nextTimeStep    = 1 << 4

};

Term	Definition
`nextTimeStep`	Searches for the next frame in the movie's media. Set this flag to 1 to step to the next frame.

Full Screen Flags

The flags parameter for the BeginFullScreen function specifies a set of bit flags that control certain aspects of full-screen mode. QuickTime defines these constants that you can use in the flags parameter:

enum {

    fullScreenHideCursor            = 1L << 0,

    fullScreenAllowEvents           = 1L << 1,

    fullScreenDontChangeMenuBar     = 1L << 2,

    fullScreenPreflightSize         = 1L << 3

};

Term	Definition
`fullScreenHideCursor`	If this flag is set, `BeginFullScreen` hides the cursor. This is useful if you are going to play a QuickTime movie and do not want the cursor to be visible over the movie.
`fullScreenAllowEvents`	If this flag is set, your application intends to allow other applications to run (by calling `WaitNextEvent` to grant them processing time). In this case, `BeginFullScreen` does not change the monitor resolution, because other applications might depend on the current resolution.
`fullScreenDontChangeMenuBar`	If this flag is set, `BeginFullScreen` does not hide the menu bar. This is useful if you want to change the resolution of the monitor but still need to allow the user to access the menu bar.
`fullScreenPreflightSize`	If this flag is set, `BeginFullScreen` doesn't change any monitor settings, but returns the actual height and width that it would use if this bit were not set. This allows applications to test for the availability of a monitor setting without having to switch to it.

Text Sample Display Flags

Thedisplayflags parameter for the TextMediaAddTESample and TextMediaAddTextSample functions control the behavior of the text media handler. QuickTime provides these flags:

enum {

    dfContinuousScroll      = 1 << 9,

    dfFlowHoriz             = 1 << 10,

    dfContinuousKaraoke     = 1 << 11,

    dfDropShadow            = 1 << 12,

    dfAntiAlias             = 1 << 13,

    dfKeyedText             = 1 << 14,

    dfInverseHilite         = 1 << 15,

    dfTextColorHilite       = 1 << 16

};

Term	Definition
`dfContinuousScroll`	If this flag is set, the text media handler lets new samples cause previous samples to scroll out. You must also set `dfScrollIn` or `dfScrollOffMovie` Data Types, or both, for this to take effect.
`dfFlowHoriz`	If this flag is set, the text media handler lets horizontally scrolled text flow within the text box instead of extending to the right.
`dfContinuousKaraoke`	If this flag is set, the text media handler ignores the starting offset when highlighting text. Instead, it highlights text from the beginning of the text sample to the ending offset.
`dfDropShadow`	If this flag is set, the text media handler displays text with a drop shadow. If you use the `TextMediaSetTextSampleData` function, the position and translucency of the drop shadow is under your application's control.
`dfAntiAlias`	If this flag is set, the text media handler displays text with anti-aliasing. Note that although anti-aliased text looks smoother, anti-aliasing can slow down performance.
`dfKeyedText`	If this flag is set, the text media handler renders text over the background without drawing the background color. This technique is also known as masked text.
`dfInverseHilite`	If this flag is set, the text media handler highlights text using inverse video instead of the highlight color.
`dfTextColorHilite`	If this flag is set, the text media handler highlights text by changing the color of the text.

Data Types

Most Movie Toolbox data structures are private data structures. Your application never modifies the contents of these structures directly. Rather, the Movie Toolbox provides a number of functions that allow you to work with these data structures.

Modifier Input Types

The media input map describes the meaning of each input to a track. Each track has particular attributes associated with it, such as size, position, and volume. The media input map of that track describes the mapping of track modifier inputs to track properties. When you want to modify the attributes of a track, you can insert a track modifier input such as kTrackModifierTypeMatrix into the input map. The values stored in the modifier input you inserted will affect the values that are currently stored with the track.

Custom media handlers can define additional input types as necessary. Apple Computer reserves all input types consisting entirely of lowercase letters.

The following input types are currently defined:

enum {

    kTrackModifierTypeMatrix            = 1,

    kTrackModifierTypeClip              = 2,

    kTrackModifierTypeGraphicsMode      = 5,

    kTrackModifierTypeVolume            = 3,

    kTrackModifierTypeBalance           = 4,

    kTrackModifierTypeImage             = 'vide',

    kTrackModifierObjectMatrix          = 6,

    kTrackModifierObjectGraphicsMode    = 7,

    kTrackModifierType3d4x4Matrix       = 8,

    kTrackModifierCameraData            = 9

    kTrackModifierSoundLocalization     = 10

};

Term	Definition
`kTrackModifierTypeMatrix`	Data sent to this input should be in the form of a QuickTime `MatrixRecordMovie` Data Types. The matrix is concatenated with the track and movie matrices to determine the tracks final location and size. The matrix modifier describes relative, not absolute, position and scaling.
`kTrackModifierTypeClip`	Data sent to this input should be in the form of a QuickDraw region. The region is intersected with the track's source box.
`kTrackModifierTypeGraphicsMode`	Data sent to this input should be in the form of a `ModifierTrackGraphicsModeRecord` data type. The contents of the record are used as the graphics mode setting for the track. The graphics mode is not combined with the track's current graphics mode, but rather overrides it.
`kTrackModifierTypeVolume`	Data sent to this input should be in the form of a 16-bit fixed-point number. This is the same format in which QuickTime sound volume levels are stored. The volume level is used as a scaling factor on the sound track's level. It is multiplied with the track and movie volumes to determine the track's overall volume.
`kTrackModifierTypeBalance`	Data sent to this input should be in the form of a 8-bit fixed-point number. This is the same format in which QuickTime balance values are stored. The balance value is used as the balance setting for the track. Unlike the volume modifier, it is not concatenated with the track's current balance level, but overrides the current balance level.
`kTrackModifierTypeImage`	Data sent to this input should be compressed video data, typically from a video track. This input type can be used with sprite tracks. For sprite tracks, the image data is used to replace the image of a specified image index in the sprite track. The index of the image to replace must be specified in the media input map when the reference is created.
`kTrackModifierObjectMatrix`	Data sent to this input should be in the form of a QuickTime `MatrixRecordMovie` Data Types. The matrix is sent to a particular object within the receiving track, as specified by the `kTrackModifierObjectID` atom in the input map. The matrix acts as an override to the object's current matrix. For example, the matrix could be sent to a sprite within a sprite track. It would cause the sprite to move, not the entire sprite track as would `kTrackModifierMatrixMovie` Data Types.
`kTrackModifierObjectGraphicsMode`	Data sent to this input should be in the form of a `ModifierTrackGraphicsModeRecord` data type. The contents of the record are used to vary the opacity of an object within the track. For example, you would use data sent to this input to vary the opacity of a sprite within a sprite track, rather than modifying the opacity of the entire sprite track.
`kTrackModifierSoundLocalization`	Data sent to this input should be in the form of a sound localization data record (`SSpLocalizationDataMovie` Data Types). This data overrides the sound localization settings already in use by the track.

Data References

The Movie Toolbox fully supports a media that refers to data in more than one file. By allowing a single media to refer to more than one file, the toolbox allows better playback performance and easier editing, primarily by reducing the number of tracks in a movie. Use the SetMediaDefaultDataRefIndex function to control which of a media’s files you access when you add new sample data.

To fully specify a data reference, it is necessary to provide the data reference itself, along with its type; the data reference handle does not contain the type of the data reference. The DataReferenceRecord data structure contains both of these pieces of information, making it possible to pass them to functions as a single parameter. The FlattenMovieData function uses the information in the data reference structure to flatten a movie to a data reference instead of to a file.

struct DataReferenceRecord {

    OSType  dataRefType;

    Handle  dataRef;

};

typedef struct DataReferenceRecord DataReferenceRecord;

typedef DataReferenceRecord *DataReferencePtr;

Field	Definition
`dataRefType`	Specifies the type of data reference. For an alias data reference, you set the parameter to `rAliasType`, indicating that the reference is an alias. For a handle data reference, set the parameter to `HandleDataHandlerSubTypeMovie` Data Types.
`dataRef`	Specifies the actual data reference. This parameter contains a handle to the information that identifies the file to be used. The type of information stored in the handle depends on the value of the `dataRefType` parameter. For example, if your application is loading the movie from a file, this parameter would contain an alias to the movie file.

Movie Identifiers

You identify a data structure to the Movie Toolbox by means of a data type that is supplied by the Movie Toolbox. The following data types are currently defined:

Type	Definition
`Media`	Specifies the media for an operation. Your application obtains a media identifier from such Movie Toolbox functions as `NewTrackMedia` and `GetTrackMedia.`
`Movie`	Specifies the movie for an operation. Your application obtains a movie identifier from such functions as `NewMovie,` `NewMovieFromFile,` and `NewMovieFromHandle.`
`MovieEditState`	Specifies the movie edit state for an operation. Your application obtains a movie edit state identifier when you create the edit state by calling the `NewMovieEditState` function.
`QTCallBack`	Specifies the callback for an operation. You obtain a callback identifier from the `NewCallBack` function.
`TimeBase`	Specifies the time base for an operation. Your application obtains a time base identifier from the `NewTimeBase` or `GetMovieTimeBase` functions.
`Track`	Specifies the track for an operation. Your application obtains a track identifier from such Movie Toolbox functions as `NewMovieTrack` and `GetMovieTrack.`
`TrackEditState`	Specifies the track edit state for an operation. Your application obtains a track edit state identifier when you create the edit state by calling the `NewTrackEditState` function.
`UserData`	Specifies the user data list for an operation. You obtain a user data list identifier by calling the `GetMovieUserData,` `GetTrackUserData,` or `GetMediaUserData` functions.

Constants

This section lists the constants that were added to QuickTime after an early release. Most of the constants are used as flags for QuickTime functions; they allow the programmer to pass numeric data as a meaningful name.

#define kFix1 = (0x00010000);             /* fixed point value equal to 1.0 */

#define gestaltQuickTime 'qtim'           /* Movie Toolbox availability */

#define MovieFileType 'MooV'              /* movie file type */

#define VideoMediaType 'vide'             /* video media type */

#define SoundMediaType 'soun'             /* sound media type */

#define MediaHandlerType 'mhlr'           /* media handler type */

#define DataHandlerType 'dhlr'            /* data handler type */

#define TextMediaType 'text'              /* text media type */

#define GenericMediaType 'gnrc'           /* base media handler type */

#define DoTheRightThing = 0L              /* indicates default flag settings

                                                 for Movie Toolbox functions */

/* sound volume values in trackVolume parameter of NewMovieTrack function */

#define kFullVolume         = 0x100       /* full, natural volume

                                                 (8.8 format) */

#define kNoVolume           =   0         /* no volume */

/* constants for whichMediaTypes parameter of GetMovieNextInterestingTime

    function */

#define VisualMediaCharacteristic 'eyes'  /* visual media */

#define AudioMediaCharacteristic 'ears'   /* audio media */

enum

/* media quality settings in quality parameter of SetMediaQuality function */

    mediaQualityDraft           = 0x0000,    /* lowest quality level */

    mediaQualityNormal          = 0x0040,    /* acceptable quality level */

    mediaQualityBetter          = 0x0080,    /* better quality level */

    mediaQualityBest            = 0x00C0     /* best quality level */

};

/*values for callBackFlags field of QuickTime callback header structure used

    by clock components to communicate scheduling information about a

    callback event to the Movie Toolbox */

enum

    qtcbNeedsRateChanges           = 1,    /* rate changes */

    qtcbNeedsTimeChanges           = 2,    /* time changes */

    qtcbNeedsStartStopChanges      = 4     /* time base changes at start &

                                                stop times */

};

/* dialog items to include in dialog box definition for use with

    SFPGetFilePreview function */

enum

    sfpItemPreviewAreaUser         = 11,       /* user preview area */

    sfpItemPreviewStaticText       = 12,       /* static text preview */

    sfpItemPreviewDividerUser      = 13,       /* user divider preview */

    sfpItemCreatePreviewButton     = 14,       /* create preview button */

    sfpItemShowPreviewButton       = 15        /* show preview button */

};

enum

    movieInDataForkResID           = -1        /* magic resource ID */

};

/* flags for LoadIntoRAM functions */

enum

    keepInRam                  = 1<<0,     /* load and make so data

                                                 cannot be purged */

    unkeepInRam                = 1<<1,     /* mark data so it can be purged */

    flushFromRam               = 1<<2,     /* empty handles and purge data

                                                 from memory */

    loadForwardTrackEdits      = 1<<3,     /* load only data around track edits;

                                                 play movie forward */

    loadBackwardTrackEdits     = 1<<4      /* load only data around edits;

                                                 play movie in reverse */

};

/* flag for PasteHandleIntoMovie function */

enum

    pasteInParallel = 1         /* changes function to take contents and type of

                                     handle and add to movie */

};

/* text description display flags used in TextMediaAddTextSample and

      TextMediaAddTESample */

enum

    dfDontDisplay           = 1<<0,   /* don't display the text */

    dfDontAutoScale         = 1<<1,   /* don't scale text as track

                                           bounds grows or shrinks */

    dfClipToTextBox         = 1<<2,   /* clip update to the text box */

    dfUseMovieBGColor       = 1<<3,   /* set text background to movie's

                                           background color */

    dfShrinkTextBoxToFit    = 1<<4,   /* compute minimum box to fit the

                                           sample */

    dfScrollIn              = 1<<5,   /* scroll text in until last of

                                           text is in view */

    dfScrollOut             = 1<<6    /* scroll text out until last of text is

                                           gone (if dfScrollIn is also set,

                                           scroll in then out) */

    dfHorizScroll           = 1<<7,   /* scroll text horizontally; otherwise,

                                           it's vertical */

    dfReverseScroll         = 1<<8    /* vertically scroll down and horizontally

                                         scroll up; justification-dependent */

};

/* find flags for TextMediaFindNextText function */

    findTextEdgeOK           = 1<<0,     /* OK to find text at specified

                                              sample time */

    findTextCaseSensitive    = 1<<1,     /* case-sensitive search */

    findTextReverseSearch    = 1<<2,     /* search from sampleTime backward */

    findTextWraparound       = 1<<3,     /* wrap search when beginning or end

                                              of movie is reached */

/* return display flags for application-defined text function */

enum

    txtProcDefaultDisplay    = 0,        /* use the media's default settings */

    txtProcDontDisplay       = 1,        /* don't display the text */

    txtProcDoDisplay         = 2         /* display the text */

};

enum

hintsScrubMode               = 1<<0,    /* toolbox can display key frames when

                                              movie is repositioned */

hintsAllowInterlace          = 1<<6,    /* use interlace option for compressor

                                              components */

hintsUseSoundInterp          = 1<<7     /* turn on sound interpolation */

};

typedef unsigned long playHintsEnum;

Result Codes

The following table shows common error codes returned by Movie Toolbox functions.

Constant	Value	Description
couldNotResolveDataRef	-2000	Cannot use this data reference
badImageDescription	-2001	Problem with this image description
badPublicMovieAtom	-2002	Movie file corrupted
cantFindHandler	-2003	Cannot locate this handler
cantOpenHandler	-2004	Cannot open this handler
badComponentType	-2005	Component cannot accommodate this data
noMediaHandler	-2006	Media has no media handler
noDataHandler	-2007	Media has no data handler
invalidMedia	-2008	This media is corrupted or invalid
invalidTrack	-2009	This track is corrupted or invalid
invalidMovie	-2010	This movie is corrupted or invalid
invalidSampleTable	-2011	This sample table is corrupted or invalid
invalidDataRef	-2012	This data reference is invalid
invalidHandler	-2013	This handler is invalid
invalidDuration	-2014	This duration value is invalid
invalidTime	-2015	This time value is invalid
cantPutPublicMovieAtom	-2016	Cannot write to this movie file
badEditList	-2017	The track's edit list is corrupted
mediaTypesDontMatch	-2018	These media don't match
progressProcAborted	-2019	Your progress procedure returned an error
movieToolboxUninitialized	-2020	You haven't initialized the Movie Toolbox
wfFileNotFound	-2021	Cannot locate this file
cantCreateSingleForkFile	-2022	Error trying to create a single-fork file. This occurs when the file already exists.
invalidEditState	-2023	This edit state is invalid
nonMatchingEditState	-2024	This edit state is not valid for this movie
staleEditState	-2025	Movie or track has been disposed
userDataItemNotFound	-2026	Cannot locate this user data item
maxSizeToGrowTooSmall	-2027	Maximum size must be larger
badTrackIndex	-2028	This track index value is not valid
trackIDNotFound	-2029	Cannot locate a track with this ID value
trackNotInMovie	-2030	This track is not in this movie
timeNotInTrack	-2031	This time value is outside of this track
timeNotInMedia	-2032	This time value is outside of this media
badEditIndex	-2033	This edit index value is not valid
internalQuickTimeError	-2034	Internal error
cantEnableTrack	-2035	Cannot enable this track
invalidRect	-2036	Specified rectangle has invalid coordinates
invalidSampleNum	-2037	There is no sample with this sample number
invalidChunkNum	-2038	There is no chunk with this chunk number
invalidSampleDescIndex	-2039	Sample description index value invalid
invalidChunkCache	-2040	The chunk cache is corrupted
invalidSampleDescription	-2041	This sample description is invalid or corrupted
dataNotOpenForRead	-2042	Cannot read from this data source
dataNotOpenForWrite	-2043	Cannot write to this data source
dataAlreadyOpenForWrite	-2044	Data source is already open for write
dataAlreadyClosed	-2045	You have already closed this data source
endOfDataReached	-2046	End of data
dataNoDataRef	-2047	No data reference value found
noMovieFound	-2048	Toolbox cannot find a movie in the movie file
invalidDataRefContainer	-2049	Invalid data reference
badDataRefIndex	-2050	Data reference index value is invalid
noDefaultDataRef	-2051	Could not find a default data reference
couldNotUseAnExistingSample	-2052	Movie Toolbox could not use a sample
featureUnsupported	-2053	Movie Toolbox does not support this feature

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