Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

Component Creation Reference for QuickTime

Framework
Frameworks/QuickTime.framework
Declared in
Movies.h
QuickTimeComponents.h

Overview

APIs are provided to help developer create new components that import and export data to and from QuickTime movies, including managing movie previews.

Functions by Task

Compressing Image Sequences

Compressing Still Images

Configuring Movie Data Export Components

Configuring Movie Data Import Components

Creating a Compression Graphics World

Creating Previews

Displaying Previews

Displaying the Standard Image-Compression Dialog Box

Exporting Movie Data

Exporting Text

Getting Default Settings for an Image or a Sequence

Handling Preview Events

Importing MIDI Files

Importing Movie Data

Managing the Time

Movie Functions

Positioning Dialog Boxes and Rectangles

Specifying a Test Image

Tween Component Requirements

Using Callback Functions

Working With Image or Sequence Settings

Working With The Idle Manager

Working With the Timecode Media Handler

Supporting Functions

Functions

ClockCallMeWhen

In a clock component, schedules a callback event for invocation.

ComponentResult ClockCallMeWhen (
   ComponentInstance aClock,
   QTCallBack cb,
   long param1,
   long param2,
   long param3
);

Parameters
aClock

Specifies the clock for the operation. Applications obtain this identifier from OpenComponent.

cb

Specifies the callback event for the operation. The Movie Toolbox obtains this value from your component's ClockNewCallBack function.

param1

Contains data supplied to the Movie Toolbox in the param1 parameter to the CallMeWhen function. Your component interprets this parameter based on the value of the callBackType parameter to the ClockNewCallBack function. If callBackType is set to callBackAtTime, the param1 parameter contains flags (see below) indicating when to invoke your callback function for this callback event. If the callBackType parameter is set to callBackAtRate, param1 contains flags (see below) indicating when to invoke your callback function for this event.

param2

Contains data supplied to the Movie Toolbox in the param2 parameter to the CallMeWhen function. Your component interprets this parameter based on the value of the callBackType parameter to the ClockNewCallBack function. If callBackType is set to callBackAtTime, the param2 parameter contains the time value at which your callback function is to be invoked for this event. The param1 parameter contains flags affecting when the Movie Toolbox calls your function. If callBackType is set to callBackAtRate, the param2 parameter contains the rate value at which your callback function is to be invoked for this event.

param3

Contains data supplied to the Movie Toolbox in the param3 parameter to the CallMeWhen function. If cbType is set to callBackAtTime, param3 contains the time scale in which to interpret the time value that is stored in param2.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

If your clock component successfully schedules the callback event, you should call the AddCallBackToTimeBase function to add it to the list of callback events for the corresponding time base. If your component cannot schedule the callback event, it should return an appropriate error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

ClockCancelCallBack

In a clock component, removes the specified callback event from the list of scheduled callback events for a time base.

ComponentResult ClockCancelCallBack (
   ComponentInstance aClock,
   QTCallBack cb
);

Parameters
aClock

Specifies the clock for the operation. Your application obtains this identifier from the Component Manager's OpenComponent function.

cb

Specifies the callback event for the operation. The Movie Toolbox obtains this value from your component's ClockNewCallBack function.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

If your clock component successfully cancels the callback event, you should call the RemoveCallBackFromTimeBase function so that the Movie Toolbox can remove the callback event from its list of scheduled events.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

ClockDisposeCallBack

In a clock component, disposes of the memory associated with the specified callback event.

ComponentResult ClockDisposeCallBack (
   ComponentInstance aClock,
   QTCallBack cb
);

Parameters
aClock

Specifies the clock for the operation. Applications obtain this identifier from the Component Manager's OpenComponent function.

cb

Specifies the callback event for the operation. The Movie Toolbox obtains this value from your component's ClockNewCallBack function.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

You should not call this function at interrupt time.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

ClockGetRate

Fetches the rate of a specified clock.

ComponentResult ClockGetRate (
   ComponentInstance aClock,
   Fixed *rate
);

Parameters
aClock

Specifies the clock for the operation. Applications obtain this identifier from the Component Manager's OpenComponent function.

rate

Pointer to memory where the clock rate is returned.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

