TweetFollow Us on Twitter

September 94 - GRAPHICAL TRUFFLES

GRAPHICAL TRUFFLES

A Cool QuickDraw GX Clipping Effect

PETE ("LUKE") ALEXANDER

[IMAGE Graphical_Truffles_final_1.GIF]

Wading through the vast sea of documentation you get with the QuickDraw GX Software Developer's Kit, you may not realize all the cool things this new graphics model lets you do. In this column, we'll look at just one of those cool things: clipping one shape to the inside of another arbitrary shape. As an illustration, we'll take a bitmapped image of a tropical beach (Figure 1) and clip it to the word "BAY" (Figure 2). Figure 3 shows the result. There's a sample application and source code on this issue's CD.

CREATING THE SHAPES
We'll be collecting the results of our operations into a picture shape. We'll assume that the QuickDraw GX environment has already been set up and that we have a window ready to draw into.

For information on setting up the QuickDraw GX environment, see "Getting Started With QuickDraw GX" in develop Issue 15. The full details are in Inside Macintosh: QuickDraw GX Objects and Inside Macintosh: QuickDraw GX Graphics. *

We start by creating an empty picture to which we can add shapes:

gxShape  thePicture;
thePicture = GXNewShape(gxPictureType);

The bitmap shape we'll be clipping (Figure 1) is stored in our application's resource fork as a 'pxmp' resource. We retrieve it with the GetPixMapShape call from the qd library.

[IMAGE Graphical_Truffles_final_2.GIF]

Figure 1. The shape to be clipped

gxShape theBitmap;
theBitmap = GetPixMapShape(kPixMapID);

To create the clip shape, we start with a text shape containing the word BAY.

gxShape theClip;
theClip = GXNewText(3, (unsigned char*)"BAY", nil);

[IMAGE Graphical_Truffles_final_3.GIF]

Figure 2. The clip shape

[IMAGE Graphical_Truffles_final_4.GIF]

Figure 3. Result of clipping Figure 1 to Figure 2

POSITIONING AND SCALING THE TEXT SHAPE
Before we set our text shape to be the clip of our bitmap shape, we need to move it to the top left corner of the bitmap shape and then scale it to encompass the entire bitmap.

We'll look at two ways to do this. The first method takes us through all the steps in the process, while the second is simpler and lets QuickDraw GX do more of the work for us.

The origin of a text shape is on the baseline, but in this case, because there are no descenders in the text, we just use the bottom left corner of the shape's bounds. We need to offset the text shape by its own height from the top of the bitmap shape. So we need to know the bounds of both the bitmap shape (to find the coordinates of its top left corner) and the text shape (to calculate its height):

gxRectangle	bitmapBounds, textBounds;
GXGetShapeBounds(theBitmap, 0, &bitmapBounds);
GXGetShapeBounds(theClip, 0, &textBounds);
textHeight = textBounds.bottom - textBounds.top;
GXMoveShapeTo(theClip, bitmapBounds.left, 
		bitmapBounds.top + textHeight);

Our original text shape, which is the default text size of 12 points, isn't big enough to cover the entire bitmap shape. If we were to do the clipping at this point, we would get just a tiny piece of the corner instead of the whole bitmap. To get the whole thing, we have to scale the text shape to match the size of the bitmap shape.

For the text shape to scale linearly, without taking the font's hinting into account, we have to turn off QuickDraw GX's built-in metrics and contour grid-fitting capabilities. We do this by setting the shape's text attributes as follows:

GXSetShapeTextAttributes(theClip,
	gxNoMetricsGridText | gxNoContourGridText);

Although QuickDraw GX lets us clip to any arbitrary shape, clipping is actually limited to primitive shapes only. That is, the clip shape must be a shape whose geometry and fill properties by themselves define the shape; primitive shapes don't use information from a style or transform object. This is not a problem, though, because we can easily convert a shape to its primitive form. The following call does the job:

GXPrimitiveShape(theClip);

The result is a filled path shape (which is a primitive shape) representing the outlines of the letters in the word BAY.

Next we need to determine how much to scale the text shape to encompass the entire bitmap shape. We do this by finding the width and height of both shapes' bounds rectangles and scaling the text shape in each direction by the ratio between the two:

