10.2 The QuickTime API

The QuickTime API is large and complex, and the underlying API's original native heritage makes it especially hard for a Java developer to get a handle on it. Fortunately, the QuickTime for Java bindings help you write your application, but they can be difficult to understand without first examining the native layer.

10.2.1 Native Origins

QuickTime's architecture is based on the original Mac OS APIs, in which each API cluster was referred to as a "toolbox" or a "manager." This section looks at the overall architecture of QuickTime and walks through some of the fundamental building blocks. This book cannot explore every nuance of QuickTime, but this section should help you understand how all the pieces fit together.

A few basic packages provide the conceptual underpinnings for QuickTime: Movie Toolbox, Image Compression Manager, Image Decompressor Manager, and Component Manager. A set of predefined components provides much of the implementation. Figure 10-3 shows how these elements relate to an application that is playing a movie.

Figure 10-3. QuickTime architecture

10.2.1.1 The Movie Toolbox

A native application's primary interface to QuickTime is the Movie Toolbox. This API set lets you store, retrieve, and manipulate time-based data stored in QuickTime movies. A single movie may contain several types of data. For example, a movie that contains video information might include both video data and the sound data that accompanies that video.

The Movie Toolbox also provides functionality for editing movies. For example, editing functions shorten a movie by removing portions of the video and sound tracks, and other functions extend a movie by adding new data from other QuickTime movies.

10.2.1.2 The Image Compression Manager

Image data requires a large amount of storage space. Storing a single 640 x 480 pixel image in 32-bit color can require as much as 1.2 MB of disk space. Sequences of images, like those that might be contained in a QuickTime movie, demand substantially more storage than do single images. This is true even for sequences that consist of fairly small images because the movie consists of a large number of those images. Consequently, minimizing the storage requirements for image data is an important consideration for any application that works with images or sequences of images.

The Image Compression Manager provides a device-independent and driver-independent means of compressing and decompressing images and image sequences. It also contains a simple interface for implementing software and hardware image-compression algorithms. Images can be imported and exported easily from many formats. In most cases, applications use the Image Compression Manager indirectly by calling Movie Toolbox functions or displaying a compressed picture.

10.2.1.3 The Component Manager

QuickTime provides components as an abstraction so that every application doesn't need to know about all possible types of audio, visual, and storage devices. A component is essentially a library or plug-in registered by the Component Manager. The component's code can be available as a system-wide resource, or in a resource that is local to a particular application.

QuickTime provides a number of useful default components for application developers. These components provide essential services to your application and to the managers that comprise the QuickTime architecture. QuickTime uses the following Apple-defined components:

Movie controller components, which allow applications to play movies by using a standard user interface
Standard image-compression dialog components, which allow the user to specify the parameters for a compression operation through a dialog box or similar mechanism
Image compressor components, which compress and decompress image data
Sequence grabber components, which allow applications to preview and record video and sound data as QuickTime movies
Video digitizer components, which allow applications to control video digitization by an external device
Media data-exchange components, which allow applications to move various types of data in and out of a QuickTime movie
Derived media handler components, which allow QuickTime to support new types of data in QuickTime movies
Clock components, which provide timing services defined for QuickTime applications
Preview components, which the Movie Toolbox's standard file preview functions use to display and create visual previews for files
Sequence grabber channel components, which manipulate captured data for a sequence grabber component
Sequence grabber panel components, which allow sequence grabber components to obtain configuration information from the user for a particular sequence grabber channel component

Applications gain access to components by calling the Component Manager. Once an application connects to a component, it calls that component directly.

10.2.1.4 Atoms

QuickTime stores most of its data by using its own custom memory structures called atoms. Movies and each of their individual tracks are organized and stored as atoms, as are various media and data samples. In fact, this is the last step before actually writing a movie file to disk. In this way, many atoms, called classic atoms (or simply "atoms"), contain both data and references to other atoms.

Atoms that contain only data and not other atoms are called leaf atoms. QuickTime in particular uses both classic and leaf atoms to form hierarchies of data, treelike structures that represent complex media files. QuickTime provides a complete API set for accessing and manipulating both types of atoms.

10.2.2 QuickTime for Java

To allow Java programmers access to QuickTime's native APIs, Apple provides bindings for the underlying QuickTime components. Fortunately, Apple's bindings between QuickTime and Java are more sophisticated than a simple API translation. In addition to providing simple APIs, QuickTime for Java provides an additional application framework to assist with integration into Java applications.

The quicktime.app package is the core of the QuickTime and Java binding set. The classes in this package present different kinds of media. The framework uses the interfaces in quicktime.app to abstract and express common functionality that exists between different QuickTime objects.

As such, the services that the QuickTime for Java application framework renders to the developer belong to the following categories:

Integration of QuickTime with the Java runtime environment, which includes sharing display space between Java and QuickTime and passing events from Java into QuickTime
A set of classes that provides services that simplify the authoring of QuickTime content and operation
Creation of objects that present different forms of media, using QTFactory.makeDrawable( ) methods
Various utilities (classes and methods) that deal with single images as well as groups of related images
Spaces and controllers architecture, which allows you to deal with complex data-generation or presentation requirements
Composition services that allow complex layering and blending of different image sources
Timing services that let you schedule and control time-related activities
Video and audio media capturing from external sources
Exposure of the QuickTime visual effects architecture

10.2.2.1 Understanding the Java bindings

The QuickTime Java classes that represent media types are created from structures and data types from the standard QuickTime C language header files. These data types provide the QuickTime for Java API basic class structure. For example, the Movie data type in Movies.h becomes the Movie class in Java; functions in C become methods in Java; and capitalization and notation conventions are changed to match the Java language. However, there is a slight twist?most QuickTime C functions have in the method name the object being operated on (remember that C is not object-oriented), creating a more procedural approach. To translate this approach to an object-oriented Java environment, classes are created for each object, and methods are bound to that object.

For example, the QuickTime native function SetMovieGWorld logically translates (or is bound by) the Java method setGWorld( ) on the Movie class. Similarly, the QuickTime native function MCSetControllerPort logically translates (or is bound by) the Java method setPort( ) on the MovieController class.

The QuickTime for Java SDK provides a complete list of the QuickTime functions that QuickTime for Java binds. The supplied HTML documentation for these binding calls provides only brief descriptions, often little more than function names and parameter lists. Therefore, you'll often need to refer to the native documentation to understand the use of a given class or method, or even the general purpose of the API.