Method Names
Usage of QTCubed is loosely modeled after the QTKit library it tries to emulate.
In particular, static methods such as:
have all been collapsed into the constructor. In general, functions in ObjectiveC are very verbose, as they include the names of the parameters. In overloading languages like C++ and Java, since the convention is to simply use a single function name with varying parameters, I have followed this practice in the creation of this library, to avoid much frustration to those unaccustomed to ObjectiveC's quirks.
Wherever possible, I will use simply the named portion of an overloaded method instead of the name with parameters. Also, wherever possible, I am using standard Java types, and converting on the fly to more QTKit friendly values before dropping into JNI. The QTMovie#canInit functions are a good example of this simplification, which differentiates which version will be called on the QTKit library by the parameters instead of the name.
If you see any public methods named with a leading underscore, BEWARE: These are NOT intended for general consumption, and will disappear from the public interfaces, so AVOID USING THEM. These are, in general, the native methods which are called from the public interface after some preprocessing in Java.
Java Native Quirks
Java has an interesting structure as it relates to native components used in conjunction with Java Components. (Canvas, Component, JComponent, JPanel, etc) In particular, the native component is instantiated when the Java Component is added to the view hierarchy and made visible. This will cause some stress because if you perform operations which must initialize a native view that has not yet been visible, Java provides no mechanism to do this.
I must emphasize this point repeatedly because it will be a HUGE source of stress if you want to initialize a panel, and immediately throw a movie up on it. While I have taken some countermeasures, such as delayed initialization if the peer is not yet created, not all scenarios are possible. In particular, you CANNOT and MUST NOT attempt to affect the playback of a movie, or a capture pane while it is not visible. This means, in particular, that while you can assign a movie to a QTKitMovieView for example, before it's made visible, the native side hasn't actually been created yet, and won't be until it is made visible, so you mustn't attempt to play the movie. I have added a descriptive exception to methods this applies to, so it's not just a mysterious error in CToolkit anymore.
What kind of performance does QTCubed get?
Because this is a JNI library, and most everything is actually done at the native level, even when you're creating a QTKitCaptureSession object for example, and wiring many other classes to it, those classes actually have a native object existence as well. When you use the QTKitCaptureSession.addInput method for example, it actually grabs the native object for both the capture session, and the input you just added, and performs those in Cocoa. That method invocation is relatively slow, but the methods they call on each other are not, so when capture data is actually moving around, it does so without invoking the JVM, and that slow bridge between native and Java code.
What this means is that even when previewing Captured Video for example, all of that data flow happens entirely on the Native side, with no frame buffers ever passing into java. There in fact is only one way to get captured data into java at present, and that's by way of the QTKitCaptureDecompressedVideo class. That said, I've used this class to push 640x480 24 bit RGB through to Java Media Framework at 30 fps. JMF doesn't actually support 24-bit RGB, and so had to decompress this up to 32-bit RGBA before displaying it using AWT.
I was rather floored by this result, as I didn't really engineer this with speed as a priority, though I will definitely focus some attention on it in the future.
Using QTCubed with JMF
At the moment, the safest way to use QTCubed with JMF is to call the method QTCubed.usesQTKit() somewhere in the initializer of your application or applet. This will initialize the QTCubed library and its associated services, including the JMF plugins. After this, you needn't do anything special to make use of the library, simply use JMF as you normally would, and the Quicktime capture and playback facilities will be available to you.
