Hardware Requirements

QuickTime 6.4 requires the following minimum hardware configuration:

• Mac OS X version 10.2.5 or later

• PowerPC G3 or better running at 400 MHz or higher

• At least 128 MB of RAM

Updating Earlier Versions

QuickTime 6.4 replaces and updates various point releases of QuickTime 6 for Mac OS X.

The QuickTime 6.4 system software, including the QuickTime Player application, is a free upgrade for QuickTime 6 users. No new Pro key is required; QuickTime 6 Pro keys will unlock the Pro features of QuickTime 6.4.

QuickTime 6 In Perspective

QuickTime 6, introduced in 2002, represented a major advance in Apple technology. Because QuickTime 6 supports ISO-compliant MPEG-4 video and audio, both encode and decode, you can create and play back MPEG-4 video and audio content and use Advanced Audio Coding (AAC).

In subsequent releases of QuickTime 6, additional support was provided for 3GPP authoring, playback, and delivery. These releases also built on Apple’s support of MPEG-4 as the standard for digital media streaming on the Internet and extended it with support for standards for mobile Internet streaming.

New Features of QuickTime 6.4

QuickTime 6.4 now adds significant new functionality to QuickTime. The following new features are discussed in the rest of this document:

• “A New Approach To Data References” describes how you can now manipulate QuickTime media via data references—opening and flattening movies, exporting graphics images, and so on.

• “Threaded Programming and QuickTime” tells how QuickTime 6.4 supports execution of background tasks on multiple threads in a preemptive multitasking environment. This new technology makes it possible to offload many tasks from your program's main thread.

• “New Graphics Functions” explains how you can now use QuickTime to read and write image files while using Core Graphics to draw and manage images.

• “New Graphics Importer Support for ColorSync” introduces new graphics importer functions that provide support for ColorSync on Mac OS X.

• “New AV Startup Synchronization Functions” describes new functions that improve audio-visual startup synchronization.

• “Processing Events” gives some guidelines for handling QuickTime events on the current Mac OS X platform.

• “New Component Properties Functions” provides details of QuickTime’s new Component Properties API, which let you configure QuickTime processes such as export and recompression without using the QuickTime user interface.

• New Movie Property Functions describes five movie property functions that are similar in purpose to the component functions described in the previous section.

• New IIDC Digitizer Functions introduces new APIs to communicate with video digitizers that have a subtype of vdSubtypeIIDC. These digitizers support new IEEE-1394-based digital cameras and webcams that have Instrumentation and Industrial Control (IIDC) features.

• “New Sound Function” describes a new sound function that identifies the audio device used by a video output component.

• “New Offset TimeBase Functions” lists two offset timebase functions that help custom media handlers implement media latency.

• “Changes to Text Drawing” explains how QuickTime now uses the ATSUI text drawing engine instead of TextEdit.

• “Encoding Text Changes” describes changes to QuickTime’s internal behavior for encoding text.

• “New Release of QuickTime for Java” discusses QuickTime for Java 1.4.1, which provides new Java functionality for both Mac OS X and Windows.

QuickTime 6.4 API Reference provides interface details for all the functions, data structures, and callbacks that are new in QuickTime 6.4.

Summary of QuickTime 6 Versions

The following table summarizes the different point releases of QuickTime 6.

New Data Reference Functions

A number of data reference utility functions are new in QuickTime 6.4.

Seven new functions create new data references from various file specifications, pathnames, and URLs:

• QTNewDataReferenceFromFSRef creates an alias data reference from a file specification.

• QTNewDataReferenceFromFSRefCFString creates an alias data reference from a file reference pointing to a directory and a file name.

• QTNewDataReferenceFromFSSpec creates an alias data reference from a file specification of type FSSpec.

• QTNewDataReferenceWithDirectoryCFString creates an alias data reference from another alias data reference pointing to the parent directory and a CFString that contains the file name.

• QTNewDataReferenceFromFullPathCFString creates an alias data reference from a CFString that represents the full pathname of a file.

• QTNewDataReferenceFromCFURL creates a URL data reference from a CFURL.

• QTNewDataReferenceFromURLCFString creates a URL data reference from a CFString that represents a URL string.

Three functions return information about data references:

• QTGetDataReferenceDirectoryDataReference returns a new data reference for a parent directory.

• QTGetDataReferenceTargetNameCFString returns the name of the target of a data reference as a CFString.

• QTGetDataReferenceFullPathCFString returns the full pathname of the target of the data reference as a CFString.

Three functions return information about the storage location associated with a data handler:

• QTGetDataHandlerDirectoryDataReference returns a new data reference to the parent directory of the storage location associated with a data handler instance.

• QTGetDataHandlerTargetNameCFString returns the name of the storage location associated with a data handler.

• QTGetDataHandlerFullPathCFString returns the full pathname of the storage location associated with a data handler.

Six functions support data references for imported graphic images:

• GraphicsImportDoExportImageFileToDataRefDialog presents a dialog box that lets the user save an imported image in a foreign file format.

• GraphicsImportExportImageFileToDataRef saves an imported image in a foreign file format.

• GraphicsImportSaveAsPictureToDataRef creates a storage location that contains a QuickDraw picture for an imported image.

• GraphicsImportSaveAsQuickTimeImageFileToDataRef creates a storage location that contains a QuickTime image of an imported image.

• MovieImportDoUserDialogDataRef requests that a movie import component display its user dialog box.

• MovieImportSetMediaDataRef specifies a storage location that is to receive imported movie data.

Two functions perform data reference conversions on movies:

• ConvertMovieToDataRef converts a specified movie (or a single track within a movie) into a specified file format and stores it in a specified storage location.

• ConvertDataRefToMovieDataRef converts a piece of data in a storage location to a movie file format and stores it in another storage location, supporting a user settings dialog box for import operations.

Movie movieFromPath(CFStringRef path, BOOL allowQTUserInteraction)

{

    Movie     qtMovie = NULL;

    Handle    dataRef = NULL;

    OSType    dataRefType;

    OSErr     err;

    err = QTNewDataReferenceFromFullPathCFString(path,

                    kQTNativeDefaultPathStyle, 0, &dataRef, &dataRefType);

    if (NULL != dataRef) {

        err = NewMovieFromDataRef( &qtMovie,

                     ( allowQTUserInteraction ? 0 :

                                 newMovieDontAskUnresolvedDataRefs ),

                       NULL, dataRef, dataRefType );

       DisposeHandle(dataRef);

    }

    return qtMovie;

}

// From Cocoa URLs

Movie movieFromURL(NSURL *url, BOOL allowQTUserInteraction)

{

    Movie     qtMovie = NULL;

    Handle    dataRef = NULL;

    OSType    dataRefType;

    OSErr     err;

    err = QTNewDataReferenceFromCFURL((CFURLRef)url, 0, &dataRef,

                                         &dataRefType);

    if (NULL != dataRef) {

        err = NewMovieFromDataRef( &qtMovie,

                     ( allowQTUserInteraction ? 0 :

                                newMovieDontAskUnresolvedDataRefs ),

                     NULL, dataRef, dataRefType );

       DisposeHandle(dataRef);

    }

    return qtMovie;

}

// Writing to movie files

// Save with dependencies to a file

void writeMovieToFile(Movie qtMovie, CFStringRef path)

{

    Handle         dataRef = NULL;

    OSType         dataRefType;

    DataHandler    dataHandler;

    err = QTNewDataReferenceFromFullPathCFString(path,

                  kQTNativeDefaultPathStyle, 0, &dataRef, &dataRefType);

    err = CreateMovieStorage(dataRef, dataRefType, kHFCarbonCreatorCode,

                  kScriptTag,

    createMovieFileDeleteCurFile, &dataHandler, NULL);

    AddMovieToStorage(qtMovie, dataHandler);

    CloseComponent(dataHandler);

    DisposeHandle(dataRef);

}

// Cocoa variant of the above using NSData

- (void) writeMovie:(Movie)qtMovie toFile:(NSString *)path

{

    Handle    publicMovieHndl;

    NSData    *movieData;

    publicMovieHndl = NewHandle(0);

    PutMovieIntoHandle(qtMovie, publicMovieHndl);

    HLock(publicMovieHndl);

    movieData = [NSData dataWithBytes:*publicMovieHndl

                      length:GetHandleSize(publicMovieHndl)];

    DisposeHandle(publicMovieHndl);

    [movieData writeToFile:path atomically:YES];

    // set file attributes via NSFileManager

}

void writeFlattenedMovieToFile(Movie qtMovie, CFStringRef path)

{

    Handle    dataRef = NULL;

    OSType    dataRefType;

    err = QTNewDataReferenceFromFullPathCFString(path,

             kQTNativeDefaultPathStyle, 0, &dataRef, &dataRefType);

    err = FlattenMovieDataToDataRef(qtMovie, flattenAddMovieToDataFork,

                             dataRef, dataRefType, kHFSCreatorCode,

                             smSystemScript, createMovieFileDeleteCurFile);

    DisposeHandle(dataRef);

}