ClockGetRateChangeConstraints

Obtains minimum and maximum delays that a clock could introduce during a rate change.

ComponentResult ClockGetRateChangeConstraints (
   ComponentInstance aClock,
   TimeRecord *minimumDelay,
   TimeRecord *maximumDelay
);

Parameters
aClock

Specifies the clock for the operation. Applications obtain this identifier from OpenComponent.

minimum

A pointer to a TimeRecord structure that the clock will update with the minimum delay introduced during a rate change. You can pass NIL if you do not want to receive this information.

maximum

A pointer to a TimeRecord structure that the clock will update with the maximum delay introduced during a rate change. You can pass NIL if you do not want to receive this information.

Return Value

See Error Codes in the QuickTime API Reference. Returns noErr if there is no error. Returns badComponentSelector if the component does not support the call.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
QuickTimeComponents.h

ClockGetTime

Obtains the current time according to a specified clock.

ComponentResult ClockGetTime (
   ComponentInstance aClock,
   TimeRecord *out
);

Parameters
aClock

Specifies the clock for the operation. You obtain this identifier from OpenComponent or OpenDefaultComponent.

out

A pointer to a TimeRecord structure. The clock component updates this structure with the current time information. Specifically, the clock component sets the value field and the scale field in the time structure. Your clock component should always return values in its native time scale. This time scale does not change during the life of the component connection.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

ClockNewCallBack

In a clock component, allocates memory for a new callback event.

QTCallBack ClockNewCallBack (
   ComponentInstance aClock,
   TimeBase tb,
   short callBackType
);

Parameters
aClock

Specifies the clock for the operation. Applications obtain this identifier from the Component Manager's OpenComponent function.

tb

Specifies the callback event's time base. Typically, your component does not need to save this specification. You can use the Movie Toolbox's GetCallBackTimeBase function to determine the callback event's time base when it is invoked. For more information about time bases, see Inside Macintosh: QuickTime.

callBackType

Contains a constant (see below) that specifies when the callback event is to be invoked. The value of this parameter governs how your component interprets the data supplied in the param1, param2, and param3 parameters to ClockCallMeWhen. See these constants:

  • callBackAtTime

  • callBackAtRate

  • callBackAtTimeJump

  • callBackAtInterrupt

Return Value

A pointer to a CallBackRecord structure. Your software can pass this structure to other functions, such as ClockRateChanged.

Discussion

Your component allocates the memory required to support the callback event. The memory must be in a locked block and must begin with a QTCallBackHeader structure initialized to 0. Your component can allocate an arbitrarily large piece of memory for the callback event.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

ClockRateChanged

In a clock component, is called whenever the callback's time base rate changes.

ComponentResult ClockRateChanged (
   ComponentInstance aClock,
   QTCallBack cb
);

Parameters
aClock

Specifies the clock for the operation. Applications obtain this identifier from the Component Manager's OpenComponent function.

cb

Specifies the callback for the operation. The Movie Toolbox obtains this value from your component's ClockNewCallBack function.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

The Movie Toolbox calls this function once for each qualified callback function associated with the time base. Note that the Movie Toolbox calls this function only for callback events that are currently scheduled.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

ClockSetTimeBase

In a clock component, is called when an application creates a time base that uses the clock component.

ComponentResult ClockSetTimeBase (
   ComponentInstance aClock,
   TimeBase tb
);

Parameters
aClock

Specifies the clock for the operation. Applications obtain this identifier from the Component Manager's OpenComponent function.

tb

Specifies the time base that is associated with the clock.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

ClockStartStopChanged

In a clock component, is called whenever the start or stop time of the callback's time base changes.

ComponentResult ClockStartStopChanged (
   ComponentInstance aClock,
   QTCallBack cb,
   Boolean startChanged,
   Boolean stopChanged
);

Parameters
aClock

Specifies the clock for the operation. Applications obtain this identifier from the Component Manager's OpenComponent function.

cb

Specifies the callback for the operation. The Movie Toolbox obtains this value from your component's ClockNewCallBack function.

startChanged

Indicates that the start time of the time base associated with the clock component instance has changed.

stopChanged

