TweetFollow Us on Twitter

August 92 - GRAPHICAL TRUFFLES

GRAPHICAL TRUFFLES

WRITING DIRECTLY TO THE SCREEN

BRIGHAM STEVENS AND BILL GUSCHWAN

[IMAGE 059-064_Graphics_rev1.GIF]

Many developers want to go beyond the speed of QuickDraw. Writing directly to the screen can allow you to create faster animation and graphics than possible with QuickDraw. However, Apple has always maintained that writing to video memory is unsupported, since it may cause your application to break on a future system. If you write directly to the screen, your application will forfeit the use of many Toolbox managers and will put future compatibility at risk. Since most applications require the Window Manager and other basic Macintosh managers, writing to the screen is only for a few specialized applications, such as video games and some animation packages that compete on the quality and speed of graphics.

We're providing guidelines for writing to the screen in this column because we know that some developers are already doing it. We also understand that, in today's market, you need every advantage you can get in order to be competitive.

BEFORE YOU READ ON
The most important thing to remember isdon't write directly to the screen if you don't have to . In general, only a few applications need to do this. If you're porting an existing graphics or animation library from another system, or writing an application that competes mainly on the speed of the graphics, writing directly to the screen may be necessary. For any other applications, turn back now and forget about writing to the screen.

Even if your application is animation intensive or a port from another system, we recommend that you always attempt to use QuickDraw first. QuickDraw may be fast enough for your purposes, and it would not be wise to sacrifice its compatibility and flexibility for no reason. You should always have a QuickDraw version of your code anyway, and it should be the default, in case your program isn't compatible with the system or video card being used. Writing directly to the screen should be a user- selectable option.

As an alternative to writing to the screen, your application may be able to increase graphics performance by using custom drawing routines in a GWorld and CopyBits to transfer your image to the screen. This allows you to have faster graphics while avoiding the compatibility nightmare that you may face by writing directly to the screen. To learn more about custom drawing routines, see "Drawing in GWorlds for Speed and Versatility" indevelop Issue 10.

We hope we've scared almost everyone away. For those of you still reading, we want to point out that violating one compatibility guideline doesn't mean your program should break others: you still need to follow certain rules in order to peacefully coexist with other applications. For example, don't assume the screen is a fixed size or depth. Use data structures like GDevice and screenBits to access this information (Inside Macintosh Volume VI, page 3-7). So remember, most applications have no need to write directly to the screen, and if you choose to do it, it may give you more compatibility headaches than you're ready for. If your program breaks in the future because you decided to write to the screen, it will beyour  responsibility to fix it. We feel that the methods outlined in this column will give you the best chance of future compatibility; however, there are no guarantees.

WHERE'D THAT MANAGER GO?
In addition to risking compatibility problems, writing directly to the screen means you have to do a lot of extra work. Specifically, you have to handle (or live without) many of the tasks that Toolbox managers would normally handle for you.

You lose the full benefit of QuickDraw's graphics routines, most importantly the clipping ability. Because the Window Manager uses QuickDraw for its clipping, you lose the ability to have multiple overlapping windows as part of your application's interface. If your application requires multiple overlapping windows, you don't want to be writing directly to the screen.

You lose the ability to stretch your windows across multiple monitors. QuickDraw automagically has the ability to split the contents of a window across multiple monitors. If you write directly to the screen, you'll be limited to one monitor, or you'll have to write a lot of code that has already been implemented in QuickDraw.

You lose the Help Manager. The Help Manager displays its balloons in a window over your application's window. If you're writing directly to the screen, you'll blast the Help Manager's windows.

You lose QuickDraw's ability to map pictures and pixMaps from one color environment to another. Replacing such code with your own is nontrivial. Just try writing an image-copying routine that deals with simultaneous multiple pixel depths and you'll gain a new respect for CopyBits!

You restrict your ability to print. The Printing Manager only understands QuickDraw. To print you'll have to use your drawing code to render your images and then use CopyBits to transfer them to the printing grafPort. This means sacrificing quality on the printed page, since pixMaps generally don't look as nice on the printer as objects composed of QuickDraw calls. Of course, if you have a QuickDraw version of your code you can easily work around this.

