Mac Developer Library

Developer

Quartz Framework Reference QCComposition Class Reference

Options
Deployment Target:

On This Page
Language:

QCComposition

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.

Inheritance


Conforms To


Import Statement


Swift

import Quartz

Objective-C

@import Quartz;

Availability


Available in OS X v10.5 and later.
  • Returns a composition object initialized with a Quartz Composer composition file.

    Declaration

    Swift

    init!(file path: String!) -> QCComposition

    Objective-C

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

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    init!(data data: NSData!) -> QCComposition

    Objective-C

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

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

  • Returns the attributes of the composition.

    Declaration

    Swift

    func attributes() -> [NSObject : AnyObject]!

    Objective-C

    - (NSDictionary *)attributes

    Return Value

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

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

  • Returns the list of protocols to which the composition conforms.

    Declaration

    Swift

    func protocols() -> [AnyObject]!

    Objective-C

    - (NSArray *)protocols

    Return Value

    A list of protocols. See “Standard Protocols”.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func identifier() -> String!

    Objective-C

    - (NSString *)identifier

    Return Value

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

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func inputKeys() -> [AnyObject]!

    Objective-C

    - (NSArray *)inputKeys

    Return Value

    An array of input keys.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func outputKeys() -> [AnyObject]!

    Objective-C

    - (NSArray *)outputKeys

    Return Value

    An array of output keys.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

  • Attributes of a composition.

    Declaration

    Swift

    let QCCompositionAttributeNameKey: NSString! let QCCompositionAttributeDescriptionKey: NSString! let QCCompositionAttributeCopyrightKey: NSString! let QCCompositionAttributeBuiltInKey: NSString! let QCCompositionAttributeHasConsumersKey: NSString! let QCCompositionAttributeCategoryKey: NSString!

    Objective-C

    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

      QCCompositionAttributeNameKey

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

      Available in OS X v10.4 and later.

    • QCCompositionAttributeDescriptionKey

      QCCompositionAttributeDescriptionKey

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

      Available in OS X v10.4 and later.

    • QCCompositionAttributeCopyrightKey

      QCCompositionAttributeCopyrightKey

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

      Available in OS X v10.4 and later.

    • QCCompositionAttributeBuiltInKey

      QCCompositionAttributeBuiltInKey

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

      Available in OS X v10.5 and later.

    • QCCompositionAttributeTimeDependentKey

      QCCompositionAttributeTimeDependentKey

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

    • QCCompositionAttributeHasConsumersKey

      QCCompositionAttributeHasConsumersKey

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

      Available in OS X v10.5 and later.

    • QCCompositionAttributeCategoryKey

      QCCompositionAttributeCategoryKey

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

      Available in OS X v10.5 and later.

  • Categories for compositions.

    Declaration

    Swift

    let QCCompositionCategoryDistortion: NSString! let QCCompositionCategoryStylize: NSString! let QCCompositionCategoryUtility: NSString!

    Objective-C

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

    Constants

    • QCCompositionCategoryDistortion

      QCCompositionCategoryDistortion

      A composition that produces a distortion effect.

      Available in OS X v10.5 and later.

    • QCCompositionCategoryStylize

      QCCompositionCategoryStylize

      A composition that produces a stylize effect.

      Available in OS X v10.5 and later.

    • QCCompositionCategoryUtility

      QCCompositionCategoryUtility

      A utility composition.

      Available in OS X v10.5 and later.

  • Input ports of a composition.

    Declaration

    Swift

    let QCCompositionInputImageKey: NSString! let QCCompositionInputSourceImageKey: NSString! let QCCompositionInputDestinationImageKey: NSString! let QCCompositionInputRSSFeedURLKey: NSString! let QCCompositionInputRSSArticleDurationKey: NSString! let QCCompositionInputPreviewModeKey: NSString! let QCCompositionInputXKey: NSString! let QCCompositionInputYKey: NSString! let QCCompositionInputScreenImageKey: NSString! let QCCompositionInputAudioPeakKey: NSString! let QCCompositionInputAudioSpectrumKey: NSString! let QCCompositionInputTrackPositionKey: NSString! let QCCompositionInputTrackInfoKey: NSString! let QCCompositionInputTrackSignalKey: NSString! let QCCompositionInputPrimaryColorKey: NSString! let QCCompositionInputSecondaryColorKey: NSString! let QCCompositionInputPaceKey: NSString!

    Objective-C

    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

      QCCompositionInputImageKey

      An image input port whose key is inputImage.

      Available in OS X v10.5 and later.

    • QCCompositionInputSourceImageKey

      QCCompositionInputSourceImageKey

      An image input port whose key is inputSourceImage.

      Available in OS X v10.5 and later.

    • QCCompositionInputDestinationImageKey

      QCCompositionInputDestinationImageKey

      An image input port whose key is inputDestinationImage.

      Available in OS X v10.5 and later.

    • QCCompositionInputRSSFeedURLKey

      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.

    • QCCompositionInputRSSArticleDurationKey

      QCCompositionInputRSSArticleDurationKey

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

      Available in OS X v10.5 and later.

    • QCCompositionInputPreviewModeKey

      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.

    • QCCompositionInputXKey

      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.

    • QCCompositionInputYKey

      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.

    • QCCompositionInputScreenImageKey

      QCCompositionInputScreenImageKey

      An image input port whose key is inputScreenImage.

      Available in OS X v10.5 and later.

    • QCCompositionInputAudioPeakKey

      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.

    • QCCompositionInputAudioSpectrumKey

      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.

    • QCCompositionInputTrackPositionKey

      QCCompositionInputTrackPositionKey

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

      Available in OS X v10.5 and later.

    • QCCompositionInputTrackInfoKey

      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.

    • QCCompositionInputTrackSignalKey

      QCCompositionInputTrackSignalKey

      A Boolean input port whose key is inputTrackSignal.

      Available in OS X v10.5 and later.

    • QCCompositionInputPrimaryColorKey

      QCCompositionInputPrimaryColorKey

      A color input port whose key is inputPrimaryColor.

      Available in OS X v10.5 and later.

    • QCCompositionInputSecondaryColorKey

      QCCompositionInputSecondaryColorKey

      A color input port whose key is inputSecondaryColor.

      Available in OS X v10.5 and later.

    • QCCompositionInputPaceKey

      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.

  • Output ports of a composition.

    Declaration

    Swift

    let QCCompositionOutputImageKey: NSString! let QCCompositionOutputWebPageURLKey: NSString!

    Objective-C

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

    Constants

    • QCCompositionOutputImageKey

      QCCompositionOutputImageKey

      An image output port whose key is outputImage.

      Available in OS X v10.5 and later.

    • QCCompositionOutputWebPageURLKey

      QCCompositionOutputWebPageURLKey

      A string output port whose key is outputWebPageURL.

      Available in OS X v10.5 and later.

  • Protocols for a composition.

    Declaration

    Swift

    let QCCompositionProtocolGraphicAnimation: NSString! let QCCompositionProtocolGraphicTransition: NSString! let QCCompositionProtocolImageFilter: NSString! let QCCompositionProtocolScreenSaver: NSString! let QCCompositionProtocolRSSVisualizer: NSString! let QCCompositionProtocolMusicVisualizer: NSString!

    Objective-C

    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

      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.

    • QCCompositionProtocolGraphicTransition

      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.

    • QCCompositionProtocolImageFilter

      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.

    • QCCompositionProtocolScreenSaver

      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.

    • QCCompositionProtocolImageTransition

      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

      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.

    • QCCompositionProtocolMusicVisualizer

      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.