Indicates that the stop time of the time base associated with the clock component instance has changed.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

The Movie Toolbox calls this function once for each qualified callback function associated with the time base. Note that the Movie Toolbox calls this function only for callback events that are currently scheduled.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

ClockTimeChanged

In a clock component, is called whenever the callback's time base time value is set.

ComponentResult ClockTimeChanged (
   ComponentInstance aClock,
   QTCallBack cb
);

Parameters
aClock

Specifies the clock for the operation. Applications obtain this identifier from the Component Manager's OpenComponent function.

cb

Specifies the callback for the operation. The Movie Toolbox obtains this value from your component's ClockNewCallBack function.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

DisposeMovieExportGetDataUPP

Disposes of a MovieExportGetDataUPP pointer.

void DisposeMovieExportGetDataUPP (
   MovieExportGetDataUPP userUPP
);

Parameters
userUPP

A MovieExportGetDataUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability
Declared In
QuickTimeComponents.h

DisposeMovieExportGetPropertyUPP

Disposes of a MovieExportGetPropertyUPP pointer.

void DisposeMovieExportGetPropertyUPP (
   MovieExportGetPropertyUPP userUPP
);

Parameters
userUPP

A MovieExportGetPropertyUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability
Declared In
QuickTimeComponents.h

DisposeMovieExportStageReachedCallbackUPP

Disposes of a MovieExportStageReachedCallbackUPP pointer.

void DisposeMovieExportStageReachedCallbackUPP (
   MovieExportStageReachedCallbackUPP userUPP
);

Parameters
userUPP

A MovieExportStageReachedCallbackUPP pointer.

Availability
Declared In
QuickTimeComponents.h

DisposeSCModalFilterUPP

Disposes of an SCModalFilterUPP pointer.

void DisposeSCModalFilterUPP (
   SCModalFilterUPP userUPP
);

Parameters
userUPP

An SCModalFilterUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability
Declared In
QuickTimeComponents.h

DisposeSCModalHookUPP

Disposes of an SCModalHookUPP pointer.

void DisposeSCModalHookUPP (
   SCModalHookUPP userUPP
);

Parameters
userUPP

An SCModalHookUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability
Declared In
QuickTimeComponents.h

GraphicsImageImportGetSequenceEnabled

Undocumented

ComponentResult GraphicsImageImportGetSequenceEnabled (
   GraphicImageMovieImportComponent ci,
   Boolean *enable
);

Parameters
ci

The component instance that identifies your connection to the movie importer component.

enable

A pointer to a Boolean that returns TRUE if enabled, FALSE otherwise.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

GraphicsImageImportSetSequenceEnabled

Undocumented

ComponentResult GraphicsImageImportSetSequenceEnabled (
   GraphicImageMovieImportComponent ci,
   Boolean enable
);

Parameters
ci

The component instance that identifies your connection to the movie importer component.

enable

Pass TRUE to enable, FALSE to disable.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

MIDIImportGetSettings

Obtains settings that control the importation of MIDI files.

ComponentResult MIDIImportGetSettings (
   TextExportComponent ci,
   long *setting
);

Parameters
ci

A text export component instance used to import a MIDI file. Your software obtains this reference from OpenComponent or OpenDefaultComponent.

setting

Flags (see below) that control the importation of MIDI files. The flags correspond to the checkboxes in the MIDI Import Options dialog box. See these constants:

  • kMIDIImportSilenceBefore

  • kMIDIImportSilenceAfter

  • kMIDIImport20Playable

  • kMIDIImportWantLyrics

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

MIDIImportSetSettings

Define settings that control the importation of MIDI files.

ComponentResult MIDIImportSetSettings (
   TextExportComponent ci,
   long setting
);

Parameters
ci

A text export component instance used to import a MIDI file. Your software obtains this reference from OpenComponent or OpenDefaultComponent.

setting

Flags (see below) that control the importation of MIDI files. The flags correspond to the checkboxes in the MIDI Import Options dialog box. See these constants:

  • kMIDIImportSilenceBefore

  • kMIDIImportSilenceAfter

  • kMIDIImport20Playable

  • kMIDIImportWantLyrics

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