Your program may have a different look and feel than a standard Macintosh application. In the case of video games and other animation packages, this may be OK . But if you're writing the next- generation word processor or spreadsheet application, you should be using QuickDraw, the Window Manager, and the Palette Manager. You lose all or most of these user interface managers if you write directly to the screen. Do your writing to the screen within a window; this will lessen the user interface impact. If you want to take over the entire screen, open a window that covers the entire screen.

Your program will also need to know when it's running in the background (seeInside Macintosh Volume VI, page 5-19). When you're in the background, other applications' windows may be covering your window. In this case, youmust  use QuickDraw to refresh your window when you get an update event. If you write directly to the screen, you may clobber the foreground application's window.

FEELIN' THE NEED FOR SPEED
Writing directly to the screen for faster animation or graphics means a lot of work for you, because it will be up to your programming skills to beat QuickDraw. QuickDraw does everything possible to be as fast as it can while still being very generic. Efficient use of QuickDraw may actually eliminate the need to write to the screen.

If you write specialized code that's tailored specifically for the kinds of images and graphics that your application deals with, you might be able to make it faster than QuickDraw. The routine presented at the end of this column, which simply draws a color icon, is about 50% faster than CopyBits. It was timed on a Macintosh LC II at 1221 frames per second. CopyBits came in at a relatively sluggish 579frames per second. The timing was done by taking the average number of frames per second for 100 seconds.

Our routine is faster because it doesn't make any of the extra checks that QuickDraw must make to work with different bit depths and color environments. This routine is also coded to copy an image of a specific size, while CopyBits is a generic bit copier.

Writing directly to the screen doesn't guarantee that you'll be faster than QuickDraw. Even if your code is good, under some circumstances QuickDraw may outperform you. If there's an accelerator in the system, you may not be able to beat QuickDraw at all. Also, CopyBits is more efficient when copying large images, because the overhead is a smaller part of the overall work.

Increasing drawing speed enhances certain special effects. Not only can you gain smoother animation, but you also may be able to perform complex transformations, such as rotating 3-D shapes, and photo-realistic shading, which QuickDraw can't do. And you can do it with a high animation frame rate. For applications such as games, increased drawing speed and improved special effects are essential.

The table below shows the trade-off between image size and drawing speed, comparing writing directly to the screen, QuickDraw CopyBits, and CopyBits in QuickDraw accelerated by an 8*24 GC card. We copied an 8-bit color image from an offscreen GWorld to the screen, on a Macintosh IIfx with System 7.0.1.

512 x 384256 x 192128 x 96
ImageImageImage
Writing to2077306
the Screen
CopyBits1972268
8*24 GC92304770
CopyBits

Numbers shown are frames per second.



GETTING READY
Before you venture into video memory, you should do a few things to prepare for writing directly to the screen. Your program should determine the pixel depth and open a window to draw into. Additionally, for maximum performance under System 7, you may want to kill all applications in the background.

To beat QuickDraw, your code should be tailored for a specific pixel depth. Your program should find the pixel depth of the screen it's writing to by accessing the screen's GDevice.gdPMap.pixelSize field. If the depth is different from the depth that your program expects, you should ask the user's permission to change the pixel depth, and then change it using SetDepth (Inside Macintosh Volume VI, page 21-23).

You must  open a window to cover the part of the screen you're drawing on. If you don't use a window, update events for applications in the background may interfere with your graphics.

If you require maximum performance, and you don't want any applications taking away your cycles at WaitNextEvent time, you may want to consider using the System 7 Process Manager to kill all the background applications. If you do this, you should ask the user's permission first. Your users will no longer be able to access any desk accessories, which require the Finder to launch. There's an example of killing the background applications, called KillEveryOneButMe, on theDeveloper CD Series disc in the Snippets folder.

