Release Notes
For Quartz Composer Leopard
This document lists all the major changes to Quartz Composer in Leopard versus the previous version released in Mac OS X Tiger.
1) Quartz Composer Engine:
1.0 Redesigned Image Pipeline:
The Quartz Composer image pipeline has been completely redesigned and provides the following major enhancements over its former Tiger implementation:
Accurate color management
Support for arbitrary sized images
Support for float and half-float rendering
Improved sharing of resources between all QCViews, QCRenderers and QCCompositionLayers in the same process
Simplified texture properties (texture target, texturing matrix..)
Optimized Image Crop and Image Transform patches
1.1 Composition Repository:
To encourage sharing of compositions through the system and applications, there is a new system-wide repository of compositions (which have to comply to standardized sets of inputs / outputs a.k.a. "protocols") located in /System/Library/Compositions, /Library/Compositions and ~/Library/Compositions. Users and installers can add new compositions to those places, while the repository can be easily be queried by application clients using new APIs.
1.2 Support For Virtual Patches:
It's now possible to use composition files as virtual patches if placed into "/Library/Graphics/Quartz Composer Patches" or "~/Library/Graphics/Quartz Composer Patches". Any composition file in these directories will appear like a native patch to Quartz Composer. You can instantiate them in your compositions like any regular 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, only weak references are stored: if the composition file corresponding to a given virtual patch has been modified, or is simply missing, its dependend composition files will be affected.
If you want remove all dependencies to virtual patches from a composition, select "Save a Copy As..." while pressing the Option key, and this will save a flattened copy of the composition that embeds real copies of the virtual patches.
1.3 Other Enhancements:
Structures generated by patches can be keyless
Closed loops are fully allowed within the graph
2) Quartz Composer Patches:
2.1 New Patches:
Anchor Position - Outputs absolute values for the location an object should be if it were pinned to the edges or center of the screen with an optional offset amount towards the center of the screen.
Apple Remote - Outputs the current state of the Apple Remote buttons if available.
Composition Loader - Loads a composition into the current composition. Provides modularity and flexibility within compositions.
Composition Info - Retrieves the metadata and a list of inputs/outputs from a composition on disk.
Cylinder - Renders a 3D cylinder in space.
Demultiplexer - Translates a value received on the input to one of the outputs selected by an index.
Derivator - Outputs the derivative of a number. In other words, the speed at which it is changing.
Image Histogram - Computes a structure of values for quantities of each Red, Green, Blue and Alpha.
Image Resize - Modifies the size of an image to best fit the parameters given on the inputs.
Image Pixel - Gives the RGBA component values of a pixel in an image.
Integrator - Outputs a running sum of the input number each time it changes.
GLSL - Live editing of GLSL shaders which apply to objects inside this macro.
Grep - Uses regular expressions to scan a string and find patterns. Can also be used to search and replace based on a pattern.
HID Input - Outputs the current state of a list of observed elements of a HID compliant USB input device.
Line - Draws a line in 3D space and interpolates between a start color and end color.
Math Expression - Parses an equation and creates the variables as input ports. Expressions are evaluated as necessary and the result is output.
MIDI Controls - Sends arbitrary MIDI controller values on a given MIDI channel to one or more MIDI destinations.
Network Broadcaster - Transmits a string over the local Bonjour network. Receivers can only listen to one Network Broadcast patch at a time so multiple values should be concatenated and sent simultaneously.
Network Receiver - Receives values from the broadcaster.
Network Synchronizer - Two way communication across the local Bonjour network.
Noise - Given an input point in 1D, 2D, or 3D space this patch outputs a random value.
Number Formatter - Outputs a number as a formatted string.
OSC Client - Implements the client of the Open Sound Control protocol.
OSC Server - Implements the server of the Open Sound Control protocol.
Pulse - Outputs a true boolean value for a single frame when the input changes. The input condition can be rising edge, falling edge or both.
Queue - Implements a first-in last-out queue of an arbitrary size and which accepts any kind of values.
Sample And Hold - Stores an arbitrary value or object on its output port.
Smooth - Gradually interpolates between the current numeric value to a new value provided on the input port.
String MD5 - Produces a hash of the input string.
String Replace - Replaces occurrences of a substring within a string with another string.
String Subrange - Extracts a substring from the input string.
Timelines - Allows drawing arbitrary curves and setting keyframes for outputting values.
Watcher - Outputs a signal when the input changes.
XML Downloader - A more generalized XML loader, for files on disk or on the internet.
2.2 Updated Patches:
Affine Transform is now Image Transform - No longer has Texture Format and Parameters.
Audio Input - Added fall speed inputs for peak and spectrum and an option to turn on specific source listening. When this is off all sources are listened to.
Billboard - Always uses Direct CI rendering now. A new setting for determining image dimensions has been added. Force pixel alignment is good for ensuring images do not get blurred by straddling pixel boundaries but is not suited for billboards which are animated because the movement will appear choppy as the image jumps from pixel to pixel.
Core Image Accumulator - Image dimensions are now an input, Texture format and Parameters have been removed.
Core Image Filter - Domain of Defintion is a union of input samplers. New advanced input sampler options are available. It is now possible to edit the filter function and call multipass core image routines.
Folder Images became Directory Scanner, with an option to scan for images, movies or compositions.
Gradient - Variable number of gradient points, at user defined positions. More direction modes were also added.
Host Info - CPU load is now a structure instead of separate output ports.
Image Crop - The crop patch is no longer a Core Image filter and is instead handled directly in QC for better performance and less image transformations.
Image Downloader - Update Signal to tell the image downloader to reload the image. Removed Texture Format and Parameters. Synchronous Download option to ensure the composition does not continue until the image has loaded. Disable Color Correction setting added. Also outputs the progress of the download.
Image Importer - Texture Format and Parameters removed. Disable Color Correction setting added.
Image Texturing Matrix is now Image Texturing Properties, has added Target and Mipmapping options.
Image With Movie is now Movie Loader - Movie playhead position output, Asynchronous mode setting added (for audio syncing). To decompress a video directly at a specific size, Frame dimensions setting has been added. Deinterlace hint, Clean aperature, Disable color correction settings have also been added.
Image With String - Texture Format and Texture Parameters are no longer available on this patch. Quartz Composer has improved support for images that are larger than can fit on the video card.
Javascript - Typed return values, function declarations, image and structure support.
Math - UI change to make number of operations visible.
Midi Clock - Option to listen to all midi sources.
Midi Controllers - Option to listen to all midi sources, Listen button to add the next modified controller to the observed controllers list.
Midi Notes - An option to listen to all midi sources has been added. There is also a setting to translate the labels on the midi notes to match other applications.
Mouse - Scroll wheel support added.
Multiplexer - UI changed so that Number of Inputs is visible
Particle System - Particle Count is now an input. Interpolate Size and Color adds inputs for a target size and an interpolation mode to arrive there over the lifetime.
Psychedelic - Clear Depth Buffer setting
RSS Feed is now RSS Downloader - Update signal input for reloading article, a setting to preserve HTML in contents, Preserve Extensions option for non-RSS xml elements, and an Synchronous dowload option to ensure the RSS is loaded before the composition continues. Also outputs the progress of the download.
Random - Now works in an iterator when "Use Perlin Noise" is selected. New instances of this patch do this automatically, but old compositions retain their previous random behavior.
Render in image - Inputs for Texture Target and Mip Mapping, dimensions. Settings for Depth Buffer Rendering, Feedback rendering and color matching.
Sphere - Scale input is now Diameter
Splitter - When the splitter has type "Index" and the range is bounded, index elements can be named. These show up as labels on the splitter and parameter views in Quartz Composer and client applications.
Sprite - Resolution setting to add fragments and verticies for GLSL to act upon
Stop Watch - Refactored start modes to be more intuitive.
TrackBall - Track Mouse allows you to disable mouse tracking as needed.
Video Input - Added a Capture input to enable camera, video device selector, Clean aperature and color correction settings, removed Image Dimensions, Texture Format and Texture Parameters
2.3 Deprecated Patches:
Plasma Image
Spotlight Images
2.4 New Core Image Filters:
CIAreaAverage - Returns a single-pixel image, containing the average color in the region-of-interest.
CIAreaHistogram - Returns a 1D image containing the component-wise histogram over the specified rectangle area.
CIAreaMaximum - Returns a single-pixel image, containing the maximum color components in the region-of-interest.
CIAreaMaximumAlpha - Returns a single-pixel image, containing the color vector with the maximal alpha value in the region-of-interest. If more than one pixel exists with the maximal alpha value, the vector with the lowest y and x coordinate is returned.
CIAreaMinimum - Returns a single-pixel image, containing the minimum color components in the region-of-interest.
CIAreaMinimumAlpha - Returns a single-pixel image, containing the color vector with the minimal alpha value in the region-of-interest. If more than one pixel exists with the minimal alpha value, the vector with the lowest y and x coordinate is returned.
CIBarsSwipeTransition - Transitions from one image to another by swiping rectangular portions of the foreground image to disclose the target image.
CIBoxBlur - Smooths or sharpens an image using a box-shaped convolution kernel.
CIBumpDistortionLinear - Creates a bump that originates from a linear portion of the image.
CIColumnAverage - Returns a 1-pixel high image containing the average color in each scan-column
CIComicEffect - Simulates a comic book drawing by outlining edges and applying a color halftone effect.
CIDiscBlur - Smooths or sharpens an image using a disc-shaped convolution kernel.
CIEightfoldReflectedTile - Produces a tiled image from a source image by applying an 8-way reflected symmetry.
CIFourfoldReflectedTile - Produces a tiled image from a source image by applying a 4-way reflected symmetry.
CIFourfoldRotatedTile - Produces a tiled image from a source image by rotating the source at increments of 90 degrees.
CIFourfoldTranslatedTile - Produces a tiled image from a source image by applying 4 tranlsation operations.
CIGlideReflectedTile - Produces a tiled image from a source image by translating and smearing the image.
CIHexagonalPixellate - Displays an image as colored hexagons whose color is an average of the pixels they replace.
CILineOverlay - Creates a sketch that outlines the edges of an image in black, leaving the non-outlined portions of the image transparent.
CIMaximumComponent - Return a grayscale image from max(r, g, b)
CIMinimumComponent - Return a grayscale image from min(r, g, b)
CIRowAverage - Returns a 1-pixel high image containing the average color in each scan-row.
CISixfoldReflectedTile - Produces a tiled image from a source image by applying a 6-way reflected symmetry.
CISixfoldRotatedTile - Produces a tiled image from a source image by rotating the source at increments of 60 degrees.
CISpotColor - Replaces one ore more color ranges with spot colors.
CITwelvefoldReflectedTile - Produces a tiled image from a source image by applying a 12-way reflected symmetry.
3) Quartz Composer Editor:
3.1 New Features:
Patch Creator
The Patch browser has been replaced with the new Patch Creator window. The Patch Creator allows users to quickly find the patch or clip they want and insert it into the graph.
You can show the Patch Creator by hitting cmd-Enter, and you can easily dismiss it by pressing escape.
There is also a preference, which is off by default, to automatically hide the Patch Creator after inserting a patch into the workspace.
Patches based on Core Image filters are no longer reported with a bullet in the list, but appear like regular patches.
Comparing Compositions
Users can now compare two compositions in order to see rendering differences, as well as graph differences.
In order to access this tool, choose 'Compare Compositions' from the File menu of the Quartz Composer Editor application.
This tool is very powerful if there are multiple individuals working on the same composition.
Template Assistant
The initial user experience has been completely rewritten to provide a better set of templates that correspond to compositions in the new Composition Repository.
Protocol Conformance Editor
This editor allows users to modify which Composition Repository protocols the composition responds to. It will insert, and remove the necessary patches to ensure compliance.
Metadata Editor
The Composition Information Editor has been extended (i.e. Metadata Editor) to allow users to enter arbitrary types of information. Thus allowing the users generate their own metadata for use in their own compositions.
Clip Management
Clip management has been integrated into the Editor application. To expose the Clip Manager, open the Preferences, and choose the 'Clips' tab.
You can also create clips on the fly from a given selection. This clip will then be added to the user's list of clips.
Choose the patches you want in your clip, then choose 'Create Clip...' from the Editor menu.
Patch Inputs Pane
There is a new Patch inputs pane that allows you to easily compare and edit selected patches input values. It also shows the parent macro's inputs.
You can expose this by selecting 'Show Input Parameters' from the Editor menu.
Independent Settings Windows
Users now have the ability to open a separate window that contains the contents of the inspector's Settings pane for the selected patch. This is very useful for programming patches, as well as duplicating settings between two similar patches.
To open one of these, select a patch with a settings pane and choose 'Show Patch Settings' from the Editor menu.
Compatibility
To ensure compositions will behave the same on OS X Tiger, select "Display 10.4 Compatibility Information" in the Editor menu.
To check which patches will be disallowed from running in safe environments (WebKit and QuickTime for example), select "Indicate Unsafe Patches" in the Editor menu. Unsafe patches are those which could potentially disclose personal user information or access certain hardware resources.
3.3 Improvements:
Workspace Improvements
The workspace now has unlimited size.
Zooming in/out is now supported via the scroll wheel, or the improved toolbar buttons.
⁃ There are now buttons to zoom to fit all patches, and zooming to fit selected patches.
Users can now click on ports to create connections, rather than having to click-drag to create them.
⁃ Option click retains hold on a connection, allowing multiple inputs to be connected from one output in succession.
Insert Input/Output Splitter Contextual menu
⁃ These menu items insert an input splitter for a specified port. All connections and published states will be moved to the new splitter's port.
Select Upstream/Downstream Patches
⁃ These menu items will allow you to select all patches 'downstream', or 'upstream' of the selected patches. This means that every patch connected to the output ports (downstream) or input ports (upstream) will be selected recursively through the graph. This is very useful for rearranging or moving functional units of your composition.
Connection highlighting
⁃ When a patch is selected, all connections in the composition that are not connected to a selected patch are drawn in a gray color. All connections that either end or begin in a selected patch are drawn their normal color. This allows users to easily track where connections originate and terminate.
Patch Titles: The patch title can now be set by simply double clicking on it.
⁃ Some patches have automatic titles (Splitters, Multiplexer, and Mathematical Expression for example). These titles are automatically set to represent specific aspects of the patch's settings. You can still customize the title on those patches by editing it and removing the quotes.
Tooltip Improvements
⁃ Patch Descriptions are now shown in the tooltip.
Workspace Notes
⁃ Users can now create Notes to annotate a composition. To create a note, right click or control click on the workspace. If a multi-line description is necessary, press option-return to insert a newline. Colors can be changed by right click or control clicking on the note.
Other Workspace Improvements
⁃ The 'Rendering Layer' section of a patch now acts like a pulldown button, rather than a contextual menu.
⁃ Blending mode now uses Replace rather than None for clarity on all patches.
⁃ Inspector Improvements
⁃ The Information pane has been removed.
⁃ Inspector window now remembers the selected pane, rather than defaulting to the Information pane when you change patches.
⁃ A new Inputs/Outputs Pane allows the reordering of input and output ports, while preserving connections, and published port state.
Viewer Improvements
The viewer window's minimum dimensions have been reduced. Allowing you to create compositions that are targeted at much smaller rendering dimensions.
The CPU load has been removed, since the numbers were quite misleading.
There is now a 'Snapshot' toolbar item that allows users to save a snapshot to disk.
Customizable Viewer dimensions
⁃ It is now possible to define arbitrary aspect ratios and pixel dimensions that the viewer will be constrained to. To choose one of these, simply select the desired setting from the lower left corner of the Viewer window.
⁃ Custom Viewer dimensions can be defined under the 'Viewer' tab Editor's preferences.
4) 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 spanned over multiple screens on a single computer or even on a cluster of computers.
The source code of Quartz Composer Visualizer is available as well in /Developer/Examples/Quartz Composer Sample Code.
5) Quartz Composer Support in Automator:
There are 3 new Automator actions for Quartz Composer Support:
Apply Quartz Composition Filter to Image Files
Convert Quartz Compositions to QuickTime Movies
Render Quartz Compositions to Image Files
6) Quartz Composer Developer Examples:
The Quartz Composer Developer Examples are now in two directories ("Quartz Composer Compositions" and "Quartz Composer Sample Code") and they contain a great number of new demo compositions, custom patches and applications demonstrating all kinds of techniques with Quartz Composer: make sure to browse them all.
7) Quartz Composer APIs:
5.1 New APIs:
QCPlugIn / QCPlugInViewController:
The API to write custom patches for Quartz Composer.
QCComposition:
An opaque object representing a Quartz composition, either created directly from a file on disk or from the composition repository.
QCCompositionRepository:
The API to access the system-wide repository of compositions which comply to standardized sets of inputs / outputs (also called "protocols").
QCCompositionLayer:
A Core Animation layer that renders a Quartz composition within Core Animation.
QCCompositionPickerView / QCCompositionPickerPanel:
A view that displays a configurable picker to select a composition from the composition repository.
QCCompositionParameterView:
A view that builds a standard UI to edit the input parameters of a composition loaded on a QC renderer.
QCView:
Loading and unloading compositions:
- (BOOL) loadComposition:(QCComposition*)composition;
- (BOOL) isCompositionLoaded;
- (void) unloadComposition;
Pausing rendering:
- (void) pauseRendering;
- (BOOL) isPausedRendering;
- (void) resumeRendering;
Customizing rendering by subclassing QCView:
- (BOOL) renderAtTime:(NSTimeInterval)time arguments:(NSDictionary*)arguments;
- (NSOpenGLContext*) openGLContext;
- (NSOpenGLPixelFormat*) openGLPixelFormat;
Capturing the QCView contents as an NSImage, CIImage, CGImage...
- (NSImage*) snapshotImage;
- (id) createSnapshotImageOfType:(NSString*)type;
Retrieving composition results as a given data type:
- (id) valueForOutputKey:(NSString*)key ofType:(NSString*)type;
New Interface Builder action to play / pause:
- (IBAction) play:(id)sender;
QCRenderer
Creating a QCRenderer from a CGLContextObj and a colorspace:
- (id) initWithCGLContext:(CGLContextObj)context pixelFormat:(CGLPixelFormatObj)format colorSpace:(CGColorSpaceRef)colorSpace composition:(QCComposition*)composition;
Creating an offscreen QCRenderer:
- (id) initOffScreenWithSize:(NSSize)size colorSpace:(CGColorSpaceRef)colorSpace composition:(QCComposition*)composition;
Creating a QCRenderer with a purely processing composition:
- (id) initWithComposition:(QCComposition*)composition colorSpace:(CGColorSpaceRef)colorSpace;
Capturing the QCRenderer contents as an NSImage, CIImage, CGImage...
- (NSImage*) snapshotImage;
- (id) createSnapshotImageOfType:(NSString*)type;
5.2 Updated APIs:
For optimal image passing between multiple QC renderers, a new opaque image type is supported: QCImage.
The methods [QCRenderer attributes] and -[QCView attributes] now returns all metadata stored in the composition.
When looking at port attributes for index ports, QCPortAttributeMenuItemsKey may be present and contain an NSArray of NSStrings representing the menu item titles.