Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

QCView Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Quartz.framework/Frameworks/QuartzComposer.framework
Availability
Available in Mac OS X v10.4 and later.
Companion guide
Declared in
QCView.h

Overview

The QCView class is a custom NSView class that loads, plays, and controls Quartz Composer compositions. It is an autonomous view that is driven by an internal timer running on the main thread.

The view can be set to render a composition automatically when it is placed onscreen. The view stops rendering when it is placed offscreen. When not rendering, the view is filled with the current erase color. The rendered composition automatically synchronizes to the vertical retrace of the monitor.

When you archive a QCView object, it saves the composition that’s loaded at the time the view is archived.

If you want to perform custom operations while a composition is rendering such as setting input parameters or drawing OpenGL content, you need to subclass QCView and implement the renderAtTime:arguments: method.

Tasks

Performing Custom Operations During Rendering

Loading a Composition

Managing the Erase Color

Setting and Getting Event Masks

Setting and Getting the Maximum Frame Rate

Managing Rendering

Using Interface Builder

Taking Snapshot Images

Working With OpenGL

Instance Methods

autostartsRendering

Checks whether the view is set to start rendering automatically.

- (BOOL)autostartsRendering

Return Value

Returns YES if the view is set to start rendering automatically when the view is put on screen.

Availability
See Also
Declared In
QCView.h

createSnapshotImageOfType:

Returns the current image in the view as an image object of the provided image type.

- (id) createSnapshotImageOfType:(NSString*)type

Parameters
type

A string that specifies any of the following image types: NSBitmapImageRep, NSImage, CIImage, CGImage, CVOpenGLBuffer, CVPixelBuffer.

Return Value

The snapshot image in the provided image type. You are responsible for releasing this object when you no longer need it.

Availability
See Also
Declared In
QCView.h

erase

Clears the view using the current erase color.

- (void)erase

Availability
See Also
Declared In
QCView.h

eraseColor

Retrieves the current color used to erase the view.

- (NSColor *)eraseColor

Return Value

The color object previously set using the setEraseColor: method.

Availability
See Also
Declared In
QCView.h

eventForwardingMask

Retrieves the mask used to filter which types of events are forwarded from the view to the composition during rendering.

- (NSUInteger)eventForwardingMask

Return Value

The event filtering mask.

Availability
See Also
Declared In
QCView.h

isPausedRendering

Returns whether or not the rendering in the view is paused.

- (BOOL) isPausedRendering;

Return Value

YES if the rendering is paused; otherwise NO.

Availability
See Also
Declared In
QCView.h

isRendering

Checks whether a composition is rendering in the view.

- (BOOL)isRendering

Return Value

Returns YES if a composition is rendering in the view; NO otherwise.

Availability
Declared In
QCView.h

loadComposition:

Loads a QCComposition object into the view.

- (BOOL) loadComposition:(QCComposition*)composition

Parameters
composition

The QCComposition object to load.

Return Value

YES if successful; otherwise NO. If unsuccessful, any composition that’s already loaded in the view remains loaded.

Availability
See Also
Declared In
QCView.h

loadCompositionFromFile:

Loads the composition file located at the specified path.

- (BOOL)loadCompositionFromFile:(NSString *)path

Parameters
path

A string that specifies the location of a Quartz Composer composition file.

Return Value

If unsuccessful, returns NO; any composition that’s already loaded in the view remains loaded.

Availability
See Also
Declared In
QCView.h

loadedComposition

Returns the composition loaded in the view.

- (QCComposition*) loadedComposition

Return Value

The composition loaded in the view; otherwise nil.

Availability
See Also
Declared In
QCView.h

maxRenderingFrameRate

Returns the maximum frame rate for rendering.

- (float)maxRenderingFrameRate

Return Value

The maximum frame rate for rendering. A value of 0.0 specifies that there is no limit.

Availability
See Also
Declared In
QCView.h

openGLContext

Returns the OpenGL context used by the view.

- (NSOpenGLContext*) openGLContext