MovieExportAddDataSource

Defines a data source for use with an export operation performed by MovieExportFromProceduresToDataRef.

ComponentResult MovieExportAddDataSource (
   MovieExportComponent ci,
   OSType trackType,
   TimeScale scale,
   long *trackID,
   MovieExportGetPropertyUPP getPropertyProc,
   MovieExportGetDataUPP getDataProc,
   void *refCon
);

Parameters
ci

A movie export component instance. Your software obtains this reference from OpenComponent or OpenDefaultComponent.

trackType

The type of media provided by this data source. This normally corresponds to a QuickTime media type such as VideoMediaType or SoundMediaType.

scale

The time scale for time values passed to getDataProc parameter. If the source data is being taken from a QuickTime track, this value is typically the media's time scale.

trackID

An identifier for the data source. This identifier is returned from the call.

getPropertyProc

A MovieExportGetPropertyProc callback that provides information about processing source samples.

getDataProc

A MovieExportGetDataProc callback the export component uses to request sample data.

refCon

Passed to the procedures specified in the getPropertyProc and getDataProc parameters. Use this parameter to point to a data structure containing any information your callbacks need.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Before starting an export operation, all the data sources must be defined by calling this function once for each data source.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

MovieExportDisposeGetDataAndPropertiesProcs

Disposes of the memory associated with the procedures returned by MovieExportNewGetDataAndPropertiesProcs.

ComponentResult MovieExportDisposeGetDataAndPropertiesProcs (
   MovieExportComponent ci,
   MovieExportGetPropertyUPP getPropertyProc,
   MovieExportGetDataUPP getDataProc,
   void *refCon
);

Parameters
ci

A movie export component instance. Your software obtains this reference from OpenComponent or OpenDefaultComponent.

getPropertyProc

A MovieExportGetPropertyProc callback that provides information about processing source samples.

getDataProc

A MovieExportGetDataProc callback that the export component uses to request sample data.

refCon

Passed to the procedures specified in the getPropertyProc and getDataProc parameters. Use this parameter to point to a data structure containing any information your callbacks need.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

MovieExportDoUserDialog

Requests that a component display its user dialog box.

ComponentResult MovieExportDoUserDialog (
   MovieExportComponent ci,
   Movie theMovie,
   Track onlyThisTrack,
   TimeValue startTime,
   TimeValue duration,
   Boolean *canceled
);

Parameters
ci

A movie export component instance. Your software obtains this reference from OpenComponent or OpenDefaultComponent.

theMovie

The movie containing the data to be exported.

onlyThisTrack

Specifies that the export component should only attempt to export the data from a single track. If this parameter is set to NIL, the exporter should attempt to export the entire movie, or all of the tracks in the movie that it can export. For example, an audio export component might export multiple audio tracks, mixing them if necessary. If this parameter is not NIL, the exporter should attempt to export only the specified track.

startTime

The movie time at which to begin the export operation. If you pass 0, the operation should start at the beginning of the movie or track.

duration

The duration, in movie timescale units, of the segment to be exported. To export the entire movie, or an entire track, pass in the value returned by GetMovieDuration or GetTrackDuration, minus the value passed in startTime, as described above.

canceled

A pointer to a Boolean value. Your component should set this value to TRUE if the user cancels the dialog box, otherwise FALSE. If the user cancels the dialog box, your component should revert to its settings as they were before executing this function.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h

MovieExportFromProceduresToDataRef

Exports data provided by MovieExportAddDataSource to a specified location.

ComponentResult MovieExportFromProceduresToDataRef (
   MovieExportComponent ci,
   Handle dataRef,
   OSType dataRefType
);

Parameters
ci

A movie export component instance. Your software obtains this reference from OpenComponent or OpenDefaultComponent.

dataRef

The data reference for the export operation.

dataRefType

The type identifier for the data reference specified by dataRef.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function exports data provided by MovieExportAddDataSource to a location specified by dataRef and dataRefType. Typically dataRef contains a Macintosh file alias and dataRefType is set to rAliasType.

Special Considerations

Movie data export components that support export operations from procedures must set the canMovieExportFromProcedures flag in their component flags.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
QuickTimeComponents.h