Fixed 		bitmapWidth, bitmapHeight;
Fixed 		textWidth, textHeight;
Fixed 		xScale, yScale;

// Determine the width ratio.
bitmapWidth = bitmapBounds.right - bitmapBounds.left;
textWidth = textBounds.right - textBounds.left;
xScale = FixedDivide(bitmapWidth, textWidth);

// Determine the height ratio.
bitmapHeight = bitmapBounds.bottom - bitmapBounds.top;
textHeight = textBounds.bottom - textBounds.top;
yScale = FixedDivide(bitmapHeight, textHeight);

GXScaleShape(theClip, xScale, yScale,
			bitmapBounds.left, bitmapBounds.top);

We've now scaled the text shape to encompass the entire area of our bitmap shape, and we're ready to use it to clip the bitmap shape. But it turns out that there's a shorter way to do this; we can actually accomplish the same thing with only three lines of code:

GXSetShapeTextAttributes(theClip,
    gxNoMetricsGridText | gxNoContourGridText);
GXGetShapeBounds(theBitmap, 0, &textBounds);
GXSetShapeBounds(theClip, &textBounds);

As in the earlier method, we turn hinting off and get the bounds of our bitmap shape. The magic here is in the GXSetShapeBounds call: when applied to typographic shapes, this call positions and scales the text to the new bounds and converts it to a primitive shape. That's it! QuickDraw GX does the hard work for us automatically, and we're ready to set the clip of our bitmap shape.

SETTING THE CLIP SHAPE
Now that the text shape is positioned and scaled the way we want it, we're ready to set it up as the clip of our bitmap shape:

GXSetShapeClip(theBitmap, theClip);

This call changes the clip shape contained within the transform used by our bitmap shape, replacing it with the new clip shape that we've created.

If the same transform were being shared by other shapes, QuickDraw GX would make a copy of the transform to associate with our bitmap shape, ensuring that the new clip would not affect any of the other shapes sharing the same transform.*The next step is to add the clipped bitmap shape to our picture with GXSetPictureParts. (Note that we could also use the library call AddToShape or the core call GXSetShapeParts to do the same thing, but I chose to be more explicit here.)

GXSetPictureParts(thePicture, 0, 0, 1, &theBitmap,
		nil, nil, nil);

The picture now contains a new reference to the original bitmap shape, complete with the new clip we've added to it. Once there's a reference to it in the picture, we don't need the original reference anymore, so we dispose of it:

GXDisposeShape(theBitmap);

DRAWING THE OUTLINE
The last order of business is to draw an outline around the clipped bitmap. We can accomplish this by setting up the drawing characteristics of our scaled text shape to draw the outline and then adding it to our picture. To frame the shape with a closed outline, we set its fill characteristic to gxClosedFrameFill. Since we want the frame to lie outside the geometry of the shape, we set its style attributes to gxOutsideFrameStyle. Finally, we set the pen size to 3 to get a satisfyingly fat outline, and we set the color of the outline to blue:

GXSetShapeFill(theClip, gxClosedFrameFill);
GXSetShapeStyleAttributes(theClip, gxOutsideFrameStyle);
GXSetShapePen(theClip, ff(3));
SetShapeCommonColor(theClip, blue);

Now we can add the outlined shape to our picture and dispose of it, as before:

GXSetPictureParts(thePicture, 0, 0, 1, &theClip,
		nil, nil, nil);
GXDisposeShape(theClip);

DRAWING THE PICTURE
Before drawing our picture, we'll move it down a little from the top left corner of the window. We could do this by retrieving the picture's transform and shifting it down and to the right with GXMoveTransform; however, since the gxMapTransformShape attribute is set for pictures by default, we can just call GXMoveShape:

GXMoveShape(thePicture, f(20), ff(15));

Finally, we're ready to draw the picture:

GXDrawShape(thePicture);

We're done! The result should look like Figure 3.

THAT'S ALL, FOLKS
You've had a quick look at one of the many cool things you can do with the QuickDraw GX graphics system. As you can see from this example, the power and flexibility of QuickDraw GX can give your application the ability to do things you could only dream about until now.

