TweetFollow Us on Twitter

Autumn 91 - BE OUR GUEST

BE OUR GUEST

GWORLDS AND NUBUS MEMORY

FORREST TANAKA AND PAUL SNIVELY

[IMAGE 095-098_Guest_column1.GIF]

In Developer Technical Support, we're asked from time to time how to make a GWorld so that its pixel image uses memory on a NuBusTM card rather than memory in the application's heap. The idea is to create a GWorld, put the address of the card into the GWorld, use QuickDraw to draw into the GWorld, which effectively draws into the NuBus card's memory, and display the resulting image on the screen. Doing this in a way that works well with the 8*24 GC version of QuickDraw and with whatever QuickDraw brews up in the future isn't possible without breaking a few guidelines. We'll talk about the reasons for this and what you can do instead. For the more cavalier among you, we'll also talk about the least offensive method of coercing a GWorld so that it uses memory on your NuBus card.

NewGWorld allocates off-screen buffers simply by using the same Memory Manager calls that you can make. To allocate the memory, NewGWorld simply calls NewHandle to allocate the buffer in your application's heap unless you have the useTempMem bit set, in which case it allocates the buffer in temporary memory. It then tries to move the buffer as high in your heap as possible by calling MoveHHi. That's really all there is to it. The GWorld's pixMap, GDevice, and CGrafPort are allocated similarly-- they're all allocated in your heap using regular Memory Manager calls with no special options, patches, or other nefarious tricks.

None of this changes when you have the 8*24 GC software active--all memory is still allocated out of your application's heap. Once you start drawing into the GWorld, though, the GC software can copy the parts of the GWorld to the 8*24 GC memory. The GWorld and its parts still occupy your heap's memory though, regardless of whether it's cached on the 8*24 GC card.

If you have a NuBus card with gobs of memory, NewGWorld can't take advantage of it because the Memory Manager calls that it uses can't allocate memory on NuBus memory cards. There are no options to NewGWorld or any other GWorld calls that let you say, "There's lots of memory over on this NuBus card, all for you." While GWorlds are absolutely fantastic for creating off-screen drawing environments for most of the usual kinds of situations, they're just not appropriate if you want complete control over where or how the parts of a GWorld are allocated.

QuickDraw is the only thing that's supposed to know how GWorlds are constructed. We know that they're CGrafPorts and we can get their pixMap, GDevice, and off-screen buffer, but we shouldn't make any assumptions about how they were allocated and where they are. For example, we know that the off-screen buffer is allocated as a handle now, but that won't necessarily be the case in the future. There's no guaranteed way to tell which way it was allocated, or even if NewGWorld uses the Memory Manager to allocate it at all (which it always does currently, of course). Even the GWorld's CGrafPort is allocated as a handle that just happens to be always locked. If you try to dispose of a GWorld in which you've modified the baseAddr, you'll need DisposeGWorld to make sure everything is deallocated properly, but its behavior is undefined when it tries to deallocate the off- screen buffer. So if you want to use the memory on your NuBus memory card and feel comfortable that you're not relying on something that could change, you're going to have to create your own off-screen drawing environment by creating an off-screen pixMap, a color table if your off-screen drawing environment uses indexed colors, a GDevice, and a CGrafPort. The April 1989 edition of Macintosh Technical Note #120, "Drawing Into an Off-Screen Pixel Map," covers creating your own off-screen pixMap, CGrafPort, and color table, but it requires you to have the same depth and the equivalent color table that the screen has, so it just steals a screen's GDevice. We think it's always a good idea to create your own GDevice when you draw off screen. If you use a screen's GDevice for drawing off screen, you have to depend on that GDevice's depth and color table. By creating your own GDevice, your off-screen drawing environment can use any depth and color table you want at any time and still be insulated from whatever changes the user makes with the Monitors control panel.

To create your own GDevice, it's better not to use NewGDevice because it always creates the GDevice in the system heap; it's better to keep your data structures in your own heap so that they don't get orphaned if your application quits unexpectedly and that precious system heap space is preserved. Here's what you should set each of your GDevice's fields to be:

gdRefNumYour GDevice has no driver, so just set this to 0.
gdIDIt doesn't matter what you set this to; you might as well set it to 0.
gdTypeSet to 2 if your off-screen pixMap uses direct colors (16 or 32 bits per pixel) or 0 if it uses a color table (1 through 8 bits per pixel).
gdITableAllocate a small (maybe just 2-byte) handle for this field. After you're done setting up this GDevice and your off-screen pixMap, color table (if any), and CGrafPort, set this GDevice as the current GDevice by calling SetGDevice, and then call MakeITable, passing it nil for both the color table and inverse table parameters, and 0 for the preferred inverse table resolution.
gdResPrefWe reckon that more than 99.9% of all inverse tables out there have a resolution of 4. Unless you have some reason not to, we'd recommend the same here.
gdSearchProcSet to nil. Use AddSearch if you want to use a SearchProc.
gdCompProcSet to nil. Use AddComp if you want to use a CompProc.
gdFlagsSet to 0 initially, and then use SetDeviceAttribute after you've set up the rest of this GDevice.
gdPMapSet to be a handle to your off-screen pixMap.
gdRefConSet to whatever you want.
gdNextGDSet to nil.
gdRectSet to be equal to your off-screen pixMap's bounds.
gdModeSet to -1. Why? We're not sure. This is intended for GDevices with drivers anyway.
gdCCBytesSet to 0.
gdCCDepthSet to 0.
gdCCXDataSet to 0.
gdCCXMaskSet to 0.
gdReservedSet to 0.

For gdFlags, you should use SetDeviceAttribute to set the noDriver bit. You should also set the gDevType bit to 1 if you're using two bits per pixel or more, but it can be left at 0 if you're using only one bit per pixel.

The other big difference from the technique shown in Technical Note #120 is that the off-screen pixel image shouldn't be allocated. Instead, just point the baseAddr field of your off-screen pixMap at your NuBus card's memory. You should also set the pmVersion field of your off-screen pixMap to be the constant baseAddr32 (equal to 4). That tells Color QuickDraw to use 32-bit addressing mode to access your off-screen buffer, and that's a requirement if your off-screen pixel image is located on a NuBus card.

When you want to draw into your off-screen pixMap, save the current port with a call to GetPort and the current GDevice with a call to GetGDevice. Then set the current port to the off-screen CGrafPort with a call to SetPort, and set the current GDevice to the off-screen GDevice with a call to SetGDevice. Now all QuickDraw commands are drawn off screen and the resulting images are in your NuBus card's memory. To switch back to drawing on screen, set the current port and GDevice back to the port and GDevice that you saved earlier. Easy!

Even with all this, there might still be a reason to use GWorlds to draw into a NuBus memory card. You might just want some quick and dirty way to get an off-screen drawing environment that uses your NuBus memory card and don't care whether it works with future system software releases or not. We'll talk about that next and also discuss the issues that you have to be careful about when you do this.

First, create a GWorld using NewGWorld as usual. If you want to, pass it a color table, or you can just pass it nil if you want it to make the default color table. For the GWorld flags, make sure you pass only the keepLocal flag. This makes sure that all the pieces of the GWorld are kept in your own heap rather than being cached into the 8*24 GC card, even when you draw into it. That way, you avoid running into any conceivable conflicts with GC QuickDraw over where the GWorld really is. There's no way to tell NewGWorld not to allocate the pixel image, so you might want to make the bounds rectangle small and then make it bigger later so that your heap isn't hit up for a lot of memory that you don't even want. Don't pass it an empty rectangle because NewGWorld just gives you a paramErr in that case. Call GetGWorldDevice to get a handle to your GWorld's GDevice and save it for later.

Now it's time to have the new GWorld use your NuBus card's memory. The baseAddr of your GWorld's pixMap is allocated as a handle, and it has to be thrown out. Call GetPixBaseAddr with a handle to your GWorld's pixMap to get a pointer to the pixel image that NewGWorld allocated for you. Call RecoverHandle with that pointer to get a handle to the pixel image, and then call DisposHandle to get rid of it. Now put the address of your NuBus board into the baseAddr of your GWorld's pixMap. Then set the pmVersion field of your GWorld's pixMap to the constant baseAddr32. That tells Color QuickDraw that the baseAddr of the pixMap is a 32-bit address and so it should switch to 32-bit addressing mode whenever it draws into your GWorld.

If you passed NewGWorld a rectangle that's smaller than you actually want, you can now set it to the real size. Set the bounds rectangle of your GWorld's pixMap and the portRect rectangle of your GWorld's CGrafPort to the rectangle that you really wanted. Also, set the visRgn of the CGrafPort and the gdRect field of your GWorld's GDevice to that same rectangle. Your GWorld is ready for use!

