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

Is there cross-platform play in slither....
So you've sunken plenty of hours into crawling around in slither.io on your iPhone or iPad. You've got your stories of tragedy and triumph, the times you coiled four snakes at one time balanced out by the others when you had a length of more than... | Read more »
Rodeo Stampede guide to running a better...
In Rodeo Stampede, honing your skills so you can jump from animal to animal and outrun the herd as long as possible is only half the fun. Once you've tamed a few animals, you can bring them home with you. [Read more] | Read more »
VoxSyn (Music)
VoxSyn 1.0 Device: iOS Universal Category: Music Price: $6.99, Version: 1.0 (iTunes) Description: VoxSyn turns your voice into the most flexible vocal sound generator ever. Instantly following even subtle modulations of pitch and... | Read more »
Catch Battleplans on Google Play from Ju...
Real-time strategy title Battleplans is due for release on Google Play on June 30th, following its release for iOS systems last month. With its simple interface and pretty graphics, the crowd-pleaser brings a formerly overlooked genre out for the... | Read more »
iDoyle: The interactive Adventures of Sh...
iDoyle: The interactive Adventures of Sherlock Holmes - A Scandal in Bohemia 1.0 Device: iOS Universal Category: Books Price: $1.99, Version: 1.0 (iTunes) Description: Special Release Price $1.99 (Normally $3.99) | Read more »
Five popular free apps to help you slim...
Thanks to retail and advertising, we're used to thinking one season ahead. Here we are just a week into the summer and we're conditioned to start thinking about the fall. [Read more] | Read more »
How to ride longer and tame more animals...
It's hard to accurately describe Rodeo Stampede to people who haven't seen it yet. It's like if someone took Crossy Roadand Disco Zoo and put them in a blender, yet with a unique game mechanic that's still simple and fun for anyone. [Read more] | Read more »
Teeny Titans - A Teen Titans Go! Figure...
Teeny Titans - A Teen Titans Go! Figure Battling Game 1.0.0 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0.0 (iTunes) Description: Teeny Titans, GO! Join Robin for a figure battling RPG of epic proportions! TEENY... | Read more »
NinjAwesome: Tips and tricks to be a mor...
Sorry about that headline, but I'm going to go ahead and assume that GameResort would not have named its game NinjAwesome without expecting some of that. It is, in fact, pretty awesome the way it combines an endless runner and old school arcade... | Read more »
Into Mirror (Games)
Into Mirror 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: "Is all that we see or seem, but a dream within a dream?"- Edgar Allan Poe New game by Lemon Jam Studio, the team behind Pursuit... | Read more »

Price Scanner via MacPrices.net

15-inch Retina MacBook Pros on sale for $200-...
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.99 $200 off MSRP - 15″ 2.5GHz... Read more
Mac minis on sale for up to $100 off MSRP
B&H Photo has Mac minis on sale for up to $100 off MSRP including free shipping plus NY sales tax only: - 1.4GHz Mac mini: $449 $50 off MSRP - 2.6GHz Mac mini: $649 $50 off MSRP - 2.8GHz Mac mini... Read more
Clearance 2015 13-inch MacBook Airs available...
B&H Photo has clearance 2015 13″ MacBook Airs available for $300 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 Mac minis available for up...
Apple has Certified Refurbished Mac minis available starting at $419. Apple’s one-year warranty is included with each mini, and shipping is free: - 1.4GHz Mac mini: $419 $80 off MSRP - 2.6GHz Mac... Read more
ABBYY TextGrabber: 1,000,000 Installs in 5 Da...
ABBYY, an international OCR technologies provider, has announced that their image-to-text application TextGrabber, got installed 1,000,000 times in just five days while being featured by the App... Read more
New SkinIt Waterproof Case For iPhone 6
With its impact and waterproof design, the Skinit Waterproof case provides security and protection to guarantee your phone will get you through even the most demanding outdoor conditions. The impact-... Read more
iMacs on sale for up to $150 off MSRP
B&H Photo has 21″ and 27″ iMacs on sale for up to $150 off MSRP including free shipping plus NY sales tax only: - 27″ 3.3GHz iMac 5K: $2181.11 $118 off MSRP - 27″ 3.2GHz/1TB Fusion iMac 5K: $1949... Read more
12-inch 1.1GHz Retina MacBooks on sale for $5...
B&H Photo has 2016 12″ 1.1GHz/256GB Retina MacBooks on sale for up to $50 off MSRP. Shipping is free, and B&H charges NY tax only: - 12″ 1.1GHz Space Gray Retina MacBook: $1249 $50 off MSRP... Read more
WWDC Announcements Revisited Still Underwhelm...
I was disappointed that no new MacBook hardware was announced at this year’s all-software World Wide Developer’s Conference. Not even a hint about what’s in the development pipeline. Of course, we... Read more
Twelve South Compass 2 iPad Stand Now Availab...
Twelve South has updated its most popular iPad stand, Compass 2, with the introduction of two new colors — Gold and Rose Gold. These new color options n perfectly complement the new Rose Gold iPad... Read more

Jobs Board

*Apple* iPhone 6s and New Products Tester Ne...
…we therefore look forward to put out products to quality test for durability. Apple leads the digital music revolution with its iPods and iTunes online store, Read more
Music Marketing Lead, iTunes & *Apple*...
…Music Marketing Lead is responsible for developing robust marketing campaigns and programs for Apple Music and iTunes across the whole of Apple ecosystem. This Read more
*Apple* Valley Medical Clinic is Hiring - AP...
Apple Valley Medical Clinic is Hiring! Apple Valley Medical Clinic is an independently owned practice operating a Family Medicine Clinic, a 24/7 Urgent Care, Read more
*Apple* New Products Testers Needed - Apple...
…we therefore look forward to put out products to quality test for durability. Apple leads the digital music revolution with its iPods and iTunes online store, 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
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.