PETE ("LUKE") ALEXANDERRegular readers of Luke's columns will know that he took his sabbatical from Apple this summer. He sent us a postcard: "Hey dudes! While you're looking out your windows at Silicon Valley smog, I'm looking out my windows at the rocky faces of Montana. Have you heard of National Parks? They're places of unusual beauty set apart from development. Not that kind of development! The kind that causes smog. At Yellowstone Park I enjoyed the clear air, I found where the buffalo roam, and I learned why they call it Old Faithful. I'm now flying somewhere over Montana (don't worry, I'm steering with my knee), admiring the mountains with their lingering snow and enjoying the wide open spaces. Oops, mountain ahead and no more room on the card." He signed it, "See you later, Luke" but then crossed out the "See you later." We're worried, really worried.*

Thanks to Hugo Ayala and Cary Clark for reviewing this column. *

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Lyn 1.8.5 - Lightweight image browser an...
Lyn is a fast, lightweight image browser and viewer designed for photographers, graphic artists, and Web designers. Featuring an extremely versatile and aesthetically pleasing interface, it delivers... Read more
Apple iOS 10.2.1 - The latest version of...
iOS 10 is the biggest release of iOS ever. A massive update to Messages brings the power of the App Store to your conversations and makes messaging more personal than ever. Find your route with... Read more
Apple Security Update 2016-003 Supplemen...
Apple Security Update is recommended for all users and improves the security of OS X. For detailed information about the security content of this update, please visit: http://support.apple.com/kb/... Read more
Apple macOS Sierra 10.12.3 - The latest...
With Apple macOS Sierra, Siri makes its debut on Mac, with new features designed just for the desktop. Your Mac works with iCloud and your Apple devices in smart new ways, and intelligent... Read more
BetterTouchTool 1.992 - Customize Multi-...
BetterTouchTool adds many new, fully customizable gestures to the Magic Mouse, Multi-Touch MacBook trackpad, and Magic Trackpad. These gestures are customizable: Magic Mouse: Pinch in / out (zoom... Read more
Viber 6.5.5 - Send messages and make cal...
Viber lets you send free messages and make free calls to other Viber users, on any device and network, in any country! Viber syncs your contacts, messages and call history with your mobile device, so... Read more
Opera 42.0.2393.137 - High-performance W...
Opera is a fast and secure browser trusted by millions of users. With the intuitive interface, Speed Dial and visual bookmarks for organizing favorite sites, news feature with fresh, relevant content... Read more
iClock Pro 3.4.7 - Customize your menuba...
iClock Pro is a menu bar replacement clock for Apple's default clock. iClock Pro is an update, total rewrite and improvement to the popular iClock. Have the day, date and time in different fonts and... Read more
PhotoDesk 4.1.5 - Instagram client for p...
PhotoDesk lets you view, like, comment, and download Instagram pictures/videos. (NO Uploads! / Image Posting! Instagram forbids that! AND you need an existing Instagram account). But you can do so... Read more
Capo 3.5.1 - Slow down and learn to play...
Capo lets you slow down your favorite songs so you can hear the notes and learn how they are played. With Capo, you can quickly tab out your songs atop a highly-detailed OpenCL-powered spectrogram... Read more

Ironhide Game Studio prepares for a busy...
Kingdom Rush breathed fresh life into the tired tower defense genre way back in 2012. The game was a robust challenge that somehow managed to lift you up, rather than leaving you feeling crushed and hopeless. The rich array of unit types and... | Read more »
Collect pets and sling arrows in Arcane...
Mobile gaming is a crowded market, but regular updates are a good way to keep us attention-short players keen. The brand new content in Arcane Online is a prime example. Published by Japanese developer Gala, Arcane Online is a fantasy MMO that... | Read more »
Super Mario Run dashes onto Android in M...
Super Mario Run was one of the biggest mobile launches in 2016 before it was met with a lukewarm response by many. While the game itself plays a treat, it's pretty hard to swallow the steep price for the full game. With that said, Android users... | Read more »
WarFriends Beginner's Guide: How to...
Chillingo's new game, WarFriends, is finally available world wide, and so far it's a refreshing change from common mobile game trends. The game's a mix of tower defense, third person shooter, and collectible card game. There's a lot to unpack here... | Read more »
Super Gridland (Entertainment)
Super Gridland 1.0 Device: iOS Universal Category: Entertainment Price: $1.99, Version: 1.0 (iTunes) Description: Match. Build. Survive. "exquisitely tuned" - Rock Paper Shotgun No in-app purches, and no ads! | Read more »
Red's Kingdom (Games)
Red's Kingdom 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Mad King Mac has kidnapped your father and stolen your golden nut! Solve puzzles and battle goons as you explore and battle your... | Read more »
Turbo League Guide: How to tame the cont...
| Read more »
Fire Emblem: Heroes coming to Google Pla...
Nintendo gave us our first look at Fire Emblem: Heroes, the upcoming mobile Fire Emblem game the company hinted at last year. Revealed at the Fire Emblem Direct event held today, the game will condense the series' tactical RPG combat into bite-... | Read more »
ReSlice (Music)
ReSlice 1.0 Device: iOS Universal Category: Music Price: $9.99, Version: 1.0 (iTunes) Description: Audio Slice Machine Slice your audio samples with ReSlice and create flexible musical atoms which can be triggered by MIDI notes or... | Read more »
Stickman Surfer rides in with the tide t...
Stickson is back and this time he's taken up yet another extreme sport - surfing. Stickman Surfer is out this Thursday on both iOS and Android, so if you've been following the other Stickman adventures, you might be interested in picking this one... | Read more »

Price Scanner via MacPrices.net

Deal alert! 13-inch 2.0GHz MacBook Pros for $...
B&H Photo has the new 2016 13″ 2.0GHz non-Touch Bar MacBook Pros in stock today and on sale for $225 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 13″ 2.0GHz MacBook Pro... Read more
Free LibreOffice Portable 5.2.4 Complete Offi...
PortableApps.com and The Document Foundation have announce the release of LibreOffice Portable 5.2.4. LibreOffice Portable is an Open Source full-featured office suite — including a word processor,... Read more
Apple Planning Three New Tablets For 2017 – D...
Digitimes’ Rebecca Kuo and Joseph Tsai say that unnamed insider sources report Apple having three new tablets in the pipeline for 2017 release: a 9.7-inch model with a friendly price range, a new mid... Read more
Roundup of 15-inch Touch Bar MacBook Pro sale...
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 refurbished iPad Pros available for up...
Apple has Certified Refurbished 9″ and 12″ Apple iPad Pros available for up to $160 off the cost of new iPads. An Apple one-year warranty is included with each model, and shipping is free: - 32GB 9″... Read more
16GB iPad Air 2, Apple refurbished, available...
Apple has Certified Refurbished 16GB iPad Air 2s available for $319 including free shipping. A standard Apple one-year is included. Their price is $60 off original MSRP for this model. Read more
Apple iMacs on sale for up to $120 off MSRP
B&H Photo has 21″ and 27″ Apple iMacs on sale for up to $120 off MSRP, each including free shipping plus NY sales tax only: - 27″ 3.3GHz iMac 5K: $2199 $100 off MSRP - 27″ 3.2GHz/1TB Fusion iMac... 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
Save up to $350 with Apple Certified Refurbis...
Apple has Certified Refurbished 2015 21″ & 27″ iMacs available for up to $350 off MSRP. Apple’s one-year warranty is standard, and shipping is free. The following models are available: - 21″ 3.... Read more
2015 12-inch Retina MacBooks, Apple refurbish...
Apple has Certified Refurbished 2015 12″ Retina MacBooks available for up to $410 off original MSRP. Apple will include a standard one-year warranty with each MacBook, and shipping is free. The... Read more

Jobs Board

*Apple* & PC Desktop Support Technician...
Apple & PC Desktop Support Technician job in Manhattan, NY Introduction: We have immediate job openings for several Desktop Support Technicians with one of our most Read more
*Apple* & PC Desktop Support Technician...
Apple & PC Desktop Support Technician job in Stamford, CT We have immediate job openings for several Desktop Support Technicians with one of our most well-known 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
*Apple* Site Security Manager - Apple (Unite...
# Apple Site Security Manager Job Number: 54692472 Culver City, California, United States Posted: Jan. 19, 2017 Weekly Hours: 40.00 **Job Summary** The Apple 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
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.