Mac Developer Library

Developer

Quartz Framework Reference QCPlugInContext Protocol Reference

Options
Deployment Target:

On This Page
Language:

QCPlugInContext

The QCPlugInContext protocol defines methods that you use only from within the execution method (execute:atTime:withArguments:) of a QCPlugIn object.

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


import Quartz @import Quartz;

Availability


Available in OS X v10.5 and later.
  • Returns the destination CGL context to use for OpenGL rendering from within the execution method. (required)

    Declaration

    Swift

    func CGLContextObj() -> CGLContextObj

    Objective-C

    - (CGLContextObj)CGLContextObj

    Return Value

    The destination CGL context.

    Discussion

    To send commands to the OpenGL context:

    • Use CGL macros instead of changing the current OpenGL context.

    • Save and restore all OpenGL states except those defines by GL_CURRENT_BIT (vertex position, color, texture, and so on)

    The following code shows how you’d use the method CGLContextObj:

    • // Set up using CGL macros.
    • #import <OpenGL/CGLMacro.h>
    • - (BOOL) execute:(id<QCPlugInContext>)context
    • atTime:(NSTimeInterval)time
    • withArguments:(NSDictionary *)arguments
    • {
    • // Set the CGL context to a local variable.
    • CGLContextObj cgl_ctx = [context CGLContextObj];
    • if(cgl_ctx == NULL)
    • return NO;
    • // Save and set OpenGL states.
    • // Put your OpenGL code here.
    • // Restore the OpenGL states.
    • return YES;
    • }

    You can retrieve the corresponding OpenGL pixel format by calling the function CGLGetPixelFormat.

    Import Statement

    import Quartz

    Availability

    Available in OS X v10.5 and later.

  • Writes a message to the Quartz Composer log. (required)

    Declaration

    Objective-C

    - (void)logMessage:(NSString *)format, ...

    Parameters

    format

    The string to write to the log. The default location for the log is the standard output.

    Discussion

    This method is an alternative to using the functions NSLog or printf.

    Import Statement

    Availability

    Available in OS X v10.5 and later.

  • userInfo() userInfo Required

    Returns a mutable dictionary that contains information that can be shared between all instances of the QCPlugIn subclass, running in the same Quartz Composer context. (required)

    Declaration

    Swift

    func userInfo() -> NSMutableDictionary!

    Objective-C

    - (NSMutableDictionary *)userInfo

    Return Value

    A mutable dictionary.

    Discussion

    When you add information to the dictionary, make sure that you use unique keys, such as com.myCompany.foo. You can use this dictionary to cache data that you want to share.

    Import Statement

    import Quartz

    Availability

    Available in OS X v10.5 and later.

  • bounds() bounds Required

    Returns the bounds of the rendering context. (required)

    Declaration

    Swift

    func bounds() -> NSRect

    Objective-C

    - (NSRect)bounds

    Return Value

    The bounds of the rendering context expressed in Quartz Composer units.

    Import Statement

    import Quartz

    Availability

    Available in OS X v10.5 and later.

  • Returns the color space used by the rendering context. (required)

    Declaration

    Swift

    func colorSpace() -> Unmanaged<CGColorSpace>!

    Objective-C

    - (CGColorSpaceRef)colorSpace

    Return Value

    An RGB color space; NULL if the custom patch execution mode is not consumer.

    Discussion

    If the method returns a color space, it must be an RGB color space.

    Import Statement

    import Quartz

    Availability

    Available in OS X v10.5 and later.

  • Returns an image provider from a single memory buffer. (required)

    Declaration

    Swift

    func outputImageProviderFromBufferWithPixelFormat(_ format: String!, pixelsWide width: Int, pixelsHigh height: Int, baseAddress baseAddress: UnsafePointer<Void>, bytesPerRow rowBytes: Int, releaseCallback callback: QCPlugInBufferReleaseCallback, releaseContext context: UnsafeMutablePointer<Void>, colorSpace colorSpace: CGColorSpace!, shouldColorMatch colorMatch: Bool) -> AnyObject!

    Objective-C

    - (id)outputImageProviderFromBufferWithPixelFormat:(NSString *)format pixelsWide:(NSUInteger)width pixelsHigh:(NSUInteger)height baseAddress:(const void *)baseAddress bytesPerRow:(NSUInteger)rowBytes releaseCallback:(QCPlugInBufferReleaseCallback)callback releaseContext:(void *)context colorSpace:(CGColorSpaceRef)colorSpace shouldColorMatch:(BOOL)colorMatch

    Parameters

    format

    The pixel format of the memory buffer. This must be compatible with the color space.

    width

    The width, in bytes, of the memory buffer.

    height

    The height, in bytes, of the memory buffer.

    baseAddress

    The base address of the memory buffer, which must be multiple of 16.

    rowBytes

    The number of bytes per row of the memory buffer, which must be multiple of 16.

    callback

    The release callback. Your callback must use this type definition:

    • typedef void (*QCPlugInBufferReleaseCallback)(const void* address, void* context);

    If you name your callback function MyQCPlugInBufferReleaseCallback, you would declare it like this:

    • void MyQCPlugInBufferReleaseCallback (const void address,
    • void * context);

    Quartz Composer invokes your callback when the memory buffer is no longer needed. The callback can be called from any thread at any time

    context

    The context to pass to the release callback.

    colorSpace

    The color space of the memory buffer. This must be compatible with the pixel format.

    colorMatch

    A Boolean that specifies whether Quartz Composer should color match the image. Pass NOfalse if the image is a mask or gradient or should not be color matched for some other reason. Otherwise, pass YEStrue.

    Return Value

    An image provider.

    Discussion

    You must not modify the image until the release callback is invoked.

    Import Statement

    import Quartz

    Availability

    Available in OS X v10.5 and later.

  • Returns an image provider from an OpenGL texture. (required)

    Declaration

    Swift

    func outputImageProviderFromTextureWithPixelFormat(_ format: String!, pixelsWide width: Int, pixelsHigh height: Int, name name: GLuint, flipped flipped: Bool, releaseCallback callback: QCPlugInTextureReleaseCallback, releaseContext context: UnsafeMutablePointer<Void>, colorSpace colorSpace: CGColorSpace!, shouldColorMatch colorMatch: Bool) -> AnyObject!

    Objective-C

    - (id)outputImageProviderFromTextureWithPixelFormat:(NSString *)format pixelsWide:(NSUInteger)width pixelsHigh:(NSUInteger)height name:(GLuint)name flipped:(BOOL)flipped releaseCallback:(QCPlugInTextureReleaseCallback)callback releaseContext:(void *)context colorSpace:(CGColorSpaceRef)colorSpace shouldColorMatch:(BOOL)colorMatch

    Parameters

    format

    The pixel format of the texture. This must be compatible with the color space.

    width

    The width, in bytes, of the texture.

    height

    The height, in bytes, of the texture.

    name

    An OpenGL texture of type GL_TEXTURE_RECTANGLE_EXT that is valid on the Quartz Composer OpenGL context. Your application must make sure that the texture exists for the life cycle of the image provider.

    flipped

    YEStrue to have Quartz Composer flip the contents of the texture vertically.

    callback

    The release callback. Your callback must use this type definition:

    • typedef void (*QCPlugInTextureReleaseCallback)(CGLContextObj cgl_ctx, GLuint name, void* context);

    If you name your callback function MyQCPlugInTextureReleaseCallback, you would declare it like this:

    • void MyQCPlugInTextureReleaseCallback (CGLContextObj cgl_ctx,
    • GLuint name,
    • void* context);

    Quartz Composer invokes your callback when the memory buffer is no longer needed. The callback can be called from any thread at any time

    context

    The context to pass to the release callback.

    colorSpace

    The color space of the texture. This must be compatible with the pixel format.

    colorMatch

    A Boolean that specifies whether Quartz Composer should color match the texture. Pass NOfalse if the texture is a mask or gradient or should not be color matched for some other reason. Otherwise, pass YEStrue.

    Return Value

    An image provider.

    Discussion

    You must not modify the texture until the release callback is invoked.

    Import Statement

    import Quartz

    Availability

    Available in OS X v10.5 and later.