QCComposition Class Reference

Inherits from	NSObject
Conforms to	NSCopying NSObject (NSObject)
Framework	/System/Library/Frameworks/Quartz.framework/Frameworks/QuartzComposer.framework
Availability	Available in OS X v10.5 and later.
Companion guide	Quartz Composer Programming Guide
Declared in	QCComposition.h QCCompositionRepository.h
Related sample code	Quartz Composer AnimatedCompostionLayer Quartz Composer LiveEdit Quartz Composer Offline Quartz Composer ParameterView Quartz Composer Poster

Overview

The QCComposition class represents a Quartz Composer composition that either:

comes from the system-wide composition repository (/Library/Compositions and ~/Library/Compositions) where it can be accessed by any application through the methods of the QCCompositionRepository class
is created from an arbitrary source (typically a file on disk) using one of its methods

This class cannot be subclassed.

A QCComposition object has the following information associated with it and that you can obtain by using the appropriate method of the QCComposition class:

Attributes include the name and description of the composition, copyright information, and whether or not its provided by OS X (built-in).
The protocols that the composition conforms to. A composition protocol defines a set of required and optional input parameters and output results.

Many methods of the QCRenderer, QCCompositionLayer, and QCView classes take a QCComposition object as a parameter.

Tasks

Creating a Composition

Getting Information About a Composition

Getting Port Keys

Class Methods

compositionWithData:

Returns a composition object initialized with the contents of a Quartz Composer composition file.

+ (QCComposition*) compositionWithData:(NSData*)data;

Parameters

data: The contents of a file created with the Quartz Composer developer tool.

Return Value

A Quartz Composer composition object or nil if there is an error.

Availability

Available in OS X v10.5 and later.

Declared In

QCComposition.h

compositionWithFile:

Returns a composition object initialized with a Quartz Composer composition file.

+ (QCComposition*) compositionWithFile:(NSString*)path;

Parameters

path: A path to a file created with the Quartz Composer developer tool (.qtz extension).

Return Value

A Quartz Composer composition object or nil if there is an error.

Availability

Available in OS X v10.5 and later.

Declared In

QCComposition.h

Instance Methods

attributes

Returns the attributes of the composition.

- (NSDictionary*) attributes

Return Value

A dictionary of composition attributes. See “Attribute Keys” for the attributes that can be returned.

Availability

Available in OS X v10.5 and later.

Related Sample Code

Quartz Composer ParameterView

Declared In

QCComposition.h

identifier

Returns the unique and persistent identifier for the composition from the composition repository.

- (NSString*) identifier

Return Value

The unique identifier for the composition if it comes from the composition repository; nil otherwise.

Availability

Available in OS X v10.5 and later.

Related Sample Code

Quartz Composer MiniBooth

Declared In

QCCompositionRepository.h

inputKeys

Returns an array listing the keys that identify the input ports of the root patch of the composition.

- (NSArray*) inputKeys

Return Value

An array of input keys.

Availability

Available in OS X v10.5 and later.

Declared In

QCComposition.h

outputKeys

Returns an array listing the keys that identify the output ports of the root patch of the composition.

- (NSArray*) outputKeys

Return Value

An array of output keys.

Availability

Available in OS X v10.5 and later.

Declared In

QCComposition.h

protocols

Returns the list of protocols to which the composition conforms.

- (NSArray*) protocols

Return Value

A list of protocols. See “Standard Protocols”.

Availability

Available in OS X v10.5 and later.

Declared In

QCComposition.h

Constants

Attribute Keys

Attributes of a composition.

extern NSString* const QCCompositionAttributeNameKey;
extern NSString* const QCCompositionAttributeDescriptionKey;
extern NSString* const QCCompositionAttributeCopyrightKey;
extern NSString* const QCCompositionAttributeBuiltInKey;
extern NSString* const QCCompositionAttributeTimeDependentKey;
extern NSString* const QCCompositionAttributeHasConsumersKey;
extern NSString* const QCCompositionAttributeCategoryKey;

Constants

QCCompositionAttributeNameKey

The key for the composition name. The associated value is an NSString object.

Available in OS X v10.4 and later.

Declared in QCComposition.h.

QCCompositionAttributeDescriptionKey

The key for the composition description. The associated value is an NSString object.

Available in OS X v10.4 and later.

Declared in QCComposition.h.

QCCompositionAttributeCopyrightKey

The key for composition copyright information. The associated value is an NSString object.

Available in OS X v10.4 and later.

Declared in QCComposition.h.

QCCompositionAttributeBuiltInKey

The key for the composition origin. The associated value is an NSNumber object that contains a Boolean value. YES indicates the composition is built-in (provided by OS X).

Available in OS X v10.5 and later.

Declared in QCComposition.h.

QCCompositionAttributeTimeDependentKey

The key for the composition time dependency. The associated value is an NSNumber object that contains a Boolean value. YES indicates that the composition is time dependent.