- (void) writeSoundMovieAsWAVEFile (Movie theMovie, NSString *path)

 {

    Handle         dataRef = NULL;

    OSType         dataRefType;

    DataHandler    dataHandler;

    err = QTNewDataReferenceFromFullPathCFString((CFStringRef)path,

              kQTNativeDefaultPathStyle, 0, &dataRef, &dataRefType);

    // use the default progress procedure, if any

    SetMovieProgressProc(theMovie, (MovieProgressUPP)-1L, 0);

    // export the movie into a file

    ConvertMovieToDataRef( theMovie,        // the movie to convert

                         NIL,               // all tracks in the movie

                         dataRef,           // the output data reference

                         dataRefType,       // the data ref type

                         kQTFileTypeWave,   // the output file type

                         kHFSCreatorCode,   // the output file creator

                         0L,                // no flags

                         NIL);              // no specific component

    DisposeHandle(dataRef);

}

Getting Ready to Use QuickTime from a Thread

To use QuickTime in the background on a preemptive thread, make a call to EnterMoviesOnThread from the thread before calling any other QuickTime functions from that thread. It is important that you call EnterMovies on your main thread before spawning any threads that call EnterMoviesOnThread.

EnterMoviesOnThread initializes QuickTime with an environment that is private to the thread. Calls to GetMoviesError or MoviesTask(null), for example, will not obtain errors or task movies in other threads.

User Interface Limited to the Main Thread

Currently, only the main thread can access the user interface. You can play movies or open user dialogs only from the main thread.

To perform an export operation that requires a user dialog, for example, you need to first execute the dialog on the main thread. You can then perform the actual export operation on a separate thread without tying up the user interface. You can pass the information returned by the dialog to another thread by passing an atom container, using functions that get settings as atom containers and set settings from atom containers.

Error Handling

Calling EnterMoviesOnThread indicates that QuickTime should perform additional thread-safety checks on components opened and operations performed on the thread. If you call a function that requires use of a non-thread-safe component, or requires access to the user interface, or performs another thread-unsafe operation, QuickTime returns a distinguished error (componentNotThreadSafeErr = -2098).

Not all QuickTime components are thread-safe, so your code should be designed to detect threading error messages and transfer necessary tasks to the main thread. For example, you might spawn a thread to import a list of image files. The thread would import all the image files that have thread-safe importer components and return a list of any unhandled cases to the main thread, which could then import any remaining image files in the foreground.

From the main thread, your application can call CSSetComponentsThreadMode, passing it kCSAcceptThreadSafeComponentsOnlyMode, to see if opening a movie or other QuickTime object will succeed when attempted from a preemptive thread. You can do this only with Mac OS X version 10.3 or later.

Using QuickTime From a Thread

It is important that you use multiple threads to perform tasks on different movies. Do not use multiple threads to act on the same movie concurrently.

You can work on a given movie in separate threads sequentially, for example to perform an export in the background after playing a movie in the foreground, by passing a data reference from one thread to another when you are through operating on the movie in the first thread.

QuickTime 6.4 includes the following functions that you can use to associate movies and time bases with threads:

• AttachMovieToCurrentThread attaches a movie to the current thread.

• AttachTimeBaseToCurrentThread attaches a time base to the current thread.

• DetachMovieFromCurrentThread detaches a movie from the current thread.

• DetachTimeBaseFromCurrentThread detaches a time base from the current thread.

• GetMovieThreadAttachState determines whether a given movie is attached to a thread.

• GetTimeBaseThreadAttachState determines whether a given time base is attached to a thread.

You can open movies in separate threads from the same source file, but each thread creates its own movie from the file. You can, however, play one movie while exporting the other, for example, which allows your application to behave as if it could concurrently process the same movie on different threads. This currently works with movies whose data is accessed from files, but not with movies accessed from a URL. The URL data handler is not currently thread-safe, so it is not possible to work with separate movies from the same URL in different threads.

Similarly, a thread-safe component type can be used by multiple threads at the same time, but each thread must instantiate its own instance of the component. Do not call a single component instance from multiple threads.

Many QuickTime functions that expect a component instance as a parameter also accept a component in that parameter. This ambiguity should generally be avoided when using different instances of the same component from multiple threads.

Cleaning Up

When your thread is done working with QuickTime, call ExitMoviesOnThread prior to closing the thread. Failure to do so may cause a memory leak, because resources allocated by EnterMoviesOnThread for the private QuickTime environment may fail to be released.

You may call EnterMoviesOnThread multiple times, which allows libraries to use this function without needing to know if their host thread has already done so. Subsequent calls do little more than increment a counter. To prevent memory leaks, one call to ExitMoviesOnThread should be made for each call to EnterMoviesOnThread.

Never call ExitMoviesOnThread without a prior call to EnterMoviesOnThread. Calls may be nested, but each instance of ExitMoviesOnThread must be balanced by a prior call to EnterMoviesOnThread.

Backward Compatibility

Because QuickTime did not previously support concurrent use from multiple threads, programs that already use QuickTime in preemptive threads may, accidentally or intentionally, make use of formerly global QuickTime states and data structures. For example, in older versions of QuickTime a call to MoviesTask(null) gives processor time to all movies in any thread. Similarly, an error handling routine in one thread might successfully detect errors in another.

While this kind of cross-thread interaction is more likely to do harm than good, the possibility exists that existing applications may rely on it. Consequently, if a thread makes calls to QuickTime without calling EnterMoviesOnThread, the thread shares QuickTime’s state and data structures on the main thread and any other threads that have not called EnterMoviesOnThread.

It is strongly recomended that you transition existing code away from any dependance on QuickTime states and data structures across threads as quickly as possible. When writing new code, threads that call QuickTime should use EnterMoviesOnThread to create private, thread-specific versions of the QuickTime environment.

Thread Safety Issues

For developers who are not familiar with QuickTime’s existing API, it’s possible to assume––largely because Mac OS X is multithreaded––that QuickTime is thread-safe. This is not the case. Your application can’t call QuickTime from arbitrary threads.

However, in some cases and with great care, in QuickTime 6.4 you are able to perform a few operations on secondary threads. The key point is that you can’t do it willy-nilly. If you need to use QuickTime on secondary threads, in limited cases, it is now possible.

The rules for new threads that call QuickTime are as follows:

• Call CSSetComponentsThreadMode(kCSAcceptThreadSafeComponentsOnlyMode) early on. This will instruct the Component Manager not to open non-thread-safe components from this thread.

• If you get componentNotThreadSafeErr from a QuickTime API call, the main thread must do the work instead.

Component developers should make their components thread-safe and set the new component flag cmThreadSafe.

The following parts of Mac OS X are newly thread-safe:

• QuickDraw

• the Component Manager

• the Alias Manager

• the Memory Manager (MemError is now per-thread.)

The following are not thread-safe:

• the Resource Manager

• Component RefCons for shared globals

In summary, you should unblock your user interface by moving slow QuickTime processing to other threads, cope with dynamic discovery of non-thread-safe media, and make your components thread-safe.

How Startup Synchronization Works

A time base may run at a nonzero rate, but the time will not move until a specific clock value is reached in order to make sure that each track can see the start time of the movie in the future.

When the rate changes to nonzero, the time base synchronizes its time with the current clock time by calculating an offset. It then tells the clock what it has done in order to reschedule any pending callbacks. An extra delay is added in this offset so that the time base time can be frozen to the current time until the delay is reached. The clock will ask the time base about this offset to properly adjust any atTime callback until the offset is reached.

The synchronization point between the time base and a clock is accomplished using the new functions listed in the previous section. Hardware developers should be able to take advantage of them in their applications.

UI Examples with QuickTime Dialogs as Sheets

The following code shows how to use an effect and standard compression dialog as a sheet.

- (QTAtomContainer) getEffectSettingsFromSheetOnWindow:(NSWindow *)parentWindow

{

  QTAtomContainer                 fxList = NULL;

  long                            minSrcs = 2;

  long                            maxSrcs = 2;

  QTEffectListOptions             lOpts = 0;

  QTEffectListOptions             dOpts = pdOptionsDisplayAsSheet;

  QTParameterDialog               paramDlg;

  QTEventLoopDescriptionRecord    eld;

  QTAtomContainer                 fxDesc = nil;

  OSErr                           myErr;

  myErr = QTGetEffectsList ( &fxList, minSrcs, maxSrcs, lOpts );

  myErr = QTNewAtomContainer ( &fxDesc );

  myErr = QTCreateStandardParameterDialog ( fxList, fxDesc,

                                             dOpts, &paramDlg );

  eld.recordSize = sizeof(eld);

  eld.windowRefKind = kEffectParentWindowCarbon;

  eld.parentWindow = [parentWindow windowRef];

  eld.eventTarget = NULL;

  QTStandardParameterDialogDoAction(paramDlg, pdActionRunInEventLoop, &eld);

  QTDismissStandardParameterDialog(gParamDlg);

  return fxList;

}

- (NSData *) getCustomAudioCompressionSettingsFromSheetOnWindow:(NSWindow  *)parentWindow

