Quartz Composer Release Note for Mac OS X v10.5

This document summarizes the major changes to Quartz Composer in Leopard since the previous version released in Mac OS X v10.4. For a full description of the major improvements see the Release Notes available through the Help menu of the Quartz Composer application, which is located in:

/Developer/Applications/Quartz Composer.app

Contents:

Redesigned Image Pipeline
Composition Repository
Support for Virtual Patches
New and Updated Patches
Quartz Composer Editor
Quartz Composer Visualizer
Quartz Composer Support in Automator
Quartz Composer Developer Examples
Quartz Composer API
Updated Reference Documentation

Redesigned Image Pipeline

The Quartz Composer image pipeline is completely redesigned and provides the following major enhancements over its previous implementation:

• Accurate color management

• Support for arbitrary-sized images

• Support for floating-point and half-floating point rendering

• Improved sharing of resources between all QCView, QCRenderer and QCCompositionLayer objects in the same process

• Simplified texture properties (texture target, texturing matrix)

Composition Repository

To encourage sharing of compositions through the system and applications, there is a new system-wide repository of compositions in these locations:

• /System/Library/Compositions

• /Library/Compositions

• ~/Library/Compositions

Compositions in the repository must comply to protocols—standardized sets of input and output ports. A composition can be added to the repository either by a user or an installer. Application clients can find out what’s in the repository by querying it using the new APIs.

Support for Virtual Patches

You can now use composition files as virtual patches. All you need to do is place a composition file in either of these directories:

• /Library/Graphics/Quartz Composer Patches

• ~/Library/Graphics/Quartz Composer Patches

Composition files in these directories look like a native patch to Quartz Composer. You can instantiate them in your compositions as you would any of the built-in patches but, contrary to editor clips, each instantiation results in a non-editable virtual copy instead of a real autonomous copy. Furthermore, when saving a composition file that uses virtual patches, Quartz Composer stores only weak references. If the composition file corresponding to a given virtual patch is modified os missing, any composition that depends on it is affected.

To remove all dependencies to virtual patches from a composition, you can select "Save a Copy As..." while pressing the Option key. Quartz Composer then saves a flattened copy of the composition that embeds real copies of the virtual patches.

New and Updated Patches

Quartz Composer introduces a significant number of new patches in Mac OS X v105. It has also improved the functionality of many of the existing patches. For a list of what is new or updated, see the Release Notes available through the Help menu of the Quartz Composer application.

Quartz Composer Editor

The Quartz Composer editor include many, many changes. A summary of highlights include:

• The Patch Creator window replaces the Patch browser. The new window is designed to allow users to quickly find a patch or clip and insert it into the graph by pressing Enter when a patch is selected. You can show the Patch Creator by pressing Command-Return. You can set an option in the Preferences pane to automatically hide the Patch Creator.

• Users can now compare two compositions by choosing Compare Compositions from the File menu of the Editor. The comparison window that opens displays rendering differences as well as differences between the two compositions.

• When you open Quartz Composer, you see the Template Assistant. It’s designed to provide a starting point for creating compositions for the composition repository. You can create compositions that conform to multiple Protocols using the Protocol Conformance Editor.

• The Metadata Editor provides a way to add information to a composition which may be read within your application, or by other users of your composition.

• You can manage clips in the Clips pane of Preferences window.

• There is a new Patch inputs pane that allows you to easily compare and edit selected patches input values. It also shows the input parameters for the parent macro.

• To ensure compositions will behave the same in both Mac OS X v10.4 as they do in Mac OS X v10.5, choose Editor > Display 10.4 Compatibility Information. You can also check which compositions won’t be able to run n safe environments (WebKit and QuickTime, for example). To do so, choose Editor > Indicate Unsafe Patches. Unsafe patches are those that have the potential to disclose personal user information or access certain hardware resources.

• The size of the workspace is now unlimited. The editor supports zooming in several ways: using the scroll wheel, through toolbar buttons, by using keyboard commands. You can also fit the selected set of patches to the viewable workspace.

• Previously you made a connection by clicking and dragging. Now you can now click ports to create connections. By using the Option modifier key you can now connect one output to multiple inputs in succession.

• The Insert Input/Output Splitter contextual menu allows you to re-factor without breaking connections.

• Select Upstream/Downstream Patches allows you to select patches that are connected to the current patch. Connections leading from the currently selected set of patches are highlighted to enhance the editing experience.

• Workspace Notes allow you to document you compositions by grouping patches without tying them together at the execution level. You can rename a patches by double clicking its title.

• The inspector has a new Inputs/Outputs pane for reordering ports on Macro patches. The Patch Description is now within the tool tip.