QCCompositionAttributeHasConsumersKey

The key for a composition that has consumer patches. The associated value is an NSNumber object that contains a Boolean value. YES indicates that the composition has consumers.

Available in OS X v10.5 and later.

Declared in QCComposition.h.

QCCompositionAttributeCategoryKey

The composition category. The associated value is a category constant. See “Composition Categories.”

Available in OS X v10.5 and later.

Declared in QCComposition.h.

Declared In

QCComposition.h

Composition Categories

Categories for compositions.

extern NSString* const QCCompositionCategoryDistortion;
extern NSString* const QCCompositionCategoryStylize;
extern NSString* const QCCompositionCategoryUtility;

Constants

QCCompositionCategoryDistortion

A composition that produces a distortion effect.

Available in OS X v10.5 and later.

Declared in QCComposition.h.

QCCompositionCategoryStylize

A composition that produces a stylize effect.

Available in OS X v10.5 and later.

Declared in QCComposition.h.

QCCompositionCategoryUtility

A utility composition.

Available in OS X v10.5 and later.

Declared in QCComposition.h.

Declared In

QCComposition.h

Standard Protocol Input Keys

Input ports of a composition.

extern NSString* const QCCompositionInputImageKey;
extern NSString* const QCCompositionInputSourceImageKey;
extern NSString* const QCCompositionInputDestinationImageKey;
extern NSString* const QCCompositionInputRSSFeedURLKey;
extern NSString* const QCCompositionInputRSSArticleDurationKey;
extern NSString* const QCCompositionInputPreviewModeKey;
extern NSString* const QCCompositionInputXKey;
extern NSString* const QCCompositionInputYKey;
extern NSString* const QCCompositionInputScreenImageKey;
extern NSString* const QCCompositionInputAudioPeakKey;
extern NSString* const QCCompositionInputAudioSpectrumKey;
extern NSString* const QCCompositionInputTrackPositionKey;
extern NSString* const QCCompositionInputTrackInfoKey;
extern NSString* const QCCompositionInputTrackSignalKey;
extern NSString* const QCCompositionInputPrimaryColorKey;
extern NSString* const QCCompositionInputSecondaryColorKey;
extern NSString* const QCCompositionInputPaceKey;

Constants

QCCompositionInputImageKey

An image input port whose key is inputImage.

Available in OS X v10.5 and later.

Declared in QCComposition.h.

QCCompositionInputSourceImageKey

An image input port whose key is inputSourceImage.

Available in OS X v10.5 and later.

Declared in QCComposition.h.

QCCompositionInputDestinationImageKey

An image input port whose key is inputDestinationImage.

Available in OS X v10.5 and later.

Declared in QCComposition.h.

QCCompositionInputRSSFeedURLKey

A string input port whose key is inputRSSFeedURL. This port must be passed an http or feed scheme URL.

Available in OS X v10.5 and later.

Declared in QCComposition.h.

QCCompositionInputRSSArticleDurationKey

A number input port whose key is inputRSSArticleDuration. The value must be expressed in seconds.

Available in OS X v10.5 and later.

Declared in QCComposition.h.

QCCompositionInputPreviewModeKey

A Boolean input port whose key is inputPreviewMode. When the value of this input port is set to TRUE, the composition that provides this port must be able to run in a low-quality mode that produces a preview of the composition.

Available in OS X v10.5 and later.

Declared in QCComposition.h.

QCCompositionInputXKey

A number input port whose key is inputX. The value must be normalized to the image width with the origin on the left.

Available in OS X v10.5 and later.

Declared in QCComposition.h.

QCCompositionInputYKey

A number input port whose key is inputY. The value must be normalized to the image height with the origin at the bottom.

Available in OS X v10.5 and later.

Declared in QCComposition.h.

QCCompositionInputScreenImageKey

An image input port whose key is inputScreenImage.

Available in OS X v10.5 and later.

Declared in QCComposition.h.

QCCompositionInputAudioPeakKey

A number input port whose key is inputAudioPeak. The value must be in the [0,1] range as a mono signal with no decay applied.

Available in OS X v10.5 and later.

Declared in QCComposition.h.

QCCompositionInputAudioSpectrumKey

A structure input port whose key is inputAudioSpectrum. The structure must contain 16 values in the [0,1] range representing 16 spectrum bands of the mono signal from low to high frequencies with no decay applied.

Available in OS X v10.5 and later.

Declared in QCComposition.h.

QCCompositionInputTrackPositionKey

A number input port whose key is inputTrackPosition. The value must be expressed in seconds.

Available in OS X v10.5 and later.

Declared in QCComposition.h.

QCCompositionInputTrackInfoKey

A structure input port whose key is inputTrackInfo. The structure contains optional entries, such as “name”, “artist”, "album", "duration", "artwork", and so on.

Available in OS X v10.5 and later.

Declared in QCComposition.h.

