Working with Quartz Composer

Quartz Composer is a groundbreaking graphics development environment that allows you to explore the incredible power of the graphics stack of Mac OS X Tiger. With Quartz Composer, you can easily combine the capabilities of Cocoa, Quartz 2D, Core Image, OpenGL, and QuickTime, all using an approachable visual programming paradigm. Use Quartz Composer to prototype Core Image filters, build engaging screen savers, create custom user-interface widgets, make data-driven visual effects, and even perform live performance animations.

This article introduces you to Quartz Composer, walks you through a simple sample composition and provides a hands-on exploration to familiarize you with the way you can use it in your own projects. Once you start working with Quartz Composer, you may think of your projects in new ways, and find many more uses for its power and speed.

NOTE: If you are developing for Mac OS X Leopard, see Working with Quartz Composer in Leopard

The Visual Programming Environment

The first thing you'll notice about Quartz Composer is that it isn't like most development tools. Instead of writing pages worth of code to directly manipulate the various graphics APIs on the system, you work visually with processing units called patches. These patches are connected into a composition. As you work with a composition, adding patches and connecting them, you can visually see the results in a viewer window. Each and every change you make is immediately reflected in the viewer—no compilation required. This results in a development experience like no other, as illustrated in Figure 1.

Figure 1: The Quartz Composer User Interface.

A patch is similar to a subroutine in a traditional programming environment. You can provide inputs to the patch, the patch will then execute and produce some results. Circles on the left side of a patch represent the various inputs the patch will accept. Circles on the right side are the outputs. The kinds of inputs a patch will accept and outputs it will create depend on its functionality. For example, a Random patch will accept Min and Max parameters and use them to create a Value output, as shown in Figure 2.

Figure 2: Anatomy of a Patch.

The input values to a patch can be set in one of two ways. The first is to set the value using the patch inspector. The second is to connect the output of another patch to the input. In Figure 3, the inspector shows the input values for the Random patch while the Value output is connected to the Math patch. When run, the Random patch will generate a random number between 0 and 1 and pass that as its Value output.

Figure 3: Patch Inputs and Outputs.

The overall programming task in Quartz Composer consists of selecting the patches that you want to use, organized in the Patch Library, and connecting them together to achieve the desired effect. At this point, let's shift gears from talking about patches in the abstract and actually put together a composition. This will explain how Quartz Composer works better than words alone.

Hands On

In order to work with Quartz Composer, you'll need to have Xcode Tools installed. When installed, you can find the application in the /Developer/Applications/Graphics Tools folder, as shown in Figure 4.

Figure 4: Location of the Quartz Composer Application.

Once you've found Quartz Composer, launch it. An Assistant will appear giving you several starting points. Select the first, labeled Basic Composition, click next, and then choose where you'd like to save it. Once you've completed the Assistant, you'll see the Quartz Composer Editor and Viewer, as shown in Figure 5.

Figure 5: The Basic Composition.

The first patch that we want to look at is the Gradient patch. This patch draws the dark blue to light blue gradient that is the background for the composition. As you can see, there aren't any other patches that are providing inputs. This means that the patch is using its default values. Select the patch and bring up the inspector using the Editor > Show Inspector menu or by pressing Command-I. Then use the pull-down menu at the top of the Inspector to examine the patch's input parameters, as shown in Figure 6. These values are editable and you can change them to whatever you like. Notice that as you change the color value, the viewer display updates in real time.

Figure 6: Adjusting the Gradient Patch Input Values.

The second patch of interest is the Billboard patch. This patch allows an image to be displayed. In this composition, the Billboard patch is displaying an image provided by an Image Importer patch. Using this patch, you can import any image supported by QuickTime into a composition, as shown in Figure 7.

Figure 7: Examining the Image Patch.

The third patch that we want to examine is a Sprite patch. This patch provides the spinning text at the bottom of the viewer by obtaining an image from the Image with String patch. You can use the Inspector to change the text used by this composition by editing the Image with String patch.

Figure 8: Examining the Image with String Patch.

So far, we've just examined how this basic composition is structured and edited a few input parameters. Let's do something a bit more fun. Lets add some patches and create something that looks a bit better than what we have in Figure 8. In the editor, select all of the patches except for the Gradient patch and delete them. This will leave us with a plain gradient on top of which to work.

Now, using the Patch Library on the left side of the Quartz Composer editor window, find the Particle System Renderer and double-click on it. This will create a new instance of the patch and you'll immediately see white squares animating on top of the background gradient, as shown in Figure 9.

Figure 9: Adding the Particle System Renderer.

Next, let's give the particle system patch a nicer image to work with. Find the Lenticular Halo Generator patch. Create a new instance of the patch and then connect its image output up to the image input of the particle system patch. Now you'll see a result similar to Figure 10.

