QuartzCrystal is an offline renderer that turns Quartz Compositions into portable QuickTime movies. It supports 3rd party plugins, as well as patches that do not work in safe-mode-only environments (such as QuickTime Pro). It also supports software scene antialiasing, so if you have a Mac with plenty of RAM and a hard-core video card, you can make spectacularly beautiful renderings of your plugins, effects, and compositions.

Beside QuartzCrystal, the only other product that renders and encodes compositions to movies is Apple’s own QuickTime Pro, which doesn’t support plugins, unsafe patches, or antialiasing.

Lately I’ve been working on integrating (or, more accurately, attempting to integrate) the Python scripting language into some plugins for an application we develop plugins for. We’ve wrapped many libraries with varying levels of success, so this one wasn’t going to be much different. Or, so we thought.

Technically, we’re interested in “Embedding” Python — We have a native Objective-C application that needs to make use of the Python interpreter at various stages of execution. The Python scripts are user-supplied, and are exceptionally free-form: the functions they write can take variable numbers of inputs, produce variable numbers of outputs, and can use any Python modules they have installed.

Unfortunately, this makes the embedding process somewhat complicated: From Objective-C, we need to be able to parse the script, find all its functions, and get all those functions’ input and output parameters. From this data, we can expose the Python module’s interface usefully. Unfortunately, Python does not appear to allow this kind of introspection from the outside (and it’s questionable whether or not it’s even possible from the inside.)

In searching for information on this, Numerous Documents are Found that Needlessly Complicate or Obfuscate the difference between Embedding and Extending. As if it’s really that difficult (embed means “fix firmly and deeply in a surrounding mass” while extend means “cause to cover a larger area; make longer or wider”. From these obvious definitions, we can infer that “Embedding” means putting something inside, while “Extending” means adding functionality or abilities. Maybe it’s not so clear for non-native english speakers. I don’t know.)

Another annoying side-trip of this research was an overwhelmingly smug idea that almost reeks of Java. This side effect is the recorded smarmy discussion of why one should “Extend” rather than “Embed” (these reasons are then used to explain away why there isn’t any good documentation on actually embedding Python). The arguments go something like this:

• Python’s so good, cross-platform, and flexible that it’s actually more cost-effective to Throw Out All Your C/C++/ObjC Code And Rewrite Everything In Python.
• Embedding is so cumbersome to code, and so difficult compared to embedding Python in Python, that you should Throw Out All Your C/C++/ObjC Code And Rewrite Everything In Python.
• High-performance code can be written in C, and then called from within Python’s runtime when you actually need to performance boost. Why not just Throw Out All Your C/C++/ObjC Code And Rewrite Everything In Python Except for the fast bits?
• If you embed Python, you’ll annoy Python developers who can’t access the modules they’re used to using. Why not Throw Out All Your C/C++/ObjC Code And Rewrite Everything In Python so you don’t annoy your Python developers?

These arguments cover some pretty diverse ground there. Unfortunately, there are 2 fatals flaws in the list above.

First, embedded Python _Can_ in fact use installed modules just like raw Python, so point 4 above is flagrantly incorrect. There are some suggestions that it’s simply annoying to develop in such an environment because namespaces are all strange (or wrong) and nothing works quite right. Guess What: Welcome To Plugin Development! It’s like these Python developers have never worked on real projects before or something.

Second, All of the above points assume that it’s possible to discard your entire code-base and rewrite everything. While this is technically possible, it’s not very likely when you don’t have access to the source of the application to be discarded (in our case). The unfortunate downside is that _All The Listed “Solutions” Hinge On This One Idea_.

What’s with these non-solutions from allegedly flexible languages? Even Objective-C, a compiled language, and the (totally undocumented) JavaVM-ObjC bridge, offer enough introspection to at least find methods and parameter counts without too much hassle. Maybe Python does this just as simply, but if so, no one’s talking about it…

Along with the new site, a few new patches are available as well based on requests from users.

This release is only compatible with Tiger (10.4).
Please see kineme.net for Leopard-specific informations.

1. Set up a QCIndexPort input. QCIndexPorts provide values from 0 to whatever max you specify using - (void)setMaxIndexValue:(unsigned int)max;.

@interface IndexPortPopUpDemoPatch : QCPatch
{
    QCIndexPort *inputPerson;
}
	
...
	
@end

2. Add the “menu” key to the port’s input attributes:

	<key>inputAttributes</key>
	<dict>
		<key>inputPerson</key>
		<dict>
			<key>description</key>
			<string>Person</string>
			<key>name</key>
			<string>Person</string>
			<key>menu</key>
			<array>
				<string>Arthur Dent</string>
				<string>Ford Prefect</string>
				<string>Zaphod Beeblebrox</string>
				<string>Marvin</string>
				<string>Trillian</string>
				<string>Slartibartfast</string>
				<string>Agrajag</string>
				<string>Wonko the Sane</string>
			</array>
		</dict>
	</dict>

3. Make sure you set the max index value in the initWithIdentifier function:

- (id)initWithIdentifier:(id)fp8
{
        id z=[super initWithIdentifier:fp8];
	
        [inputPerson setMaxIndexValue:7];
	
        return z;
}

4. Read the value out of the QCIndexPort using - (unsigned int)indexValue;.

Changes:

• Rebuilt from scratch — no longer depends on QCJP’s work — and, by extension, the Creative Commons “Attribution-NonCommercial-ShareAlike” license. My Xcode Template, as of version 0.2, is released into the Public Domain. You are free to use it for whatever — commercial or non-commercial.
• QCJP’s headers were replaced with headers assembled directly from the QuartzComposer framework — now located in the QuartzComposer/ folder of the project. I’ve exported a few more headers than QCJP had constructed, so there’s some added functionality (namely, image input/output ports).
• The project now automatically assigns an icon to the patch bundle, and installs it in /Library/Graphics/Patches/ for you each time you build, for faster edit-build-test workflow.

This release is out-of-date.
Please see the latest version.

Download the installer, version 0.2.

See the old version’s blogpost for some additional instructions and user comments.

This release is only compatible with Tiger (10.4).
Please see kineme.net for Leopard-compatible patches.

Get version 0.1 here.

Notes:

• This depends on Tim Kreger’s OS X kernel extension — part of P5osc. Install and enable the driver first.
• Make sure you’ve plugged the glove in before attempting to render the patch — there’s currently no way for it to detect the plugging/unplugging of the glove.
• Only a single glove at a time is supported.

This release is only compatible with Tiger (10.4).
Please see kineme.net for Leopard-compatible patches.

Get version 0.1 here.

Notes:

• These require the Phidget21 drivers to be installed.
• Device Labels are specified using POSIX Regular Expressions.
• Due to a bug in the Phidget21 driver, I can’t manually fetch a list of interfaces, and so need to rely on notifications.. So if you change the Device Label regex, you’ll need to unplug-and-replug the Phidget for it to be recognized.
• Both patches are pink “Renderer” patches because they provide output from Quartz Composer — they are “sinks” in graph theory. Given QC’s graph evaluation model, I haven’t yet found a way to make these patches reliably output data unless they’re (improperly) marked as “Renderer”s.
• Both patches should support multiple InterfaceKits of the same or differing types — as long as you specify non-overlapping Device Labels for each. I haven’t been able to test this yet — my second InterfaceKit 8/8/8 should arrive later this week.

Here’s a little test setup, using a distance sensor connected to one of the InterfaceKit 8/8/8’s analog inputs, which — via Quartz Composer — controls a relay output on the InterfaceKit 0/0/4. Beth and Robert built the 0/0/4 into a box of 120VAC receptacles, into which I’ve plugged a light.

Far from distance sensor = Relay off

Close to distance sensor = Relay on

Piece of cake.

I took Martin Kahr’s Apple Remote Controller Wrapper Class and built a Quartz Composer patch around it.

This release is only compatible with Tiger (10.4).
Leopard (10.5) includes a built-in Apple Remote patch.
Please see also kineme.net for Leopard-compatible patches.

Get version 0.1 here.

Some notes:

• The events received from the Apple Remote are fairly strange to begin with.. You don’t simply get “key down” / “key up” events as I would have assumed, but instead get cooked events — for many of the buttons, holding the button down generates a different event than tapping it.
• My patch queues events, to ensure that each keypress is visible for at least one frame.

• QCPatch Configuration
• QCPatch Events
• QCPatch Methods

This release is only compatible with Tiger (10.4).
Please see kineme.net for Leopard-specific informations.

1. Start up Interface Builder:
   
2. Make a new NIB, with a “Cocoa / Empty” starting point:
   
3. Make a subclass of NSObject called QCInspector. Then make a subclass of QCInspector with the class name of your patch, followed by “UI”. P5GloveUI in this case:
   
4. Drag a “CustomView” into the project:
   
5. Select “File’s Owner” and set its “Custom Class” to the UI subclass you created above (P5GloveUI in this case):
   
6. Control-drag from “File’s Owner” to “View”, then “Connect” the view to the UI subclass’s “view” outlet:
   
7. Throw a few controls onto the View if you’d like:
   
8. Save the NIB in your patch’s English.lproj folder, and add it to the project:
   
9. Add the QCInspector interface to your patch’s qcplugin.h:

   @interface QCInspector : NSObject
   {
   	NSView *view;
   	QCPatch *_patch;
   	void *_unused2[4];
   }
   + (id)viewNibName;
   + (id)viewTitle;
   - (id)init;
   - (void)didLoadNib;
   - (id)patch;
   - (void)setupViewForPatch:(id)fp8;
   - (void)resetView;
   - (id)view;
   @end
   

10. Add inspectorClassWithIdentifier to your patch’s interface:

    P5Glove.h:

    @interface P5Glove : QCPatch
    	
    ...
    	
    + (Class)inspectorClassWithIdentifier:(id)fp8;
    @end
    

11. Implement inspectorClassWithIdentifier:

    P5Glove.m:

    @implementation P5Glove : QCPatch
    	
    ...
    	
    + (Class)inspectorClassWithIdentifier:(id)fp8
    {
    	return [P5GloveUI class];
    }
    @end
    

12. Add the P5GloveUI class interface and implementation to your patch’s project:

    P5GloveUI.h:

    @interface P5GloveUI : QCInspector
    + (id)viewNibName;	// IMP=0x97b89415
    @end
    

    P5GloveUI.m:

    @implementation P5GloveUI : QCInspector
    + (id)viewNibName
    {
    	return @\"P5GloveUI\";
    }
    

13. Build and launch Quartz Composer. You’ve got an inspector:
    
14. Enjoy.