QCComposition Class Reference

Inherits from
Conforms to
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

Overview

The QCComposition class represents a Quartz Composer composition that either:

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:

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.
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
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