Using the NSGradient Class

In OS X v10.5 and later, you can use the NSGradient class to create complex gradient fill patterns without having to write your own color computation function. Gradient objects are immutable objects that store information about the colors in the gradient and provide an interface for drawing those colors to the current context. When you create an NSGradient object, you specify one or more NSColor objects and a set of optional location parameters. During drawing, the gradient object uses this information to compute the color transitions for the gradient.

The NSGradient class supports both high-level and primitive drawing methods. The high-level methods provide a simple interface for drawing gradients as a fill pattern for a Bezier path or rectangle. If you need additional control over the final shape and appearance of the gradient fill, you can set up the clipping path your self and use the primitive drawing methods of NSGradient to do your drawing.

Drawing to a High-Level Path

The NSGradient class defines several convenience methods for drawing both radial and axial gradients:

• drawInRect:angle:

• drawInRect:relativeCenterPosition:

• drawInBezierPath:angle:

• drawInBezierPath:relativeCenterPosition:

These convenience methods are easily identified by the fact that they take either an NSBezierPath or a rectangle as their first parameter. This parameter is used as a clipping region for the gradient when it is drawn. You might use these methods to draw a gradient fill inside an existing shape in your interface.

Listing 6-2 shows some code that draws an axial gradient pattern. The NSBezierPath object containing the rounded rectangle shape acts as the clipping region for the gradient when it is drawn. Figure 6-3 shows the resulting gradient.

Listing 6-2  Clipping an axial gradient to a rounded rectangle

- (void)drawRect:(NSRect)rect

{

NSRect bounds = [self bounds];

NSBezierPath* clipShape = [NSBezierPath bezierPath];

[clipShape appendBezierPathWithRoundedRect:bounds xRadius:40 yRadius:30];

NSGradient* aGradient = [[[NSGradient alloc]

initWithColorsAndLocations:[NSColor redColor], (CGFloat)0.0,

[NSColor orangeColor], (CGFloat)0.166,

[NSColor yellowColor], (CGFloat)0.33,

[NSColor greenColor], (CGFloat)0.5,

[NSColor blueColor], (CGFloat)0.75,

[NSColor purpleColor], (CGFloat)1.0,

nil] autorelease];

[aGradient drawInBezierPath:clipShape angle:0.0];

}

Using the Primitive Drawing Routines

In addition to the high-level convenience methods, the NSGradient class defines two primitive methods for drawing gradients:

• drawFromPoint:toPoint:options:

• drawFromCenter:radius:toCenter:radius:options:

These methods give you more flexibility over the gradient parameters, including the ability to extend the gradient colors beyond their start and end points. Unlike the high-level routines, these methods do not change the clip region prior to drawing. If you do not set up a custom clip region prior to drawing, the resulting gradient could potentially expand to fill your entire view, depending on the gradient options.

Listing 6-3 shows the code for drawing a radial gradient in a view using the primitive drawing routine of NSGradient. The second circle in the gradient is offset from the first one by 60 points in both the horizontal and vertical directions, causing the overall gradient to skew towards the upper-right of the circle. Because the code passes the value 0 for the options parameter, the gradient does not draw beyond the start and end colors and therefore does not fill the entire view. Figure 6-4 shows the gradient resulting from this code.

Listing 6-3  Drawing a radial gradient using primitive routine

- (void)drawRect:(NSRect)rect

{

NSRect bounds = [self bounds];

NSGradient* aGradient = [[[NSGradient alloc]

initWithStartingColor:[NSColor orangeColor]

endingColor:[NSColor cyanColor]] autorelease];

NSPoint centerPoint = NSMakePoint(NSMidX(bounds), NSMidY(bounds));

NSPoint otherPoint = NSMakePoint(centerPoint.x + 60.0, centerPoint.y + 60.0);

CGFloat firstRadius = MIN( ((bounds.size.width/2.0) - 2.0),

((bounds.size.height/2.0) -2.0) );

[aGradient drawFromCenter:centerPoint radius:firstRadius

toCenter:otherPoint radius:5.0

options:0];

}

Using Quartz Shadings in Cocoa

Because the NSGradient class is available only in OS X v10.5 and later, software that runs on earlier versions of OS X must use Quartz or Core Image to draw gradient fills. Quartz supports the creation of both radial and axial gradients in different color spaces using a mathematical computation function you provide. The use of a mathematical function means that the gradients you create using Quartz scale well to any resolution. Core Image, on the other hand, provides filters for creating a fixed-resolution image consisting of a radial, axial, or Gaussian gradient. Because the end result is an image, however, Core Image gradients may be less desirable for PDF and other print-based drawing.

To draw a Quartz shading in your Cocoa program, you would do the following from your drawRect: method:

1. Get a CGContextRef using the graphicsPort method of NSGraphicsContext. (You will pass this reference to other Quartz functions.)