• You can customize the dimensions and aspect ratios of the Viewer, including a much smaller minimum size. You can add a Snapshot item to the Viewer toolbar that lets you copy the current image to the clipboard.

For a complete list of new and improved features, see the Release Notes available through the Help menu of the Quartz Composer application.

Quartz Composer Visualizer

There's a new Quartz Composer developer tool located in /Developer/Applications/Graphic Tools—Quartz Composer Visualizer. This application can render a Quartz Composition so that the rendered output spans multiple screens attached to a single computer or to a cluster of computers.

The source code of Quartz Composer Visualizer is located in /Developer/Examples/Quartz Composer.

Quartz Composer Support in Automator

There are three new Automator actions for Quartz Composer:

• Apply Quartz Composition Filter to Image Files

• Convert Quartz Compositions to QuickTime Movies

• Render Quartz Compositions to Image Files

Quartz Composer Developer Examples

The Quartz Composer Developer Examples, located in /Developer/Examples/Quartz Composer, contain a many new demonstration compositions, custom patches, and applications that demonstrate a variety of techniques that you can use with Quartz Composer. Make sure to browse them all.

Quartz Composer API

The Quartz Composer programming interface includes these new classes:

• QCPlugIn and QCPlugInViewController support writing custom patches for Quartz Composer.

• QCComposition is an opaque object that represents a Quartz composition, either created directly from a file on disk or from the composition repository.

• QCCompositionRepository provides access to the system-wide repository of compositions that comply to standardized sets of inputs and outputs (also called protocols).

• QCCompositionLayer is a Core Animation layer that renders a Quartz composition within Core Animation.

• QCCompositionPickerView and QCCompositionPickerPanel are views that display a configurable picker that allows users to select a composition from the composition repository.

• QCCompositionParameterView is a view that builds a standard user interface to edit the input parameters of a composition loaded on a QCRenderer object.

The QCView class has many new methods:

• For loading and unloading compositions:

  • - (BOOL) loadComposition:(QCComposition*)composition;

  • - (BOOL) isCompositionLoaded;

  • - (void) unloadComposition;

• To pause rendering:

  • - (void) pauseRendering;

  • - (BOOL) isPausedRendering;

  • - (void) resumeRendering;

• To customize rendering by subclassing QCView:

  • - (BOOL) renderAtTime:(NSTimeInterval)time arguments:(NSDictionary*)arguments;

  • - (NSOpenGLContext*) openGLContext;

  • - (NSOpenGLPixelFormat*) openGLPixelFormat;

• For retrieving composition results as a given data type:

  • - (id) valueForOutputKey:(NSString*)key ofType:(NSString*)type;

• For controlling a composition from Interface Builder:

  • - (IBAction) play:(id)sender;

The QCRenderer class has several new methods:

• To create a QCRenderer from a CGLContextObj and a color space:

  • - (id) initWithCGLContext:(CGLContextObj)context pixelFormat:(CGLPixelFormatObj)format colorSpace:(CGColorSpaceRef)colorSpace composition:(QCComposition*)composition;

• To create an offscreen QCRenderer:

  • - (id) initOffScreenWithSize:(NSSize)size colorSpace:(CGColorSpaceRef)colorSpace composition:(QCComposition*)composition;

• To create a QCRenderer with a purely processing composition:

  • - (id) initWithComposition:(QCComposition*)composition colorSpace:(CGColorSpaceRef)colorSpace;

• To capture QCRenderer contents as an NSImage, CIImage, CGImage or other image type:

  • - (NSImage*) snapshotImage;

  • - (id) createSnapshotImageOfType:(NSString*)type;

Other updates include:

• For optimal image passing between multiple Quartz Composer renderers, Quartz Composer supports a new opaque image, QCImage.

• The methods -[QCRenderer attributes] and -[QCView attributes] now return all metadata stored in the composition.

• When looking at port attributes for index ports, QCPortAttributeMenuItemsKey may be present and contain an NSArray of NSString objects that represent the menu item titles.

Updated Reference Documentation

The complete documentation suites is updated for Mac OS X v10.5:

• Quartz Composer Custom Patch Programming Guidedescribes how to use the QCPlugIn class.

• Quartz Composer User Guide introduces the features in the latest Quartz Composer editor and describes how to create compositions.

• Quartz Composer Programming Guide describes how to use the classes and methods provided in the API. In Mac OS X v10.4, this document included a description of the Quartz Composer editor. All information related to the editor is now in the user guide.

• Quartz Composer Reference Collection provides reference documentation for the classes, protocols, and methods in the API. There are 8 new classes and 6 new protocols in Mac OS X v10.5.