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. *

 
AAPL
$95.22
Apple Inc.
+0.19
MSFT
$42.09
Microsoft Corpora
+0.41
GOOG
$579.18
Google Inc.
+8.08

MacTech Search:
Community Search:

Software Updates via MacUpdate

NeoOffice 2014 - Mac-tailored, OpenOffic...
To download NeoOffice from the Apple Mac App Store, a $29.99 purchase is required. NeoOffice is a fully-featured set of office applications (including word processing, spreadsheet, presentation,... Read more
PhotoDesk 2.3.8 - Instagram client for p...
PhotoDesk (formerly InstaDesk) is an Instagram client for the Mac. PhotoDesk lets you not only browse your or your friends Instagram pictures, but easily explore the social graph and find new people... Read more
Garmin Express 3.2.13.0 - Manage your Ga...
Garmin Express is your essential tool for managing your Garmin devices. Update maps, golf courses and device software. You can even register your device. Update maps Update software Register your... Read more
Apple iTunes 11.3 - Manage your music, m...
Apple iTunes lets you organize and play digital music and video on your computer. It can automatically download new music, app, and book purchases across all your devices and computers. And it's a... Read more
Iridient Developer 2.4.3 - Powerful imag...
Iridient Developer (was RAW Developer) is a powerful image conversion application designed specifically for OS X. Iridient Developer gives advanced photographers total control over every aspect of... Read more
CrossOver 13.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
Tweetbot 1.6 - Popular Twitter client. (...
Tweetbot is a full-featured OS X Twitter client with a lot of personality. Whether it's the meticulously-crafted interface, sounds and animation, or features like multiple timelines and column views... Read more
Capo 3.1 - Slow down and learn to play y...
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
Backblaze 2.5.1.750 - Online backup serv...
Backblaze is an online backup service designed from the ground-up for the Mac.With unlimited storage available for $5 per month, as well as a free 15-day trial, peace of mind is within reach with... Read more
ExpanDrive 4.1.2 - Access remote files o...
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

Latest Forum Discussions

See All

Minimalistic Puzzler Bicolor Adds New Le...
Minimalistic Puzzler Bicolor Adds New Levels in Latest Update Posted by Ellis Spice on July 11th, 2014 [ permalink ] | Read more »
Civilization Revolution 2 Review
Civilization Revolution 2 Review By Blake Grundman on July 11th, 2014 Our Rating: :: MORE REDUX THAN REVOLUTIONUniversal App - Designed for iPhone and iPad Is a new 3D coat of paint worth spending $14.99? In this case, probably not... | Read more »
Simian Flu Infects Plague Inc.’s Latest...
Simian Flu Infects Plague Inc.’s Latest Update Posted by Jennifer Allen on July 11th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
The Rhythm of Fighters Review
The Rhythm of Fighters Review By Lee Hamlet on July 11th, 2014 Our Rating: :: OFF-BEATiPhone App - Designed for the iPhone, compatible with the iPad The Rhythm of Fighters can’t capture the excitement of its beat-em-up equivalent,... | Read more »
Real Racing 3′s Gold Payout Substantiall...
Real Racing 3′s Gold Payout Substantially Increased in Latest Update Posted by Jennifer Allen on July 11th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Lomotif Review
Lomotif Review By Lee Hamlet on July 11th, 2014 Our Rating: :: INSTANT MUSIC VIDEOSiPad Only App - Designed for the iPad Adding music to short video clips has never been easier than it is with Lomotif.   | Read more »
Roll a Critical Sucess for Getting in Sh...
Roll a Critical Sucess for Getting in Shape With FitRPG: Gamifying Fitbit Posted by Jessica Fisher on July 11th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Alphabeats Review
Alphabeats Review By Jennifer Allen on July 11th, 2014 Our Rating: :: WORDY MUSICAL MASH-UPUniversal App - Designed for iPhone and iPad Tricky due to an awkward control system, Alphabeats is still an interesting combination of... | Read more »
iblazr: Portable Flash for Smarphone Cam...
iblazr: Portable Flash for Smarphone Cameras from BiteMyApple.co. Posted by Jessica Fisher on July 11th, 2014 [ permalink ] BiteMyApple.co has announced that they will begin shipping their new iblazr today. | Read more »
Transworld Endless Skater Review
Transworld Endless Skater Review By Jennifer Allen on July 11th, 2014 Our Rating: :: TRICKY IN EVERY SENSEUniversal App - Designed for iPhone and iPad A little too tricky at times, Transworld Endless Skater is a more true to... | Read more »

Price Scanner via MacPrices.net

Save up to $100 on MacBook Airs
Adorama has the new 2014 MacBook Airs on sale for up to $100 off MSRP for a limited time. Shipping is free, and Adorama charges NY & NJ sales tax only: - 11″ 128GB MacBook Air: $854.99 MSRP $899... Read more
Tablet PC Quarterly Shipments Fall for the Fi...
NPD DisplaySearch’s Quarterly Mobile PC Shipment and Forecast Report provides more evidence that sub-8-inch tablet computers such as Apple’s iPad mini, Google’s Nexus 7 and Amazon’s Kindle Fire 7 are... Read more
MCE Ships Portable USB 3.0 2 TB + Blu-ray Rec...
MCE Technologies (MCE) has announced the company is shipping the MCE Complement: the world’s first portable, all-in-one, USB 3.0 device consisting of a 2 TB Hard Drive, a Blu-ray, DVD, CD Reader/... Read more
Daughters Of Zion Magazine Now Available for...
London, England based Vision Genesis Ltd has just released Daughters Of Zion Magazine for iPad, a digital magazine published monthly on the Apple Newsstand. Making full use of the iPad’s powerful... Read more
Apple refurbished Mac mini available for $509
The Apple Store has Apple Certified Refurbished 2.5GHz Mac minis available for $509, $90 off MSRP. Apple’s one-year warranty is included, and shipping is free. Read more
Take $150 off 15″ MacBook Pros
Adorama has 15″ Retina MacBook Pros on sale for $150 off MSRP for a limited time. Shipping is free, and Adorama charges NY & NJ sales tax only: - 15″ 2.3GHz Retina MacBook Pro: $2449, $150 off -... Read more
PC Rebound Stabilizes Mature Markets, But Fal...
Worldwide PC shipments totaled 74.4 million units in the second quarter of 2014 (2Q14), a year-on-year decline of -1.7%, according to the market metrics firm International Data Corporation (IDC)’s... Read more
Panasonic Updates Toughpad FZ-G1 10-inch Rugg...
Panasonic has announced upgrades to the Toughpad FZ-G1 fully-rugged 10-inch tablet. Featuring a faster 4th generation Intel Core i5 vPro processor, the Microsoft Windows 8.1 Pro update, a single... Read more
iPad Rules The Enterprise Tablet Market, Why...
Motley Fool’s Sean Chandler posted a blog last week advocating that Apple copy Microsoft’s Surface Pro 3, arguing that Microsoft has a point in its contention that too many users own both laptops and... Read more
Apple refurbished Time Capsules available for...
The Apple Store has certified refurbished Time Capsules available for up to $60 off MSRP. Apple’s one-year warranty is included with each Time Capsule, and shipping is free: - 2TB Time Capsule: $255... Read more

Jobs Board

*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
*Apple* Computer Technician - Fairfield Coun...
Company DescriptionWe are an Apple Authorized Sales and Service Provider. We have been selling and servicing Apple computers in the Fairfield County area for over 20 Read more
Sr. Product Leader, *Apple* Store Apps - Ap...
**Job Summary** Imagine what you could do here. At Apple , great ideas have a way of becoming great products, services, and customer experiences very quickly. Bring Read more
Project Manager / Business Analyst, WW *Appl...
…a senior project manager / business analyst to work within our Worldwide Apple Fulfillment Operations and the Business Process Re-engineering team. This role will work Read more
Sr. Project Manager for *Apple* Campus 2 -...
…the design and construction of one building or building components of the New Apple Campus located in Cupertino, CA. They will provide project management oversight for Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.