Using Quartz Features

Because Quartz implements some features that Cocoa does not, there may be times when you need to use Quartz function calls from your Cocoa code. Because Cocoa uses Quartz for most drawing operations, mixing the two technologies is not an issue.

Some of the Quartz features that are not supported directly by Cocoa include the following:

• Layers

• Gradients (also called shadings)

• Image data sources

• Blend modes (Cocoa uses compositing modes instead)

• Masking images

• Transparency layers (for grouping content)

• Arbitrary patterns (other than images)

In each case, you are free to use Quartz functions to take advantage of these features. Some features can produce data types that you can then incorporate back into a Cocoa object. (For example, you can use an image data source to obtain a Quartz image (CGImageRef), which you can then use to create an NSImage object.) In some cases, however, you may need to perform the entire operation using Quartz functions.

For information on how to use Quartz features, see Quartz 2D Programming Guide.

Graphics Type Conversions

When going back and forth between Cocoa and Quartz code, some conversion of data types may be necessary. Table 9-1 shows the Cocoa equivalents of some basic Quartz types.

Although in each case the structure layout is the same, you cannot pass the Quartz data type directly to a method expecting the Cocoa type. To convert, you must cast from one type to another, as shown in the following example:

NSRect cocoaRect = *(NSRect*)&myCGRect;

Table 9-2 lists the Cocoa classes that approximate the behavior of specific Quartz data types. In some cases, the Cocoa class wraps an instance of its Quartz counterpart, but that is not always true. In the case of shadows, Quartz provides no direct data type for managing the shadow parameters; you must set shadows attributes in Quartz using several different functions. In the case of layers, there are no Cocoa equivalents.

Because Cocoa types often wrap equivalent Quartz types, you should look at the Cocoa reference documentation for information about how to get equivalent Quartz objects, if any. In many cases, Cocoa classes do not offer direct access to their Quartz equivalent and you may need to create the Quartz type based on information in the Cocoa object, such as in the following cases:

• To create a CGPathRef object from an NSBezierPath object, you must redraw the path using Quartz function calls. Use the elementAtIndex:associatedPoints: method of NSBezierPath to retrieve the path’s point information.

• To convert back and forth between CGColorRef and NSColor objects, get the color component values from one object and use those values to create the other object. When creating colors, you may also need to specify the color space for that color. For the most part, Quartz and Cocoa support the same color spaces. If a color uses a custom color space, you can use the available ICC profile data to create the appropriate color space object.

• To create an NSImage object from a Quartz image, you need to create the image object indirectly. For information on how to do this, see Using a Quartz Image to Create an NSImage.

• To create Quartz shadows, you can use the methods of NSShadow to retrieve the color, offset, and blur radius values prior to calling CGContextSetShadow or CGContextSetShadowWithColor.

Getting a Quartz Graphics Context

Before using any Quartz features, you need to obtain a Quartz graphics context (CGContextRef) for drawing. For view-based drawing, you can get the context by sending a graphicsPort message to the current Cocoa graphics context (NSGraphicsContext). This method returns a pointer that you can cast to a CGContextRef data type and use in subsequent Quartz function calls.

Creating a Cocoa Graphics Context Using Quartz

In OS X v10.4 and later, if you have an existing Quartz graphics context, you can create a Cocoa graphics context object using the graphicsContextWithGraphicsPort:flipped: class method of NSGraphicsContext. You then use the setCurrentContext: class method to make that context the current context.

Modifying the Graphics State

When mixing calls to Quartz and Cocoa, remember that many Cocoa classes maintain a local copy of some graphics attributes normally associated with the Quartz graphics context. When such a class is ready to draw its content, it modifies the graphics state to match its local settings, draws its content, and restores the graphics state to its original settings. If you use Quartz to change an attribute that is maintained locally by a Cocoa class, your changes may not be used.

If you make changes to the graphics state using the NSGraphicsContext class, your changes are immediately conveyed to the Quartz graphics context, and vice versa. If you are not using NSGraphicsContext to set an attribute, you should assume that the attribute is local to the object. For example, the NSBezierPath class prefers local copies of graphics attributes over the default (or global) attributes stored in the current context.

Using NSOpenGLView

