Retired Document
Important: This document may not represent best practices for current development. Links to downloads and other resources may no longer be valid.
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 |
---|---|
|
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. |
|
If this flag is set and the |
|
If this flag is set and the |
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 |
---|---|
|
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 |
---|---|
|
Set this flag to 1 if the |
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 |
---|---|
|
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 |
---|---|
|
If this flag is set, |
|
If this flag is set, your application intends to allow other applications to run (by calling |
|
If this flag is set, |
|
If this flag is set, |
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 |
---|---|
|
If this flag is set, the text media handler lets new samples cause previous samples to scroll out. You must also set |
|
If this flag is set, the text media handler lets horizontally scrolled text flow within the text box instead of extending to the right. |
|
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. |
|
If this flag is set, the text media handler displays text with a drop shadow. If you use the |
|
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. |
|
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. |
|
If this flag is set, the text media handler highlights text using inverse video instead of the highlight color. |
|
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 |
---|---|
|
Data sent to this input should be in the form of a QuickTime |
|
Data sent to this input should be in the form of a QuickDraw region. The region is intersected with the track's source box. |
|
Data sent to this input should be in the form of a |
|
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. |
|
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. |
|
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. |
|
Data sent to this input should be in the form of a QuickTime |
|
Data sent to this input should be in the form of a |
|
Data sent to this input should be in the form of a sound localization data record ( |
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 |
---|---|
|
Specifies the type of data reference. For an alias data reference, you set the parameter to |
|
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 |
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 |
---|---|
|
Specifies the media for an operation. Your application obtains a media identifier from such Movie Toolbox functions as |
|
Specifies the movie for an operation. Your application obtains a movie identifier from such functions as |
|
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 |
|
Specifies the callback for an operation. You obtain a callback identifier from the |
|
Specifies the time base for an operation. Your application obtains a time base identifier from the |
|
Specifies the track for an operation. Your application obtains a track identifier from such Movie Toolbox functions as |
|
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 |
|
Specifies the user data list for an operation. You obtain a user data list identifier by calling the |
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