REACHING FIRST BASE
To access video memory, you need the base address of the video buffer for the screen to which you're writing. Depending on the version of QuickDraw installed, you'll need to use a different method of getting the base address. Use the Gestalt function with the gestaltQuickdrawVersion selector to determine the QuickDraw version.

  • If you're running on a system with the original black-and-white QuickDraw, which has a Gestalt result of gestaltOriginalQDxx, you can access the address of the screen by using the QuickDraw global variable screenBits.baseAddr.
  • If you're running Color QuickDraw, which has a Gestalt result of gestalt8BitQD, you can get the base address of the screen you're drawing on from the baseAddr field of the GDevice's pixMap. You should leave the addressing mode alone.
  • If you're running 32-Bit QuickDraw, which has a Gestalt result of gestalt32BitQDxx, you can get the 32-bit-clean base address of the screen's video memory by calling GetPixBaseAddr on the screen's GDevice's pixMap. Before you begin writing to the screen, you'll need to shift to 32-bit addressing mode to access video memory (see SwapMMUMode,Inside Macintosh Volume V, page 593). After you change the addressing mode, you can't make any Toolbox or OS calls until you switch back, because they all expect to be called with the addressing mode established when the Macintosh was booted. Also, if you're changing modes from 24 bit to 32 bit, you should call StripAddress on any master pointers that may be dereferenced in 32-bit mode, because the high byte may contain garbage.

On multiple-monitor systems, you have to decide whether you want your windows to be on any of the additional screens. If you decide to allow users to drag your window to other monitors, you should get the base address from the monitor that the window is on. See Graphical Truffles indevelop Issue 10 for a discussion of multiple monitors, including code.

PIXEL ACCESS
Now that you have the base address of video memory, you need to know how to get to a pixel. To access a pixel within video memory, you need to translate the screen coordinate into a byte address.

To map the vertical coordinate, multiply it by the rowBytes and add this product to the base address of the screen's video memory; this gives you the row address. To map the horizontal coordinate, calculate the byte number and add it to the row address. Voilà! You now have the pixel address.

Below is a formula to translate a pixel coordinate into a pixel address. We leave it up to you to implement these formulas in the most efficient way for the graphics you're working with.

rowAddr = screenBaseAddr + (rowBytes 
                * pixel_vertical_coordinate);
if (pixel_depth < 8) {
    pixels_per_byte = 8/pixel_depth;
    byteNum = pixel_horizontal_coordinate
                / pixels_per_byte;
}
else {
    bytes_per_pixel = pixel_depth/8;
    byteNum = pixel_horizontal_coordinate
                * bytes_per_pixel;
} 
pixelAddr = rowAddr + byteNum;

For the example at the end of this column, we use the formula for a pixel depth of 8 because it's the simplest. In this case, the above calculations can be reduced to

rowAddr = screenBaseAddr + (rowBytes * pixel_vertical_coordinate);
pixelAddr = rowAddr + pixel_horizontal_coordinate;
MOUSETRAP
You must call ShieldCursor (Inside Macintosh Volume I, page 474) before you actually start writing to video memory. If you don't call ShieldCursor, your application will not be compatible with some third-party monitors. Also, if you don't have the cursor hidden and the mouse is moving over an area as you draw to it, the mouse will leave behind "serially repeating artifacts" (garbage). When you're done writing to video memory, call ShowCursor (Inside Macintosh Volume I, page 168) to reverse the effects of ShieldCursor.

CONCLUSIONWriting directly to the screen is risky because the Macintosh hardware or OS may change in the future; Apple makes no guarantee that these methods will always work. In writing directly to the screen, you'll sacrifice the services of many Toolbox managers. For mainstream applications, QuickDraw's speed and flexibility will suffice. But for certain applications, such as games and animation, writing directly to the screen may provide an extra competitive edge.

AN EXAMPLE
Below is a sample function, DirectPlotColorIcon, that draws an 8-bit color icon (an 'icl8' resource) to an 8-bit color screen device whose pixMap is passed.