One way to do OpenGL drawing is to add an OpenGL view (an instance of NSOpenGLView) to your window. An OpenGL view behaves like any other view but also stores a pointer to an OpenGL graphics context object (an instance of NSOpenGLContext). Storing the graphics context in the view eliminates the need for your code to recreate the context during each drawing cycle, which can be expensive.

To use an OpenGL view in your program, you create a subclass of NSOpenGLView and add that view to your window, either programmatically or using Interface Builder. When creating an OpenGL view programmatically, you specify the pixel format object you want to associate with the view. A pixel format object (an instance of NSOpenGLPixelFormat) specifies the buffers and other rendering attributes of the OpenGL graphics context. For information on the meaning of different pixel format attributes, see OpenGL Programming Guide for Mac.

If you use Interface Builder to add your view to a window, you specify the pixel format information using the inspector for your view. Interface Builder lets you specify some pixel attributes, but not all. To support other attributes, you must replace the view’s pixel format object at runtime using the setPixelFormat: method.

As with other views, you use your OpenGL view’s drawRect: method to draw the content of your view. When your drawRect: method is invoked, the environment is automatically configured for drawing using the OpenGL graphics context associated with your view.

Unlike with other graphics contexts, you do not need to restore the previous OpenGL graphics context when you are done drawing. OpenGL does not maintain a stack of graphics contexts that need to be popped as they are no longer needed. Instead, it simply uses the most recent context that was made current.

Creating an OpenGL Graphics Context

Before creating an OpenGL graphics context object, you first create a pixel format object (NSOpenGLPixelFormat). The attributes you specify when creating your pixel format object determine the rendering behavior of the graphics context. Once you have a valid pixel format object, you can create and initialize your OpenGL graphics context object.

Listing 9-1 attempts to create an OpenGL graphics context that supports full-screen, double-buffered, 32-bit drawing. If the desired renderer is available, it returns the context; otherwise, it returns nil.

Listing 9-1  Creating an OpenGL graphics context

- (NSOpenGLContext*)getMyContext

{

    // Specify the pixel-format attributes.

    NSOpenGLPixelFormatAttribute attrs[] =

    {

        NSOpenGLPFAFullScreen,

        NSOpenGLPFADoubleBuffer,

        NSOpenGLPFADepthSize, 32,

        0

    };

    // Create the pixel-format object.

    NSOpenGLContext* myContext = nil;

    NSOpenGLPixelFormat* pixFmt = [[NSOpenGLPixelFormat alloc]

                                     initWithAttributes:attrs];

    // If the pixel format is valid, create the OpenGL context.

    if (pixFmt != nil)

    {

        myContext = [[NSOpenGLContext alloc] initWithFormat:pixFmt

                                 shareContext:NO];

    }

    [pixFmt release];

    return myContext;

}

Because the creation of OpenGL graphics contexts depends on the currently available renderers, your code should always verify that the desired objects were created before trying to use them. If creating an object fails, you can always try to create it again using a different set of attributes.

Using the QuickTime Kit

The QuickTime Kit framework (QTKit.framework) works with QuickTime movies in Cocoa applications in OS X. The QuickTime Kit framework was introduced in OS X v10.4 and was designed as an alternative to and eventual replacement for the existing NSMovie and NSMovieView classes in Cocoa. This new framework provides more extensive coverage of QuickTime functions and data types than had been offered by the Application Kit classes. More importantly, the framework does not require Cocoa programmers to be conversant with Carbon data types such as handles, aliases, file-system specifications, and so on.

The QuickTime Kit framework is available primarily in OS X v10.4 and later, but it is also supported in OS X v10.3 with QuickTime 7 or later installed. For information on how to use the QuickTime Kit, see QuickTime Kit Programming Guide. For a reference of the classes in the QuickTime Kit, see QTKit Framework Reference.

Using QuickTime C-Based Functions

Long before the introduction of the QuickTime Kit framework, QuickTime programs were written using a C-based API. The QuickTime API encompasses thousands of functions and gives you the maximum flexibility in managing QuickTime content. You can use this API in your Cocoa applications like you would any other framework.

For an introduction to QuickTime, see QuickTime Overview. For the complete QuickTime reference, see QuickTime Framework Reference.