Return Value

An NSOpenGLContext object.

Discussion

This context as a read-only object . Do not attempt to change any of its settings. If you subclass QCView so that you can perform custom OpenGL drawing, you’ll need to use this method to retrieve the view’s OpenGL context.

Availability
See Also
Declared In
QCView.h

openGLPixelFormat

Returns the OpenGL pixel format used by the view.

- (NSOpenGLPixelFormat*) openGLPixelFormat

Return Value

An NSOpenGLPixelFormat object.

Discussion

This pixel format as a read-only object. Do not attempt to change any of its settings.

Availability
Declared In
QCView.h

pauseRendering

Pauses rendering in the view.

- (void) pauseRendering

Discussion

You can nest calls to this method.

Availability
See Also
Declared In
QCView.h

play:

Plays or pauses a composition in a view.

- (IBAction) play:(id)sender

Parameters
sender

The object (such as a button or menu item) sending the message to play the composition. You need to connect the object in the interface to the action.

Return Value

The message sent to the target.

Discussion

This method starts rendering a composition if it is not already rendering, pauses a composition that is rendering, or resumes rendering for a composition whose rendering is paused. The method is invoked when the user clicks a button or issues a command from some other user interface element, such as a menu.

Availability
See Also
Declared In
QCView.h

renderAtTime:arguments:

Overrides to perform your custom operations prior to or after rendering a frame of a composition.

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

Parameters
time

The rendering time, in seconds, of the composition frame.

arguments

An optional dictionary that can contain QCRendererEventKey or QCRendererMouseLocationKey and the associated values. (See QCRenderer Class Reference or more information.)

Return Value

NO if your custom rendering fails, otherwise, YES.

Discussion

Do not call this method directly. You override this method only for subclasses of the QCView class and only if you want to perform custom operations or OpenGL rendering before and/or after Quartz Composer renders a frame of the composition.

The most common reasons to override this method are to:

To synchronize communication between a composition and another part of the application, the implementation looks similar to the following:

 
- (BOOL) renderAtTime:(NSTimeInterval)time
            arguments:(NSDictionary*)arguments
{
  // Your code to computer the value of myParameterValue
  [self setValue:myParameterValue forInputKey:@"myInput"];
 
  BOOL success = [super renderAtTime:time arguments:arguments];
 
  id result = [self valueForOutputKey:@"myOutput"];
  //Your code to perform some operation on the result
 
  return success;
}

To perform OpenGL drawing in a QCView object, follow these guidelines:

Here’s an example implementation of this method using OpenGL to draw an overlay:

#import <OpenGL/CGLMacro.h>  // Set up using macros
 
- (BOOL) renderAtTime:(NSTimeInterval)time
            arguments:(NSDictionary*)arguments
{
    BOOL success = [super renderAtTime:time arguments:arguments];
 
    // Use the OpenGL context of the view for drawing.
    CGLContextObj cgl_ctx = [[self openGLContext] CGLContextObj];
 
    // Save and set OpenGL states appropriately.
    glGetIntegerv(GL_MATRIX_MODE, &saveMode);
    glMatrixMode(GL_MODELVIEW);
    glPushMatrix();
    glRotatef(45.0, 0.0, 0.0, 1.0);
 
    // The code that performs OpenGL drawing goes here.
    //After drawing, restore original OpenGL states.
    glPopMatrix();
    glMatrixMode(saveMode);
 
    // Check for errors.
    glGetError();
    return success;
}
Availability
Declared In
QCView.h

resumeRendering

Resumes rendering a paused composition.

- (void) resumeRendering

Discussion

You can nest calls to this method.

Availability
See Also
Declared In
QCView.h

setAutostartsRendering:

Sets whether the composition that is in the view starts rendering automatically when the view is put on the screen.

- (void)setAutostartsRendering:(BOOL)flag

Parameters
flag

Pass YES to enable autostart mode; NO otherwise.

Availability
See Also
Declared In
QCView.h