void DirectPlotColorIcon(long *colorIconPtr,
    PixMapHandle screenPixMap, short row, short col)
{
    register long *screenMemPtr;   // Pointer to video memory
    register short numRowsToCopy;  // Rows we're going to copy
    register short stripRowBytes;  // To clear high bit of rowBytes
    register short rowLongsOffset; // rowBytes converted to long
    char    mmuMode;               // 32-bit mode required
    Rect    cursRect;              // Rectangle for ShieldCursor call
    Point cursOffset;              // 0,0 to indicate rect is in
                                   // global coordinates

    /* High bit of pixMap rowBytes must be cleared. */
    stripRowBytes = (0x7FFF & (**screenPixMap).rowBytes);

    /* Strip high byte of icon address to prevent bus error */
    /* in 24-bit mode. */
    colorIconPtr = (long *)StripAddress(colorIconPtr);
    /* Calculate the address of the first byte of the */
    /* destination. */
    screenMemPtr = (long *)(GetPixBaseAddr(screenPixMap) +
        (stripRowBytes * row) + col);

    /* Call ShieldCursor to maintain compatibility with all */
    /* displays. */
    cursRect.top = row;
    cursRect.left = col;
    cursRect.bottom = row + 32;
    cursRect.right = col + 32;
    cursOffset.h = 0;
    cursOffset.v = 0;
    ShieldCursor(&cursRect, cursOffset);

    /* Change to 32-bit addressing mode to access video memory. */
    /* The previous addressing mode is returned in mmuMode for */
    /* restoring later. */
    mmuMode = true32b;
    SwapMMUMode(&mmuMode);
    
    /* Color icons have 32 rows. */
    numRowsToCopy = 32;
    
    /* Calculate the long word offset from the end of one row of */
    /* the color icon on the screen's pixMap to the first byte of */
    /* the icon in the next row. */
    rowLongsOffset = (stripRowBytes/4) - 8;
    
    /* Draw the color icon directly to the screen. */
    do {
            *screenMemPtr++ = *colorIconPtr++;
            *screenMemPtr++ = *colorIconPtr++;
            *screenMemPtr++ = *colorIconPtr++;
            *screenMemPtr++ = *colorIconPtr++;
            *screenMemPtr++ = *colorIconPtr++;
            *screenMemPtr++ = *colorIconPtr++;
            *screenMemPtr++ = *colorIconPtr++;
            *screenMemPtr++ = *colorIconPtr++;
    
        /* Bump to start of next row. */
            screenMemPtr += rowLongsOffset;
    } while(--numRowsToCopy);
    
    /* Restore addressing mode back to what it was. */
    SwapMMUMode(&mmuMode);

    ShowCursor();
}

THE TEN COMMANDMENTS OF WRITING TO THE SCREEN

  1. Be sure your code is faster than QuickDraw.
  2. Have a QuickDraw version of your code for compatibility.
  3. Write your code for a specific QuickDraw version.
  4. Write your code specifically for the kind of data you're dealing with.
  5. Write your code for a specific pixel depth.
  6. Never change the pixel depth without the user's permission.
  7. Always bracket your drawing code with ShieldCursor and ShowCursor.
  8. Always draw into a window.
  9. Never draw directly to the screen while you're in the background. Use QuickDraw instead.
  10. Don't write off the edge of video memory.