{

    ComponentInstance   ci;

    Handle              settingsHndl = NULL;

    ComponentResult     result = noErr;

    SCWindowSettings    windowSettings;

    NSData              *settingsAsData = nil;

    ci = OpenDefaultComponent(StandardCompressionType,

                                StandardCompressionSubTypeSound);

    // Tell the standard compression component to show the settings panel

    // as a sheet

    windowSettings.size = sizeof(SCWindowSettings);

    windowSettings.windowRefKind = scWindowRefKindCarbon;

    windowSettings.parentWindow = [parentWindow windowRef];

    (void)SCSetInfo(ci, scWindowOptionsType, &windowSettings);

    // Get compression settings from the user.

    result = SCRequestImageSettings(ci);

    // Get the settings back from the standard compression component

    result = SCGetInfo(ci, scSettingsStateType, &settingsHndl);

    if (NULL != settingsHndl) {

        HLock(settingsHndl);

        settingsAsData = [NSData dataWithBytes:*settingsHndl

                                 length:GetHandleSize(settingsHndl)];

        DisposeHandle(settingsHndl);

    }

    CloseComponent(ci);

    return settingsAsData;

}

IIDC Atoms

The information about IIDC features that a camera might support is contained in a hierarchy of new big-endian QuickTime atom types:

• At the top level, the QuickTime atom container passed into VDIIDCSetFeatures or returned by VDIIDCGetFeatures, VDIIDCGetDefaultFeatures, or VDIIDCGetFeaturesForSpecifier contains a set of atoms of type vdIIDCAtomTypeFeature, one for each feature of the camera being interrogated.

• Each atom of type vdIIDCAtomTypeFeature contains one atom of type vdIIDCAtomTypeFeatureAtomTypeAndID. This atom contains a data structure of type VDIIDCFeatureAtomTypeAndID, which conveys general information about the feature and specifies the type and ID of the atom that conveys that feature’s current settings.

• Each atom of type vdIIDCAtomTypeFeature also contains a Settings atom. This may be an atom of type vdIIDCAtomTypeFeatureSettings, vdIIDCAtomTypeTriggerSettings, vdIIDCAtomTypeFocusPointSettings, or vdIIDCAtomTypeLightingHintSettings, each of which stores a particular class of camera settings.

Details of the new atom types are given in the next sections. To determine the number of features in a particular atom container, you can use this code:

SInt16 featureCount = QTCountChildrenOfType(container,

    kParentAtomIsContainer, vdIIDCAtomTypeFeature);

vdIIDCFeatureHue                = 'hue ', // Uses VDIIDCFeatureSettings

vdIIDCFeatureSaturation         = 'satu', // Uses VDIIDCFeatureSettings

vdIIDCFeatureSharpness          = 'shrp', // Uses VDIIDCFeatureSettings

vdIIDCFeatureBrightness         = 'brit', // Uses VDIIDCFeatureSettings

vdIIDCFeatureGain               = 'gain', // Uses VDIIDCFeatureSettings

vdIIDCFeatureIris               = 'iris', // Uses VDIIDCFeatureSettings

vdIIDCFeatureShutter            = 'shtr', // Uses VDIIDCFeatureSettings

vdIIDCFeatureExposure           = 'xpsr', // Uses VDIIDCFeatureSettings

vdIIDCFeatureWhiteBalanceU      = 'whbu', // Uses VDIIDCFeatureSettings

vdIIDCFeatureWhiteBalanceV      = 'whbv', // Uses VDIIDCFeatureSettings

vdIIDCFeatureGamma              = 'gmma', // Uses VDIIDCFeatureSettings

vdIIDCFeatureTemperature        = 'temp', // Uses VDIIDCFeatureSettings

vdIIDCFeatureZoom               = 'zoom', // Uses VDIIDCFeatureSettings

vdIIDCFeatureFocus              = 'fcus', // Uses VDIIDCFeatureSettings

vdIIDCFeaturePan                = 'pan ', // Uses VDIIDCFeatureSettings

vdIIDCFeatureTilt               = 'tilt', // Uses VDIIDCFeatureSettings

vdIIDCFeatureOpticalFilter      = 'opft', // Uses VDIIDCFeatureSettings

vdIIDCFeatureTrigger            = 'trgr', // Uses VDIIDCTriggerSettings

vdIIDCFeatureCaptureSize        = 'cpsz', // Undefined settings

vdIIDCFeatureCaptureQuality     = 'cpql', // Undefined settings

vdIIDCFeatureFocusPoint         = 'fpnt', // Uses VDIIDCFocusPointSettings

vdIIDCFeatureEdgeEnhancement    = 'eden'  // Uses VDIIDCFeatureSettings

vdIIDCFeatureLightingHint       = 'lhnt'  // Uses VDIIDCLightingHintSetting

// Atom type and ID that contains the VDIIDCFeatureSettings struct

vdIIDCAtomTypeFeatureSettings       = 'fstg',

vdIIDCAtomIDFeatureSettings         = 1

// Atom type and ID that contains the VDIIDCTriggerSettings struct

vdIIDCAtomTypeTriggerSettings       = 'tstg',

vdIIDCAtomIDTriggerSettings         = 1

// Atom type and ID that contains the VDIIDCFocusPointSettings struct

vdIIDCAtomTypeFocusPointSettings     = 'fpst',

vdIIDCAtomIDFocusPointSettings       = 1

// Atom type and ID that contains the VDIIDCLightingHintSetting struct

vdIIDCAtomTypeLightingHintSettings   = 'lhst',

vdIIDCAtomIDLightingHintSettings     = 1

vdIIDCAtomTypeFeature    = 'feat'

    vdIIDCAtomTypeFeatureAtomTypeAndID    = 't&id'

    vdIIDCAtomIDFeatureAtomTypeAndID      = 1

        feature     = vdIIDCFeatureShutter            // shutter feature

        atomType    = vdIIDCAtomTypeFeatureSettings

        atomID      = 1

    vdIIDCAtomTypeFeatureSettings    = 'fstg'

    vdIIDCAtomIDFeatureSettings      = 1

vdIIDCAtomTypeFeature    = 'feat'

    vdIIDCAtomTypeFeatureAtomTypeAndID    = 't&id'

    vdIIDCAtomIDFeatureAtomTypeAndID      = 1

        feature     = vdIIDCFeatureFocus              // focus feature

        atomType    = vdIIDCAtomTypeFeatureSettings

        atomID      = 1

    vdIIDCAtomTypeFeatureSettings    = 'fstg'

    vdIIDCAtomIDFeatureSettings      = 1

vdIIDCAtomTypeFeature    = 'feat'

    vdIIDCAtomTypeFeatureAtomTypeAndID    = 't&id'

    vdIIDCAtomIDFeatureAtomTypeAndID      = 1

        feature     = vdIIDCFeatureTrigger            // trigger feature

        atomType    = vdIIDCAtomTypeTriggerSettings

        atomID      = 1

    vdIIDCAtomTypeTriggerSettings    = 'tstg'

    vdIIDCAtomIDFTriggerSettings     = 1

Goals

The goal of this release is to provide QuickTime for Java developers with a new version of QTJava that works with both JDK 1.3 and JDK 1.4.1 on Mac OS X. The current version of QTJava supports JDK 1.4.1, but only on Windows. The intent of this release is to provide a minimal set of functionality across all platforms.

QuickTime for Java 1.4.1 supports this goal by introducing a new quicktime.app.view package, adding other packages, and deprecating some existing packages. But note that all classes that are directly bound to the underlying QuickTime API, including all quicktime.std packages, remain the same and are supported. Developers will still have access to all the QuickTime features through Java using these bindings.

Because many features of QTJava are already available in standard Java, this refinement and simplification of the QTJava architecture has become necessary.

Hierarchy For All New Packages

This section describes the new packages and interfaces in QuickTime for Java 1.4.1, including the quicktime.app.view package, its class hierarchy and its interface hierarchy.

quicktime.app.time

quicktime.app.view