setEraseColor:

Sets the color used to erase the view.

- (void)setEraseColor:(NSColor *)color

Parameters
color

A color object.

Availability
See Also
Declared In
QCView.h

setEventForwardingMask:

Sets the mask used to filter which types of events are forwarded from the view to the composition during rendering.

- (void)setEventForwardingMask:(NSUInteger)mask

Parameters
mask

An event filtering mask. The mask can be a combination of any of the mask constants listed in Table 1 or the constant NSAnyEventMask.

Table 1  Events that can be forwarded to a composition

Event

Description

NSLeftMouseDownMask

The user pressed the left button.

NSLeftMouseDraggedMask

The user moved the mouse with the left button down.

NSLeftMouseUpMask

The user released the left button.

NSRightMouseDownMask

The user pressed the right button.

NSRightMouseDraggedMask

The user moved the mouse with the right button down.

NSRightMouseUpMask

The user released the right button.

NSOtherMouseDownMask

The user pressed the middle button, or some button other than the left or right button.

NSOtherMouseDraggedMask

The user moved the mouse with the middle button down, or some button other than the left or right button.

NSOtherMouseUpMask

The user released the middle button, or some button other than the left or right button.

NSMouseMovedMask

The user moved the mouse without holding down a mouse button.

NSScrollWheelMask

The user moved the mouse scroll wheel.

NSKeyDownMask

The user generated a character or characters by pressing a key.

NSKeyUpMask

The user released a key.

NSFlagsChangedMask

The user pressed or released a modifier key, or toggled the Caps Lock key.
Availability
See Also
Declared In
QCView.h

setMaxRenderingFrameRate:

Sets the maximum rendering frame rate.

- (void)setMaxRenderingFrameRate:(float)maxFPS

Parameters
maxFPS

The frame rate to set. Pass 0.0 to specify that there is no limit.

Availability
See Also
Declared In
QCView.h

snapshotImage

Returns an NSImage object of the current image in the view.

- (NSImage*) snapshotImage

Return Value

The snapshot image.

Availability
See Also
Declared In
QCView.h

start:

Starts rendering a composition in a view.

- (IBAction)start:(id)sender

Parameters
sender

The object (such as a button or menu item) sending the message to start rendering. You need to connect the object in the interface to the action.

Return Value

The message sent to the target.

Discussion

The method is invoked when the user clicks a button or issues a command from some other user interface element, such as a menu. It is equivalent to the startRendering method.

Availability
See Also
Declared In
QCView.h

startRendering

Starts rendering the composition that is in the view.

- (BOOL)startRendering

Return Value

Returns NO if the composition fails to start rendering; YES otherwise.

Availability
See Also
Declared In
QCView.h

stop:

Stops rendering a composition in a view.

- (IBAction)stop:(id)sender

Parameters
sender

The object (such as a button or menu item) sending the message to stop rendering. You need to connect the object in the interface to the action.

Return Value

The message sent to the target.

Discussion

The method is invoked when the user clicks a button or issues a command from some other user interface element, such as a menu. It is equivalent to the stopRendering method.

Availability
See Also
Declared In
QCView.h

stopRendering

Stops rendering the composition that is in the view.

- (void)stopRendering

Availability
See Also
Declared In
QCView.h

unloadComposition

Unloads the composition from the view.

- (void) unloadComposition;

Discussion

If necessary, this method calls stopRendering prior to unloading the composition.

Availability
See Also
Declared In
QCView.h

Notifications

QCViewDidStartRenderingNotification

Posted when the view starts rendering.

Availability
Declared In
QCView.h

QCViewDidStopRenderingNotification

Posted when the view stops rendering.

Availability
Declared In
QCView.h

Next Page > Hide TOC

Last updated: 2007-05-09

Did this document help you?
Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.
Get information on Apple products.
Visit the Apple Store online or at retail locations.
1-800-MY-APPLE

Copyright © 2007 Apple Inc.
All rights reserved. | Terms of use | Privacy Notice