Figure 10: Adding an Image to the Particle System Renderer.

The last thing we need to do is to change the way the halo images are blended by the particle system renderer on top of the gradient. The default results in those ugly black squares. Using the inspector, change the blending input to parameter to Over. This will result in something like what Figure 11 shows.

Figure 11: Adding an Image to the Particle System Renderer.

You can add interactivity to a composition using a variety of Controller patches. For example, you can add a Mouse Controller patch and hook the X and Y outputs up to the X Position and Y Position inputs of the particle system patch. This lets you steer the creation point of the halos with your mouse.

Figure 12: Adding a Mouse Controller Patch to the Composition.

In just a few short simple steps, we've covered the basics of how to work with the Quartz Composer programming model. Now, let's look a bit more at the types of patches that you can work with.

Types of Patches

As you've seen from the example above, Quartz Composer provides patches that render to the screen, patches that work with values, and patches that pull in data from external sources. These patches can be formally defined as:

• Consumer patches which render a result to the screen. Both the Gradient and Particle System patches in our example fall into this category. You can identify these kinds of patches by their magenta header.
• Processor patches which process data at specific intervals or in response to changing input values. The Lenticular Halo patch in our example provides an image to the Particle System to display. You can identify these kinds of patches by their green header.
• Provider patches which supply data from an outside source. In our example, the Mouse patch provides the X and Y coordinates of the current mouse position to the composition. You can identify these patches by their light blue header.

At runtime, Quartz Composer executes the functionality in consumer patches first. Processor and provider patches are executed as consumer patches pull data from them. In our example above, each time Quartz Composer tells the Particle System patch to render to screen, the patch will obtain the X and Y mouse coordinates from it's connections to the Mouse patch. It will then get an image to display from the Lentincular Halo patch from its connection to it. For each frame, the process is repeated.

Using Compositions

Once built, Quartz Composer compositions can be used in a variety of ways. To use one as a screen saver, you can save the composition to your ~/Library/Screen Savers or /Library/Screen Savers folder and it will be come available in the Screen Saver Preference Panel, as shown in Figure 13.

Figure 13: Using a Composition as a Screen Saver.

You can also embed Quartz Composer compositions into a Cocoa application using the QCView object. An example of our example composition embedded in a Cocoa window is shown in Figure 14 (click to activate).

Figure 14: A Composition Embedded into a Cocoa Window (Click to View the QuickTime Movie [8 Kb])

Simply embedding a composition in an application is flashy, but to be useful, there needs to be a way for a composition to either be fed data from external sources or for it to provide data. Luckily, Quartz Composer offers us a way to do this.

Publishing Inputs and Outputs

To communicate with the outside world, you can designate various inputs and outputs of the patches in your composition to be published inputs and outputs. This means that external objects can bind themselves to the inputs and outputs and either feed data into a composition or obtain data from it. This lets you drive a composition with external controls or use it to create images for use elsewhere.

To show this, let's set up the X and Y position of the Particle System patch to be published inputs instead of being driven by the mouse. First delete the Mouse patch. Then, Control-click on the Particle System patch. A context menu will appear, as shown in Figure 15, letting you select inputs and outputs to publish. SelectingPublished Inputs > X Position from the context menu to publish it. You will then be prompted to name the input. Do the same for the Y Position input.

Figure 15: Publishing an Input.

To see the published inputs in action, use the Viewer > Show Parameters menu. This will show you the published inputs for the composition as well as let you adjust them, as shown in Figure 16.

Figure 16: Viewing and Manipulating a Composition's Published Inputs.

Now that the parameters have been published, they are available when the composition is run as a screen saver, as shown in Figure 17.

Figure 17: Manipulating Parameters for a Screen Saver Composition.

You can also use a compositions published inputs and outputs in Cocoa application using Cocoa Bindings. Figure 18 shows two sliders that are bound to the compositions inputs. This would let a user manipulate the composition from the host application.

Figure 18: Providing Input to a Composition using Cocoa Bindings.

As you can imagine, the ability to interact with other parts of a program through published inputs and outputs gives compositions a great deal of potential. You can use them for the creation of innovative and exciting visual applications.

Examples and Inspiration

Now that we've scratched the surface of Quartz Composer and shown you how the programming model works, you should take a look at the following examples to see how others are putting Quartz Composer to use:

• The Quartz Composer Discussion List is a key resource for Quartz Composer issues among developers.
• Futurismo Zugakousaku has a wonderful set of Quartz Composer examples, all of which you can view in your browser.
• Sam Kass has created several examples that use an iSight as an input source.
• Quartonian is a tool for Video DJs (VJs) built with Quartz Composer.