2. Create a CGShadingRef using Quartz; see Gradients in Quartz 2D Programming Guide.

3. Configure the current clipping path to the desired shape for your shading; see Setting the Clipping Region.

4. Draw the shading using CGContextDrawShading.

For information on using Core Image to create images with gradient fills, see Core Image Programming Guide.

Capturing the Screen

Cocoa does not provide direct support for capturing and releasing screens. The NSScreen class provides read-only access to information about the available screens. To capture or manipulate a screen, you must use the functions found in Quartz Services.

To capture all of the available screens, you can simply call the CGCaptureAllDisplays function. To capture an individual display, you must get the ID of the desired display and call the CGDisplayCapture function to capture it. The following example shows how to use information provided by an NSScreen object to capture the main screen of a system.

- (BOOL) captureMainScreen

{

    // Get the ID of the main screen.

    NSScreen* mainScreen = [NSScreen mainScreen];

    NSDictionary* screenInfo = [mainScreen deviceDescription];

    NSNumber* screenID = [screenInfo objectForKey:@"NSScreenNumber"];

    // Capture the display.

    CGDisplayErr err = CGDisplayCapture([screenID longValue]);

    if (err != CGDisplayNoErr)

        return NO;

    return YES;

}

To release a display you previously captured, use the CGDisplayRelease function. If you captured all of the active displays, you can release them all by calling the CGReleaseAllDisplays function.

For more information about capturing and manipulating screens, see Quartz Display Services Reference.

Full-Screen Drawing in OpenGL

Applications that do full-screen drawing tend to be graphics intensive and thus use OpenGL to improve rendering speed. Creating a full-screen context using OpenGL is easy to do from Cocoa. After capturing the desired displays, create and configure an NSOpenGLContext object and then invoke its setFullScreen and makeCurrentContext methods. After invoking these methods, your application goes immediately to full-screen mode and you can start drawing content.

When requesting a full-screen context in OpenGL, the pixel format for your context should include the following attributes:

• NSOpenGLPFAFullScreen

• NSOpenGLPFAScreenMask

• NSOpenGLPFAAccelerated

• NSOpenGLPFANoRecovery (only if your OpenGL graphics context is shared)

Listing 6-4 shows the basic steps for capturing all displays and setting up the OpenGL context for full-screen drawing. For information on how to create an NSOpenGLContext object, see Creating an OpenGL Graphics Context.

Listing 6-4  Creating an OpenGL full-screen context

NSOpenGLContext* CreateScreenContext()

{

    CGDisplayErr err;

    err = CGCaptureAllDisplays();

    if (err != CGDisplayNoErr)

        return nil;

    // Create the context object.

    NSOpenGLContext* glContext = CreateMyGLContext();

    // If the context is bad, release the displays.

    if (!glContext)

    {

        CGReleaseAllDisplays();

        return nil;

    }

    // Go to full screen mode.

    [glContext setFullScreen];

    // Make this context current so that it receives OpenGL calls.

    [glContext makeCurrentContext];

    return glContext;

}

Once you go into full-screen mode with your graphics context, your application has full control of the screen. To exit full-screen mode, invoke the clearDrawable method of your OpenGL context and call the CGReleaseAllDisplays function to release the screens back to the system.

For detailed sample code showing you how to enter full-screen mode using OpenGL and Cocoa, see the NSOpenGL Fullscreen sample in Sample Code > Graphics & Imaging > OpenGL.

Full-Screen Drawing in Cocoa

All Cocoa drawing occurs in a window, but for full screen drawing, the window you create is a little different. Instead of a bordered window with a title bar, you need to create a borderless window that spans the entire screen area.

Although you create a full-screen window using Cocoa classes, you still have to use Quartz Services to capture the display and configure the window properly. The capture process is described in Capturing the Screen. Once you capture the screen, the window server puts up a shield window that hides most other content. To make your full-screen window visible, you must adjust its level to sit above this shield. You can get the shield level using the CGShieldingWindowLevel function and pass the returned value to the setLevel: method of your window.

Listing 6-5 shows an action method defined in a subclass of NSDocument. The document object uses this method to capture the main display and create the window to fill that screen space. The window itself contains a single view (of type MyFullScreenView) for drawing content. (In your own code, you would replace this view with your own custom drawing view.) A reference to the window is stored in the myScreenWindow class instance variable, which is initialized to nil when the class is first instantiated.

Listing 6-5  Creating a Cocoa full-screen context

- (IBAction)goFullScreen:(id)sender