REFERENCES

  • "Drawing in GWorlds for Speed and Versatility" by Konstantin Othmer and Mike Reed, develop  Issue 10.
  • "Making the Most of Color on 1-Bit Devices" by Konstantin Othmer and Daniel Lipton, develop  Issue 9.
  • "QuickDraw's CopyBits Procedure: Better Than Ever in System 7.0" by Konstantin Othmer, develop Issue
  • "Realistic Color for Real-World Applications" by Bruce Leak, develop  Issue 1.
  • "Compatibility: Rules of the Road" by Dave Radcliffe, develop  Issue 1.
  • Macintosh Technical Note "Of Time and Space and _CopyBits" (formerly #277).
  • Macintosh Technical Note "Compatibility: Why & How" (formerly #117).
  • "Accessing Hardware," Inside Macintosh  Volume VI, page 3-7.BRIGHAM STEVENS (AppleLink: BRIGHAM) escaped from mainframe hell to work for Apple in June 1991 on the HyperCard® IIGS project. (He's the one on the right in the photo.) After a short and amazingly entertaining stint writing XCMDs, he joined Developer Support as a contractor in November 1991, and has never been home since. You can tell when you're getting near Brigham's office, because you'll be ducking Nerf arrows, and the sounds of "Dude!" will be raging across your lobes. At night you can find him there basking in the cathode rays of his 16" color monitor. By day you can find him romancing the sidewalk with his skateboard. On weekends he may be dancing in San Francisco, enmeshed in the rhythm of something relentless and metallic. He says one of his weirdest dreams was missing a turn while driving, and then setting up a 68000 jump table to return. His next goal is to be in a PowerBook commercial, on his skateboard saying "Dude, it's the next thing!" while doing an axle grind over a DOS PC--all this with a PowerBook in his right hand running his favorite application, MacsBug.

BILL GUSCHWAN, reflecting his lack of belief in a self, quotes Wittgenstein: "Whereof one cannot speak thereof one must be silent." Bill enjoys the wrath of Peleus's son, Smashing Pumpkins, Skinny Puppy, and Smashing Candy, which are his favorite book theme, rock groups, and poem, respectively. On a Shakespearean note, he quotes the tenet, "For O, for O, the hobbyhorse is forgot!" or, deconstructed, "Language deceives; never trust it." We think Bill's brain needs a little deconstruction; we could donate it to science because we now know how unselfish he really is. *To learn how to influence the speed of CopyBits, see the Macintosh Technical Note "Of Time and Space and _CopyBits" (formerly #277).*

The code used to measure the trade-off between image size and drawing speed can be found on the Developer CD Series disc.*

For information about killing the Finder, see the Q & A on page 115. *

For more about 32-bit addressing, see develop  Issue 6, page 36.*What about that 0x7FFF rowBytes? The largest rowBytes of a pixMap passed into CopyBits is 0x3FFE, otherwise the largest rowBytes is 0x7FFE.*

Thanks to C. K. Haun, Dennis Hescox, Guillermo Ortiz, and Forrest Tanaka for reviewing this column. *

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

How to become the ultimate robot warrior...
Chrono Strike is a delightfully immersive beat ‘em up with a sense of humor (any game with a good Sims reference gets points in my book). [Read more] | Read more »
Tips and tricks to get a higher score in...
Snow Roll is a devilish endless runner very much in the vein of Flappy Bird. It revels in its dastardly level of difficulty, and doesn’t really care how angry you get at it as it knows you’ll keep coming back for more. [Read more] | Read more »
How to win big in Slots Deluxe
Cheating while gambling is illegal and morally wrong, and in some parts of the world it leads to men with names like Vinnie "Six Knuckles" Manchenzo beating you to a pulp in a dark alley. [Read more] | Read more »
How to take over the world in Dictator 2
Running a country isn't easy - especially when you're a dictator who wants to take over the world and crush everyone in your path while you do it. [Read more] | Read more »
Tips and tricks to get a higher score in...
Tank.iois - you guessed it! - another multiplayer arena battler likeAgar.io and Slither.io. It does differentiate itself by putting you in a tiny tank though, so it's not exactly the same. To help you get that all-important high score, we've got a... | Read more »
How to unlock characters in One Tap Tenn...
As the title suggests, One Tap Tennis requires only a single tap to play its particular brand of tennis, and rewards you with a ton of unlockable characters if you perform well. Fortunately for you, we at 148Apps have got a few tips and tricks to... | Read more »
Grab it now: Game Craft’s Legend of War...
The real time strategy game is now available for you to sink your teeth into, through the App Store and Google Play. Combining elements of skill, strategy and empire building, Legend of War is a real gamers’ game. [Read more] | Read more »
Skateboard Party 3 ft. Greg Lutzka (Gam...
Skateboard Party 3 ft. Greg Lutzka 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Skateboard Party is back! This third edition of the popular sports franchise features professional skater... | Read more »
Cubious (Games)
Cubious 1.0 Device: iOS Universal Category: Games Price: $.99, Version: 1.0 (iTunes) Description: Cubious – How smart are you? How high is your IQube? Solve the impossible puzzles to find out, and help a lost little cube find his... | Read more »
Goat Simulator Waste of Space (Games)
Goat Simulator Waste of Space 1.1 Device: iOS Universal Category: Games Price: $4.99, Version: 1.1 (iTunes) Description: ** IMPORTANT - SUPPORTED DEVICESiPhone 4S, iPad 2, iPod Touch 5 or better.** | Read more »

Price Scanner via MacPrices.net

Enterprise Workers Pick Technology Over Perks...
New Adobe study shows surprising attitudes about office jobs and where the future of work is heading. Adobe has released survey findings revealing that a surprising 70 percent of U.S. office workers... Read more
Memorial Day Weekend Sale: $50-$100 off 11-in...
B&H Photo has 13″ and 11″ MacBook Airs with 256GB SSDs on sale for $50-$100 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 11″ 1.6GHz/256GB MacBook Air: $999 $100 off MSRP... Read more
Memorial Day Weekend Sales: Apple MacBook Pro...
B&H Photo has 13″ and 15″ Retina MacBook Pros on sale for up to $210 off MSRP. Shipping is free, and B&H charges NY tax only: - 15″ 2.2GHz Retina MacBook Pro: $1799 $200 off MSRP - 15″ 2.5GHz... Read more
Memorial Day Weekend Sales: Apple iMacs and M...
Take up to $150 off the price of a new iMac or Mac mini at the following Apple resellers this Memorial Day weekend: iMacs: B&H Photo has 21″ and 27″ iMacs on sale for up to $150 off MSRP... Read more
Apple refurbished Retina MacBook Pros availab...
Apple has Certified Refurbished 2015 13″ and 15″ Retina MacBook Pros available for up to $380 off the cost of new models. An Apple one-year warranty is included with each model, and shipping is free... Read more
Apple refurbished 11-inch MacBook Airs availa...
Apple has Certified Refurbished 11″ MacBook Airs (the latest models), available for up to $170 off the cost of new models. An Apple one-year warranty is included with each MacBook, and shipping is... Read more
Goal Zero and OtterBox Partner to Expand iPh...
Goal Zero, specialists in portable power, have announced a partnership with OtterBox, brand smartphone case protection, to offer the Slide and Slide Plus Batteries as modules compatible with the new... Read more
15-inch Retina MacBook Pros on sale for up to...
B&H Photo has 15″ Retina MacBook Pros on sale for up to $210 off MSRP. Shipping is free, and B&H charges NY tax only: - 15″ 2.2GHz Retina MacBook Pro: $1799 $200 off MSRP - 15″ 2.5GHz Retina... Read more
Clearance 2015 13-inch MacBook Airs available...
B&H Photo has clearance 2015 13″ MacBook Airs available for $250 off original MSRP. Shipping is free, and B&H charges NY sales tax only: - 13″ 1.6GHz/4GB/128GB MacBook Air (MJVE2LL/A): $799... Read more
Apple refurbished Apple TVs available for up...
Apple has Certified Refurbished 32GB and 64GB Apple TVs available for up to $30 off the cost of new models. Apple’s standard one-year warranty is included with each model, and shipping is free: -... Read more

Jobs Board

*Apple* Architect - AECOM (United States)
**Requisition/Vacancy No.** 132759BR **Position Title** Apple Architect **Job Category** Information Technology **Business Line** Government **Country** United Read more
*Apple* Solutions Consultant - APPLE (United...
Job Summary As an Apple Solutions Consultant, you'll be the link between our future customers and our products. You'll showcase your entrepreneurial spirit as you Read more
*Apple* Project Engineer - Smart Source Inc...
SmartSource is in need of an Apple Project Engineer for a 12 month contract opportunity in Pittsburg, PA. Role: Apple Project Engineer Location: Pittsburg, PA Read more
Automotive Sales Consultant - Apple Ford Linc...
…you. The best candidates are smart, technologically savvy and are customer focused. Apple Ford Lincoln Apple Valley is different, because: $30,000 annual salary Read more
Service Assistant - *Apple* Chevrolet *App...
Apple Automotive is one of the fastest growing dealer...and it shows. Consider making the switch to the Apple Automotive Group today! At Apple Automotive, we Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.