Now the bad news. Many of the GWorld routines assume that the baseAddr field is either a real handle or a copy of the handle's master pointer. Because the pointer in the baseAddr field isn't a master pointer, those routines can crash when they expect one. Setting the pmVersion field doesn't help in most cases; these routines just assume that the GWorld's pixel image was allocated by NewGWorld, which is a reasonable assumption. What this implies is that you can no longer call many of the GWorld routines to maintain your GWorld without a risk of crashing. When you call SetGWorld for your GWorld, you should pass it the GWorld's GDevice instead of nil (that's why we recommended that you save the GWorld's GDevice after calling NewGWorld). For safety's sake, don't call any of the following:

LockPixels
UnlockPixels
AllowPurgePixels
NoPurgePixels
GetPixelsState
SetPixelsState
UpdateGWorld
GetGWorldDevice

You can call DisposeGWorld because it won't get hung up trying to deallocate the pixel image on your NuBus card; setting your pmVersion to baseAddr32 makes this possible. Of course, since all these GWorld routines are off limits, almost all the benefits of having a GWorld at all are gone as well.

Another piece of bad news is that this doesn't take advantage of the speed benefits of using GWorlds with an 8*24 GC card. Most of the speed benefit of using GWorlds with GC QuickDraw is that the GWorld's pixel image is allocated on the 8*24 GC card itself, and so the image data doesn't have to take the time to move across NuBus. If your GWorld draws into a NuBus memory card, the image data has to be moved across NuBus, and so that speed benefit is gone.

The last bit of bad news is that even if you follow all of this, you're still not guaranteed that it will still work in future system software or future video card releases. As we said earlier, this should only be done if you don't care whether it works on future system software releases or not. The description above breaks a lot of rules: don't assume that the pixel image is allocated as a handle; don't set the baseAddr of a GWorld; don't change the dimensions of a GWorld without UpdateGWorld; and don't set the pmVersion field of a GWorld.

You have your choices when you want to use QuickDraw to draw off screen into the memory of a NuBus video card. You can be safe for future compatibility by creating your own off-screen drawing environment from scratch, or you can modify a GWorld so that it uses your NuBus card's memory at the risk of breaking on future systems and at the cost of losing most of the benefits of GWorlds. If you choose the first method and you have no existing routines to create off-screen drawing environments, it's worth it to take a look at Skippy White's Famous High-Level Off-Screen Map Routines in DTS Sample Code #15 on theDeveloper CD Series disc. You can see these routines in action in DTS Sample Code #16. These routines are GWorld-like to some extent, except this time you have the great benefit of source code!



REFERENCES

  • "About 32-Bit Addressing," Konstantin Othmer, develop Issue 6, Spring 1991, pp. 36-37.
  • "Deaccelerated _CopyBits & 8*24 GC QuickDraw," Guillermo Ortiz, Macintosh Technical Note #289, January 1991.
  • "Drawing Into an Off-Screen Pixel Map," Jim Friedlander, Rick Blair, and Rich Collyer, Macintosh Technical Note #120, April 1989.
  • Inside Macintosh Volume VI, Graphics Devices Manager chapter, Addison-Wesley, 1991.
  • Inside Macintosh Volume V, Color Manager chapter, Addison-Wesley, 1988.


FORREST TANAKA has been in Developer Technical Support just shy of two years after a stint with unemployment and trying to get a job at Apple. Before that, he got a BSCS while writing Macintosh device drivers for scanners and writing utility software for a PBX. Now he's working with anything that makes images appear on the Macintosh's screen while avoiding anything that makes images appear on paper. Whenever he's not working, eating, sleeping, watching TV, reading, or watching a movie, he's out riding his bike and wondering whether he should shave his legs. *

PAUL SNIVELY, formerly of Apple's DTS group, came to Apple from ICOM Simulations, Inc., the land of the TMON debugger. He wrote the TMON 2.8 User's Guide and has written for MacTutor magazine. His interests include natural- language processing, knowledge representation, adventure-game programming, horror and suspense, hiking, camping, spelunking, and other things better left unsaid.*

For information about inverse tables, see pages 137 through 139 in the Color Manager chapter of Inside Macintosh Volume V.*

