TweetFollow Us on Twitter

June 96 - Graphical Truffles: Dynamic Display Dilemmas

Graphical Truffles: Dynamic Display Dilemmas

CAMERON ESFAHANI and KENT "LIDBOY" MILLER

In the Dark Ages, an application could examine the graphics environment once and gather all the information it needed to know. After the System 7.1.2 Renaissance, the Display Manager made the graphics environment dynamic, which provided many new features (and introduced a few implementation issues). In Issue 24 of develop, the Graphical Truffles column described some important features of the Display Manager. Here we'll discuss some common pitfalls that can cause an application to fail in a dynamic display environment -- and ways you can overcome them.

If you use QuickDraw routines in an existing application, your application may already support some aspects of the Display Manager without requiring any extra work on your part. An example we touch on in this column is the graphics mirroring feature, which allows users to make two graphics devices display the same image. QuickDraw, whose routines have already been updated to support the Display Manager, accomplishes graphics mirroring by overlapping the gdRects (global bounds) of the graphics devices. QuickDraw's internal version of DeviceLoop behaves correctly by detecting when devices overlap, then rendering the image properly for each device. This allows overlapping devices to have different color tables or bit depths and still be imaged correctly.

On this issue's CD, we've included a sample application, SuperFly, which illustrates several techniques you can use to support a dynamic environment in your application. Some of the sample code in this column is excerpted from SuperFly.

COMMON ERRORS

When we were integrating the Display Manager into new system software releases, we encountered some common problems that existing applications had when running in a dynamic display environment. Here's a list of suggestions regarding things that might have worked in the past but won't work now; we'll examine each error in turn and suggest a solution.

  • Don't forget to account for mirrored graphics devices when walking the device list.

  • Don't assume that just because your application uses only one logical display, it's drawing on only one physical device.

  • Don't cache the graphics devices and their state on application startup.

  • Don't assume that the menu bar will never move.

  • Don't assume that menus will be drawn on only one display.

  • Don't draw directly to the screen and bypass QuickDraw without checking for the mirrored case.

  • Don't assume that certain 680x0 registers will contain the same values inside a DeviceLoop drawing procedure as when DeviceLoop was called.

Don't forget to account for mirrored graphics devices when walking the device list. When writing applications in the past, some programmers assumed that graphics devices would never overlap. For example, you might assume that if a certain rectangle is fully contained within a gdRect, it isn't on any other device. To implement highlighting, your application might walk the device list and invert the selection if the global rectangle of what you want to highlight intersects the gdRect of that device. However, when there are two displays with the same gdRect in the device list, the first inversion accomplishes the highlighting but the second inversion restores the highlighted area to the original -- unhighlighted -- state.

Solution: Use DeviceLoop for your drawing. If you want to write your own version of DeviceLoop for some reason, make sure that it handles overlapping displays. You could solve the inverting problem by designing an algorithm to guarantee that each rectangle in global space is highlighted only once. The MyHiliteRect routine in Listing 1 is an example of a suitable algorithm.

The code in Listing 1 solves the highlighting problem by keeping track of the global area that has been highlighted. When DMGetNextScreenDevice returns a mirrored device (which will already have been highlighted by the first QuickDraw call), the SectRgn will fail and that device will not be highlighted again.

Listing 1. Highlighting a global rectangle only once

