Next Page > Hide TOC

QCView Class Reference

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

• – renderAtTime:arguments:

Loading a Composition

• – loadCompositionFromFile:
• – loadComposition:
• – loadedComposition
• – unloadComposition

Managing the Erase Color

• – erase
• – eraseColor
• – setEraseColor:

Setting and Getting Event Masks

• – eventForwardingMask
• – setEventForwardingMask:

Setting and Getting the Maximum Frame Rate

• – maxRenderingFrameRate
• – setMaxRenderingFrameRate:

Managing Rendering

• – startRendering
• – isRendering
• – autostartsRendering
• – setAutostartsRendering:
• – stopRendering
• – pauseRendering
• – isPausedRendering
• – resumeRendering

Using Interface Builder

• – play:
• – start:
• – stop:

Taking Snapshot Images

• – snapshotImage
• – createSnapshotImageOfType:

Working With OpenGL

• – openGLContext
• – openGLPixelFormat

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

• Available in Mac OS X v10.4 and later.

See Also

• – setAutostartsRendering:

Declared In

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

• Available in Mac OS X v10.5 and later.

See Also

• – snapshotImage

Declared In

erase

Clears the view using the current erase color.

- (void)erase

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – eraseColor

Declared In

eraseColor

Retrieves the current color used to erase the view.

- (NSColor *)eraseColor

Return Value

The color object previously set using the setEraseColor: method.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – erase

Declared In

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

• Available in Mac OS X v10.4 and later.

See Also

• – setEventForwardingMask:

Declared In

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

• Available in Mac OS X v10.5 and later.

See Also

• – pauseRendering
• – resumeRendering

Declared In

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

• Available in Mac OS X v10.5 and later.

Declared In

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

• Available in Mac OS X v10.5 and later.

See Also

• – loadCompositionFromFile:
• – unloadComposition
• – loadedComposition

Declared In

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

• Available in Mac OS X v10.4 and later.

See Also

• – loadComposition:
• – unloadComposition
• – loadedComposition

Declared In

loadedComposition

Returns the composition loaded in the view.

- (QCComposition*) loadedComposition

Return Value

The composition loaded in the view; otherwise nil.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – loadCompositionFromFile:
• – loadComposition:
• – unloadComposition

Declared In

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

• Available in Mac OS X v10.4 and later.

See Also

• – setMaxRenderingFrameRate:

Declared In

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

• Available in Mac OS X v10.5 and later.

See Also

• – renderAtTime:arguments:

Declared In

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

• Available in Mac OS X v10.5 and later.

Declared In

pauseRendering

Pauses rendering in the view.

- (void) pauseRendering

Discussion

You can nest calls to this method.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – resumeRendering
• – isPausedRendering

Declared In

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

• Available in Mac OS X v10.5 and later.

See Also

• – stop:

Declared In

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:

• synchronize communication with the composition. For example, you might want to set input parameters of the composition. By overriding this method, you can set parameters only when necessary and only at a specific time.

• underlay or overlay custom OpenGL rendering.

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:

• Use the OpenGL context of the QCView object to do drawing. You can retrieve the OpenGL context by calling [self openGLContext]. Note that this context won't necessarily be set as the current OpenGL context.

• Use CGL macros instead of managing the current OpenGL context yourself.

  OpenGL performs a global context and renderer lookup for each command it executes to ensure that all OpenGL commands are issued to the correct rendering context and renderer. There is significant overhead associated with these lookups that can measurably affect performance. CGL macros let you provide a local context variable and cache the current renderer in that variable. They are simple to use, taking only a few lines of code to set up.

• Save and restore all state changes except the ones that are part of GL_CURRENT_BIT (RGBA color, color index, normal vector, texture coordinates, and so forth).

• Check for OpenGL errors with glGetError.

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

• Available in Mac OS X v10.5 and later.

Declared In

resumeRendering

Resumes rendering a paused composition.

- (void) resumeRendering

Discussion

You can nest calls to this method.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – pauseRendering
• – isPausedRendering

Declared In

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

• Available in Mac OS X v10.4 and later.

See Also

• – autostartsRendering

Declared In

setEraseColor:

Sets the color used to erase the view.

- (void)setEraseColor:(NSColor *)color

Parameters

color

A color object.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – erase
• – eraseColor

Declared In

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

• Available in Mac OS X v10.4 and later.

See Also

• – eventForwardingMask

Declared In

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

• Available in Mac OS X v10.4 and later.

See Also

• – maxRenderingFrameRate

Declared In

snapshotImage

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

- (NSImage*) snapshotImage

Return Value

The snapshot image.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – createSnapshotImageOfType:

Declared In

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

• Available in Mac OS X v10.4 and later.

See Also

• – stop:

Declared In

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

• Available in Mac OS X v10.4 and later.

See Also

• – stopRendering

Declared In

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

• Available in Mac OS X v10.4 and later.

See Also

• – start:

Declared In

stopRendering

Stops rendering the composition that is in the view.

- (void)stopRendering

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – startRendering

Declared In

unloadComposition

Unloads the composition from the view.

- (void) unloadComposition;

Discussion

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

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – loadCompositionFromFile:
• – loadComposition:
• – loadedComposition

Declared In

Notifications

QCViewDidStartRenderingNotification

Posted when the view starts rendering.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

QCViewDidStopRenderingNotification

Posted when the view stops rendering.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

Next Page > Hide TOC