Thanks to Guillermo Ortiz for reviewing this column.*

We welcome guest columns from readers who have something interesting or useful to say. Send your column idea or draft to Caroline Rose at Apple Computer, Inc., 20525 Mariani Avenue, M/S 75-2B, Cupertino, CA 95014 (AppleLink: CROSE).*

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Bookends 12.8 - Reference management and...
Bookends is a full-featured bibliography/reference and information-management system for students and professionals. Bookends uses the cloud to sync reference libraries on all the Macs you use.... Read more
Adobe Creative Cloud 4.0.0.185 - Access...
Adobe Creative Cloud costs $19.99/month for a single app, or $49.99/month for the entire suite. Introducing Adobe Creative Cloud desktop applications, including Adobe Photoshop CC and Illustrator CC... Read more
Default Folder X 5.1.4 - Enhances Open a...
Default Folder X attaches a toolbar to the right side of the Open and Save dialogs in any OS X-native application. The toolbar gives you fast access to various folders and commands. You just click on... Read more
Amazon Chime 4.1.5587 - Amazon-based com...
Amazon Chime is a communications service that transforms online meetings with a secure, easy-to-use application that you can trust. Amazon Chime works seamlessly across your devices so that you can... Read more
Persecond 1.0.9 - Timelapse video made e...
Persecond is the easy, fun way to create a beautiful timelapse video. Import an image sequence from any camera, trim the length of your video, adjust the speed and playback direction, and you’re done... Read more
CrossOver 16.2 - Run Windows apps on you...
CrossOver can get your Windows productivity applications and PC games up and running on your Mac quickly and easily. CrossOver runs the Windows software that you need on Mac at home, in the office,... Read more
MegaSeg 6.0.2 - Professional DJ and radi...
MegaSeg is a complete solution for pro audio/video DJ mixing, radio automation, and music scheduling with rock-solid performance and an easy-to-use design. Mix with visual waveforms and Magic... Read more
Apple iTunes 12.6 - Play Apple Music and...
Apple iTunes lets you organize and stream Apple Music, download and watch video and listen to Podcasts. It can automatically download new music, app, and book purchases across all your devices and... Read more
GraphicConverter 10.4 - $39.95
GraphicConverter is an all-purpose image-editing program that can import 200 different graphic-based formats, edit the image, and export it to any of 80 available file formats. The high-end editing... Read more
OpenEmu 2.0.5 - Open Source game-emulati...
OpenEmu is about to change the world of video game emulation, one console at a time... For the first time, the 'It just works' philosophy now extends to open source video game emulation on the Mac.... Read more

The Elder Scrolls: Legends is now availa...
| Read more »
Ticket to Earth beginner's guide: H...
Robot Circus launched Ticket to Earth as part of the App Store's indie games event last week. If you're not quite digging the space operatics Mass Effect: Andromeda is serving up, you'll be pleased to know that there's a surprising alternative on... | Read more »
Leap to victory in Nexx Studios new plat...
You’re always a hop, skip, and a jump away from a fiery death in Temple Jump, a new platformer-cum-endless runner from Nexx Studio. It’s out now on both iOS and Android if you’re an adventurer seeking treasure in a crumbling, pixel-laden temple. | Read more »
Failbetter Games details changes coming...
Sunless Sea, Failbetter Games' dark and gloomy sea explorer, sets sail for the iPad tomorrow. Ahead of the game's launch, Failbetter took to Twitter to discuss what will be different in the mobile version of the game. Many of the changes make... | Read more »
Splish, splash! The Pokémon GO Water Fes...
Niantic is back with a new festival for dedicated Pokémon GO collectors. The Water Festival officially kicks off today at 1 P.M. PDT and runs through March 29. Magikarp, Squirtle, Totodile, and their assorted evolved forms will be appearing at... | Read more »
Death Road to Canada (Games)
Death Road to Canada 1.0 Device: iOS Universal Category: Games Price: $7.99, Version: 1.0 (iTunes) Description: Get it now at the low launch price! Price will go up a dollar every major update. Update news at the bottom of this... | Read more »
Bean's Quest Beginner's Guide:...
Bean's Quest is a new take on both the classic platformer and the endless runner, and it's free on the App Store for the time being. Instead of running constantly, you can't stop jumping. That adds a surprising new level of challenge to the game... | Read more »
How to rake in the cash in Bit City
Our last Bit City guide covered the basics. Now it's time to get into some of the more advanced techniques. In the later cities, cash flow becomes much more difficult, so you'll want to develop some strategies if you want to complete each level.... | Read more »
PixelTerra (Games)
PixelTerra 1.1.1 Device: iOS Universal Category: Games Price: $.99, Version: 1.1.1 (iTunes) Description: The world of PixelTerra is quite dangerous so you need to build a shelter, find some food supply and get ready to protect... | Read more »
Tokaido™ (Games)
Tokaido™ 1.0 Device: iOS Universal Category: Games Price: $6.99, Version: 1.0 (iTunes) Description: Discover the digital adaptation of Tokaido, the boardgame phenomenon that has already sold more than 250,000 copies worldwide, and... | Read more »

