Capturing Displays

If you're writing an immersive application such as a game or a presentation program, you may want to do full screen drawing.

A common approach is to capture the display you want to use. When you capture a display, you have exclusive use of the display. Other applications and system services are not allowed to use the display or change its configuration. In addition, they are not notified of display changes, thus preventing them from repositioning their windows and the Finder from repositioning desktop icons.

To capture a single display, call the function CGDisplayCapture. To capture all online displays at once, call CGCaptureAllDisplays. By default, a captured screen is filled with black color; you have the option of disabling this feature if you capture using the functions CGDisplayCaptureWithOptions or CGCaptureAllDisplaysWithOptions.

After capturing a display, there are several drawing options:

If you're writing an OpenGL application, you can create an OpenGL full screen drawing context. For more information, see OpenGL Programming Guide for Mac OS X.
You can draw directly to the screen using Quartz 2D. Use the function CGDisplayGetDrawingContext to obtain a full-featured graphics context for the display. The graphics context remains valid until the display is released or its configuration changes. The context's origin is the lower-left corner of the display.
You can draw directly to the screen using your own drawing engine. Call CGDisplayBaseAddress or CGDisplayAddressForPosition to get an address in the frame buffer to which to draw.

Note: None of these drawing options require a window. Attempting to position a window over a captured display and draw into the window may be unsuccessful—or may present undesirable results such as illegible or invisible content—because of interactions between full-screen graphics and the graphics hardware.

When you are finished using a captured display, you should release it by calling CGDisplayRelease or CGReleaseAllDisplays.

Listing 1 shows how to capture the main display and draw a text string using Quartz 2D. A detailed explanation for each numbered line of code appears following the listing.

Listing 1 Capturing the main display

char *text = "Hello, World!";

CGDirectDisplayID display = kCGDirectMainDisplay; // 1

CGError err = CGDisplayCapture (display); // 2

if (err == kCGErrorSuccess)

    CGContextRef ctx = CGDisplayGetDrawingContext (display); // 3

    if (ctx != NULL)

        CGContextSelectFont (ctx, "Times-Roman", 48, kCGEncodingMacRoman);

        CGContextSetTextDrawingMode (ctx, kCGTextFillStroke);

        CGContextSetRGBFillColor (ctx, 1, 1, 1, 0.75);

        CGContextSetRGBStrokeColor (ctx, 1, 1, 1, 0.75);

        CGContextShowTextAtPoint (ctx, 40, 40, text, strlen(text)); // 4

        sleep (4); // 5

    CGDisplayRelease (display); // 6

Here's what the code does:

Gets the display ID of the main display.
Captures the main display and changes the color to black. An error is returned only if the display has been captured by another application.
Gets a Quartz graphics context associated with the captured display.
Draws the text string in the lower-left corner of the screen.
Suspends processing for a few seconds to allow the user to read the text.
Releases the captured display.

Note: It's not necessary to capture a display to do full-screen drawing. Another approach is to create and draw into a borderless window the size of the display. This approach allows you to use all the features of the windowing system, it plays well with the rest of the operating system, and it reduces the complexity of display handling (for example, you don't have to worry about mirrored displays). On systems with modern graphics hardware, drawing performance in a full-screen window is almost as fast as a full-screen drawing context.

< Previous PageNext Page >

Hide TOC

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.