{

    // Get the screen information.

    NSScreen* mainScreen = [NSScreen mainScreen];

    NSDictionary* screenInfo = [mainScreen deviceDescription];

    NSNumber* screenID = [screenInfo objectForKey:@"NSScreenNumber"];

    // Capture the screen.

    CGDirectDisplayID displayID = (CGDirectDisplayID)[screenID longValue];

    CGDisplayErr err = CGDisplayCapture(displayID);

    if (err == CGDisplayNoErr)

    {

        // Create the full-screen window if it doesn’t already  exist.

        if (!myScreenWindow)

        {

            // Create the full-screen window.

            NSRect winRect = [mainScreen frame];

            myScreenWindow = [[NSWindow alloc] initWithContentRect:winRect

                    styleMask:NSBorderlessWindowMask

                    backing:NSBackingStoreBuffered

                    defer:NO

                    screen:[NSScreen mainScreen]];

            // Establish the window attributes.

            [myScreenWindow setReleasedWhenClosed:NO];

            [myScreenWindow setDisplaysWhenScreenProfileChanges:YES];

            [myScreenWindow setDelegate:self];

            // Create the custom view for the window.

            MyFullScreenView* theView = [[MyFullScreenView alloc]

                                             initWithFrame:winRect];

            [myScreenWindow setContentView:theView];

            [theView setNeedsDisplay:YES];

            [theView release];

        }

        // Make the screen window the current document window.

        // Be sure to retain the previous window if you want to  use it again.

        NSWindowController* winController = [[self windowControllers]

                                                 objectAtIndex:0];

        [winController setWindow:myScreenWindow];

        // The window has to be above the level of the shield window.

        int32_t     shieldLevel = CGShieldingWindowLevel();

        [myScreenWindow setLevel:shieldLevel];

        // Show the window.

        [myScreenWindow makeKeyAndOrderFront:self];

    }

}

To exit full screen mode using Cocoa, simply release the captured display, resize your window so that it does not occupy the entire screen, and set its level back to NSNormalWindowLevel. For more information about the shield window, see Quartz Display Services Reference.

Disabling Screen Updates

You can disable and reenable all screen flushes using the NSDisableScreenUpdates and NSEnableScreenUpdates functions. (In OS X v10.4 and later, you can also use the disableScreenUpdatesUntilFlush method of NSWindow.) You can use this technique to synchronize flushes to both a parent and child window. As soon as you reenable screen updates, all windows are flushed simultaneously (or at least close to it).

To prevent the system from appearing frozen, the system may automatically reenable screen updates if your application leaves them disabled for a prolonged period of time. If you leave screen updates disabled for more than 1 second, the system automatically reenables them.

Draw Minimally

Even with modern graphics hardware, drawing is still an expensive operation. The best way to reduce the amount of time spent in your drawing code is to draw only what is needed in the first place.

During a view update, the drawRect: method receives a rectangle that specifies the portion of the view that needs to be updated. This rectangle is always limited to the portion of the view that is currently visible and in some cases may be even smaller. Your drawing code should pay attention to this rectangle and avoid drawing content outside of it. Because the rectangle passed to drawRect: might be a union of several smaller rectangles, an even better approach is to call the view’s getRectsBeingDrawn:count: method and constrain your drawing to the exact list of rectangles returned by that method.

Avoid Forcing Synchronous Updates

When invalidating portions of your views, you should avoid using the display family of methods to force an immediate update. These methods cause the system to send a drawRect: message to the affected view (and potentially other views in the hierarchy) immediately rather than wait until the next regular update cycle. If there are several areas to update, this may result in a lot of extra work for your drawing code.

Instead, you should use the setNeedsDisplay: and setNeedsDisplayInRect: methods to mark areas as needing an update. When you call these methods, the system collects the rectangles you specify and coalesces them into a combined update region, which it then draws during the next update cycle.

If you are creating animated content, you should also be careful not to trigger visual updates more frequently than the screen refresh rate allows. Updating faster than the refresh rate results in your code drawing frames that are never seen by the user. In addition, updating faster than the refresh rate is not allowed in OS X v10.4 and later. If you try to update the screen faster than the refresh rate, the window server may block the offending thread until the next update cycle.

Reuse Your Objects

If you have objects that you plan to use more than once, consider caching them for later use. Caching saves time by eliminating the need to recreate objects each time you want to draw them. Of course, caching requires more memory, so be judicious about what you cache. It is faster to recreate an object in memory than page it in from disk.

Many objects are cached automatically by Cocoa and do not need to be cached in your own code. For example, Cocoa caches NSColor objects representing commonly used colors as those colors are requested.

Minimize State Changes

Every time you save the graphics state, you incur a small performance penalty. Whenever you have objects with the same rendering attributes, try to draw them all at the same time. If you save and restore the graphics state for each object, you may waste some CPU cycles.

With Cocoa, methods and functions that draw right away usually involve a change in graphics state. For example, when you call the stroke method of NSBezierPath, the object automatically saves the graphics state and applies the options associated with that path. While you are building the path, however, the graphics state does not change. Thus, if you want to draw several shapes using the same graphics attributes, it is advantageous to fill a single NSBezierPath with all of the shapes and then draw them all as a group.