Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 1 - QuickDraw GX and the Macintosh Environment / QuickDraw GX and the Macintosh Environment Reference

QuickDraw-to-QuickDraw GX Translator Functions / Converting QuickDraw Pictures

GXConvertPICTToShape

You can use the GXConvertPICTToShape function to convert a QuickDraw picture to a QuickDraw GX shape.

gxShape GXConvertPICTToShape(const PicHandle pict,
                        gxTranslationOptions options, 
                        const Rect *srcRect, 
                        const Rect *dstRect, 
                        Point styleStretch, 
                        gxShape destination,
                        gxTranslationStatistic *statistics);

pict

A handle to the QuickDraw picture image to be converted to
QuickDraw GX.

options

The translation options to use for the translation.

srcRect

A pointer to the source rectangle (normally the QuickDraw picture frame) of the QuickDraw image, in QuickDraw coordinates.

dstRect

A pointer to the destination rectangle of the QuickDraw image, in QuickDraw coordinates.

styleStretch

The scale factor (both horizontal and vertical) to apply to certain items, such as dashes, in QuickDraw picture comments.

destination

A reference to the destination shape--the shape in which to store the translated picture.

statistics

A pointer to the location in which to store the translation statistics.

function result

A reference to the destination shape. This is the same shape referenced in the destination parameter, or a newly created picture shape if the destination parameter was nil.

DESCRIPTION

The GXConvertPICTToShape function provides a conversion of a QuickDraw GX picture image within the boundaries of the source rectangle srcRect to a QuickDraw GX shape within the boundaries of the destination rectangle dstRect. You pass QuickDraw picture to the translator and it returns a QuickDraw GX picture shape that approximates the original QuickDraw picture.

The srcRect and dstRect parameters represent the source and destination space of the image, expressed in QuickDraw coordinates. The relation between the source and destination rectangles specifies the amount of scaling to be applied during translation. You can use this scaling capability to ensure that the resulting QuickDraw GX shape is a good representation of the original QuickDraw object. The srcRect parameter is normally the QuickDraw picture frame of the original picture data. If scaling is not required, you can pass in the source rectangle of the original data for both parameters.

If the destination parameter is nil, a QuickDraw GX picture shape is created and returned by the function. If the destination parameter is not nil, the function returns the same shape reference that it was passed. The QuickDraw GX shapes resulting from the translation are contained in that picture shape.

The translator keeps various statistics about the QuickDraw picture data it is translating. You can examine the mask that describes these statistics after the translation if you are interested in this information. The flags in the translation statistics masks are defined in the gxTranslationStatistics enumeration. If you are not interested in this information, you should pass nil for the stats parameter.

SPECIAL CONSIDERATIONS

If you pass nil for the destination parameter and if no error occurs, this function creates a QuickDraw GX shape object. You are responsible for disposing of that object when you no longer need it.

Before using the translator, you must first call the GXInitPrinting function.

ERRORS, WARNINGS, AND NOTICES

Errors

out_of_memory

SEE ALSO

For an example of the use of this function, see Listing 1-4 on page 1-20.

To translate individual QuickDraw drawing commands as they are executed, use the GXInstallQDTranslator function, described next.

Translation options from the gxTranslationOptions enumeration are described in Table 1-2 on page 1-12.

Translation statistics flags from the gxTranslationStatistics enumeration are described in Table 1-3 on page 1-20.

For a general description of the QuickDraw-to-QuickDraw GX translator, see the section "Using the QuickDraw-to-QuickDraw GX Translator" beginning on page 1-10.

The GXInitPrinting function is described in the chapter "Core Printing Features" in Inside Macintosh: QuickDraw GX Printing.