Price Scanner via MacPrices.net

SSD Speeder RAM Disk SSD Life Extender App Fo...
Fehraltorf, Switzerland based B-Eng has announced they are making their SSD Speeder app for macOS publicly available for purchase on their website. SSD Speeder is a RAM disk utility that prevents... Read more
iPhone Scores Highest Overall in Smartphone D...
Customer satisfaction is much higher among smartphone owners who use their device to operate other connected home services such as smart thermostats and smart appliances, according to the J.D. Power... Read more
Swipe CRM Free Photo-Centric CRM Sales DEal C...
Swipe CRM LLC has introduced Swipe CRM: Visual Sales 1.0 for iPad, an app for creating, managing, and sharing visually stunning sales deals. Swipe CRM is targeted to small-and-medium creative... Read more
13-inch 2.0GHz Apple MacBook Pros on sale for...
B&H has the non-Touch Bar 13″ 2.0GHz MacBook Pros in stock today and on sale for $150 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 13″ 2.0GHz MacBook Pro Space Gray (... Read more
15-inch Touch Bar MacBook Pros on sale for up...
B&H Photo has the new 2016 15″ Apple Touch Bar MacBook Pros in stock today and on sale for up to $150 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 15″ 2.7GHz Touch Bar... Read more
Apple’s iPhone 6s Tops Best-Selling Smartphon...
In terms of shipments, the iPhone 6s from Apple bested all competitors for sales in 2016, according to new analysis from IHS Markit, a world leader in critical information, analytics and solutions.... Read more
Logitech Rugged Combo Protective iPad Case an...
Logitech has announced its Logitech Rugged Combo, Logitech Rugged Case, and Logitech Add-on Keyboard for Rugged Case for Apple’s new, more affordable $329 9.7-inch iPad, a complete solution designed... Read more
T-Mobile To Offer iPhone 7 and iPhone 7 Plus...
T-Mobile has announced it will offer iPhone 7 and iPhone 7 Plus (PRODUCT)RED Special Edition in a vibrant red aluminum finish. The introduction of this special edition iPhone celebrates Apple’s 10... Read more
9-inch 128GB iPad Pros on sale for $50-$70 of...
B&H Photo has 9.7″ 128GB Apple WiFi iPad Pros on sale for up to $70 off MSRP, each including free shipping. B&H charges sales tax in NY only: - 9″ Space Gray 128GB WiFi iPad Pro: $649 $50... Read more
27-inch iMacs on sale for up to $200 off MSRP...
B&H Photo has 27″ Apple iMacs on sale for up to $200 off MSRP, each including free shipping plus NY sales tax only: - 27″ 3.3GHz iMac 5K: $2099 $200 off MSRP - 27″ 3.2GHz/1TB Fusion iMac 5K: $... Read more

Jobs Board

*Apple* Retail - Multiple Positions- Chicago...
SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Fulltime aan de slag als shopmanager in een h...
Ben jij helemaal gek van Apple -producten en vind je het helemaal super om fulltime shopmanager te zijn in een jonge en hippe elektronicazaak? Wil jij werken in Read more
Starte Dein Karriere-Abenteuer in den Hauptst...
…mehrsprachigen Teams betreust Du Kunden von bekannten globale Marken wie Apple , Mercedes, Facebook, Expedia, und vielen anderen! Funktion Du wolltest schon Read more
*Apple* macOS Systems Integration Administra...
…most exceptional support available in the industry. SCI is seeking an Junior Apple macOS systems integration administrator that will be responsible for providing Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.