|
What is an Idling Movie Importer?As described in the Movie Data Exchange Components documentation, movie import components import data from non-movie sources into QuickTime movies. For example, a CD audio track can be imported into a QuickTime movie. In general, this is accomplished by a single call to one of the importer's Idling movie importer components differ from non-idling importer components in that they implement a special routine Because they are called at periodic intervals, idling movie importers are given the opportunity to display the movie data as it is downloaded, similar to how fast-start movies are displayed, rather than after the data has been completely downloaded. Designating your Importer as an Idling ImporterYou must identify your movie importer as an idling movie importer in order for your Listing 1: canMovieImportWithIdle component flag. canMovieImportWithIdle = 1L << 20 MovieImportIdleHere's a description of the new Listing 2: MovieImportIdle
MovieImportIdle
Call the movie data import component to handle periodic tasks.
ComponentResult MovieImportIdle ( // IV-2677
MovieImportComponent ci, // IV-2677
long inFlags,
long *outFlags );
ci
A movie data import component instance. Your software obtains this reference
from OpenComponent or OpenDefaultComponent.
inFlags
Flags (see below) that specify control information governing the import operation.
outFlags
Flags (see below) that identify a field that is to receive status information about
the import operation. Your component sets the appropriate flags in this field
when the operation is complete.
Function Result: Returns noErr if there is no error.
inFlags Constants
Currently not used. Set to 0.
outFlags Constants
movieImportResultComplete
Indicates whether or not your component has completed importing the data. Set
this flag to 1 if your component is finished importing the data.
VERSION NOTES
Introduced in QuickTime 4.
PROGRAMMING INFO
C interface file: QuickTimeComponents.h
Availability:
Non-Carbon CFM: in QuickTimeLib 4.0 and later
CarbonLib: in CarbonLib 1.0.2 and later
Mac OS X: in version 10.0 or later
Windows: in qtmlClient.lib 4.0 and later
Notifying the Movie Controller that the Movie has changedAfter idling importers append newly processed media to a movie (usually via calls to Listing 3: Notify the movie controller that the movie has changed.
QTAtomContainer container;
Movie theMovie;
// We must notify the movie controller that the movie has changed,
// so we'll send it the kActionMovieChanged wired action
if (QTNewAtomContainer(&container) == noErr)
{
QTAtom anAction;
OSType whichAction = EndianU32_NtoB(kActionMovieChanged);
OSErr err = QTInsertChild(container, kParentAtomIsContainer,
kAction, 1, 0, 0, NULL, &anAction);
if (err == noErr)
{
err = QTInsertChild(container, anAction, kWhichAction, 1, 0,
sizeof (whichAction), &whichAction, NULL);
}
if (err == noErr)
{
err = MovieExecuteWiredActions(theMovie, 0, container);
}
err = QTDisposeAtomContainer(container);
}
Note: Do not execute this action more frequently than two or three times per second. Concurrent playback may become choppy if a movie's state is reset via this action too frequently. Here's a description of the Listing 4: MovieExecuteWiredActions function. MovieExecuteWiredActions Execute the specified wired actions for the movie OSErr MovieExecuteWiredActions ( Movie theMovie, long flags, QTAtomContainer actions ); Parameter Descriptions theMovie A movie identifier. Your application obtains this identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle. flags Flags (see below) that specify control information for the wired action to be performed actions An atom container with the wired action(s) to execute function result You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes. flags Constant movieExecuteWiredActionDontExecute Any wired action callback procedures shouldn't execute the actions, but may want to look at them. The AddMovieExecuteWiredActionsProc function lets you add a callback to a movie to execute wired actions. The RemoveMovieExecuteWiredActionsProc lets you remove the callback. Version Notes Introduced in QuickTime 4. Programming Info C interface file: Movies.h Carbon status: Supported Related Java Methods quicktime.std.movies.Movie.executeWiredActions() MovieImportSetIdleManagerQuickTime 6 introduces a number of new Idle Manager APIs. These are discussed in the What\x92s New in QuickTime 6 documentation. Among them is the MovieImportDataRef/MovieImportFile/MovieImportHandle Special ConsiderationsMovie Importer components may of course choose to implement the Idling movie importers which support any of the above routines should return MovieImportDataRefImport components (in general) should implement An import component indicates it supports Here's a description of the Listing 5: the MovieImportDataRef function.
MovieImportDataRef
Import movie data from a data reference.
ComponentResult MovieImportDataRef ( // IV-2677
MovieImportComponent ci, // IV-2677
Handle dataRef, // IV-2683
OSType dataRefType, // IV-2695
Movie theMovie, // IV-2685
Track targetTrack, // IV-2685
Track *usedTrack, // IV-2685
TimeValue atTime, // IV-2697
TimeValue *addedDuration, // IV-2697
long inFlags,
long *outFlags );
ci
A movie import component instance. Your software obtains this
reference from OpenComponent (II-1161) or OpenDefaultComponent (II-1163).
dataRef
The data reference to the data to be imported.
dataRefType
The type of data reference in the dataRef parameter.
theMovie
A movie identifier. Your application obtains this identifier from such
functions as NewMovie (II-1098), NewMovieFromFile (II-1110), and NewMovieFromHandle (II-1113).
targetTrack
The track that is to receive the imported data. This track identifier is supplied by the Movie Toolbox
and is valid only if the movieImportMustUseTrack flag in the inFlags parameter is set to 1.
usedTrack
A pointer to the track that received the imported data. Your component
returns this track identifier to the Movie Toolbox. Your component needs
to set this parameter only if you operate on a single track or if you
create a new track. If you modify more than one track, leave the field
referred to by this parameter unchanged.
atTime
The time corresponding to the location where your component is to place
the imported data. This time value is expressed in the movie's time
coordinate system.
addedDuration
A pointer to the duration of the data that your component added to
the movie. Your component must specify this value in the movie's
time coordinate system.
inFlags
Flags (see below) that control the behavior of this function.
outFlags
Flags (see below) that this function sets on return.
Function Result: See "Error Codes" (IV-2718). Returns noErr if there
is no error.
inFlags Constants
movieImportCreateTrack
Indicates that your component should create a new track to receive
the imported data. You must create a track whose type value corresponds
to the media type that you have specified in your component's
manufacturer code. You should return the track identifier of this new
track in the field referred to by the usedTrack parameter, unless you
create more than one track. If you create more than one track, be sure
to set the movieImportResultUsedMultipleTracks flag in the field referred
to by the outFlags parameter to 1. If the movieImportCreateTrack flag is
set to 1, then the movieImportMustUseTrack flag is set to 0.
movieImportMustUseTrack
Indicates that your component must use an existing track. That track is identified
by the targetTrack parameter. If you create more than one
track, be sure to set the movieImportResultUsedMultipleTracks flag in the
field referred to by the outFlags parameter to 1. If the
movieImportMustUseTrack flag is set to 1, then the movieImportCreateTrack
flag is set to 0. If both the movieImportCreateTrack and
movieImportMustUseTrack flags are set to 0, then you are free to use any existing
tracks in the movie or to create a new track (or tracks) as
needed.
movieImportInParallel
Indicates whether you are to perform an insert operation or a paste
operation. If this flag is set to 0, then you should insert the
imported data into the target track. If this flag is set to 1, then
you should add the imported data to the track, overwriting preexisting
open space currently in the track. Note that an application may use
MovieImportSetDuration (II-982) to control the amount of data you paste
into a movie. If the movieImportMustUseTrack flag is set to 1, then
you should use the track specified by the targetTrack parameter. If
this is not possible, return an appropriate Movie Toolbox result code.
movieImportWithIdle
Indicates you should perform the import operation as an idling importer. Set the
movieImportResultNeedIdles flag in the outFlags parameter to 1, and your
MovieImportIdle routine will get called periodically to process the movie data.
outFlags Constants
movieImportResultUsedMultipleTracks
Indicates that your component modified more than one track in the movie.
Set this flag to 1 if your component places imported data into more than
one track. In this case, you do not need to update the field referred to
by the usedTrack parameter.
movieImportResultNeedIdles
Indicates your component would like it\x92s MovieImportIdle routine to be
called periodically to process the movie data.
movieImportResultComplete
Indicates your component is finished processing the movie data.
VERSION NOTES
Introduced in QuickTime 3 or earlier.
PROGRAMMING INFO
C interface file: QuickTimeComponents.h
Carbon status: Supported
RELATED JAVA METHODS
quicktime.std.movies.Track.fromMovieImporterDataRef(), quicktime.std.qtcomponents.MovieImporter.fromDataRef()
MovieImportGetLoadStateIdling importers may choose to implement the movie importer Documentation for the asynchronous movie loading process (and the high-level function Here\x92s a brief description of the Listing 6: MovieImportGetLoadState.
Returns the asynchronous load state for a movie.
ComponentResult
MovieImportGetLoadState(
MovieImportComponent ci,
long * importerLoadState)
ci
A movie import component instance.
importerLoadState
A pointer that is to receive the current load state for the movie.
Values for loading process are as follows:
kMovieLoadStateLoading
Indicates the importer is searching for the movie resource
kMovieLoadStatePlayable
Indicates the movie is fully formed, fast-start would work
kmovieLoadStatePlaythroughOK
Indicates that the download would complete before the playback
would complete. This value will be returned after the movie has
become playable
kMovieLoadStateComplete
Indicates all media data is available
Function Result: See "Error Codes" (IV-2718). Returns noErr if
there is no error.
DISCUSSION
Your component can implement this function if it supports
asynchronous movie loading over slow connections. Use it to
report the current load state of the movie.
VERSION NOTES
Availability:
Non-Carbon CFM: in QuickTimeLib 4.1 and later
CarbonLib: in CarbonLib 1.1 and later
Mac OS X: in version 10.0 or later
Windows: in qtmlClient.lib 4.1 and later
PROGRAMMING INFO
C interface file: QuickTimeComponents.h
Programming summary: "Importing Movie Data" (V-2910)
Carbon status: Supported
Idling Importers & Movie ControllersIdling importers may wish to supply a hint regarding the type of movie controller to use for the imported movie. For example, if the importer implements a still image format it might want to make sure the movie does not display any controller. This is accomplished by specifying the no-interface movie controller (also referred to as the none movie controller) as the desired movie controller for the movie. The no-interface movie controller operates just like the standard movie controller except that no controller bar is displayed and no keyboard events are passed to it. When an application calls Importers can specify the suggested controller for the movie by calling the Listing 7: Specifying the no-interface movie controller hint.
OSErr err;
OSType noneType = FOUR_CHAR_CODE('none');
/* set the "none" controller for this movie */
err = SetUserDataItem(GetMovieUserData(theMovie), &noneType, sizeof(noneType),
kUserDataMovieControllerType, 1);
You should call SummaryIdling movie importer components are just like regular movie import components except they implement a special routine Document Revision History
Posted: 2004-11-12 |
|