Retired Document
Important: This document may not represent best practices for current development. Links to downloads and other resources may no longer be valid.
Using Movie Data Exchange Components
This chapter describes how to use movie exchange components from within your application. The chapter focuses on three particular features: the ability to specify part of a file to import, getting a list of supported MIME types, and determining whether movie data export is possible.
Importing and Exporting Movie Data
Your application starts a data import or export operation by calling the Movie Toolbox. There are several Movie Toolbox functions that allow you to specify a data import or data export component. For example, the PasteHandleIntoMovie
and ConvertFileToMovieFile
functions allow you to specify a movie data import component. The PutMovieIntoTypedHandle
and ConvertMovieToFile
functions allow you to specify a movie data export component. All of these functions select a component for you if you do not specify one yourself.
When you import data into a QuickTime movie, you can specify that the data be placed into a specific existing track in the movie, into a new track that is created by the movie data import component, or into one or more existing tracks (in this case, the component may create additional tracks, if necessary).
When you export data from a QuickTime movie, you can request data from a specific track or from the entire movie. In addition, you can specify a segment of the track or movie to be exported.
Configuring a Movie Data Exchange Component
You do not need to configure a movie data exchange component before you use it to convert data into or out of a QuickTime movie. These components are implemented in such a way that they can operate successfully using their own default configuration information. In fact, some data exchange components do not allow you to configure them. However, most data exchange components do support some or all of the configuration functions that are defined for components of this type.
If you are going to configure a data exchange component, you must do so before you start the data exchange operation. You must call the component directly in order to set the configuration; the Movie Toolbox does not do this for you. Use the functions described in Configuring Movie Data Import Components and Configuring Movie Data Export Components as appropriate. Note that all of these functions are optional; that is, it is up to the developer of the component to decide whether or not to support a given configuration function. If the component does not support a function you have called, the component returns an error code of badComponentSelector
.
Configuring Movie Data Import Components
Your component may provide one or more configuration functions. These functions allow applications to configure your component before the Movie Toolbox calls your component to start the import process. Note that applications may call these functions directly.
All of these functions are optional. If your component receives a request that it does not support, you should return the badComponentSelector
error code. In addition, your component should work properly even if none of these functions is called.
These functions address a variety of configuration issues. The MovieImportSetSampleDuration
function allows an application to set your component’s sample duration. Use the MovieImportSetDuration
function to control the duration of the imported data. Applications can use the MovieImportSetDimensions
function to specify the spatial dimensions of a new track. Use the MovieImportSetSampleDescription
function to supply a sample description structure to your movie data import component.
The MovieImportSetMediaFile
function allows applications to direct your component’s output to a specific media file. Applications can provide additional data to your component by calling the MovieImportSetAuxiliaryData
function. The MovieImportSetChunkSize
function allows applications to control the chunk size in the new media. Applications can inform you that the source data came from the scrap by calling your MovieImportSetFromScrap
function.
Applications can specify a progress function for use by your component by calling the MovieImportSetProgressProcfunction
.
Applications can instruct your component to display its user dialog box by calling the MovieImportDoUserDialog
function.
Configuring Movie Data Export Components
Your component may provide one or more configuration functions. These functions allow applications to configure your component before the Movie Toolbox calls your component to start the export process. Note that applications may call these functions directly.
All of these functions are optional. If your component receives a request that it does not support, you should return the badComponentSelector
error code. In addition, your component should work properly even if none of these functions is called.
These functions address a variety of configuration issues. Applications can retrieve additional data from your component by calling the MovieExportGetAuxiliaryData
function.
Applications can specify a progress function for use by your component by calling the MovieExportSetProgressProc
function.
Applications can instruct your component to display its user dialog box by calling the MovieExportDoUserDialog
function.
Finding a Specific Movie Data Exchange Component
If you are going to specify a particular data exchange component to the Movie Toolbox, you must first open a connection to that component. Use the Component Manager’s OpenDefaultComponent
or OpenComponent
function to open a connection to a movie data exchange component. Before you can open that connection, however, you must find an appropriate movie data exchange component.
To find an appropriate data exchange component, you may need to use the Component Manager’s FindNextComponent
function. You specify the characteristics of the component you are seeking in a component description record; in particular, in the componentType
, componentSubtype
, componentManufacturer
, and componentFlags
fields.
Movie data import components have a component type value of 'eat
'
, which is defined by the MovieImportType
constant. Movie data export components have a type value of 'spit'
, which is defined by the MovieExportType
constant.
Movie data exchange components use their component subtype and manufacturer values to indicate the type of data that they support. The subtype value indicates the type of data that these components can import or export. For example, movie data import components that convert text into QuickTime movie data have a component subtype value of 'TEXT'
. A single data exchange component may support only one data type.
The manufacturer field indicates the QuickTime media type that is supported by the component. For example, movie data export components that can read data from a sound media have a manufacturer value of 'soun'
(this value is defined by the SoundMediaType
constant). If a data exchange component can work with more than one media type, it specifies a manufacturer value of 0.
In addition, these components use the componentFlags
field to indicate more specific information about their capabilities. The following flags are currently defined:
enum { |
canMovieImportHandles = 1, /* can import from handles */ |
canMovieImportFiles = 2, /* can import from files */ |
hasMovieImportUserInterface = 4, /* import has user interface */ |
canMovieExportHandles = 8, /* can export to handles */ |
canMovieExportFiles = 16, /* can export to files */ |
hasMovieExportUserInterface = 32, /* export has user interface */ |
dontAutoFileMovieImport = 64 /* turn off automatic file conversion */ |
}; |
Movie data import components use the first three flags to specify their capabilities. If a component can convert data from a handle, its canMovieImportHandles
flag is set to 1. If it can work with files, its canMovieImportFiles
flag is set to 1. Note that both of these flags may be set to 1 if a single component can work with both files and handles. If a component provides a dialog box that allows the user to specify configuration information, the hasMovieImportUserInterface
flag is set to 1. If a component does not support the automatic conversion of standard files to movies in an import component, set the dontAutoFileMovieImport
flag to 1 (the default setting is 0).
Movie data export components use the other three flags in the same way.
Specifying a Part of a File to Import
When using certain movie import components, applications can import data from a part of a file rather than the entire file by calling MovieImportSetOffsetAndLimit
or MovieImportSetOffsetAndLimit64
. The latter function accomodates 64-bit offsets instead of just 32-bit offsets. These functions let an application specify a byte offset into the file at which the import operation begins and another offset, known as the limit, that indicates the last data in the file that can be imported. This function is especially useful when one file format is embedded in another; it allows an application to skip header data for the enclosing file and begin importing data at the start of the desired format.
Not all movie import components support the MovieImportSetOffsetAndLimit
or MovieImportSetOffsetAndLimit64
function. Those that do include the movie import components provided with QuickTime for the kQTFileTypeAIFF
, kQTFileTypeWave
, and kQTFileTypeMuLaw
file types. Those that do not return the result code badComponentSelector
in response to a MovieImportSetOffsetAndLimit
or MovieImportSetOffsetAndLimit64
call. If your export component implements MovieImportSetOffsetAndLimit64
, it should implement MovieImportSetOffsetAndLimit
too, since older clients may not use the new 64-bit offset version of the call.
Getting a List of Supported MIME Types
Applications can get a list of MIME types supported by a movie import component by calling the MovieImportGetMIMETypeList
function.
In QuickTime, import components should additionally include a public component resource holding the same data that MovieImportGetMIMETypeList
would return. This public resource’s public type and ID should be 'mime'
and 1, respectively; these values are held in the import component’s public resource list. The following shows an example of such a list:
resource 'thnr' (kMyImportComponentResID) |
{ |
'mime', 1, 0, |
'mime', kMyImportMIMETypeListResID, 0 |
} |
By including this public resource, QuickTime and applications don’t need to open the import component and call MovieImportGetMIMETypeList
to determine the MIME types the importer supports. In the absence of this resource, QuickTime and applications will use MovieImportGetMIMETypeList
.
Determining Whether Movie Data Export Is Possible
Although a movie export component can export one or more media types, it may not be able to export all the kinds of data stored in those media. Applications can find out whether a movie export component can export all the data for a particular movie or track by calling the MovieExportValidate
function.
Not all export components implement the MovieExportValidate
call. In the following code snippet, you make the Validate
call, and even if the component routine is not implemented it is still true:
Boolean canExport = true; |
MovieExportValidate(ci, &canExport); |
if(canExport) { |
. . . |
} |
Copyright © 2005, 2006 Apple Computer, Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2006-01-10