OSErr MyHiliteRect(Rect* hiliteRect)
{
   RgnHandle    hiliteRgn, gdRectRgn, tempRgn;
   GDHandle    theGDevice;
   
   hiliteRgn = NewRgn();
   if (hiliteRgn == nil) 
      return (QDError());
   gdRectRgn = NewRgn();
   if (gdRectRgn == nil) 
      return (QDError());
   tempRgn = NewRgn()
   if (tempRgn == nil)
      return (QDError());
      
   // Make hiliteRect into a region.
   RectRgn(hiliteRgn, hiliteRect);
   
   // Get the first screen device from the Display Manager.
   // Tell it to return only active screen devices so that we won't
   // have to check here.
   theGDevice = DMGetFirstScreenDevice(true);
   
   // Loop until we run out of hiliteRgn or GDevices.
   while ((theGDevice) && (!EmptyRgn(hiliteRgn)) {
      // Does this device's rect intersect hiliteRgn?
      RectRgn(&(**theGDevice).gdRect, gdRectRgn);
      SectRgn(hiliteRgn, gdRectRgn, &tempRgn);
      // If it does, highlight it.
      if (!EmptyRgn(tempRgn)) {
         // Highlight the area described by tempRgn.
         ...
         // Take the area we just highlighted out of the region to
         // highlight. 
         DiffRgn(hiliteRgn, tempRgn, hiliteRgn);
      }
      theGDevice = DMGetNextScreenDevice(theGDevice, true);
   }   
   DisposeRgn(hiliteRgn);
   DisposeRgn(gdRectRgn);
   DisposeRgn(tempRgn);
}
Another solution is given in the sample code in the GDeviceUtilities.cp file on this issue's CD. The function BuildAListOfUniqueDevices builds a list of all graphics devices but eliminates mirrored devices. An application could cache this list and use it for highlighting. However, the list could be invalidated if the user changes the device configuration. The application should register with the Display Manager so that it will be notified (through a notification callback or an Apple event) if the graphics world has changed.

Don't assume that just because your application uses only one logical display, it's drawing on only one physical device. Some applications assume that they're using only one piece of graphics hardware when they're actually using multiple physical devices. An example of this is a multimedia player that searches through graphics devices and uses the first device it finds that meets its criteria for bit depth or size. This technique causes a problem when the application uses Toolbox calls specific to one physical graphics device, such as using SetEntries to animate the color table. If mirroring is turned on, this changes the color table of only one device; the second physical device still has the old color table.

Solution: If you use Toolbox calls specific to one physical graphics device, make sure you do it for all devices that overlap your application's windows and not just the first one you find. As shown in Listing 2, you could use DeviceLoop to accomplish this by calling SetEntries in your DeviceLoop drawing procedure. Or you could use the Palette Manager instead of SetEntries.

Listing 2. Calling SetEntries for overlapping devices

OSErr MySavvySetEntries(WindowRef aWindow, CTabHandle newColorTable)
{
   RgnHandle              tempWindowStructRgn;
   DeviceLoopDrawingUPP   setEntriesDeviceLoopRD;
   OSErr                  theErr = noErr;

   tempWindowStructRgn = NewRgn();
   // Was there a problem making the region?
   if ((theErr = QDError()) != noErr)
      return (theErr);
   GetWindowStructureRgn(aWindow, tempWindowStructRgn);
   
   // We want to get called for every display that intersects our
   // window.
   setEntriesDeviceLoopRD =
       NewDeviceLoopDrawingProc(SetEntriesDeviceLoop);
   DeviceLoop(tempWindowStructRgn, setEntriesDeviceLoopRD,
       (long) newColorTable, singleDevices);
   DisposeRoutineDescriptor(setEntriesDeviceLoopRD);
   DisposeRgn(tempWindowStructRgn);
   return (theErr);
}

static pascal void SetEntriesDeviceLoop(short depth,
      short deviceFlags, GDHandle targetDevice, long userData)
{
#pragma unused(depth, deviceFlags)
   CTabHandle   newColorTable = (CTabHandle) userData;
   GDHandle      savedCurrentGDevice;

   // Since we'll be changing the current GDevice, we need to save
   // and restore it.
   savedCurrentGDevice = GetGDevice();

   // SetEntries applies to the current GDevice, so make targetDevice
   // the current GDevice.
   SetGDevice(targetDevice);

   // Insert the entire table into targetDevice. Do it in indexed
   // mode.
   SetEntries(-1, 255, &(**newColorTable).ctTable[0]);

   // Restore the old current GDevice.
   SetGDevice(savedCurrentGDevice);
}
Don't cache the graphics devices and their state on application startup. With the Display Manager, many things about the graphics world can change, such as the following:

  • Users can change resolutions on multiple-scan displays.

  • Users can deactivate displays with the Monitors & Sound control panel (system software version 7.5.2 and later).

  • Graphics mirroring could be off when the application is launched and turned on while it's running.

  • Users can put their PowerBooks to sleep and attach or remove an external display.
If your application doesn't respond to these changes, it might present an inconsistent interface to the user. For example, the MPW Shell used to cache the gdRect of the main display and pass it to SizeWindow and MoveWindow. So if users changed the resolution of a display, they couldn't grow or move windows beyond the previous size of the display.

Solution: If the Display Manager is present, you should watch for Display Manager notifications to detect changes in the graphics world. (See "Receiving and Responding to Display Manager Events.") Specialized pieces of code, such as extensions or components, can register a callback procedure with the Display Manager. To avoid problems, you should use this method instead of patching to determine when the display environment changes. (Display Manager 2.0 and later even notifies you when the bit depth changes.) Better yet, don't cache device information at all unless your code absolutely needs the extra ounce of performance.


    RECEIVING AND RESPONDING TO DISPLAY MANAGER EVENTS

    The Display Manager has been available since System 7 and is built into system software version 7.1.2 and later. If the Display Manager isn't around, the application can count on devices not moving around and changing sizes.

    An application must set the isDisplayManagerAware flag in its 'SIZE' resource to receive Display Manager events in its main event loop. If your application sets this flag, it's responsible for moving its windows if the graphics world changes, making sure that the windows all remain visible. If it doesn't set this flag, the Display Manager will automatically move windows for your application. Even if your application lets the Display Manager handle its windows automatically, it can still register for Display Manager events by using a callback procedure. The callback procedure is passed an Apple event that the application has to parse.

    The Graphical Truffles column in develop Issue 25 describes this in more detail.


The Display Manager passes all the information about the old and new display configurations to the application when the world changes. The Apple event-handling code on this issue's CD shows some ways to handle Display Manager events. For instance, to detect whether any of the graphics devices have moved, we parse the Apple event and compare the old and new gdRects:
AEGetNthDesc(&DisplayID, 1, typeWildCard, 
   &tempWord, &OldConfig);
AEGetKeyPtr(&OldConfig, keyDeviceRect,
   typeWildCard, (UInt32 *) &returnType,
   &oldRect, sizeof(Rect), nil);
AEGetNthDesc(&DisplayID, 2, typeWildCard,
   &tempWord, &NewConfig);
AEGetKeyPtr(&NewConfig, keyDeviceRect,
   typeWildCard, (UInt32 *) &returnType, 
   &newRect, sizeof(Rect), nil);      
if (!EqualRect(&oldRect, &newRect))
   HandleGDevicesMoved();
Don't assume that the menu bar will never move. This is especially a problem with games or multimedia applications that would like to hide the menu bar. Most applications hide the menu bar by adding the menu bar area to the gray region. (The pointer to the gray region is stored in the GrayRgn global variable and can be retrieved with the Window Manager function GetGrayRgn.) When the user moves the menu bar from one display to another (using the Monitors or Monitors & Sound control panel), the Display Manager reconstructs the gray region. If the application wants to show the menu bar again, it removes the old menu bar area from the rebuilt gray region, but this will not accurately reflect the available screen real estate. This top strip, where the menu bar was, would be lost.

As shown in Figure 1, the menu bar was on the display on the left before the application was launched. The application saved the menu bar location and added it to the gray region so that it could draw there. As shown in Figure 2, when the application quit, it subtracted the old menu bar area back out of the gray region. Since the menu bar was moved, this part of the gray region is now lost. No desktop is drawn where the menu bar used to be (the black rectangle).

Figure 1. Original location of menu bar

Figure 2. Gray region lost because menu bar movedSolution: Become Display Manager-aware and get notified by the Display Manager when the menu bar moves.

Don't assume that menus will be drawn on only one display. In the past, it was a safe assumption that the menu bar would be drawn on only one device at a time, so anything that wanted to draw in the menu bar (such as an MDEF) needed to know about only one display and a single bit depth. Since developers typically don't use DeviceLoop to draw menus or draw in the menu bar, sometimes images are drawn incorrectly when there are overlapped displays, especially on displays with different bit depths. An example would be a menu that contains color, like the Label menu in the Finder.

Solution: If you draw directly to the menu bar or to your menus and bypass QuickDraw, use DeviceLoop. Note that drawing in the menu bar with standard QuickDraw calls works fine in the mirrored case because QuickDraw takes care of the overlapping case for you.

Don't draw directly to the screen and bypass QuickDraw without checking for the mirrored case. Obviously, if an application draws directly to the screen and mirroring is on, the other displays will not reflect any of the drawing.

Solution: Always allow the user to go back to a more "compatible" mode that uses QuickDraw. If the application detects that mirroring is on (by calling DMIsMirroringOn), consider falling back to CopyBits to get your data to the screen.

Don't assume that certain 680x0 registers will contain the same values inside a DeviceLoop drawing procedure as when DeviceLoop was called. We discovered this bug when we made DeviceLoop PowerPC-native for mirroring performance. Some developers who write their DeviceLoop drawing procedure in 680x0 assembly language rely on the fact that the value of A6 when the drawing procedure was called is the same as when DeviceLoop was called. Application developers relied on this to enable them to share stack frames between the caller of DeviceLoop and the DeviceLoop drawing procedure. This will not work if a PowerPC-only version of DeviceLoop is present, so it will not work under Mac OS 8. If you write your DeviceLoop drawing procedure in a high-level language like C, however, you don't have to worry about this problem.

Solution: If you want to share data with your DeviceLoop drawing procedure, use the userData refCon supplied with DeviceLoop. If you need to rely on A6 remaining constant, one solution would be to pass in the A6 of the DeviceLoop caller in the userData parameter and set that to the A6 of the DeviceLoop drawing procedure. Be sure to save and restore the original A6 of the DeviceLoop drawing procedure.

SUCCEEDING IN A CHANGING GRAPHICS WORLD

The Display Manager offers many new features that enable users to configure their graphics devices dynamically. However, this dynamic display environment invalidates certain assumptions that developers might have made when programming in a static graphics environment. This column should start you thinking about these issues. Although the Display Manager does attempt to preserve compatibility with existing applications by moving windows around and preserving graphics device information, it can't fix everything. Your application needs to be able to function in a changing graphics world.

KENT "LIDBOY" MILLER, in a recent attempt to reshape the course of history, has renounced the use of caffeine on a by-minute basis. Lidboy hails from the halls of Apple, where he can be seen pacing in his fuzzy bear slippers. He considers the pinnacle of western culture to have been achieved by the rock group known as Rancid, although he occasionally reads from literary quarterlies on the sly. Were Lidboy to be granted one wish, a side of rice from Taco Bell would no doubt be involved. The single most used word in his vocabulary is "Salsa!"*

CAMERON ESFAHANI (cameron_esfahani@powertalk.apple.com, AppleLink DIRTY) began his career in the spaghetti westerns of Sergio Leone. Industry analysts felt that by going off into that area he would cut himself off from the mainstream and ruin his career, but Cameron felt it was more important to follow his dreams. Now at Apple Computer and looking back, he feels that his spaghetti western period was one of the most exciting and rewarding of his life. He therefore dedicates this column to the memory of Sergio Leone.*

Thanks to Tom Dowdy, Ian Hendry, Mike Marinkovich, and Mike Puckett for reviewing this column.*

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

SpamSieve 2.9.38 - Robust spam filter fo...
SpamSieve is a robust spam filter for major email clients that uses powerful Bayesian spam filtering. SpamSieve understands what your spam looks like in order to block it all, but also learns what... Read more
TeamViewer 15.0.8397 - Establish remote...
TeamViewer gives you remote control of any computer or Mac over the Internet within seconds or can be used for online meetings. Find out why more than 200 million users trust TeamViewer! Free for non... Read more
SteerMouse 5.4.3 - Powerful third-party...
SteerMouse is an advanced driver for USB and Bluetooth mice. SteerMouse can assign various functions to buttons that Apple's software does not allow, including double-clicks, modifier clicks,... Read more
Toast Titanium 18.2.1 - The ultimate med...
Roxio Toast Titanium, the leading DVD burner for Mac, makes burning even better, adding Roxio Secure Burn to protect your files on disc and USB in Mac- or Windows-compatible formats. Get more style... Read more
HoudahSpot 5.0.11 - Advanced file-search...
HoudahSpot is a versatile desktop search tool. Use HoudahSpot to locate hard-to-find files and keep frequently used files within reach. HoudahSpot will immediately feel familiar. It works just the... Read more
ClipGrab 3.8.6 - Download videos from Yo...
ClipGrab is a free downloader and converter for YouTube, Vimeo, Facebook and many other online video sites. It converts downloaded videos to MPEG4, MP3 or other formats in just one easy step Version... Read more
ExpanDrive 7.4.0 - Access cloud storage...
ExpanDrive builds cloud storage in every application, acts just like a USB drive plugged into your Mac. With ExpanDrive, you can securely access any remote file server directly from the Finder or... Read more
Adobe Dreamweaver CC 2020 20.0 - Build w...
Dreamweaver CC 2020 is available as part of Adobe Creative Cloud for as little as $20.99/month (or $9.99/month if you're a previous Dreamweaver customer). Adobe Dreamweaver CC 2020 allows you to... Read more
Eye Candy 7.2.3.85 - 30 professional Pho...
Eye Candy renders realistic effects that are difficult or impossible to achieve in Photoshop alone, such as Fire, Chrome, and the new Lightning. Effects like Animal Fur, Smoke, and Reptile Skin are... Read more
Sparkle Pro 2.8.5 - Visual website creat...
Sparkle Pro will change your mind if you thought building websites wasn't for you. Sparkle is the intuitive site builder that lets you create sites for your online portfolio, team or band pages, or... Read more

Latest Forum Discussions

See All

Pre-register for Hello Kitty AR: Kawaii...
Hello Kitty — the cute cat that launched a multi-billion-pound franchise — has been brought to life… sort of. Sanrio has teamed up with the Bublar Group to create a new mobile game that uses AR tech to turn the real world into Hello Kitty’s... | Read more »
Gorgeous and tranquil puzzler Spring Fal...
One-man indie studio SPARSE//GameDev has now launched its tranquil puzzler, Spring Falls. It's described as "a peaceful puzzle game about water, erosion, and watching things grow". [Read more] | Read more »
Black Desert Mobile gets an official rel...
Pearl Abyss has just announced that its highly-anticipated MMO, Black Desert Mobile, will launch globally for iOS and Android on December 11th. [Read more] | Read more »
Another Eden receives new a episode, cha...
Another Eden, WFS' popular RPG, has received another update that brings new story content to the game alongside a few new heroes to discover. [Read more] | Read more »
Overdox guide - Tips and tricks for begi...
Overdox is a clever battle royale that changes things up by adding MOBA mechanics and melee combat to the mix. This new hybrid game can be quite a bit to take in at first, so we’ve put together a list of tips to help you get a leg up on the... | Read more »
Roterra Extreme - Great Escape is a pers...
Roterra Extreme – Great Escape has been described by developers Dig-It Games as a mini-sequel to their acclaimed title Roterra: Flip the Fairytale. It continues that game's tradition of messing with which way is up, tasking you with solving... | Read more »
Hearthstone: Battlegrounds open beta lau...
Remember earlier this year when auto battlers were the latest hotness? We had Auto Chess, DOTA Underlords, Chess Rush, and more all gunning for our attention. They all had their own reasons to play, but, at least from where I'm standing, most... | Read more »
The House of Da Vinci 2 gets a new gamep...
The House of Da Vinci launched all the way back in 2017. Now, developer Blue Brain Games is gearing up to deliver a second dose of The Room-inspired puzzling. Some fresh details have now emerged, alongside the game's first official trailer. [Read... | Read more »
Shoot 'em up action awaits in Battl...
BattleBrew Productions has just introduced another entry into its award winning, barrelpunk inspired, BattleSky Brigade series. Whilst its previous title BattleSky Brigade TapTap provided fans with idle town building gameplay, this time the... | Read more »
Arcade classic R-Type Dimensions EX blas...
If you're a long time fan of shmups and have been looking for something to play lately, Tozai Games may have just released an ideal game for you on iOS. R-Type Dimensions EX brings the first R-Type and its sequel to iOS devices. [Read more] | Read more »

Price Scanner via MacPrices.net

13″ 2.4GHz MacBook Pros available for up to $...
Apple has a full line of Certified Refurbished 2019 13″ 2.4GHz 4-Core Touch Bar MacBook Pros available starting at $1529 and up to $300 off MSRP. Apple’s one-year warranty is included, shipping is... Read more
New at T-Mobile: Switch to T-Mobile, and get...
T-Mobile is offering a free 64GB iPhone 8 for new customers who switch to T-Mobile and open a new line of service. Eligible trade-in required, and discount applied over a 24 month period. The fine... Read more
Xfinity Mobile’s Black Friday Apple savings:...
Take $250 off the purchase of any iPhone at Xfinity Mobile with a new line activation, and transfer of phone number to Xfinity Mobile, through December 8, 2019. This includes Apple’s new iPhone 11... Read more
2019 13″ 1.4GHz MacBook Pros available starti...
Apple has a full line of Certified Refurbished 2019 13″ 1.4GHz 4-Core Touch Bar MacBook Pros available starting at $1099 and up to $230 off MSRP. Apple’s one-year warranty is included, shipping is... Read more
Save up to $350 on a 21″ or 27″ iMac with the...
Apple has Certified Refurbished 2019 21″ & 27″ iMacs available starting at $929 and up to $350 off the cost of new models. Apple’s one-year warranty is standard, shipping is free, and each iMac... Read more
Early Holiday 2019 Sale: B&H again offers...
B&H Photo has 10.2″ iPads on sale again for $30 off Apple’s MSRP, starting at $299, as part of their early Holiday 2019 sale. Overnight shipping is free to many addresses in the US: – 10.2″ 32GB... Read more
Apple iMacs on sale today at B&H Photo fo...
B&H Photo has new 2019 21″ and 27″ 5K iMacs on stock today and on sale for up to $150 off Apple’s MSRP. Overnight shipping is free to many locations in the US. These are the same iMacs sold by... Read more
2018 4 and 6-Core Mac minis on sale today for...
Apple resellers are offering new 2018 4-Core and 6-Core Mac minis for $80-$100 off MSRP for a limited time. B&H Photo has the new 2018 4-Core and 6-Core Mac minis on sale for up to $100 off Apple... Read more
Early Holiday 2019 sale at B&H Photo: 12....
B&H Photo has new 12.9″ iPad Pros on sale for up to $120 off Apple’s MSRP as part of their early Holiday 2019 sale. Overnight shipping is free to many addresses in the US: – 12.9″ 64GB WiFi iPad... Read more
8-Core iMac Pro on sale today for $4499 at B...
B&H Photo has the base 8-Core 3.2GHz 32GB/1TB iMac Pro on sale today for $4499 — $500 off Apple’s MSRP. Shipping is free. Their price is the lowest available for a new iMac Pro from any Apple... Read more

Jobs Board

*Apple* Health Benefit Specialist - Call Cen...
Description ** Apple Health Benefit Specialist - Call Center (MAS 3/MACSC)** **Olympia, WA Multiple Positions** *The ideal candidate for this position will have Read more
Hair Stylist - *Apple* Blossom Mall - JCPen...
Hair Stylist - Apple Blossom Mall Location:Winchester, VA, United States- Apple Blossom Mall 1850 Apple Blossom Dr Job ID:1065040Salon Professionals Job Read more
*Apple* Mobility Pro - Best Buy (United Stat...
**747088BR** **Job Title:** Apple Mobility Pro **Job Category:** Store Associates **Store NUmber or Department:** 000297-Reston-Store **Job Description:** At Best Read more
Nurse Practitioner - Field Based (San Bernard...
Nurse Practitioner - Field Based (San Bernardino, CA, Apple Valley, Hesperia) **Location:** **United States** **Requisition #:** PS30312 **Post Date:** Nov 11, 2019 Read more
Best Buy *Apple* Computing Master - Best Bu...
**747061BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Store Associates **Store NUmber or Department:** 000647-Kildeer-Store **Job Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.