QCCompositionInputTrackSignalKey

A Boolean input port whose key is inputTrackSignal.

Available in OS X v10.5 and later.

Declared in QCComposition.h.

QCCompositionInputPrimaryColorKey

A color input port whose key is inputPrimaryColor.

Available in OS X v10.5 and later.

Declared in QCComposition.h.

QCCompositionInputSecondaryColorKey

A color input port whose key is inputSecondaryColor.

Available in OS X v10.5 and later.

Declared in QCComposition.h.

QCCompositionInputPaceKey

A number input port whose key is inputPace. The value must be in the [0,1] range.

Available in OS X v10.5 and later.

Declared in QCComposition.h.

Declared In

QCComposition.h

Standard Protocol Output Keys

Output ports of a composition.

extern NSString* const QCCompositionOutputImageKey;
extern NSString* const QCCompositionOutputWebPageURLKey;

Constants

QCCompositionOutputImageKey

An image output port whose key is outputImage.

Available in OS X v10.5 and later.

Declared in QCComposition.h.

QCCompositionOutputWebPageURLKey

A string output port whose key is outputWebPageURL.

Available in OS X v10.5 and later.

Declared in QCComposition.h.

Declared In

QCComposition.h

Standard Protocols

Protocols for a composition.

extern NSString* const QCCompositionProtocolGraphicAnimation;
extern NSString* const QCCompositionProtocolGraphicTransition;
extern NSString* const QCCompositionProtocolImageFilter;
extern NSString* const QCCompositionProtocolImageCompositor;
extern NSString* const QCCompositionProtocolImageTransition;
extern NSString* const QCCompositionProtocolScreenSaverRSS;

Constants

QCCompositionProtocolGraphicAnimation

A composition that renders a generic graphical animation. It has the option to use QCCompositionInputPrimaryColorKey for the primary color of the animation, QCCompositionInputSecondaryColorKey for the secondary color of the animation, QCCompositionInputPaceKey for the global pace of the animation, and QCCompositionInputPreviewModeKey to indicate if the animation should run in lower-quality for preview purposes.

Available in OS X v10.5 and later.

Declared in QCComposition.h.

QCCompositionProtocolGraphicTransition

A composition that performs a transition between two images, using a transition time in range of 0 to 1. A conforming composition must use the input keys QCCompositionInputSourceImageKey for the starting image and QCCompositionInputDestinationImageKey for the image to transition to. The composition can optionally use QCCompositionInputPreviewModeKey to indicate if the animation should run in lower-quality for preview purposes.

Available in OS X v10.5 and later.

Declared in QCComposition.h.

QCCompositionProtocolImageFilter

A composition that applies an effect to a source image. A conforming composition must use the input key QCCompositionInputImageKey for the source image and QCCompositionOutputImageKey for the output image. The composition can optionally use QCCompositionInputXKey to specify the X position of the center point of the effect, QCCompositionInputYKey to specify the Y position of the center point of the effect, andQCCompositionInputPreviewModeKey to indicate if the animation should run in lower-quality for preview purposes.

Available in OS X v10.5 and later.

Declared in QCComposition.h.

QCCompositionProtocolScreenSaver

A composition that can be used as a screen saver. The composition has the option to use QCCompositionInputScreenImageKey for a screenshot image of the screen that the screen saver runs on, QCCompositionInputPreviewModeKey to indicate if the animation should run in lower-quality for preview purposes, and QCCompositionOutputWebPageURLKey for a URL to open in the default web browser when screen saver exits (only allowed if screen saver password is disabled).

Available in OS X v10.5 and later.

Declared in QCComposition.h.

QCCompositionProtocolImageTransition

A composition that performs a transition between two images, using a parametric time value to drives the transition from start (at time 0) to end (at time 1). A conforming composition must use the input keys QCCompositionInputImageKey for the starting image and QCCompositionInputDestinationImageKey for the ending image. The composition can optionally use QCCompositionInputPreviewModeKey to indicate if the animation should run in lower-quality for preview purposes.

QCCompositionProtocolRSSVisualizer

A composition that acts as a visualizer for an RSS feed. A conforming composition must use the input key QCCompositionInputRSSFeedURLKey for the URL to use for the RSS feed. It can optionally use QCCompositionInputRSSArticleDurationKey to specify the duration of each feed article.

Available in OS X v10.5 and later.

Declared in QCComposition.h.

QCCompositionProtocolMusicVisualizer

A composition that acts as a visualizer for music. A conforming composition must use the input key QCCompositionInputAudioPeakKey for the instantaneous audio peak and the QCCompositionInputAudioSpectrumKey for the instantaneous audio spectrum. It can optionally use the QCCompositionInputTrackInfoKey to indicate it receives information about the current track and the QCCompositionInputTrackSignalKey to indicate the start of a new track.

Available in OS X v10.5 and later.

Declared in QCComposition.h.

Declared In

QCComposition.h

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.