OK, let’s look a little bit at the wild world of Quartz Composer plugins.
1) How does Isadora make use of Quartz Composer (.qtz) files?
Apple provides an API (Application Programming Interface) that allows any app to load a QC patch and use it. That’s how Isadora “imports” them into the program. Isadora creates a “wrapper” around the QC patches so that they appear as normal Isadora actors.
2) Where does Isadora find the patches?
The agreed upon location for the Quartz Composer files are
/Users/YOUR_NAME_HERE/Library/Compositions (also referred to as ~/Library/Compositions)
Isadora also searches the “FreeFrame” folder at /Library/Application Support/FreeFrame — not an Apple “approved” of place, but it’s where the Isadora community and I agreed to put these beasts back in the old days before Apple designated the three folders above.
There are two more important folders: /Library/Graphics and ~/Library/Graphics — it is in these locations that you may need to add a file with the .plugin extension. These are files that add some behavior to QC that can’t be implemented in QC. For instance, the Kineme “ArtNet” plugin (which controls lighting) has an associated .plugin file.
So, first let’s take a look at /System/Library/Compositions. Here you’ll find quite few QC plugins created by Apple. (A default install of 10.7 seems to have 102.) Most of these will work fine in Isadora. But there are few that won’t. For instance, “User Backdrop 1,” “User Backdrop 2,” etc. These won’t load because Apple limited them to run with three particular apps: iChat, Quartz Composer Editor, and Photo Booth. I created a work around for this particular plugin by creating a small app called “Quartz Composer Compatibility” that adds Isadora to the list — it ships with the normal Isadora Core Installer. There may be others that may not load for reasons like this, but the bulk of Apple’s plugins will load and work correctly.
In the default 10.7 install, there’s actually nothing placed in the other two locations (/Library/Compositions/ and
~/Library/Compositions.) If you want add a plugin so that its available to every user, then it would go in /Library/Compositions/. If you wanted to add a plugin that you would see only when logged in to a specific account, you would add it into ~/Library/Compositions.
You may choose to not load from one of the designated folders by unchecking the appropriate check box in under “Quartz Composer Load Options” in the Video Tab of the Preferences. (Why would you want to disable one or more folders? Because Isadora has to open each one to find out about its published inputs and outputs every time it starts up. That can add considerable time to Isadora’s start up sequence which can be annoying if you’re not actually using all 102 default plugins.)
3) How does Isadora get data in and out of a Quartz Composer plugin?
In the Quartz Composer editor application, you can “publish” and input or an output. By so doing, the API mentioned above allows an external program to “see” that input or output, and get information about its characteristics. Isadora does just that, and for every published input and every published output, you’ll see a corresponding input and output on the QC actor in Isadora.
4) Why don’t some plugins work?
There can be any number of reasons for this.
First, there are many, many people out there creating patches using Quartz Composer. Some of them do a good job of making these plugins useful in environments other than QC: they and publish the relevant inputs and outputs so that other apps can access them. But, some plugins might not have and published inputs or outputs. In that case, there isn’t much Isadora can do. Using Apple’s API, no way to “discover” inputs or outputs that are not published.
Second, there simply might be a programming error or other problem in the qtz file. For instance, right now, I’ve got a QC plugin called “Datamosh” that a user was having trouble with. It won’t load because of an error, which is only displayed in the System Console (see /Utilities/Console.) For this particular patch, one of the errors looks something like this:
2012-07-31 15:16:23.725 IsadoraCore[7353:a0f] *** Message from <QCPatch = 0x01493A50 “(null)”>:
Cannot publish input port [“insertKeyFrameOne” @ “PlugInPatch_DataMoshPlugIn_1”]
2012-07-31 15:16:23.727 IsadoraCore[7353:a0f] *** State restoration failed on <QCPatch = 0x01493A50 “(null)”>
Third, there may be an associated plugin required to run the QC patch. For instance, I have a patch called “v002 Rutt Etra isadora” that generates a ton of errors because it’s missing the associated RuttEtra plugin. If you load it in Quartz Composer, you see those errors in a dialog. Isadora doesn’t show a dialog with this information because 1) I can’t get it from the API and 2) for those not concerned with Quartz Composer patches, I don’t want to disturb them with information that’s not useful.
So, the upshot of all of this can be summarized by the abbreviation YMMV — “Your Mileage May Vary.” Meaning, some of Quartz Composer plugins that you find on the internet are going to work right out of the box; others just won’t. If you’ve paid someone for a plugin you might be able to get support (e.g., the folks at Kineme.) But if its a freebie or you don’t know the source, you really don’t have anyone to whom you can turn.
To really make the most of these plugins I would say you have to be a bit of an expert, because they have not always been designed to be used by an application other than Quartz Composer. You might just have to crack them open and work on them a bit to get them going. The problem is, especially for students, they may not have the skill to do so.
I hope that helps explain the situation a bit.