What's New in QuickTime 4.1
| Previous | Chapter Contents | Chapter Top | Next |
The loading model has changed from this
NewMovieFrom ... <playable> <complete>
NewMovieFrom ... <incomplete> <playable> <complete>
During this <incomplete> phase querying the movie for its characteristics is not helpful. Only at the point where it is playable can such queries be useful.
To determine when such queries are useful or to enable or disable behavior, a new QuickTime Movie Toolbox API has been introduced in QuickTime 4.1. This is the GetMovieLoadState function.
pascal long GetMovieLoadState( Movie theMovie );
The GetMovieLoadState routine returns a value that indicates the state of the loading process.
kMovieLoadStateLoading // searching for movie resource
kMovieLoadStatePlayable // movie fully formed, fast-start would work
kMovieLoadStateComplete // all media data is available
These values are ordered so that the values treated as numbers conform to this rule:
kMovieLoadStateLoading < kMovieLoadStatePlayable
< kMovieLoadStateComplete
This allows code to perform relative comparisons against these milestones to determine if certain operations make sense.
There is also an additional state kMovieLoadStateError indicating that the loading of the movie failed. This typically means that a URL could not be found or loaded. This has a negative value, so that the above rule becomes:
kMovieLoadStateError < kMovieLoadStateLoading < kMovieLoadStatePlayable <
kMovieLoadStateComplete
Note
Any load states with values less than 0 should be considered as errors.
Finally, not all states will be seen by a client. A completely local movie will transition directly to kMovieLoadStateComplete . A local movie with media stored on a slow connection will probably transition to kMovieLoadStatePlayable since fast-starting will occur.
By way of a quick example of code using this new information, consider how the load state might be used by an application updated to recognize asynchronous movie loading. Assume that it called the NewMovieFromDataRef function to open a URL:
err = NewMovieFromDataRef( &theMovie, newMovieActive | newMovieAsyncOK,
nil, url, URLDataHandlerSubType );
and periodically it will check the movie to see if it has reached a particular state of interest:
void checkOnMovie( MovieInfo movieInfo )
{
long loadState;
loadState = GetMovieLoadState(movieInfo->theMovie);
if (movieInfo->loadState == loadState) // didn't change
return;
movieInfo->loadState = loadState; // new state
if (loadState < 0) {
// failed to load the movie so tell the user and dispose of movie
}
if (loadState < kMovieLoadStatePlayable) {
// just keep tasking the movie so it gets time to load
}
if (loadState < kMovieLoadStateComplete) {
// we just became playable
// get movie box and size window
// put a movie controller on this movie
// update other UI appropriately
// check for auto play
}
if (loadState >= kMovieLoadStateComplete) {
// now we know all media data is available and we might
// only now allow the user to perform a self-contained save
// or an export
}
}
Until the movie has reached its playable state, an application should not try to attach a movie controller, since the user data that allows the QuickTime Movie Toolbox to choose the type of movie controller will not be available. Also, the application should call the MoviesTask function on the movie to give it time to continue loading.
One of the capabilities that this offers is a way to detect the difference between when the movie is fast-starting and therefore its data is not all available and when it is fully loaded. This is useful in enabling certain menu items only appropriate when all media is accessible.
Also, this eliminates to a certain degree the necessity to understand how to detect fast-start with the GetMaxLoadedTimeInMovie function.
In the future, it is expected that new and useful states will be added. However, it will be done in such a way that the above ordering still holds.
| Previous | Chapter Contents | Chapter Top | Next |