class java.lang.Object

    class quicktime.app.view. GraphicsImporterDrawer (implements

                                   quicktime.app.view.Presentable)

    class quicktime.app.view. MoviePlayer (implements

                                   quicktime.app.view.DrawingNotifier,

                                   quicktime.app.view.Presentable,

                                   quicktime.app.time. Timeable

    class quicktime.app.view. QTFactory

    class quicktime.app.view. QTImageProducer (implements

                                   java.awt.image.ImageProducer)

    class quicktime.app.time. Tasking (implements

                                   quicktime.app.time.Taskable)

    class quicktime.app.time. TaskAllMovies

    class quicktime.app.time. TaskThread (implements

                                   java.lang.Runnable)

interface quicktime.app.view. QTComponent

interface quicktime.app.view. QTJComponent

interface quicktime.app.time. Timeable

Migrating Existing Code to the New Classes

To take advantage of the new functionality in QuickTime for Java 1.4.1, developers will need to migrate their code to use the new classes and interfaces. This means rewriting existing application code.

New sample code, however, is listed below. It illustrates the usage of the new QTJava classes and methods. These new classes are backward compatible, so that you can use the same new classes on the Java 1.3 and 1.4.1 virtual machines.

SDK Examples That Work with JDK 1.4.1

The following SDK examples, accompanying this release, will work with JDK 1.4.1 and QuickTime for Java 1.4.1. You can build and compile these examples in Xcode on Mac OS X version 10.3:

AddTextMovie

PlaySound

TimeCallbackDemo

Applets

CustomMedia

KeyboardController

PlayTune

TimeCode

AudioBroadcaster

DetachedController

ImageFile

MovieCallbacks¸

SoundMemRecord

ImageProducing

MovieTextFinder

QTVector

SoundMeter

VRInteraction

ImportExport

Music

QTtoJavaImage

SoundRecord

CreatePictFile

DukeMovie

JavaDrawing

PlayMovie

The following SDK examples will not work with JDK 1.4.1 and QuickTime for Java 1.4.1. This is because these examples use presenters, compositing, or sprites, which are not supported.

JavaSprites

GroupDrawing

BouncingSprites

DraggingSprites

CurvesDemo

GraphicsExport

MediaPresenter

SlideShow

DraggingSpritesApplet

DrawableBroadcaster

WiredSprites

ImageCompositing

QTButtonDemo

QTEffects

Transitions

TextDemo

The following SDK examples are not yet implemented in QuickTime for Java 1.4.1:

SGCapture

TimeSlaving

SGCapture2Disk

Packages Not Supported in this Release

The following packages are not supported in QuickTime for Java 1.4.1:

quicktime.app.actions

quicktime.app.anim

quicktime.app.audio

quicktime.app.display

quicktime.app.event

quicktime.app.image

quicktime.app.players

quicktime.app.sg

quicktime.app.spaces

quicktime.app.ui

This means that such capabilities as compositing, animation with sprites and a sprite world, and the usage of spaces and controllers are not supported using the new classes in QuickTime for Java 1.4.1.

Although sequence grabbing is currently not supported in QuickTime for Java 1.4.1, it may be provided in future releases.

For developers, note that the QTDrawable interfaces, as well as QTCanvas and JQTCanvas, are not supported in QuickTime for Java 1.4.1. These interfaces and classes were part of the quicktime.app.display package and dealt with displaying QuickTime content in a Java AWT or Swing frame.

Note that quicktime.app.time is still supported, including classes such as TaskThread, Tasking, TaskAllMovies, and the Timeable interface.

The quicktime.app.view Package

The new quicktime.app.view package now deals with issues of display and the content that QuickTime can draw into Java. The underlying implementation is hidden: QTJava now provides a Java AWT or Java Swing component, based on what you want to use it for. This means that you won't need to access QTCanvas or subclass the component and add your own functionality as you want and draw into it. The component will already be constructed for you when you want to display a movie, an image, or a movie with a controller.

This new package includes the following classes:

• QTFactory (which has been moved from the quicktime.app package)

• QTImageProducer (moved from the quicktime.app.image package)

• MoviePlayer (moved from the quicktime.app.players package)

• GraphicsImporterDrawer (moved from the quicktime.app.image package)

The package also includes two new interfaces:

• QTComponent

• QTJComponent

The methods for these new interfaces and classes in the quicktime.app.view package are described in the Javadoc documentation accompanying QuickTime for Java 1.4.1.

The QTFactory class includes two new factory methods in addition to those already supported. These methods are

• makeQTComponent

• makeQTJComponent

Developers can use these new methods to create either QTComponent or QTJComponent objects. For example, you can use the makeQTComponent factory method, passing it a movie object, and it will return an instance of a QTComponent interface. Then, if you want, you can directly use this component, which is a regular AWT component, and add it to a Frame and display it.

QTComponent and QTJComponent provide you with interfaces to set and get the existing movie or image, whichever is displayed in the component. You pass in null as a parameter in order to remove an existing image or movie controller.

QTComponent has three set and get methods:

• setMovie and getMovie

• setMovieController and getMovieController

• setImage and getImage

The QTComponent and QTJComponent interfaces are implemented by the underlying component classes.

You can create a QTComponent object with an existing movie or image in it, and if you want to change the movie or image displayed, you can use the set methods to change the movie or image displayed in the component. If you just want to remove it, while cleaning up, you can pass in a null parameter.

To create a movie controller, you need to pass in a movie first. You create a movie object, pass it in to a movie controller, and create a movie controller object. Then you take this movie controller object and pass it to the makeQTComponent QuickTime factory method. This will return a Java AWT component with a movie and a controller attached and visible. This will be a regular QuickTime movie with a controller attached to it.

You use the makeQTJComponent method to create a QTJComponent, which is a Swing component. To display a movie inside a Swing component, you use the QTFactory.makeQTJComponent method.

Migrating Old QTJava Code to New QTJava Code

The following example illustrate some ways that you can migrate existing QuickTime for Java code—for example, code that uses QTCanvas—to the new classes and methods supported in release 1.4.1.

// Old Code :

// Movie Example Using QTCanvas :

// create movie from QTFile

QTFile qtfile = new QTFile (moviePath);

Movie mov = Movie.fromFile(qtfile);

MovieController mc = new MovieController(mov);

QTPlayer qtp = new QTPlayer(mc);

// create canvas and set the client

QTCanvas qtc = new QTCanvas ();

frame.add(qtc);

qtc.setClient(qtp, true);

frame.show();

// New Code :

// Movie Example Using QTFactory methods :

// create movie from QTFile

QTFile qtfile = new QTFile (moviePath);

Movie mov = Movie.fromFile(qtfile);

MovieController mc = new MovieController(mov);

// create component using factory methods

QTComponent movComp = QTFactory.makeQTComponent(mc);

frame.add((Component)movComp);

frame.show();

// Swing Example :

// Old Code :

// create movie from QTFile

QTFile qtfile = new QTFile (moviePath);

Movie mov = Movie.fromFile(qtfile);

MoviePlayer movPlayer = new MoviePlayer(mov);

// create JQTCanvas and set client

JQTCanvas jcanvas = new JQTCanvas();

jframe.getConentPane().add(jcanvas);

jcanvas.setClient(movPlayer, true);

jframe.show();

// New Code :

// create movie from QTFile

QTFile qtfile = new QTFile (moviePath);

Movie mov = Movie.fromFile(qtfile);

MoviePlayer movPlayer = new MoviePlayer(mov);

// create component using factory methods

QTJComponent  movComponent = QTFactory.makeQTJComponent(movPlayer);

jframe.getConentPane().add((JComponent)movComponent);

jframe.show();

Functions

The functions new to the QuickTime 6.4 API are documented alphabetically in this section.

AttachMovieToCurrentThread

Attaches a movie to the current thread.

OSErr AttachMovieToCurrentThread (Movie m);

AttachTimeBaseToCurrentThread

Attaches a time base to the current thread.

OSErr AttachTimeBaseToCurrentThread (TimeBase tb);

ClockGetRateChangeConstraints

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

ComponentResult ClockGetRateChangeConstraints (
   ComponentInstance    aClock,
   TimeRecord           *minimum,
   TimeRecord           *maximum );

ClockGetTimeForRateChange

Obtains the current rate change time according to a specific clock, a preferred time, and a safe increment duration.

ComponentResult ClockGetTimesForRateChange (
   ComponentInstance    aClock,
   Fixed                fromRate,
   Fixed                toRate,
   TimeRecord           *currentTime,
   TimeRecord           *preferredTime,
   TimeRecord           *safeIncrementForPreferredTime );

ConvertDataRefToMovieDataRef

Converts a piece of data in a storage location to a movie file format and stores it in another storage location, supporting a user settings dialog box for import operations.

OSErr ConvertDataRefToMovieDataRef (
   Handle               inputDataRef,
   OSType               inputDataRefType,
   Handle               outputDataRef,
   OSType               outputDataRefType,
   OSType               creator,
   long                 flags,
   ComponentInstance    userComp,
   MovieProgressUPP     proc,
   long                 refCon );

ConvertMovieToDataRef

Converts a specified movie (or a single track within a movie) into a specified file format and stores it in a specified storage location.

OSErr ConvertMovieToDataRef (
   Movie                theMovie,
   Track                onlyTrack,
   Handle               dataRef,
   OSType               dataRefType,
   OSType               fileType,
   OSType               creator,
   long                 flags,
   ComponentInstance    userComp );

ConvertTimeToClockTime

Converts a time record in a time base to clock time.

void ConvertTimeToClockTime ( TimeRecord *time );

DetachMovieFromCurrentThread

Detaches a movie from the current thread.

OSErr DetachMovieFromCurrentThread (Movie m);

DetachTimeBaseFromCurrentThread

Detaches a time base from the current thread.

OSErr DetachTimeBaseFromCurrentThread (TimeBase tb);

EnterMoviesOnThread

Indicates that the client will be using QuickTime on the current thread.

OSErr EnterMoviesOnThread (UInt32 inFlags);

ExitMoviesOnThread

Indicates to QuickTime that the client will no longer be using QuickTime on the current thread.

OSErr ExitMoviesOnThread (void);

GetMovieRateChangeConstraints

Returns the minimum and maximum delay you can get when a movie’s rate is changed.

void GetMovieRateChangeConstraints (
   Movie         theMovie,
   TimeRecord    *minimumDelay,
   TimeRecord    *maximumDelay );

GetMovieThreadAttachState

Determines whether a given movie is attached to a thread.

OSErr GetMovieThreadAttachState (
   Movie      m,
   Boolean    *outAttachedToCurrentThread,
   Boolean    *outAttachedToAnyThread );

GetTimeBaseMasterOffsetTimeBase

Allows an offset time base to retrieve the master time base it is attached to.

TimeBase GetTimeBaseMasterOffsetTimeBase ( TimeBase
tb );

GetTimeBaseRateChangeStatus

Lets a time base client determine the time base’s last rate change status.

void GetTimeBaseRateChangeStatus (
   TimeBase          tb,
   TimeScale         scale,
   Fixed             *rateChangedTo,
   TimeBaseStatus    *flags,
   TimeRecord        *rateChangeTimeBaseTime,
   TimeRecord        *rateChangeClockTime,
   TimeRecord        *currentClockTime );

GetTimeBaseThreadAttachState

Determines whether a given time base is attached to a thread.

OSErr GetTimeBaseThreadAttachState (
   TimeBase    inTimeBase,
   Boolean     *outAttachedToCurrentThread,
   Boolean     *outAttachedToAnyThread );

GraphicsExportGetInputCGBitmapContext

Retrieves the CGBitmapContext that the graphics exporter is using as its input image.

ComponentResult GraphicsExportGetInputCGBitmapContext
(
   GraphicsExportComponent    ci,
   CGContextRef               *bitmapContextRef );

GraphicsExportGetInputCGImage

Determines which Core Graphics CGImage is the source for a graphics export operation.

ComponentResult GraphicsExportGetInputCGImage (
   GraphicsExportComponent    ci,
   CGImageRef                 *imageRef );

GraphicsExportSetInputCGBitmapContext

Sets the CGBitmapContext that the graphics exporter will use as its input image.

ComponentResult GraphicsExportSetInputCGBitmapContext
(
   GraphicsExportComponent    ci,
   CGContextRef               bitmapContextRef );

GraphicsExportSetInputCGImage

Specifies a Core Graphics CGImage as the source for a graphics export operation.

ComponentResult GraphicsExportSetInputCGImage(
   GraphicsExportComponent    ci,
   CGImageRef                 imageRef );

GraphicsImportCreateCGImage

Imports an image as a Core Graphics CGImage.

ComponentResult GraphicsImportCreateCGImage (
   GraphicsImportComponent    ci,
   CGImageRef                 *imageRefOut,
   UInt32                     flags );

GraphicsImportDoExportImageFileToDataRefDialog

Presents a dialog box that lets the user save an imported image in a foreign file format.

ComponentResult GraphicsImportDoExportImageFileToDataRefDialog
(
   GraphicsImportComponent    ci,
   Handle                     inDefaultDataRef,
   OSType                     inDefaultDataRefType,
   CFStringRef                prompt,
   ModalFilterYDUPP           filterProc,
   OSType                     *outExportedType,
   Handle                     *outExportedDataRef,
   OSType                     *outExportedDataRefType );

GraphicsImportExportImageFileToDataRef

Saves an imported image in a foreign file format.

ComponentResult GraphicsImportExportImageFileToDataRef
(
   GraphicsImportComponent    ci,
   OSType                     fileType,
   OSType                     fileCreator,
   Handle                     dataRef,
   OSType                     dataRefType );

GraphicsImportGetDestinationColorSyncProfileRef

Retrieves a ColorSync profile from a graphics importer component.

GraphicsImportGetDestinationColorSyncProfileRef (
   GraphicsImportComponent   ci,
   CMProfileRef              *destinationProfileRef); 

GraphicsImportGetGenericColorSyncProfile

Retrieves the generic colorsync profile for a graphics importer component.

GraphicsImportGetGenericColorSyncProfile (
   GraphicsImportComponent    ci,
   OSType                     pixelFormat,
   void                       *reservedSetToNULL,
   UInt32                     flags,
   Handle                     *genericColorSyncProfileOut );

GraphicsImportGetOverrideSourceColorSyncProfileRef

Retrieves the override ColorSync profile for a graphics importer component.

ComponentResult GraphicsImportGetOverrideSourceColorSyncProfileRef
(
   GraphicsImportComponent   ci,
   CMProfileRef              *outOverrideSourceProfileRef );

GraphicsImportSaveAsPictureToDataRef

Creates a storage location that contains a QuickDraw picture for an imported image.

ComponentResult GraphicsImportSaveAsPictureToDataRef
(
   GraphicsImportComponent    ci,
   Handle                     dataRef,
   OSType                     dataRefType );

GraphicsImportSaveAsQuickTimeImageFileToDataRef

Creates a storage location that contains a QuickTime image of an imported image.

ComponentResult GraphicsImportSaveAsQuickTimeImageFileToDataRef
(
   GraphicsImportComponent    ci,
   Handle                     dataRef,
   OSType                     dataRefType );

GraphicsImportSetDestinationColorSyncProfileRef

Sets the ColorSync profile for a graphics importer component.

ComponentResult GraphicsImportSetDestinationColorSyncProfileRef
(
   GraphicsImportComponent   ci,
   CMProfileRef              newDestinationProfileRef);

GraphicsImportSetOverrideSourceColorSyncProfileRef

Sets the override ColorSync profile for a graphics importer component.

ComponentResult GraphicsImportSetOverrideSourceColorSyncProfileRef
(
   GraphicsImportComponent   ci,
   CMProfileRef              newOverrideSourceProfileRef);

GraphicsImportWillUseColorMatching

Asks whether GraphicsImportDraw will use color matching if called with the current importer settings.

ComponentResult GraphicsImportWillUseColorMatching
(
   GraphicsImportComponent   ci,
   Boolean                   *outWillMatch );

MovieImportDoUserDialogDataRef

Requests that a movie import component display its user dialog box.

ComponentResult MovieImportDoUserDialogDataRef (
   MovieImportComponent    ci,
   Handle                  dataRef,
   OSType                  dataRefType,
   Boolean                 *canceled );

MovieImportSetMediaDataRef

Specifies a storage location that is to receive imported movie data.

ComponentResult MovieImportSetMediaDataRef (
   MovieImportComponent    ci,
   Handle                  dataRef,
   OSType                  dataRefType );

QTAddComponentPropertyListener

Installs a callback to monitor a component property.

ComponentResult QTAddComponentPropertyListener (
   ComponentInstance                 inComponent,
   ComponentPropertyClass            inPropClass,
   ComponentPropertyID               inPropID,
   QTComponentPropertyListenerUPP    inDispatchProc,
   void                              *inUserData );

QTAddMoviePropertyListener

Installs a callback to monitor a movie property.

OSErr QTAddMoviePropertyListener (
   Movie                         inMovie,
   QTPropertyClass               inPropClass,
   QTPropertyID                  inPropID,
   QTMoviePropertyListenerUPP    inListenerProc,
   void                          *inUserData );

QTComponentPropertyListenerCollectionAddListener

Adds a listener callback for a specified property class and ID to a property listener collection.

OSStatus QTComponentPropertyListenerCollectionAddListener
(
   QTComponentPropertyListenersRef    inCollection,
   ComponentPropertyClass             inPropClass,
   ComponentPropertyID                inPropID,
   QTComponentPropertyListenerUPP     inListenerProc,
   const void                         *inListenerProcRefCon );

QTComponentPropertyListenerCollectionCreate

Creates a collection of component property monitors.

OSStatus QTComponentPropertyListenerCollectionCreate
(
   CFAllocatorRef                                        inAllocator,
   const QTComponentPropertyListenerCollectionContext    *inContext,
   QTComponentPropertyListenersRef                    *outCollection
);

Platform Considerations

This function can be used to create a collection for use with ComponentPropertyListenerCollectionAddListener, ComponentPropertyListenerCollectionRemoveListener, ComponentPropertyListenerCollectionNotifyListeners, ComponentPropertyListenerCollectionIsEmpty, and ComponentPropertyListenerCollectionHasListenersForProperty.

QTComponentPropertyListenerCollectionHasListenersForProperty

Determines if there are any listeners in a component property listener collection registered for a specified property class and ID.

Boolean QTComponentPropertyListenerCollectionHasListenersForProperty
(
   QTComponentPropertyListenersRef    inCollection,
   ComponentPropertyClass             inPropClass,
   ComponentPropertyID                inPropID );

QTComponentPropertyListenerCollectionIsEmpty

Determines if a listener collection is empty.

Boolean QTComponentPropertyListenerCollectionIsEmpty
(
   QTComponentPropertyListenersRef    inCollection );

QTComponentPropertyListenerCollectionNotifyListeners

Calls all listener callbacks in a component property listener collection registered for a specified property class and ID.

OSStatus QTComponentPropertyListenerCollectionNotifyListeners
(
   QTComponentPropertyListenersRef    inCollection,
   ComponentInstance                  inNotifier,
   ComponentPropertyClass             inPropClass,
   ComponentPropertyID                inPropID,
   const void                         *inFilterProcRefCon,
   UInt32                             inFlags );

QTComponentPropertyListenerCollectionRemoveListener

Removes a listener callback with a specified property class and ID from a property listener collection.

OSStatus QTComponentPropertyListenerCollectionRemoveListener
(
   QTComponentPropertyListenersRef    inCollection,
   ComponentPropertyClass             inPropClass,
   ComponentPropertyID                inPropID,
   QTComponentPropertyListenerUPP     inListenerProc,
   const void                         *inListenerProcRefCon)

QTGetComponentProperty

Returns the value of a specific component property.

ComponentResult QTGetComponentProperty (
   ComponentInstance         inComponent,
   ComponentPropertyClass    inPropClass,
   ComponentPropertyID       inPropID,
   ByteCount                 inPropValueSize,
   ComponentValuePtr         outPropValueAddress,
   ByteCount                 *outPropValueSizeUsed );

QTGetComponentPropertyInfo

Returns information about the properties of a component.

ComponentResult QTGetComponentPropertyInfo (
   ComponentInstance         inComponent,
   ComponentPropertyClass    inPropClass,
   ComponentPropertyID       inPropID,
   ComponentValueType        *outPropType,
   ByteCount                 *outPropValueSize,
   UInt32                    *outPropertyFlags );

QTGetDataHandlerDirectoryDataReference

Returns a new data reference to the parent directory of the storage location associated with a data handler instance.

OSErr  QTGetDataHandlerDirectoryDataReference (
   DataHandler    dh,
   UInt32         flags,
   Handle         *outDataRef,
   OSType         *outDataRefType );

QTGetDataHandlerFullPathCFString

Returns the full pathname of the storage location associated with a data handler.

OSErr QTGetDataHandlerFullPathCFString (
   DataHandler    dh,
   QTPathStyle    style,
   CFStringRef    *outPath );

QTGetDataHandlerTargetNameCFString

Returns the name of the storage location associated with a data handler.

OSErr  QTGetDataHandlerTargetNameCFString (
   DataHandler    dh,
   CFStringRef    *fileName );

QTGetDataReferenceDirectoryDataReference

Returns a new data reference for a parent directory.

OSErr QTGetDataReferenceDirectoryDataReference (
   Handle    dataRef,
   OSType    dataRefType,
   UInt32    flags,
   Handle    *outDataRef,
   OSType    *outDataRefType );

QTGetDataReferenceFullPathCFString

Returns the full pathname of the target of the data reference as a CFString.

OSErr QTGetDataReferenceFullPathCFString (
   Handle         dataRef,
   OSType         dataRefType,
   QTPathStyle    pathStyle,
   CFStringRef    *outPath );

QTGetDataReferenceTargetNameCFString

Returns the name of the target of a data reference as a CFString.

OSErr QTGetDataReferenceTargetNameCFString (
   Handle         dataRef,
   OSType         dataRefType,
   CFStringRef    *name );

QTGetMovieProperty

Returns the value of a specific movie property.

OSErr QTGetMovieProperty (
   Movie                 inMovie,
   QTPropertyClass       inPropClass,
   QTPropertyID          inPropID,
   ByteCount             inPropValueSize,
   QTPropertyValuePtr    outPropValueAddress,
   ByteCount             *outPropValueSizeUsed );

QTGetMoviePropertyInfo

Returns information about the properties of a movie.

OSErr QTGetMoviePropertyInfo (
   Movie                  inMovie,
   QTPropertyClass        inPropClass,
   QTPropertyID           inPropID,
   QTPropertyValueType    *outPropType,
   ByteCount              *outPropValueSize,
   UInt32                 *outPropertyFlags );

QTNewDataReferenceFromCFURL

Creates a URL data reference from a CFURL.

OSErr QTNewDataReferenceFromCFURL (
   CFURLRef    url,
   UInt32      flags,
   Handle      *outDataRef,
   OSType      *outDataRefType );

QTNewDataReferenceFromFSRef

Creates an alias data reference from a file specification.

OSErr QTNewDataReferenceFromFSRef (
   const FSSpec    *fsspec,
   UInt32          flags,
   Handle          *outDataRef,
   OSType          *outDataRefType );

QTNewDataReferenceFromFSRefCFString

Creates an alias data reference from a file reference pointing to a directory and a file name.

OSErr QTNewDataReferenceFromFSRefCFString (
   const FSRef    *directoryRef,
   CFStringRef    fileName,
   UInt32         flags,
   Handle         *outDataRef,
   OSType         *outDataRefType );

QTNewDataReferenceFromFSSpec

Creates an alias data reference from a file specification of type FSSpec.

OSErr QTNewDataReferenceFromFSSpec (
   const FSSpec    *fsspec,
   UInt32          flags,
   Handle          *outDataRef,
   OSType          *outDataRefType );

QTNewDataReferenceFromFullPathCFString

Creates an alias data reference from a CFString that represents the full pathname of a file.

OSErr QTNewDataReferenceFromFullPathCFString (
   CFStringRef    filePath,
   QTPathStyle    pathStyle,
   UInt32         flags,
   Handle         *outDataRef,
   OSType         *outDataRefType );

QTNewDataReferenceFromURLCFString

Creates a URL data reference from a CFString that represents a URL string.

OSErr QTNewDataReferenceFromURLCFString (
   CFStringRef    urlString,
   UInt32         flags,
   Handle         *outDataRef,
   OSType         *outDataRefType );

QTNewDataReferenceWithDirectoryCFString

Creates an alias data reference from another alias data reference pointing to the parent directory and a CFString that contains the file name.

OSErr QTNewDataReferenceWithDirectoryCFString (
   Handle         inDataRef,
   OSType         inDataRefType,
   CFStringRef    targetName,
   UInt32         flags,
   Handle         *outDataRef,
   OSType         *outDataRefType );

QTRemoveComponentPropertyListener

Removes a component property monitoring callback.

ComponentResult QTRemoveComponentPropertyListener (
   ComponentInstance                 inComponent,
   ComponentPropertyClass            inPropClass,
   ComponentPropertyID               inPropID,
   QTComponentPropertyListenerUPP    inDispatchProc,
   void                              *inUserData );   /* can be
NULL */

QTRemoveMoviePropertyListener

Removes a movie property monitoring callback.

OSErr QTRemoveMoviePropertyListener (
   Movie                         inMovie,
   QTPropertyClass               inPropClass,
   QTPropertyID                  inPropID,
   QTMoviePropertyListenerUPP    inListenerProc,
   void                          *inUserData );

QTSetComponentProperty

Sets the value of a specific component property.

ComponentResult QTSetComponentProperty (
   ComponentInstance         inComponent,
   ComponentPropertyClass    inPropClass,
   ComponentPropertyID       inPropID,
   ByteCount                 inPropValueSize,
   ConstComponentValuePtr    inPropValueAddress );

QTSetMovieProperty

Sets the value of a specific movie property.

OSErr QTSetMovieProperty (
   Movie                      inMovie,
   QTPropertyClass            inPropClass,
   QTPropertyID               inPropID,
   ByteCount                  inPropValueSize,
   ConstQTPropertyValuePtr    inPropValueAddress );

QTVideoOutputCopyIndAudioOutputDeviceUID

Identifies the audio device being used by a video output component.

OSErr QTVideoOutputCopyIndAudioOutputDeviceUID (
   QTVideoOutputComponent    vo,
   long                      index,
   CFStringRef               *audioDeviceUID );

SetTimeBaseOffsetTimeBase

Attaches an offset time base to another time base.

OSErr SetTimeBaseOffsetTimeBase ( 
   TimeBase            masterOffsetTimeBase,
   TimeBase            offsetTimeBase,
   const TimeRecord    *offsetZero );

VDIIDCGetCSRData

Reads a camera’s CSR registers directly.

VideoDigitizerError VDIIDCGetCSRData (
   VideoDigitizerComponent    ci,
   Boolean                    offsetFromUnitBase,
   UInt32                     offset,
   UInt32*                    data );

VDIIDCGetDefaultFeatures

Places atoms in a QuickTime atom container that specify the default capabilities and default state of a camera’s IIDC features.

VideoDigitizerError VDIIDCGetDefaultFeatures (
   VideoDigitizerComponent    ci,
   QTAtomContainer            *container );

VDIIDCGetFeatures

Places atoms in a QuickTime atom container that specify the current capabilities of a camera and the state of its IIDC features.

VideoDigitizerError VDIIDCGetFeatures (
   VideoDigitizerComponent    ci,
   QTAtomContainer            *container );

VDIIDCGetFeaturesForSpecifier

Places atoms in a QuickTime atom container that specify the current state of a single camera IIDC feature or group of features.

VideoDigitizerError VDIIDCGetFeaturesForSpecifier (
   VideoDigitizerComponent    ci,
   OSType                     specifier,
   QTAtomContainer            *container );

VDIIDCSetCSRData

Writes to a camera’s CSR registers directly.

VideoDigitizerError VDIIDCSetCSRData (
   VideoDigitizerComponent    ci,
   Boolean                    offsetFromUnitBase,
   UInt32                     offset,
   UInt32*                    data );

VDIIDCSetFeatures

Changes the state of a camera’s IIDC features.

VideoDigitizerError VDIIDCSetFeatures (
   VideoDigitizerComponent    ci,
   QTAtomContainer            *container );

Callbacks

The callback functions new to the QuickTime 6.4 API are documented alphabetically in this section.

QTComponentPropertyListenerFilterProc

Supports QTComponentPropertyListenerCollectionNotifyListeners.

typedef Boolean (*QTComponentPropertyListenerFilterProcPtr) (QTComponentPropertyListenersRef
inCollection, const QTComponentPropertyListenerCollectionContext
*inCollectionContext, ComponentInstance inNotifier, ComponentPropertyClass
inPropClass, ComponentPropertyID inPropID, QTComponentPropertyListenerUPP inListenerCallbackProc,
const void *inListenerProcRefCon, const void *inFilterProcRefCon);

// Declaration of a typical application-defined function
Boolean MyQTComponentPropertyListenerFilterProc (
   QTComponentPropertyListenersRef    inCollection, 
   const QTComponentPropertyListenerCollectionContext
   *inCollectionContext,
   ComponentInstance                  inNotifier,
   ComponentPropertyClass             inPropClass,
   ComponentPropertyID                inPropID,
   QTComponentPropertyListenerUPP     inListenerCallbackProc,
   const void                         *inListenerProcRefCon,
   const void                         *inFilterProcRefCon );

QTComponentPropertyListenerProc

Supports QTAddComponentPropertyListener and QTRemoveComponentPropertyListener.

typedef void (*QTComponentPropertyListenerProcPtr)
(ComponentInstance inComponent, ComponentPropertyClass inPropClass,
ComponentPropertyID inPropID, void *inUserData);

// Declaration of a typical application-defined function
void MyQTComponentPropertyListenerProc (
   ComponentInstance         inComponent,
   ComponentPropertyClass    inPropClass,
   ComponentPropertyID       inPropID,
   void                      *inUserData );

QTMoviePropertyListenerProc

Supports QTAddMoviePropertyListener and QTRemoveMoviePropertyListener.

typedef void (*QTMoviePropertyListenerProcPtr) (Movie
inMovie, QTPropertyClass inPropClass, QTPropertyID inPropID, void
*inUserData);

// Declaration of a typical application-defined function
void MyQTMoviePropertyListenerProc (
   Movie              inMovie,
   QTPropertyClass    inPropClass,
   QTPropertyID       inPropID,
   void               *inUserData );

Data Structures

The data structures new to the QuickTime 6.4 API are documented alphabetically in this section.

QTComponentPropertyInfo

Stores information for component property functions.

struct ComponentPropertyInfo {
   ComponentPropertyClass    propClass;
   ComponentPropertyID       propID;
   ComponentValueType        propType;
   ByteCount                 propSize;
   UInt32                    propFlags;
};

Fields

propClass

A value of type OSType that specifies a property class:

kComponentPropertyClassPropertyInfo ('pnfo')

A QTComponentPropertyInfo structure that defines a property information class.

kComponentPropertyInfoList ('list')

An array of QTComponentPropertyInfo structures, one for each property.

kComponentPropertyCacheSeed ('seed')

A component property cache seed value.

kComponentPropertyExtendedInfo ('meta')

A CFDictionary with extended property information.

kComponentPropertyCacheFlags ('flgs')

One of the following two flags:

kComponentPropertyCacheFlagNotPersistent

Property metadata should not be saved in persistent cache.

kComponentPropertyCacheFlagIsDynamic

Property metadata should not be cached at all.

propID

A value of type OSType that specifies a property ID.

propType

The type of the property.

propSize

The size of the property in bytes.

propFlags

Component property flags.

Platform Considerations

Associated functions: QTAddComponentPropertyListener, QTComponentPropertyListenerCollectionAddListener, QTComponentPropertyListenerCollectionHasListenersForProperty, QTComponentPropertyListenerCollectionNotifyListeners, QTComponentPropertyListenerCollectionRemoveListener, QTGetComponentProperty, QTGetComponentPropertyInfo, QTRemoveComponentPropertyListener, QTSetComponentProperty, QTComponentPropertyListenerFilterProc, QTComponentPropertyListenerProc

QTComponentPropertyListenerCollectionContext

Provides context information for a QTComponentPropertyListenerFilterProc callback.

struct QTComponentPropertyListenerCollectionContext
{
UInt32                                  version;
QTComponentPropertyListenerFilterUPP    filterProcUPP;
void                                    *filterProcData;
};

Fields

version

The version of this callback.

filterProcUPP

A Universal Procedure Pointer to a QTComponentPropertyListenerFilterProc callback.

filterProcData

A pointer to data for the callback.

Platform Considerations

Associated function: QTComponentPropertyListenerCollectionNotifyListeners

VDIIDCFeatureAtomTypeAndID

Provides content for the vdIIDCAtomTypeFeatureAtomTypeAndID atom type. See Type And ID Atoms.

struct VDIIDCFeatureAtomTypeAndID {
   OSType        feature;
   OSType        group;
   Str255        name;
   QTAtomType    atomType;
   QTAtomID      atomID;
};

Fields

feature

Type of the feature (see Discussion below).

group

Group that categorizes the feature (see Discussion below).

name

Name of the feature.

atomType

Atom type that contains the feature’s settings. See IIDC Settings Atoms.

atomID

Atom ID of the atom that contains the feature’s settings.

// IIDC Feature OSTypes

    vdIIDCFeatureHue            = 'hue ', // Uses VDIIDCFeatureSettings

    vdIIDCFeatureSaturation     = 'satu', // Uses VDIIDCFeatureSettings

    vdIIDCFeatureSharpness      = 'shrp', // Uses VDIIDCFeatureSettings

    vdIIDCFeatureBrightness     = 'brit', // Uses VDIIDCFeatureSettings

    vdIIDCFeatureGain           = 'gain', // Uses VDIIDCFeatureSettings

    vdIIDCFeatureIris           = 'iris', // Uses VDIIDCFeatureSettings

    vdIIDCFeatureShutter        = 'shtr', // Uses VDIIDCFeatureSettings

    vdIIDCFeatureExposure       = 'xpsr', // Uses VDIIDCFeatureSettings

    vdIIDCFeatureWhiteBalanceU  = 'whbu', // Uses VDIIDCFeatureSettings

    vdIIDCFeatureWhiteBalanceV  = 'whbv', // Uses VDIIDCFeatureSettings

    vdIIDCFeatureGamma          = 'gmma', // Uses VDIIDCFeatureSettings

    vdIIDCFeatureTemperature    = 'temp', // Uses VDIIDCFeatureSettings

    vdIIDCFeatureZoom           = 'zoom', // Uses VDIIDCFeatureSettings

    vdIIDCFeatureFocus          = 'fcus', // Uses VDIIDCFeatureSettings

    vdIIDCFeaturePan            = 'pan ', // Uses VDIIDCFeatureSettings

    vdIIDCFeatureTilt           = 'tilt', // Uses VDIIDCFeatureSettings

    vdIIDCFeatureOpticalFilter  = 'opft', // Uses VDIIDCFeatureSettings

    vdIIDCFeatureTrigger        = 'trgr', // Uses VDIIDCTriggerSettings

    vdIIDCFeatureCaptureSize    = 'cpsz', // Undefined settings

    vdIIDCFeatureCaptureQuality = 'cpql', // Undefined settings

    vdIIDCFeatureFocusPoint     = 'fpnt', // Use VDIIDCFocusPointSettings

    vdIIDCFeatureEdgeEnhancement = 'eden' // Uses VDIIDCFeatureSettings

    vdIIDCFeatureLightingHint   = 'lhnt'  // Use VDIIDCLightingHintSettings

// IIDC Group OSTypes that features are categorized into

    vdIIDCGroupImage        = 'imag',    // Related to image control

    vdIIDCGroupColor        = 'colr',    // Related to color control

    vdIIDCGroupMechanics    = 'mech',    // Related to mechanics

    vdIIDCGroupTrigger      = 'trig'     // Related to trigger

Platform Considerations

Associated functions: VDIIDCGetDefaultFeatures, VDIIDCGetFeatures, VDIIDCGetFeaturesForSpecifier

VDIIDCFeatureCapabilities

Provides IIDC feature capabilities information to the VDIIDCFeatureSettings data structure.

struct VDIIDCFeatureCapabilities {
   UInt32           flags;
   UInt16           rawMinimum;
   UInt16           rawMaximum;
   QTFloatSingle    absoluteMinimum;
   QTFloatSingle    absoluteMaximum;
};

Fields

flags

Flags that determine characteristics of a given feature.

vdIIDCFeatureFlagOn

Set if feature can be turned on.

vdIIDCFeatureFlagOff

Set if the feature can be turned off.

vdIIDCFeatureFlagManual

Set if the feature can be put into manual mode.

vdIIDCFeatureFlagAuto

Set if the feature can be put into automatic mode.

vdIIDCFeatureFlagTune

Set if the feature can be tuned. When tuned, a feature drops into automatic mode until it stabilizes and then it reverts to manual mode.

vdIIDCFeatureFlagRawControl

Set if the feature’s value can be specified in raw values. Raw values are unitless and their meaning can vary from camera to camera.

vdIIDCFeatureFlagAbsoluteControl

Set if the feature’s value can be specified in absolute units. Absolute values are expressed in engineering units, such as dB or degrees.

rawMinimum

Raw minimum value.

rawMaximum

Raw maximum value.

absoluteMinimum

Absolute minimum value.

absoluteMaximum

Absolute maximum value.

Platform Considerations

Associated functions: VDIIDCGetDefaultFeatures, VDIIDCGetFeatures, VDIIDCGetFeaturesForSpecifier

VDIIDCFeatureSettings

Provides content for the vdIIDCAtomTypeFeatureSettings atom type. See IIDC Feature Atoms.

struct VDIIDCFeatureSettings {
   VDIIDCFeatureCapabilities    capabilities;
   VDIIDCFeatureState           state;
};

Fields

capabilities

A VDIIDCFeatureCapabilities data structure that describes a camera’s feature capabilities.

state

A VDIIDCFeatureState data structure that describes a camera’s current feature state.

Platform Considerations

Associated functions: VDIIDCGetDefaultFeatures, VDIIDCGetFeatures, VDIIDCGetFeaturesForSpecifier, VDIIDCSetFeatures (uses only the state field)

VDIIDCFeatureState

Provides IIDC feature state information for the VDIIDCFeatureSettings data structure.

struct VDIIDCFeatureState {
   UInt32           flags;
   QTFloatSingle    value;
};

Fields

flags

Feature flags.

value

Feature value.

Platform Considerations

Associated functions: VDIIDCGetDefaultFeatures, VDIIDCGetFeatures, VDIIDCGetFeaturesForSpecifier, VDIIDCSetFeatures

VDIIDCFocusPointSettings

Provides focus point data for the vdIIDCAtomTypeFocusPointSettings atom type. See IIDC Settings Atoms.

struct VDIIDCFocusPointSettings {
   Point    focusPoint;
};

Fields

focusPoint

A focus point value relative to the rectangle returned by SGGetSrcVideoBounds. When using this data structure to set the focus point, the focus point must be within the rectangle specified by SGSetVideoRect.

Platform Considerations

Associated functions: VDIIDCGetDefaultFeatures, VDIIDCGetFeatures, VDIIDCGetFeaturesForSpecifier, VDIIDCSetFeatures

VDIIDCLightingHintSettings

Provides lighting hint data for the vdIIDCAtomTypeLightingHintSettings atom type. See IIDC Settings Atoms.

struct VDIIDCLightingHintSettings {
   UInt32    capabilityFlags;
   UInt32    stateFlags;
};

Fields

capabilityFlags

Flags that specify particular lighting hint capabilities. This field is ignored by the VDIIDCSetFeatures function:

vdIIDCLightingHintNormal

Set if the camera supports the normal light hint.

vdIIDCLightingHintLow

Set if the camera supports the low light hint.

stateFlags

Flags that specify particular lighting hint states:

vdIIDCLightingHintNormal

Set if the camera is using or should be using the normal light hint.

vdIIDCLightingHintLow

Set if the camera is using or should be using the low light hint.

Platform Considerations

Associated functions: VDIIDCGetDefaultFeatures, VDIIDCGetFeatures, VDIIDCGetFeaturesForSpecifier, VDIIDCSetFeatures

VDIIDCTriggerCapabilities

Provides IIDC trigger capability information for the VDIIDCTriggerSettings data structure.

struct VDIIDCTriggerCapabilities {
   UInt32           flags;
   QTFloatSingle    absoluteMinimum;
   QTFloatSingle    absoluteMaximum;
};

Fields

flags

Flags that specify particular trigger capabilities:

vdIIDCTriggerFlagOn

Set if the trigger can be turned on.

vdIIDCTriggerFlagOff

Set if the trigger can be turned off.

vdIIDCTriggerFlagActiveHigh

Set if the trigger can be active high.

vdIIDCTriggerFlagActiveLow

Set if the trigger can be active low.

vdIIDCTriggerFlagMode0

Set if the trigger can operate in mode 0. In mode 0, the camera starts integrating light at the active edge of the external trigger. The integration time is controlled by the shutter feature.

vdIIDCTriggerFlagMode1

Set if the trigger can operate in mode 1. In mode 1, the camera starts integrating light at the active edge of the external trigger. The integration time is equal to the time the trigger is active.

vdIIDCTriggerFlagMode2

Set if the trigger can operate in mode 2. In mode 2, the camera starts integrating light at the active edge of the external trigger. Integration continues until the nth active edge, where n is greater than or equal to 2.

vdIIDCTriggerFlagMode3

Set if the trigger can operate in mode 3. In mode 3, the camera starts integrating light at the active edge of the internal trigger. The trigger’s cycle time is n times the cycle time of the fastest frame rate, where n is greater than or equal to 1. Integration time is controlled by the shutter feature.

vdIIDCTriggerFlagRawControl

Set if the trigger’s value can be specified in unitless terms.

vdIIDCTriggerFlagAbsoluteControl

Set if the trigger’s value can be specified in absolute (engineering) units of time.

absoluteMinimum

The minimum trigger value when vdIIDCTriggerFlagAbsoluteControl is set.

absoluteMaximum

The maximum trigger value when vdIIDCTriggerFlagAbsoluteControl is set.

Platform Considerations

Associated functions: VDIIDCGetDefaultFeatures, VDIIDCGetFeatures, VDIIDCGetFeaturesForSpecifier,

VDIIDCTriggerSettings

Provides trigger data for the vdIIDCAtomTypetriggerSettings atom type. See IIDC Settings Atoms.

struct VDIIDCTriggerSettings {
   VDIIDCTriggerCapabilities    capabilities;
   VDIIDCTriggerState           state;
};

Fields

capabilities

A VDIIDCTriggerCapabilities data structure.

state

A VDIIDCTriggerState data structure.

Platform Considerations

Associated functions: VDIIDCGetDefaultFeatures, VDIIDCGetFeatures, VDIIDCGetFeaturesForSpecifier, VDIIDCSetFeatures

VDIIDCTriggerState

Provides IIDC trigger state information for the VDIIDCTriggerSettings data structure.

struct VDIIDCTriggerState {
   UInt32           flags;
   UInt16           mode2TransitionCount;
   UInt16           mode3FrameRateMultiplier;
   QTFloatSingle    absoluteValue;
};

Fields

flags

Flags that specify current or default trigger settings (depending on whether VDIIDCGetFeatures, VDIIDCSetFeatures, or VDIIDCGetDefaultFeatures was originally called):

vdIIDCTriggerFlagOn

Set if the trigger is or should be turned on.

vdIIDCTriggerFlagOff

Set if the trigger is or should be turned off.

vdIIDCTriggerFlagActiveHigh

Set if the trigger is or should be active high.

vdIIDCTriggerFlagActiveLow

Set if the trigger is or should be active low.

vdIIDCTriggerFlagMode0

Set if the trigger is or should operate in mode 0. In mode 0, the camera starts integrating light at the active edge of the external trigger. The integration time is controlled by the shutter feature.

vdIIDCTriggerFlagMode1

Set if the trigger is or should operate in mode 1. In mode 1, the camera starts integrating light at the active edge of the external trigger. The integration time is equal to the time the trigger is active.

vdIIDCTriggerFlagMode2

Set if the trigger is or should operate in mode 2. In mode 2, the camera starts integrating light at the active edge of the external trigger. Integration continues until the nth active edge, where n is greater than or equal to 2.

vdIIDCTriggerFlagMode3

Set if the trigger is or should operate in mode 3. In mode 3, the camera starts integrating light at the active edge of the internal trigger. The trigger’s cycle time is n times the cycle time of the fastest frame rate, where n is greater than or equal to 1. Integration time is controlled by the shutter feature.

vdIIDCTriggerFlagRawControl

Set if the trigger’s value is or should be specified in unitless terms.

vdIIDCTriggerFlagAbsoluteControl

Set if the trigger’s value is or should be specified in absolute (engineering) units of time.

mode2TransitionCount

When mode 2 is set, the current or default number of transitions.

mode3FrameRateMultiplier

When mode 3 is set, the current or default frame rate multiplier.

absoluteValue

When using absolute units, the QTFloatSingle representation of the value in either mode2TransitionCount (if mode 2 is set) or mode3FrameRateMultiplier (if mode 3 is set).

Platform Considerations

Associated functions: VDIIDCGetDefaultFeatures, VDIIDCGetFeatures, VDIIDCGetFeaturesForSpecifier, VDIIDCSetFeatures

VDIIDC Call Selectors

The following selectors apply to VDIIDC component calls:

    kVDIIDCGetFeaturesSelect                = 0x0200,

    kVDIIDCSetFeaturesSelect                = 0x0201,

    kVDIIDCGetDefaultFeaturesSelect         = 0x0202,

    kVDIIDCGetCSRDataSelect                 = 0x0203,

    kVDIIDCSetCSRDataSelect                 = 0x0204,

    kVDIIDCGetFeaturesForSpecifierSelect    = 0x0205