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.

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


Copyright © 2005, 2018 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2018-06-04