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
$101.58
Apple Inc.
+0.72
MSFT
$46.52
Microsoft Corpora
-0.24
GOOG
$584.77
Google Inc.
+4.82

MacTech Search:
Community Search:

Software Updates via MacUpdate

BusyCal 2.6 - Powerful calendar app with...
BusyCal is an award-winning desktop calendar that combines personal productivity features for individuals with powerful calendar sharing capabilities for families and workgroups. BusyCal's unique... Read more
Apple iOS 8.0 - The latest version of Ap...
The latest version of iOS can be downloaded through iTunes. Apple iOS 8 comes with big updates to apps you use every day, like Messages and Photos. A whole new way to share content with your family.... Read more
Apple Digital Camera RAW Compatibility 5...
Apple Digital Camera RAW Compatibility update adds RAW image compatibility to Aperture 3 and iPhoto '11. For more information on supported RAW formats, see here.Version 5.07: Adds RAW camera... Read more
Transmit 4.4.7 - Excellent FTP/SFTP clie...
Transmit is an excellent FTP (file transfer protocol), SFTP, S3 (Amazon.com file hosting) and iDisk/WebDAV client that allows you to upload, download, and delete files over the internet. With the... Read more
Macgo Blu-ray Player 2.10.8.1715 - Blu-r...
Macgo Mac Blu-ray Player can bring you the most unforgettable Blu-ray experience on your Mac. Overview Macgo Mac Blu-ray Player can satisfy just about every need you could possibly have in a Blu-ray... Read more
Capture One Pro 8.0.0.433 - RAW workflow...
Capture One Pro 8 is a professional RAW converter offering you ultimate image quality with accurate colors and incredible detail from more than 300 high-end cameras -- straight out of the box. It... Read more
Adobe Acrobat Pro 11.0.09 - Powerful PDF...
Adobe Acrobat allows users to communicate and collaborate more effectively and securely. Unify a wide range of content in a single organized PDF Portfolio. Collaborate through electronic document... Read more
Adobe Reader 11.0.09 - View PDF document...
Adobe Reader allows users to view PDF documents. You may not know what a PDF file is, but you've probably come across one at some point. PDF files are used by companies and even the IRS to... Read more
iFFmpeg 4.6.1 - Convert multimedia files...
iFFmpeg is a graphical front-end for FFmpeg, a command-line tool used to convert multimedia files between formats. The command line instructions can be very hard to master/understand, so iFFmpeg does... Read more
NTFS 11.3.62 - Provides full read and wr...
Paragon NTFS breaks down the barriers between Windows and OS X. Paragon NTFS effectively solves the communication problems between the Mac system and NTFS, providing full read and write access to... Read more

Latest Forum Discussions

See All

Minuum - The Little Keyboard for Big Fin...
Minuum - The Little Keyboard for Big Fingers 1.0 Device: iOS iPhone Category: Utilities Price: $1.99, Version: 1.0 (iTunes) Description: Type faster, see more of your screen, and take control of autocorrect with Minuum: the little... | Read more »
TextExpander 3 + custom keyboard (Utili...
TextExpander 3 + custom keyboard 3.0 Device: iOS Universal Category: Utilities Price: $4.99, Version: 3.0 (iTunes) Description: | Read more »
Swype - Keyboard (Utilities)
Swype - Keyboard 1.0.1411 Device: iOS Universal Category: Utilities Price: $.99, Version: 1.0.1411 (iTunes) Description: Why type when you can Swype? One of the most requested apps for iPhone is finally here. "If Swype itself ever... | Read more »
Joinz (Games)
Joinz 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Joinz is a clever block sliding puzzle game that is easy to play, nice to look at but tricky to master. You will be coming back again... | Read more »
Little World Escape Review
Little World Escape Review By Jordan Minor on September 17th, 2014 Our Rating: :: EARTHBOUNDUniversal App - Designed for iPhone and iPad Little World Escape draws players in with captivating concepts before pushing them away with... | Read more »
Light in the Dark Review
Light in the Dark Review By Nadia Oxford on September 17th, 2014 Our Rating: :: LIGHT 'EM UP UP UPUniversal App - Designed for iPhone and iPad Light in the Dark is an interesting and challenging puzzle game with some amusing bits... | Read more »
ShareFile for iPad is iOS 8-Ready with N...
ShareFile for iPad is iOS 8-Ready with New File-Editi​ng Feature Posted by Jessica Fisher on September 17th, 2014 [ permalink ] | Read more »
Pizo Animals
Pizo Animals By Amy Solomon on September 17th, 2014 Our Rating: :: DELIGHTFUL PUZZLESUniversal App - Designed for iPhone and iPad Pizo Animals is a puzzle app that includes many options adults can choose to customize the experience... | Read more »
ETA for iOS 8 Introduces Today View Exte...
ETA for iOS 8 Introduces Today View Extension and is Having a 50% Off Sale Posted by Jessica Fisher on September 17th, 2014 [ permalink ] | Read more »
Get Ready to Hit the Ice – NHL 2K is Com...
Get Ready to Hit the Ice – NHL 2K is Coming to the App Store Soon Posted by Jessica Fisher on September 17th, 2014 [ permalink ] 2K announced today that they are bringing NHL 2K< | Read more »

Price Scanner via MacPrices.net

Logitech Bluetooth Multi-Device Cross-Platfor...
Logitech has an enviable track record of making some of the best computer keyboards and mice. At least in my estimation, the best freestanding keyboards I’ve ever used have been Logitech units,... Read more
Roundup of Apple refurbished iPad Airs and iP...
Apple is offering Certified Refurbished iPad Airs for up to $140 off MSRP. Apple’s one-year warranty is included with each model, and shipping is free. Stock tends to come and go with some of these... Read more
Sprint offers 16GB iPad mini for $199.99 with...
Sprint is offering 1st generation 16GB iPad minis for $199.99 with a 2-year service agreement. Standard MSRP for this iPad is $429. Their price is the lowest available for this model. Read more
2.5GHz Mac mini remains on sale for $549, sav...
B&H Photo has the 2.5GHz Mac mini on sale for $549.99 including free shipping. That’s $50 off MSRP, and B&H will also include a free copy of Parallels Desktop software. NY sales tax only. Read more
Apple refurbished iMacs available for up to $...
The Apple Store has Apple Certified Refurbished iMacs available for up to $300 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free. These are the best prices on... Read more
13″ 2.5GHz MacBook Pro offered for $100 off M...
B&H Photo has the 13″ 2.5GHz MacBook Pro on sale for $999.99 including free shipping plus NY sales tax only. Their price is $100 off MSRP. Read more
Free GIMP Professional Grade Graphics App Ver...
The latest 2.8.14 version of the oddly-named GIMP (acronym for: GNU Image Manipulation Program) open source, high-end image editing and creation alternative to Adobe’s Photoshop and refuge from... Read more
Apple Announces Record Pre-orders for iPhone...
Apple has released metrics showing a record number of first day pre-orders of iPhone 6 and iPhone 6 Plus, with over four million sold in the first 24 hours. Demand for the new iPhones exceeds the... Read more
10% off iPhone 6 and 6 Plus Otterbox cases
Get 10% off on popular Otterbox iPhone 6 and iPhone 6 Plus cases at MacMall through September 19th. Use code OTTERBOX10 to see the discount. Read more
15-inch MacBook Pros on sale for up to $125 o...
Amazon has the new 2014 15″ Retina MacBook Pros on sale for up to $125 off MSRP including free shipping: - 15″ 2.2GHz Retina MacBook Pro: $1899.99 save $100 - 15″ 2.5GHz Retina MacBook Pro: $2374... Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.