QuickTime for Java: A Developer's Notebook/Working with Components - Revision history

Newacct at 01:16, 29 January 2010

Newacct — Fri, 29 Jan 2010 01:16:32 GMT

←Older revision		Revision as of 01:16, 29 January 2010
Line 42:		Line 42:
	import quicktime.util.QTUtils;		import quicktime.util.QTUtils;

-	public class FourCharCodeTest ~~extends Object~~ {	+	public class FourCharCodeTest {

	public static void main (String[ ] args) {		public static void main (String[ ] args) {
Line 118:		Line 118:
	import com.oreilly.qtjnotebook.ch01.QTSessionCheck;		import com.oreilly.qtjnotebook.ch01.QTSessionCheck;

-	public class SimpleMovieExport ~~extends Object~~ {	+	public class SimpleMovieExport {

	public static final void main (String[ ] args) {		public static final void main (String[ ] args) {
Line 379:		Line 379:
	import com.oreilly.qtjnotebook.ch01.QTSessionCheck;		import com.oreilly.qtjnotebook.ch01.QTSessionCheck;

-	public class GraphicImportExport ~~extends Object~~ {	+	public class GraphicImportExport {

	Button exportButton;		Button exportButton;

Docbook2Wiki: Initial conversion from Docbook

Docbook2Wiki — Fri, 07 Mar 2008 13:22:47 GMT

Initial conversion from Docbook

←Older revision

Revision as of 13:22, 7 March 2008

Docbook2Wiki: Initial conversion from Docbook

Docbook2Wiki — Fri, 07 Mar 2008 13:17:34 GMT

Initial conversion from Docbook

←Older revision

Revision as of 13:17, 7 March 2008

Evanlenz: 1 revision(s)

Evanlenz — Fri, 07 Mar 2008 00:25:57 GMT

1 revision(s)

←Older revision

Revision as of 00:25, 7 March 2008

Docbook2Wiki: Initial conversion from Docbook

Docbook2Wiki — Fri, 07 Mar 2008 00:17:35 GMT

Initial conversion from Docbook

←Older revision		Revision as of 00:17, 7 March 2008
Line 82:		Line 82:
	'''Figure 4-1. Bit-wise, hex, and character representation of a FOUR_CHAR_CODE'''		'''Figure 4-1. Bit-wise, hex, and character representation of a FOUR_CHAR_CODE'''

-	[[Image:QuickTime for Java: A ~~Developer's~~ Notebook_I_4_tt57.png\|Bit-wise, hex, and character representation of a FOUR_CHAR_CODE]]	+	[[Image:QuickTime for Java: A Developers Notebook_I_4_tt57.png\|Bit-wise, hex, and character representation of a FOUR_CHAR_CODE]]
	</div>		</div>

Line 200:		Line 200:
	'''Figure 4-2. Choice dialog with canned MovieExporter types'''		'''Figure 4-2. Choice dialog with canned MovieExporter types'''

-	[[Image:QuickTime for Java: A ~~Developer's~~ Notebook_I_4_tt58.png\|Choice dialog with canned MovieExporter types]]	+	[[Image:QuickTime for Java: A Developers Notebook_I_4_tt58.png\|Choice dialog with canned MovieExporter types]]
	</div>		</div>

Line 208:		Line 208:
	'''Figure 4-3. MPEG-4 export dialog'''		'''Figure 4-3. MPEG-4 export dialog'''

-	[[Image:QuickTime for Java: A ~~Developer's~~ Notebook_I_4_tt59.png\|MPEG-4 export dialog]]	+	[[Image:QuickTime for Java: A Developers Notebook_I_4_tt59.png\|MPEG-4 export dialog]]
	</div>		</div>

Line 245:		Line 245:
	'''Figure 4-4. Audio non-options for MPEG-4 export on Windows'''		'''Figure 4-4. Audio non-options for MPEG-4 export on Windows'''

-	[[Image:QuickTime for Java: A ~~Developer's~~ Notebook_I_4_tt60.png\|Audio non-options for MPEG-4 export on Windows]]	+	[[Image:QuickTime for Java: A Developers Notebook_I_4_tt60.png\|Audio non-options for MPEG-4 export on Windows]]
	</div>		</div>

Line 293:		Line 293:
	'''Figure 4-5. Discovered Movie Exporters'''		'''Figure 4-5. Discovered Movie Exporters'''

-	[[Image:QuickTime for Java: A ~~Developer's~~ Notebook_I_4_tt63.png\|Discovered Movie Exporters]]	+	[[Image:QuickTime for Java: A Developers Notebook_I_4_tt63.png\|Discovered Movie Exporters]]
	</div>		</div>

Line 504:		Line 504:
	'''Figure 4-6. Selecting a GraphicsExporter'''		'''Figure 4-6. Selecting a GraphicsExporter'''

-	[[Image:QuickTime for Java: A ~~Developer's~~ Notebook_I_4_tt65.png\|Selecting a GraphicsExporter]]	+	[[Image:QuickTime for Java: A Developers Notebook_I_4_tt65.png\|Selecting a GraphicsExporter]]
	</div>		</div>

Evanlenz: 1 revision(s)

Evanlenz — Fri, 07 Mar 2008 00:16:19 GMT

1 revision(s)

←Older revision

Revision as of 00:16, 7 March 2008

Docbook2Wiki: Initial conversion from Docbook

Docbook2Wiki — Fri, 07 Mar 2008 00:15:32 GMT

Initial conversion from Docbook

←Older revision

Revision as of 00:15, 7 March 2008

Evanlenz: 1 revision(s)

Evanlenz — Thu, 06 Mar 2008 23:57:56 GMT

1 revision(s)

←Older revision

Revision as of 23:57, 6 March 2008

Docbook2Wiki: Initial conversion from Docbook

Docbook2Wiki — Thu, 06 Mar 2008 23:50:56 GMT

Initial conversion from Docbook

New page

{{QuickTime for Java: A Developer's Notebook/TOC}}
When QuickTime came out in 1990, it could play movies the size of a postage stamp—barely—on $7,000 hardware. It used audio and video codecs that, although still supported today, have long since been abandoned by users. Yet it's been a smooth transition from Apple Video to Cinepak to MPEG-4. This is thanks to an extraordinarily modular design—most of the heavy lifting in QuickTime is performed by ''components'' , or shared code fragments that can be discovered and used dynamically. Components provide support for importing and exporting image and movie formats, performing image and sound compression and decompression, accessing system resources, and much more. The QuickTime installer provides components for many features, and components added later by the end user, from either Apple or third parties, can provide more functionality, like support for more media formats.

Components aren't always front-and-center in the API—after all, the first few chapters have managed to avoid mentioning them entirely. QuickTime has been assumed to just "do the right thing" when it comes to opening files and turning them into movies, decompressing and rendering the data, saving it to disk, etc. When needed, QuickTime looks through its catalog of components for required functionality and gets what it needs.

But sometimes it's desirable or necessary for the developer to work with components more directly, to figure out what's available or to specify behavior. Figuring out what tools are available at runtime can be a powerful asset.

== Specifying a Component's Type ==

In QuickTime, components are identified by a ''type'' and a ''subtype'' . The type specifies a broad area of functionality, while the subtype is a specific implementation of that functionality. For example, there's a "movie exporter" type, which identifies components that can write a movie into a non-QuickTime format, with subtypes identifying the exporters for AVI, MPEG-4, etc.

These identifiers are 32-bit <tt>int</tt> values, but typically they're not enumerated constants like you might expect from Java. Usually, the 32 bits are read as four 8-bit ASCII characters, making a short, human-readable name. These are defined in the native API as <tt>OSType</tt>s, but when populated with meaningful values, they're called "four character codes," from the native <tt>FOUR_CHAR_CODE</tt> function that returns an <tt>OSType</tt> for a string. This often is abbreviated as FCC, or 4CC.

The scheme makes a lot of sense from the C programmer's point of view. For example, defining the 4CC for a movie requires a nice, simple one-liner, as seen in the native <tt>Movies.h</tt> header file:

MovieResourceType = ''''moov''''

<div class="note">
'''Note'''

"''moov" shows up a lot in QuickTime: as an identifier for a movie's copy-and-paste type, as its Carbon file type, as the top-level "atom" in the file format, etc. Say it out loud if you don't get the joke: moo-vee''.
</div>

It turns out that dealing with 4CCs is harder in Java, thanks to Java's more modern approach to text. Specifically, the use of Unicode means Java characters are 2 bytes each, which means help is needed to turn a Java string into a 4CC.

=== How do I do that? ===

Fortunately, the <tt>QTUtils</tt> class provides two methods for converting to and from 4CCs: <tt>toOSType()</tt> and <tt>fromOSType( )</tt>. [[QuickTime for Java: A Developer's Notebook/Working with Components#quicktimejvaadn-CHP-4-EX-1|Example 4-1]] exercises these methods by converting a Java string to and from its 4CC representation.

<div class="note">
'''Note'''

''Compile and run this example from the downloaded book code with ant run-ch04-fourcharcodetest''.
</div>

<div id="quicktimejvaadn-CHP-4-EX-1">
'''Example 4-1. Converting to and from FOUR_CHAR_CODEs'''

package com.oreilly.qtjnotebook.ch04;

import quicktime.util.QTUtils;

public class FourCharCodeTest extends Object {

public static void main (String[ ] args) {
if (args.length < 1) {
System.out.println ("Usage: FourCharCodeTest <fcc>");
return;
}
System.out.println (args[0]);
int fcc = QTUtils.toOSType (args[0]);
System.out.println (fcc);
System.out.println (Integer.toHexString (fcc));
String fccString = QTUtils.fromOSType(fcc);
System.out.println (fccString);
}

}
</div>

The <tt>main( )</tt> method takes a <tt>String</tt> from the command line, converts it to a 4CC, prints that value in decimal and hex, then converts it back to a <tt>String</tt>. When it's run with <tt>moov</tt> as an argument, the output looks like this:

cadamson% java -classpath classes
com.oreilly.qtjnotebook.ch04.FourCharCodeTest moov
moov
1836019574
6d6f6f76
moov

<div class="note">
'''Note'''

''Really hard-core QuickTime developers can read 4CCs in hex without thinking about it. Drop a movie file on a hex editor and you'll probably see 6d6f6f76 (moov) as bytes 4-8''.
</div>

=== What just happened? ===

These utility methods provide some good, old-fashioned bit-munging to do their conversions. <tt>toOSType( )</tt> takes a <tt>String</tt> as its argument, grabbing the low 8 bits of each character and putting them in the proper place in the returned <tt>int</tt>. In other words, the bottom 8 bits of the first character take up the first 8 bits of the <tt>int</tt>, then the next character is used for the next 8 bits, and so on. [[QuickTime for Java: A Developer's Notebook/Working with Components#quicktimejvaadn-CHP-4-FIG-1|Figure 4-1]] shows where the bits end up in the bit-shifted "<tt>moov</tt>".

<div id="quicktimejvaadn-CHP-4-FIG-1">
'''Figure 4-1. Bit-wise, hex, and character representation of a FOUR_CHAR_CODE'''

[[Image:QuickTime for Java: A Developer's Notebook_I_4_tt57.png|Bit-wise, hex, and character representation of a FOUR_CHAR_CODE]]
</div>

<tt>fromOSType( )</tt> does the opposite conversion, masking off the bits of an <tt>int</tt> and returning a four-character Java string.

== Exporting Movies ==

One of the most obviously useful components is the <tt>MovieExporter</tt>, which you can use to convert a QuickTime movie into a non-QuickTime format, such as AVI or MPEG-4.

=== How do I do that? ===

The <tt>quicktime.std.qtcomponents.MovieExporter</tt> class provides a convenient Java wrapper around movie exporter components. It requires that you pass it a subtype indicating which exporter you want—i.e., which format you want to export to. [[QuickTime for Java: A Developer's Notebook/Working with Components#quicktimejvaadn-CHP-4-EX-2|Example 4-2]] shows how a <tt>MovieExporter</tt> can be created and used from a canned list of subtypes.

<div class="note">
'''Note'''

''Compile and run this example with ant run-ch04-simplemovieexport''.
</div>

<div id="quicktimejvaadn-CHP-4-EX-2">
'''Example 4-2. Simple MovieExporter creation and use'''

package com.oreilly.qtjnotebook.ch04;

import quicktime.*;
import quicktime.std.*;
import quicktime.std.movies.*;
import quicktime.io.*;
import quicktime.std.qtcomponents.*;
import quicktime.utils.QTUtils;

import java.awt.*;
import javax.swing.*;

import com.oreilly.qtjnotebook.ch01.QTSessionCheck;

public class SimpleMovieExport extends Object {

public static final void main (String[ ] args) {
new SimpleMovieExport( );
}

public SimpleMovieExport( ) {
// build choices
ExportChoice[ ] choices = new ExportChoice[3];
choices[0] =
new ExportChoice ("QuickTime Movie",
StdQTConstants.kQTFileTypeMovie);
choices[1] =
new ExportChoice ("AVI file",
StdQTConstants.kQTFileTypeAVI);
choices[2] =
new ExportChoice ("MPEG-4 file",
QTUtils.toOSType("mpg4"));

try {
// query user for a movie to open
QTSessionCheck.check( );
QTFile file =
QTFile.standardGetFilePreview (QTFile.kStandardQTFileTypes);
OpenMovieFile omFile = OpenMovieFile.asRead (file);
Movie movie = Movie.fromFile (omFile);

// offer a choice of movie exporters
JComboBox exportCombo = new JComboBox (choices);
JOptionPane.showMessageDialog (null,
exportCombo,
"Choose exporter",
JOptionPane.PLAIN_MESSAGE);
ExportChoice choice =
(ExportChoice) exportCombo.getSelectedItem( );

// create an exporter
MovieExporter exporter =
new MovieExporter (choice.subtype);

QTFile saveFile =
new QTFile (new java.io.File("Untitled"));

// do the export
movie.setProgressProc( );
movie.convertToFile (null,
saveFile,
StdQTConstants.kQTFileTypeMovie,
StdQTConstants.kMoviePlayer,
IOConstants.smSystemScript,
StdQTConstants.showUserSettingsDialog |
StdQTConstants.movieToFileOnlyExport |
StdQTConstants.movieFileSpecValid,
exporter);

// need to explicitly quit (since awt is running)
System.exit(0);
} catch (QTException qte) {
qte.printStackTrace( );
}

}

public class ExportChoice {
String name;
int subtype;
public ExportChoice (String n, int st) {
name = n;
subtype = st;
}
public String toString( ) {
return name;
}
}
}
</div>

When run, this program prompts the user to open a movie file. Once the movie loads, the program offers a dialog with a choice of formats to export to, as shown in [[QuickTime for Java: A Developer's Notebook/Working with Components#quicktimejvaadn-CHP-4-FIG-2|Figure 4-2]].

<div id="quicktimejvaadn-CHP-4-FIG-2">
'''Figure 4-2. Choice dialog with canned MovieExporter types'''

[[Image:QuickTime for Java: A Developer's Notebook_I_4_tt58.png|Choice dialog with canned MovieExporter types]]
</div>

Next, it shows the user a save dialog detailing the proposed export (e.g., "Movie to MPEG-4") and an Options button. The button brings up a dialog specific to the export format. For example, the AVI export dialog is fairly simple, offering only a few settings to choose from. On the other hand, the MPEG-4 export dialog, seen in [[QuickTime for Java: A Developer's Notebook/Working with Components#quicktimejvaadn-CHP-4-FIG-3|Figure 4-3]], is extraordinarily busy, packed with descriptions of the many options to help end users understand their choices and potentially keep their exported file compliant with MPEG-4 standards.

<div id="quicktimejvaadn-CHP-4-FIG-3">
'''Figure 4-3. MPEG-4 export dialog'''

[[Image:QuickTime for Java: A Developer's Notebook_I_4_tt59.png|MPEG-4 export dialog]]
</div>

After the user makes his choices and clicks OK, the long export process begins. Because movie export is very computationally intensive—potentially every frame of video and every audio sample must be re-encoded—a progress dialog appears, so the user can see how much of the export has completed and how much longer it will take.

=== What just happened? ===

This program uses an inner class called <tt>ExportType</tt> to wrap a subtype, <tt>int</tt>, and a <tt>String</tt>, largely for the purpose of simplifying the <tt>JComboBox</tt> used in the format-choice dialog. These subtypes come from constants defined in the <tt>StdQTConstants</tt> class.

Once a choice is made, the program instantiates a <tt>MovieExporter</tt> by passing the subtype to its constructor. Next, it requests a progress dialog by calling <tt>setProgressProc()</tt> on the movie.

Finally, the export is performed by calling <tt>convertToFile()</tt> and passing in the exporter. This method takes several parameters:

* A <tt>Track</tt> to indicate that only this track should be exported, or <tt>null</tt> for all tracks.
* A <tt>QTFile</tt> to export to.
* A file type, such as <tt>StdQTConstants.kQTFileTypeMovie</tt>.
* A creator, such as <tt>StdQTConstants.kMoviePlayer</tt>.
* A script tag, typically <tt>IOConstants.smSystemScript</tt>.
* Behavior flags. This example uses all three of the valid values: <tt>showUserSettingsDialog</tt> makes the export bring up the Save As dialog that includes the filename and the options button; <tt>movieToFileOnlyExport</tt> limits the export choices to formats supported by the exporter component; and <tt>movieFileSpecValid</tt> asserts that the <tt>QTFile</tt> is valid and should be used as the default name in the dialog.

<div class="note">
'''Note'''

''Including showUserSettingsDialog allows you to pick up the settings and the save-as GUIs in one call, instead of having to show separate dialogs for each. Too bad flags like this aren't described in Javadoc''.
</div>

* The <tt>MovieExporter</tt> to use for the export.

=== What about... ===

...using the <tt>MovieExporter</tt> itself to do the export? That's an alternative. The exporter's <tt>toFile()</tt> exports the movie to a file, and its <tt>toHandle( )</tt> exports to memory. This also has the advantage of being able to export just part of a movie, as specified by the <tt>startTime</tt> and <tt>duration</tt> arguments. Note that doing this requires a different program flow, because first you'd need to get a valid <tt>QTFile</tt> (perhaps with an AWT file dialog) and then you'd need to call the exporter's <tt>doUserDialog( )</tt> to configure the export. Also the <tt>Movie</tt> class's <tt>convertToFile( )</tt> method can be more convenient, because, as seen here, it allows use of the default progress dialog. When using the <tt>MovieExporter</tt> methods, there's no access to the default dialog. In that case, the only alternative is to provide a custom progress dialog and handle progress callbacks with <tt>setProgressProc( )</tt>.

Also, a complaint: I tried exporting to MPEG-4 on Windows and didn't get any audio options. When I click the Audio Track menu in the Exporter dialog, I get the useless panel as shown in [[QuickTime for Java: A Developer's Notebook/Working with Components#quicktimejvaadn-CHP-4-FIG-4|Figure 4-4]].

<div id="quicktimejvaadn-CHP-4-FIG-4">
'''Figure 4-4. Audio non-options for MPEG-4 export on Windows'''

[[Image:QuickTime for Java: A Developer's Notebook_I_4_tt60.png|Audio non-options for MPEG-4 export on Windows]]
</div>

This is not a technical issue but a legal one. Apple has licensed MPEG-4 audio encoding for its Mac-based QuickTime users, but not for Windows users. The codecs exist, but apparently you have to contact Dolby about license terms to enable them for Windows.

== Exporting Movies to Any Installed Format ==

Exporting to a list of known formats is limiting—if the end user has installed new movie exporters, either from third parties or via an update to QuickTime itself, a program that uses a canned list of exporters won't be able to pick them up. Fortunately, QuickTime provides a means of querying for installed components of a given type. You can use this strategy to offer a list of all available exporters.

=== How do I do that? ===

The <tt>AdvancedMovieExport</tt> eliminates the three canned entries in the <tt>choices</tt> array that were used by <tt>SimpleMovieExport</tt> (shown in [[QuickTime for Java: A Developer's Notebook/Working with Components#quicktimejvaadn-CHP-4-EX-2|Example 4-2]]) and instead builds the array through a process of discovery; this code would replace the short "build choices" block in the constructor for <tt>SimpleMovieExport</tt> but needs to go inside the try-catch, because it makes calls that can throw <tt>QTException</tt>:

Vector choices = new Vector( );
ComponentIdentifier ci = null;
ComponentDescription cd =
new ComponentDescription(StdQTConstants.movieExportType);
while ( (ci = ComponentIdentifier.find(ci, cd)) != null) {
// check to see that the movie can be exported
// with this component (this throws some obnoxious
// exceptions, maybe a bit expensive?)
try {
MovieExporter exporter = new MovieExporter (ci);
if (exporter.validate (movie, null)) {
ExportChoice choice =
new ExportChoice (ci.getInfo( ).getName( ),
ci);
choices.addElement(choice);
}
} catch (StdQTException expE) {
System.out.println ("** can't validate " +
ci.getInfo( ).getName( ) + " **");

<div class="note">
'''Note'''

''Run this example with ant run-ch04-advancedmovieexport''.
</div>

// expE.printStackTrace( );
} // ow!
}

When run, the list of supported exporters is surprisingly large, as seen in [[QuickTime for Java: A Developer's Notebook/Working with Components#quicktimejvaadn-CHP-4-FIG-5|Figure 4-5]]. In this case, a "normal" movie, consisting of a video track and an audio track, is being exported, meaning that any audio-only format (Wave, AIFF, etc.) or audio/video format (QuickTime, AVI, MPEG-4, etc.) will work.

<div id="quicktimejvaadn-CHP-4-FIG-5">
'''Figure 4-5. Discovered Movie Exporters'''

[[Image:QuickTime for Java: A Developer's Notebook_I_4_tt63.png|Discovered Movie Exporters]]
</div>

<div class="note">
'''Note'''

''Hinted Movie, the format selected in Figure 4-5, is a QuickTime movie with "hints" to optimize streaming''.
</div>

You also should take note of the discovered exporters that cannot export the movie. These are logged to standard out:

run-ch04-advancedmovieexport:
[java] ** can't validate BMP **
[java] ** can't validate Standard MIDI **
[java] ** can't validate Picture **
[java] ** can't validate Text **
[java] ** can't validate QuickTime TeXML **
[java] ** can't validate QuickTime Media Link **

These fail because the source movie doesn't contain tracks that can be exported to these formats. With a source movie with different kinds of tracks, some of these would succeed and others would fail.

=== What just happened? ===

The process of discovering components by subtype is rather peculiar. It hinges on making repeated calls to a "find" method, passing in the last matching component. Doing this requires a <tt>ComponentDescription</tt> , used as a template to match against, and a <tt>ComponentIdentifier</tt>, which refers to a specific component (though not a specific instance of that component). To find movie exporters, initialize a <tt>ComponentDescription</tt> template with the constant <tt>movieExporterType</tt>.

The static <tt>ComponentIdentifier.find()</tt> method finds matching components, but instead of offering an array or other collection of matches, it requires you to repeatedly pass in the <tt>ComponentDescription</tt> template, along with the previous <tt>ComponentIdentifier</tt> found by the method. For the first iteration, this will be <tt>null</tt>. The <tt>find( )</tt> call returns a <tt>ComponentIdentifier</tt>, which you pass to the <tt>MovieExporter</tt> constructor to create a new exporter. When <tt>find( )</tt> returns <tt>null</tt>, there are no more matches.

<div class="note">
'''Note'''

''Yes, this is ''totally'' weird, at least from a Java perspective''.
</div>

The matched <tt>ComponentIdentifier</tt> provides information about itself via the <tt>getInfo( )</tt> method. This returns another <tt>ComponentDescription</tt> object, different from the one used as a template. You can use this to get type and subtype information (as <tt>FOUR_CHAR_CODE</tt> <tt>int</tt>s, of course), a name, an information <tt>String</tt>, a manufacturer code, etc.

Finding a <tt>MovieExporter</tt> is no guarantee that it actually will work. You can call <tt>validate( )</tt>, as this example does, to check that the instantiated exporter can do an export from the given movie. In this example, if validate throws an exception, it's logged to standard out and the exporter is not added to the <tt>JComboBox</tt>.

=== What about... ===

...setting the export parameters programmatically, instead of using the export dialog every time? This is possible, although it will require using the export dialog at least once in development. A configured <tt>MovieExporter</tt> can return its configured state in the form of an <tt>AtomContainer</tt> object, by way of the <tt>getExportSettingsFromAtomContainer()</tt> method. This object can be passed to an exporter via the <tt>setExportSettingsFromAtomContainer()</tt> method.

<div class="note">
'''Note'''

"''Atoms" are a low-level data structure that do almost all of QuickTime's heavy lifting. Application-level code uses them only for really advanced stuff (see [[QuickTime for Java: A Developer's Notebook/Miscellaneous Media|Chapter 9]])''.
</div>

Within a single running application, this is pretty straightforward. To persist between sessions, you must save off the native structure by calling <tt>getBytes( )</tt> on the <tt>AtomContainer</tt> and then persist it to disk, database, etc. To recreate the settings in the future, read the bytes into a byte array, create a <tt>QTHandle</tt> from the array, and then pass that to <tt>AtomContainer.fromQTHandle( )</tt> to create the <tt>AtomContainer</tt>.

QuickTime 6.3 introduced a new API for setting exporters programmatically, but as of this writing, it has not been exposed via QTJ method calls.

Also, if I specify type and subtype, will I always get one match? No, in some cases, you'll get multiple matching components, and you might need to use other criteria to pick which one to use. In a rather infamous case pointed out by one of my tech reviewers:

Sometimes you get more than one exporter with the same subtype and need to use the "manufacturer" code to distinguish them. This applies particularly to AIFF exporters—the first exporter you find of that type only exports MIDI. To export an arbitrary QT audio file to AIFF you need to explicitly iterate and pick the second one!

== Importing and Exporting Graphics ==

QuickTime offers many components whose job is to import from and export to different graphics formats. As you might expect, these components are wrapped by classes called <tt>GraphicsImporter</tt> and <tt>GraphicsExporter</tt>.

The <tt>GraphicImportExport</tt> example application (shown in [[QuickTime for Java: A Developer's Notebook/Working with Components#quicktimejvaadn-CHP-4-EX-3|Example 4-3]]) uses both of these classes to illustrate the dynamic lookup of importers and exporters.

<div class="note">
'''Note'''

''Compile and run this example with ant run-ch04-graphicimport-export.''.
</div>

<div id="quicktimejvaadn-CHP-4-EX-3">
'''Example 4-3. Graphics import and export'''

package com.oreilly.qtjnotebook.ch04;

import quicktime.*;
import quicktime.io.*;
import quicktime.std.*;
import quicktime.std.comp.*;
import quicktime.std.image.*;
import quicktime.app.view.*;
import java.awt.*;
import java.awt.event.*;
import javax.swing.*;
import java.util.Vector;
import java.io.*;

import com.oreilly.qtjnotebook.ch01.QTSessionCheck;

public class GraphicImportExport extends Object {

Button exportButton;
Frame frame;
GraphicsImporter importer;

static final int[ ] imagetypes =
{ StdQTConstants.kQTFileTypeQuickTimeImage};
/* other interesting values:
StdQTConstants.kQTFileTypeGIF,
StdQTConstants.kQTFileTypeJPEG,
StdQTConstants4.kQTFileTypePNG,
StdQTConstants4.kQTFileTypeTIFF
StdQTConstants.kQTFileTypeMacPaint,
StdQTConstants.kQTFileTypePhotoShop,
StdQTConstants.kQTFileTypePICS,
StdQTConstants.kQTFileTypePicture,
*/

public static void main (String[ ] args) {
new GraphicImportExport( );
}

public GraphicImportExport( ) {
try {
QTSessionCheck.check( );
QTFile inFile = QTFile.standardGetFilePreview (imagetypes);
importer = new GraphicsImporter (inFile);
// put image onscreen
QTComponent qtc = QTFactory.makeQTComponent (importer);
java.awt.Component c = qtc.asComponent( );
frame = new Frame ("Imported image");
frame.setLayout (new BorderLayout( ));
frame.add (c, BorderLayout.CENTER);
exportButton = new Button ("Export");
exportButton.addActionListener (new ActionListener( ) {
public void actionPerformed (ActionEvent ae) {
try {
doExport( );
} catch (QTException qte) {
qte.printStackTrace( );
}
}
});
frame.add (exportButton, BorderLayout.SOUTH);
frame.pack( );
frame.setVisible(true);
} catch (QTException qte) {
qte.printStackTrace( );
}
}

public void doExport( ) throws QTException {
// build list of GraphicExporters
Vector choices = new Vector( );
ComponentDescription cd =
new ComponentDescription (
StdQTConstants.graphicsExporterComponentType);
ComponentIdentifier ci = null;
while ( (ci = ComponentIdentifier.find(ci, cd)) != null) {
choices.add (new ExportChoice (ci.getInfo( ).getName( ),
ci.getInfo( ).getSubType( )));
}

// offer a choice of movie exporters
JComboBox exportCombo = new JComboBox (choices);
JOptionPane.showMessageDialog (frame,
exportCombo,
"Choose exporter",
JOptionPane.PLAIN_MESSAGE);
ExportChoice choice =
(ExportChoice) exportCombo.getSelectedItem( );
System.out.println ("chose " + choice.name);

// build a GE, wire up to the GraphicsImporter
GraphicsExporter exporter =
new GraphicsExporter (choice.subtype);
exporter.setInputGraphicsImporter (importer);

// ask for destination, settings
FileDialog fd =
new FileDialog (frame, "Save As",
FileDialog.SAVE);
fd.setVisible(true);
String filename = fd.getFile( );
if (filename.indexOf('.') = = -1)
filename = filename + "." +
exporter.getDefaultFileNameExtension( );
File file = new File (fd.getDirectory( ), filename);
exporter.setOutputFile (new QTFile(file));
exporter.requestSettings( );

// export
exporter.doExport( );

// need to explicitly quit (since awt is running)
System.exit(0);
}

public class ExportChoice {
String name;
int subtype;
public ExportChoice (String n, int st) {
name = n;
subtype = st;
}
public String toString( ) {
return name;
}
}

}
</div>

When run, the program shows a dialog to select a graphic to be imported. On Windows, the "file type" in this dialog is QuickTime Image. Once an image is selected, it appears in a window with an "export" button. When the user clicks the button, she is asked for an export type, as shown in [[QuickTime for Java: A Developer's Notebook/Working with Components#quicktimejvaadn-CHP-4-FIG-6|Figure 4-6]].

<div class="note">
'''Note'''

''GraphicsImporter and GraphicsExporter are in quicktime.std.image, not quicktime.std.qtcomponents like most other components''.
</div>

<div id="quicktimejvaadn-CHP-4-FIG-6">
'''Figure 4-6. Selecting a GraphicsExporter'''

[[Image:QuickTime for Java: A Developer's Notebook_I_4_tt65.png|Selecting a GraphicsExporter]]
</div>

After this, the program displays a configuration dialog specific to the type of exporter selected—at a minimum, this dialog usually offers a choice of color depths (256 colors, 256 grays, millions of colors, etc.). Next, a save dialog requests the location of the exported file. Once approved, the program converts the image to the specified format and saves it to the supplied location.

=== What just happened? ===

Notice the <tt>QTFile.standardGetFilePreview()</tt> . This shows a file-open dialog and takes an array of up to four <tt>int</tt>s, representing <tt>FOUR_CHAR_CODE</tt> s of various file format constants, which are used as a filter of what file types to make selectable. You can use <tt>kQTFileTypeQuickTimeImage</tt> as a convenient wildcard that matches any kind of image QuickTime can open, though it seems to work only on Windows (on the Mac, any file can be selected).

<div class="tip">
'''Tip'''

If you want to specify formats, interesting constants in <tt>StdQTConstants</tt> include <tt>kQTFileTypeGIF</tt>, <tt>kQTFileTypeJPEG</tt>, and <tt>kQTFileTypePhotoShop</tt>. The <tt>StdQTConstants4</tt> class adds similarly named constants for PNG and TIFF. Unfortunately, you can send only four.
</div>

Given a file, you can construct a <tt>GraphicsImporter</tt> object to load it into QuickTime. To put the imported image on-screen, pass the importer to <tt>QTFactory.makeQTComponent()</tt> , which returns a <tt>QTComponent</tt> that you can either cast to an AWT <tt>Component</tt> or, to be type-safe, convert with the <tt>asComponent( )</tt> method.

<div class="warning">
'''Warning'''

<tt>java.awt</tt> and <tt>quicktime.std.comp</tt> both define a class called <tt>Component</tt> . If you're casually <tt>import</tt>ing every class from these packages, you're probably headed for a compile-time error. You'll have to make your imports more selective or use a fully qualified class name for one of the <tt>Component</tt>s, like this example does.
</div>

To export an image to another format, you can search for graphics exporter subtypes by creating a <tt>ComponentDescription</tt> template to match components of the <tt>graphicsExporterComponentType</tt>. In the example, the names of matching components are shown in a <tt>JComboBox</tt>. With a subtype selected, create the <tt>GraphicsExporter</tt> by passing the subtype to its constructor.

<div class="note">
'''Note'''

''This method of looking up exporter components was shown in the previous lab''.
</div>

A <tt>GraphicsExporter</tt> needs to be wired up to some kind of source image. With a <tt>GraphicsImporter</tt>, you wire the two together with <tt>setInputGraphicsImporter()</tt> . The exporter also needs a destination. If writing to a file (as opposed to, say, memory), you set this with <tt>setOutputFile( )</tt> —just to be safe, it's wise to sanity-check the user-provided filename extension against the value returned by the exporter's <tt>getDefaultFileNameExtension()</tt> .

The user probably wants some say in the color depth, image quality, and other settings for the export, a dialog for which is provided with a <tt>requestSettings()</tt> .

After all that, you finally can do the export with...<tt>doExport( )</tt>.

=== What about... ===

...other sources for the export? The Javadoc for <tt>GraphicsExporter</tt> shows a bunch of <tt>setInputXXX( )</tt> methods. True enough, and in the next chapter, we'll explore some of these, including <tt>Pict</tt>s, <tt>QDGraphics</tt>, and <tt>PixMap</tt>s.

And what about setting export parameters programmatically? QTJ exposes some methods that could be used instead of the user dialog, such as <tt>setDepth()</tt> and <tt>setCompressionMethod( )</tt>. One interesting method, <tt>setTargetDataSize( )</tt> , lets exporters with a "quality" option (like JPEG) find a value that will result in a file of the given size in bytes.

<div class="note">
'''Note'''

''GraphicsExporters have an AtomContainer-based settings scheme that's just as painful as the MovieExporter equivalent from the last lab''.
</div>

== Discovering All Installed Components ==

I hope that by this point you're at least a little interested in what other kinds of components are available in QuickTime. It's easy to discover them all, in much the same way we discovered the various <tt>MovieExporter</tt>s and <tt>GraphicExporter</tt>s: by providing a <tt>ComponentDescription</tt> template and using <tt>ComponentIdentifier.find( )</tt>. With a "blank" template, all components can be revealed.

=== How do I do that? ===

[[QuickTime for Java: A Developer's Notebook/Working with Components#quicktimejvaadn-CHP-4-EX-4|Example 4-4]] discovers all installed components and logs their type, subtype, and description to standard out.

<div id="quicktimejvaadn-CHP-4-EX-4">
'''Example 4-4. Discovering all installed components'''

package com.oreilly.qtjnotebook.ch04;

import quicktime.*;
import quicktime.std.*;
import quicktime.std.comp.*;
import quicktime.util.QTUtils;

import com.oreilly.qtjnotebook.ch01.QTSessionCheck;

public class ComponentTour {

public static void main (String[ ] args) {
try {
QTSessionCheck.check( );
/* use this wildcard to show all components in QT
*/
ComponentDescription wildcard =
new ComponentDescription( );
ComponentIdentifier ci = null;
while ( (ci = ComponentIdentifier.find(ci, wildcard)) != null) {
ComponentDescription cd = ci.getInfo( );
System.out.println (cd.getName( ) +
" (" +
QTUtils.fromOSType (cd.getType( )) +
"/" +
QTUtils.fromOSType (cd.getSubType( )) +
") " +
cd.getInformationString( ));
}

} catch (QTException qte) {
qte.printStackTrace( );
}
}

}
</div>

The resulting output is hundreds of lines long, looking something like this:

run-ch04-componenttour:
[java] Apple MP3 Decoder (adec/.mp3) An AudioCodec that decodes MPEG-1, MPEG-2,
MPEG-2.5 Layer III into linear PCM data
[java] MPEG-4 AAC Decoder (adec/aac ) An AudioCodec that decodes MPEG-4 AAC into
linear PCM data
[java] Apple Lossless Decoder (adec/alac) An AudioCodec that decodes Apple Lossless
into linear PCM data
[java] Apple IMA4 Decoder (adec/ima4) An AudioCodec that decodes IMA4 into linear
PCM data
[java] MPEG-4 AAC Encoder (aenc/aac ) An AudioCodec that encodes linear PCM data
into MPEG-4 AAC
[java] Apple Lossless Encoder (aenc/alac) An AudioCodec that encodes linear PCM
data into Apple Lossless
[java] Apple IMA4 Encoder (aenc/ima4) An AudioCodec that encodes linear PCM data
into IMA4
[java] Applet (aplt/scpt) The component that runs script applications
[java] Apple: AUConverter (aufc/conv) AudioConverter unit
[java] Apple: AUVarispeed (aufc/vari) Apple's varispeed playback
[...]

=== What just happened? ===

The key is the line that gets a <tt>ComponentDescriptor</tt> via a no-arg constructor. This creates a completely blank template for <tt>ComponentIdentifier.find( )</tt> to run against. Of course, if you just wanted to tour components of a specific type, you could pass in a type constant such as <tt>StdQTConstants.movieImportType</tt>, which would limit the search to <tt>MovieImporter</tt>s, and thus indicate what kinds of formats QuickTime can import.

Documenting and explaining every kind of component is beyond the scope of this book—in fact, it filled up a whole volume of the old ''Inside Macintosh'' series. Still, a few of the important ones are listed in [[QuickTime for Java: A Developer's Notebook/Working with Components#quicktimejvaadn-CHP-4-TABLE-1|Table 4-1]]. Note that not all components have (or need) a Java wrapper class.

<div id="quicktimejvaadn-CHP-4-TABLE-1">
'''Table 4-1. Some important QuickTime for Java components'''

{| border="1"
|-
! Type !! Java wrapper class !! Sample subtypes
|-
| "<tt>eat</tt>" || <tt>MovieImporter</tt> || "<tt>AVI</tt>", "<tt>AIFF</tt>", "<tt>MP3</tt>", "<tt>SWF</tt>"
|-
| "<tt>spit</tt> " || <tt>MovieExporter</tt> || "<tt>VfW</tt>", "<tt>MooV</tt>", "<tt>mpg4</tt>"
|-
| "<tt>grip</tt>" || <tt>GraphicsImporter</tt> || "<tt>BMP</tt>", "<tt>GIF</tt>", "<tt>JPEG</tt>"
|-
| "<tt>grex</tt>" || <tt>GraphicsExporter</tt> || "<tt>BMP</tt>", "<tt>JPEG</tt>"
|-
| "<tt>clok</tt>" || <tt>Clock</tt> (provides timing and callback services) || "<tt>tick</tt>", "<tt>micr</tt>"
|-
| "<tt>mhlr</tt>" || <tt>MediaHandler</tt> || "<tt>vide</tt>", "<tt>soun</tt>", "<tt>text</tt>"
|-
| "<tt>imco</tt>" || None; image compressor (used for still images and video) || "<tt>jpeg</tt>", "<tt>mp4v</tt>", "<tt>h263</tt>"
|-
| "<tt>imdc</tt>" || None; image decompressor (used for still images and video) || "<tt>jpeg</tt>", "<tt>mp4v</tt>", "<tt>h263</tt>"
|-
| "<tt>rtpm</tt>" || None; real-time packetizer (used for streaming) || "<tt>263+</tt>", "<tt>mpeg</tt>", "<tt>mp4a</tt>", "<tt>mp4v</tt>"
|}
</div>

<div class="note">
'''Note'''

''Yep, "eat" and "spit" for movie importers and exporters. Hardy har har''.
</div>

It's important to remember that all types and subtypes are <tt>FOUR_CHAR_CODE</tt> s—any type or subtype seemingly shorter than that is padded with space characters.