Mac Developer Library

Developer

Quartz Framework Reference QCView Class Reference

Options
Deployment Target:

On This Page
Language:

QCView

Conforms To


Import Statement


Swift

import Quartz

Objective-C

@import Quartz;

Availability


Available in OS X v10.4 and later.

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.

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

    Declaration

    Swift

    func renderAtTime(_ time: NSTimeInterval, arguments arguments: [NSObject : AnyObject]!) -> Bool

    Objective-C

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

    NOfalse if your custom rendering fails, otherwise, YEStrue.

    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;
    • }

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

  • Clears the view using the current erase color.

    Declaration

    Swift

    func erase()

    Objective-C

    - (void)erase

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.4 and later.

    See Also

    – eraseColor

  • Retrieves the current color used to erase the view.

    Declaration

    Swift

    func eraseColor() -> NSColor!

    Objective-C

    - (NSColor *)eraseColor

    Return Value

    The color object previously set using the setEraseColor: method.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.4 and later.

    See Also

    – erase

  • Sets the color used to erase the view.

    Declaration

    Swift

    func setEraseColor(_ color: NSColor!)

    Objective-C

    - (void)setEraseColor:(NSColor *)color

    Parameters

    color

    A color object.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func eventForwardingMask() -> Int

    Objective-C

    - (NSUInteger)eventForwardingMask

    Return Value

    The event filtering mask.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func setEventForwardingMask(_ mask: Int)

    Objective-C

    - (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 1Events 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.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.4 and later.

  • Returns the maximum frame rate for rendering.

    Declaration

    Swift

    func maxRenderingFrameRate() -> Float

    Objective-C

    - (float)maxRenderingFrameRate

    Return Value

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

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.4 and later.

  • Sets the maximum rendering frame rate.

    Declaration

    Swift

    func setMaxRenderingFrameRate(_ maxFPS: Float)

    Objective-C

    - (void)setMaxRenderingFrameRate:(float)maxFPS

    Parameters

    maxFPS

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

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.4 and later.

  • Starts rendering the composition that is in the view.

    Declaration

    Swift

    func startRendering() -> Bool

    Objective-C

    - (BOOL)startRendering

    Return Value

    Returns NOfalse if the composition fails to start rendering; YEStrue otherwise.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.4 and later.

  • Checks whether a composition is rendering in the view.

    Declaration

    Swift

    func isRendering() -> Bool

    Objective-C

    - (BOOL)isRendering

    Return Value

    Returns YEStrue if a composition is rendering in the view; NOfalse otherwise.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.4 and later.

  • Checks whether the view is set to start rendering automatically.

    Declaration

    Swift

    func autostartsRendering() -> Bool

    Objective-C

    - (BOOL)autostartsRendering

    Return Value

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

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func setAutostartsRendering(_ flag: Bool)

    Objective-C

    - (void)setAutostartsRendering:(BOOL)flag

    Parameters

    flag

    Pass YEStrue to enable autostart mode; NOfalse otherwise.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.4 and later.

  • Stops rendering the composition that is in the view.

    Declaration

    Swift

    func stopRendering()

    Objective-C

    - (void)stopRendering

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.4 and later.

  • Pauses rendering in the view.

    Declaration

    Swift

    func pauseRendering()

    Objective-C

    - (void)pauseRendering

    Discussion

    You can nest calls to this method.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func isPausedRendering() -> Bool

    Objective-C

    - (BOOL)isPausedRendering

    Return Value

    YEStrue if the rendering is paused; otherwise NOfalse.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

  • Resumes rendering a paused composition.

    Declaration

    Swift

    func resumeRendering()

    Objective-C

    - (void)resumeRendering

    Discussion

    You can nest calls to this method.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

  • Plays or pauses a composition in a view.

    Declaration

    Swift

    @IBAction func play(_ sender: AnyObject!)

    Objective-C

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

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

    See Also

    – stop:

  • Starts rendering a composition in a view.

    Declaration

    Swift

    @IBAction func start(_ sender: AnyObject!)

    Objective-C

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

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.4 and later.

    See Also

    – stop:

  • Stops rendering a composition in a view.

    Declaration

    Swift

    @IBAction func stop(_ sender: AnyObject!)

    Objective-C

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

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.4 and later.

    See Also

    – start:

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

    Declaration

    Swift

    func snapshotImage() -> NSImage!

    Objective-C

    - (NSImage *)snapshotImage

    Return Value

    The snapshot image.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func createSnapshotImageOfType(_ type: String!) -> AnyObject!

    Objective-C

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

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

  • Returns the OpenGL context used by the view.

    Declaration

    Swift

    func openGLContext() -> NSOpenGLContext!

    Objective-C

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

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

  • Returns the OpenGL pixel format used by the view.

    Declaration

    Swift

    func openGLPixelFormat() -> NSOpenGLPixelFormat!

    Objective-C

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

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.