Macintosh Q & A

Q How do I determine whether a Power Macintosh has PCI expansion slots?

A If there's a Name Registry, you can use it to determine whether a PCI bus exists. To determine whether the Name Registry exists, use the new Gestalt selector gestaltNameRegistryVersion ('nreg'). If the Name Registry exists, the value returned is the version number of the Registry; otherwise, gestaltUndefSelectorErr is returned, and you can assume that the machine doesn't have PCI slots.

If the Name Registry exists, call RegistryEntrySearch to look for an entry having a property name of device_type and a propertyValue of pci. If an entry is found, there is a PCI bus on the machine.

Q Our software doesn't awaken properly on a PowerBook that has come out of sleep mode. Are there any special handling requirements to recover from sleep mode?

A The changes to the system state when a PowerBook goes to sleep include the following:

• All AppleTalk connections are lost, because the AppleTalk driver is turned off.
• The serial ports are entirely shut down to conserve power.

There are two Macintosh Technical Notes that relate to your situation: "Little PowerBook in Slumberland" (HW 24), which provides a brief overview of the sleep process, and "Sleep Queue Tasks" (HW 31), which presents additional material regarding the sleep process. The second one includes sample code that demonstrates a sleep queue task implementation. The sleep queue task enables your program to save state information that otherwise might be lost. Typically, this is important for a networked process that needs to reestablish a connection upon awakening.

Q Can we define our own extensions to QuickTime's ImageDescription structure? In other words, can we just attach any kind of data to the end of the ImageDescription structure? Our codec would use this data only on the Macintosh.

A Yes, you can add any extended data you like, with the utility routines provided for this purpose (described in Inside Macintosh: QuickTime Components, starting on page 4-65). You have complete control over how your codec interprets the extensions. Therefore, as long as the default image description handle remains intact (for the benefit of the various Movie Toolbox calls that depend on the documented structure being there), you can add whatever information you like. Note that Apple reserves all extension types consisting entirely of lowercase letters.

Q We're trying to write a QuickTime codec, but we're having trouble because Inside Macintosh: QuickTime Components was written before the universal headers, and the sample codec source doesn't build at all with the latest headers. Where can we get a QuickTime codec that builds for PowerPC under the current universal headers?

A Until a PowerPC-native codec example becomes available, you can get the information you need from the Macintosh Technical Note "Component Manager version 3.0" (QT 5), which provides details on creating native components. Note that you have to use Resorcerer or Rez to create the component templates; ResEdit won't suffice.

Q Our codec needs to provide more options to the user than the normal image-compression dialog contains. The documentation suggests that it's possible to provide an extra Options button in the dialog, and I've seen some applications that do provide an Options button for certain codecs. Is this a function of the application? How does the application know to do this?

A If your codec component has an exported function named CDRequestSettings, the standard image-compression dialog will automatically provide the specific button. In other words, QuickTime checks the codec component, adds the button (provided it's available), tracks clicks in the button, and calls your CDRequestSettings routine appropriately. For further details, see the Macintosh Technical Note "QuickTime 1.6.1 Features" (QT 4) where CDRequestSettings is documented.

Q We have a non-Macintosh device that creates and reads QuickTime movies, and we need to pass additional information about the images between the non-Macintosh device and our QuickTime codec. It seems that the logical place to put this information is in an ImageDescription extension (within the sample description atom), since this is about all that's accessible to a codec. Is the format of this extension documented anywhere? We've looked at the extension created by SetImageDescriptionExtension, and the format seems simple, but it would be nice to know what the "official" format is.

A Chapter 4 of Inside Macintosh: QuickTime has a listing of the atoms and their formats. Sample description atoms are described on page 4-35. Note that each media format has its own sample description tables, which are not directly accessible.

The official guideline is to use, if possible, the provided APIs for creating sample description atoms. If you're working on a platform for which there are no Toolbox APIs, you'll have to obtain a source-code license agreement to get real source code showing how the atoms are constructed. (For details regarding licensing part or all of the QuickTime source code, contact Apple Software Licensing at AppleLink SW.LICENSE or (512)919-2645.)

Q Our application plays QuickTime movies. Some older movies played well in System 7.1, but they don't play properly in System 7.5 or 7.5.1. We happened to find the Apple Multimedia Tuner, and it solves the problem. What is the Apple Multimedia Tuner, who needs it, how does a customer get it, and can we distribute it?p> A The real solution to your problem is just to preroll the movie before playing it, which is what the Apple Multimedia Tuner is doing for you. QuickTime 2.1 incorporates all the Tuner improvements, so there's no longer any need to distribute the Tuner separately.

Q We have a problem when we draw to an offscreen GWorld under low-memory conditions (when the system heap can't grow) on a Power Macintosh. The GWorld drawn contains digital noise. The same code works just fine in an 680x0 environment. Any idea what's happening?

A It sounds as if the Code Fragment Manager is unable to load the code from the PowerPlug library into temporary memory. This will cause QuickTime to issue a noCodecErr error. You should always try to catch QuickTime-generated errors, checking, for instance, for playback errors after each MoviesTask call like this:

anErr = GetMoviesStatus(Movie theMovie, Track *problemTrack);

Here's a possible workaround to your problem: Launch a small application that has the QuickTimeLib (PowerPlug) library statically linked in, so that it's loaded. This application should launch the main application and then kill itself. The second application could try to grow to a predefined size and handle low-memory conditions in whatever way it wants, but the CFM libraries are already in memory by then.

The Code Fragment Manager will never load fragments into an application heap, because there's a global registry of CFM libraries present. If another application registers to use a CFM library that's in an application heap that subsequently goes away, this will obviously be a Bad Thing. In the 680x0 environment, the codecs are components, and the Component Manager will always try to load components into the application heap if the system heap doesn't have any available space.

Q I need to add print items to a QuickDraw GX dialog box. In attempting to use the Experiment no.9 sample, I found what appears to be a bug. This example uses GXGetMessageHandlerResFile when it calls GXSetupDialogPanel, but it should call CurResFile.

A You're right. Applications should call CurResFile. GXGetMessageHandlerResFile is reserved for extensions and drivers.

For additional code examples that add print items to a QuickDraw GX dialog box, see the Worldwide Developers Conference 1995 Technology CD (or the Mac OS Software Developer's Kit). The Extension Shell, UserItems, and Additions samples provide the basic item adding/handling code that you require.

Q Where can I find some good sample code that demonstrates the techniques required for a "panel" with QuickDraw GX printing (as an application -- not an extension)?

A There are two sample applications ("Experiment no.9" and "Banana Jr.") that show how to do this. In both of these applications, the panels appear in the Custom Page Setup dialog. However, the sample code can easily be modified to add panels to the Page Setup and Print dialogs.

Q How can I draw and print hairlines with QuickDraw GX? We use a picture comment in the normal print code, but this seems to make QuickDraw GX fail. We get a -51 error (reference number invalid) when we call GXGetJobError after calling GXFinishJob, and we sometimes get this error without the picture comment code.

We also tried calling GXSetShapePen in our spool procedure. When we set it to a fractional value, we get a wide line, but when we set it to a wide value, such as 8, it works properly. What do we need to do to print fractional widths?

A Here are two ways to get QuickDraw GX to draw hairlines when printing:

• Call GXSetShapePen(myShape, 0). This sets your pen width to 0, meaning as thin as possible on the output device. QuickDraw GX always draws hairlines at the resolution of the output device -- one pixel wide.
• Call GXSetStylePen(myStyle, 0). This also sets your pen width to 0, with the same result.

When using GXSetShapePen and GXSetStylePen, don't specify the pen width as an integer: remember that it's a fixed-point value. GXSetStylePen(myStyle, 1) sets the pen width to 1/65536; GXSetStylePen(myStyle, ff(1)) sets it to 1.0.

QuickDraw GX uses a backing store file (an invisible file within the System Folder) to send QuickDraw GX objects to disk when additional space is needed within the QuickDraw GX heap. Almost all -51 errors from within QuickDraw GX or an application using QuickDraw GX are caused by double-disposing of a QuickDraw GX object (that is, a shape, ink, style, or transform). The -51 error occurs because the double dispose causes QuickDraw GX to set the shape attributes, which indicates that it has sent the object to disk. When it needs this object, it goes to the backing store and tries to get it, but it's not there. We've found a few cases where QuickDraw GX itself was double-disposing of objects, and these were fixed in QuickDraw GX version 1.1.

Before calling GXDrawShape, call GXValidateShape on the shape or shapes you're trying to print. This ensures that a shape is valid before it's drawn or printed. It slows things down a little, but you'll be able to determine whether a shape is still available before you attempt to draw it (you might be disposing of a shape before you draw it). If you have an error handler installed, you usually receive the "shape_already_disposed" message, but you may not receive this message if something is wrong with the QuickDraw GX backing store.

It's also possible that the hairline drawing problems you're encountering are related to the translation options you're using. A translator takes your QuickDraw drawing commands and converts them to QuickDraw GX objects, based on options you provide. If you use the gxDefaultOptionsTranslation setting, a QuickDraw line turns into a six-sided filled polygon. When your object is a polygon, changing the pen width has no effect.

To avoid translation problems, call GXInstallQDTranslator with the gxSimpleGeometryTranslation or the gxReplaceLineWidthTranslation option.

• gxSimpleGeometryTranslation turns on both the simple-lines and simple-scaling translation options, and it translates QuickDraw lines into QuickDraw GX lines with flat endcaps. The QuickDraw GX line shape runs along the center of the original QuickDraw line, and it covers all the pixels of the QuickDraw line and more.
• gxReplaceLineWidthTranslation turns a QuickDraw line into a QuickDraw GX line with a width that is the average of the original pen's width and height. This option also affects the way the SetLineWidth picture comment is interpreted.

Once you set the translation option, your calls to GXSetShapePen or GXSetStylePen should behave as you expect them to, because they're acting on QuickDraw GX lines, not polygons. When you've installed a translator, be sure to remove it with GXRemoveQDTranslator. To learn more about the translation options, see Chapter 1 of Inside Macintosh: QuickDraw GX Environment and Utilities.

Q I'm trying to send messages from within a QuickDraw GX message override. I want to send GXWriteData to flush the buffer so that I can send the GXGetDeviceStatus message. I override the GXHandlePanelEvent message. In my override, sending messages causes the system to crash. What would cause this to happen?

A The crash is occurring because there's no connection to the printer at the time you're sending the message. You have to send the GXOpenConnection, GXWriteData, and GXCloseConnection messages. Note that when you send GXOpenConnection, QuickDraw GX puts up the default job status dialog for a short time. If you don't want this dialog to appear, you can override the GXJobStatus message to prevent it from being shown. See also Dave Hersey's Print Hints column, "Writing QuickDraw GX Drivers With Custom I/O and Buffering," in develop Issue 21.

Q I used the sample driver showing how to do custom dialogs as the basis for the compatibility part of our QuickDraw GX PostScript driver, and I added an Options dialog to it for our printer-specific features. I have two problems with it when using applications that aren't QuickDraw GX-aware. First, the paper-type always defaults to the fifth paper-type listed in the resource file, so whichever paper-type is the fifth one listed becomes the default paper-type in the QuickDraw GX compatibility driver. This is, of course, reflected in the Page Setup dialog. Second, the driver always defaults to having the "Print to File" checkbox on. What can I do about these problems?

A Both the quirks you describe (improper default paper-type and the "Print to File" checkbox defaulting to on) can be fixed by modifying the 'PREC' 0 resource in the driver.

When an application using old-style printing calls PrintDefault to request the default print record from the current printer driver, the driver gives it the contents of the 'PREC' 0 resource. Then, when the application calls PrJobDialog or PrStlDialog, it passes in that print record. In its overrides, the QuickDraw GX printer driver interprets the contents of the old-style print record to set up the states of the dialog's buttons, checkboxes, and so on.

To determine which paper-type radio button to select in the Page Setup dialog, QuickDraw GX compares the page rectangle specified in the old-style print record to the rectangles of all the paper-types in the driver (or paper-type extensions, such as "3-Hole Punch"), and tries to find the best match. Because of the way that the old-style print record in the sample is defined, that best match turns out to be the fifth paper-type in your list. So, to fix this quirk, all you have to do is change the bounds setting in the 'PREC' 0 resource so that it matches the bounds of the US Letter paper-type in the driver.

To determine the state of the "Print to File" checkbox, the driver looks at the UlOffset field of the old-style print record. (You might not think to look here, but old-style print records are limited to 120 bytes, and there was no better place to store this information.) Because the 'PREC' 0 resource in this driver has this field set to 1, the checkbox defaults to on. So, to fix this, all you have to do is set the field to 0.

Q I want to create an extension for the Page Setup/Format dialog that performs "flipping" functions. Is it feasible to create an extension for the Page Setup/Format dialog rather than the Print dialog?

A There's nothing to prevent you from creating an extension that adds a panel to the Page Setup dialog. Most printing extensions add to the Print dialog because in most cases this is the proper place to add a panel that affects the entire output, and because what extensions usually do is best suited for the Print dialog. Drivers and applications, on the other hand, typically add to the Format dialog. Note that if you're trying to modify an existing sample extension so that it adds to the Page Setup dialog, you have a bit of work to do.

There's a way that you can test your flipping code without writing a new extension, by the way. Applications can override the GXJobDefaultFormatDialog or GXFormatDialog message. There are two examples ("Experiment no.9" and "Banana Jr.") that demonstrate overriding GXFormatDialog. You might try adding your flipping code to one of these.

Q A car passed me the other day with one of those round white country stickers that said WAL. Where was it from?

A Sierra Leone.

Q In QuickDraw 3D, when we have the interactive renderer on and we try to turn off the draw context's clearImageMethod (setting it to kQ3ClearMethodNone), it still clears. This works properly with the wireframe renderer, but we need this feature in the interactive renderer, since we're pasting in background pictures that we want to act as a backdrop to our 3D models. The interactive renderer always obliterates the background with the clearImageColor. What can we do?

A Unfortunately, this is a renderer-dependent feature that's supported by the wireframe renderer, but not the interactive renderer. We intend to provide a "Clear with picture" method in the next major release of QuickDraw 3D (version 1.1).

Q The interactive renderer doesn't draw flat surfaces that are parallel to the camera view direction with the orthographic camera, but the wireframe renderer does. We put in a "floor" of polygons, and when we look along the edge of the floor with the orthographic camera, it totally disappears. With the wireframe renderer, we see a line where the floor is, which is as expected. What gives?

A Filled primitives have no thickness, so when you look at them edge-on, they do not appear. Lines, however, are a mathematical abstraction, so they always appear to be one pixel thick (when you zoom in on a line, its thickness doesn't increase). While this may seem somewhat odd, it's the way many libraries work. To achieve the effect you want, make the floor a thin box, and texture-shade the top surface. If the depth of the box is nonzero, it appears to be a slab-like structure, and it won't disappear when viewed edge-on.

Q If we iterate through the vertices in a mesh, will the vertices still be in the same order as they were when they were added?

A Yes. The ordering of the vertices doesn't change until you duplicate the mesh or write it out. A duplicated mesh (or one that was written out and read back in) doesn't necessarily have the vertices in the same order as when they were added.

Q When I try to render models with different types of lights, the point light and the directional light work correctly, but the spot light doesn't. Any idea why?

A The spot light's cone of light needs to touch a number of vertices for any effect to be seen. If the light is attenuated, it may have insufficient intensity when it strikes the surface. The cone of light also needs to be wide enough to cover a significant area of the object being modeled for the renderer to draw a reasonable effect.

Q What effect does the TQ3ViewObject parameter have in the bounding box calculating routines (Q3View_StartBoundingBox and Q3View_EndBoundingBox)? The old geometric-object routine descriptions refer to world space, but if this is so, there's no need for a view parameter. However, if the view's camera is used, the bounding box is returned in camera coordinates rather than view coordinates. Since both are useful, would it be possible to have both sets of routines available? I can apply a rotation/translation matrix to all of the items to be drawn to generate camera coordinates from a world coordinate routine, but I need to find out if I need to do this or if this has already been accomplished.

A The QuickDraw 3D routines return the bounding box or bounding sphere in local coordinates. Part of the reason that the API was modified to use submit calls, rather than having separate picking, rendering, and writing calls, is that the transformations that are applied matter more than the camera. Since these modifications were made, the submit calls for everything (including transformations, if they're not stored in the group) can be in one submission function that's called from inside the picking, rendering, or writing loop. If you need the bounding box for a single geometry in its own coordinate space, this is also easy to do -- you can write a simple routine that performs bounds calculations on a single object. For example:

Q3View_StartBoundingBox;
Q3xxx_Submit;
Q3View_EndBoundingBox;

Q Does QuickDraw 3D prefer meshes or NURB patches? Which kind of data yields better performance?

A Meshes are convenient for editing, but they take quite a bit of memory, so the tradeoff is time versus space. NURB patches are more convenient for dealing with surfaces as a whole and for representing surfaces at different tessellations.

Although meshes exhibit better performance than NURB patches in the first version of QuickDraw 3D, later versions may have improved patch performance. In the meantime, consider experimenting with the tessellation factor for your patches, since overtessellating reduces performance.

Q I'd like to make sure that I'm running under version 1.0.2 of QuickDraw 3D. When I get the version from Q3GetVersion the major version is 1 and the minor version is 0, but I can't get the revision (the third number). Is there a Gestalt selector for this?

A Starting with version 1.0.2, there is a Gestalt selector to get the version of QuickDraw 3D: gestaltQD3DVersion. The return value has two bytes for the major version, a byte for the minor version, and a byte for the revision. So for version 1.0.2 Gestalt will return 0x00010002. Note that this Gestalt selector works only with QuickDraw 3D 1.0.2 and later.

Q The ColorSync documentation (in the reference section of Inside Macintosh: Advanced Color Imaging) states that each color component in the L*a*b* color space is within the range of 0 to 65,280. Shouldn't this be 0 to 65,535, since this is the value for the other spaces and the value in the ICC Profile Format Specification?

A No. The correct maximum value for this particular color space is 65,280 (0xFF00). Note that the final documentation is now available as Advanced Color Imaging on the Mac OS, published by Addison-Wesley.

Q What exactly are the internal parameters for the ColorSync quality settings? That is, how large a lookup table is built for "draft" versus "normal" versus "best"?

A The quality flag bits provide a place in the profile for an application to indicate the desired quality of a color match (potentially at the expense of speed and memory). In ColorSync 2.0, these bits do not mandate the use of one algorithm over another, or one lookup table size over another; they're just recommendations that a particular CMM may choose to ignore.

Let's look at how the default Apple CMM uses the quality recommendations specified in the flag bits. Other CMMs, of course, will have different implementations.

When Apple's CMM builds a color world from two or more profiles, and one or more of these profiles contain TRC curves or A2Bx tables, the CMM also builds a private, multidimensional lookup table. The quality flag bits determine the resolution of this private table. Draft quality is treated the same as Normal quality, so there are really only two effective settings, Normal/Draft and Best. In most cases, the quality is only slightly better in Best mode, so the difference is difficult to see, unless one of the profiles has a high gamma value. For high gamma values, the extra resolution in the lookup table is helpful.

Best mode typically takes twice as long to build a color world (about two seconds, versus one second in Normal/Draft mode). However, once the color world is built, the time to use it is the same for either mode (approximately 1.5 MB/second on a Power Macintosh 8100/110).

Best mode also requires significantly more memory than Normal/Draft mode. A color world typically requires 120K of heap space in Best mode versus 25K in Normal mode, and the "high-water" memory requirement while a color world is being built is typically 300K for Best mode versus 90K for Normal mode.

Note again that these guidelines apply only to the default Apple CMM. The tradeoffs between speed, quality, and resources may be quite different for other CMMs.

Q I want to go directly from an input CMYK space to an output CMYK space (without going through an intermediate three-component space) to preserve the original GCR/UCR settings. Can I create a "link" profile for this purpose? If I do, will I have to write my own CMM to use it?

A You can build a CMYK-to-CMYK device-link profile for this purpose, and you can use it without writing your own CMM.

Q I'm using the ColorSync call CWCheckBitMap to do gamut checking in a plug-in for Photoshop. The result bitmap is not what I expected, and seems to be different every time I try it. Any idea what could be going on?

A CWCheckBitMap sets each pixel in the result bitmap to black if the corresponding pixel in the source bitmap is out of the gamut. It doesn't, however, set each pixel in the result bitmap to white if the pixel in the source bitmap is in the gamut. If you aren't erasing the bitmap before calling CWCheckBitMap, that would explain what you're seeing. Always erase the result bitmap to white before calling CWCheckBitMap. (This is also true of CWCheckPixMap and CWCheckColors.)

Q If I have a physical drive ID, how can I determine whether that drive is a network volume? I'm not sure where to look, and I need to know whether the information is dependable and not subject to change.

A Under the current Macintosh file system, there's no completely dependable way to determine whether a volume originates over a network or is implemented on a local disk. This is the result of the way external file systems are implemented -- a third party can build a network file system in a variety of ways.

You can, however, easily determine whether a volume uses the AFP (AppleShare) file system, which in many cases is adequate. To make this determination, compare the driver refNum in the drive queue entry to the AppleShare client's refNum.

The following code enumerates the drive queue and displays the relevant information:

main()
{
   QHdrPtr      drvQHdr = GetDrvQHdr();
   DrvQElPtr   dqeP;
   short         afpRefNum = 0;
   OSErr         errNo;

   // Get the driver refNum for AFP. 
   errNo = OpenDriver("\p.AFPTranslator", &afpRefNum);
   if (errNo != noErr)
      return

   // Scan each drive in the drive table.
   dqeP = (DrvQElPtr) drvQHdr->qHead;
   do {
      // Is it an AFP volume or SCSI device?
      if (dqeP->dQRefNum == afpRefNum) printf("AFP");
   } while (dqeP =(DrvQElPtr) dqeP->qLink);
}

For other third-party file systems, such as DECNET and NFS, you have to determine the name of the driver and then compare it to the AppleShare client's refNum.

Q I need to get a list of files in a particular directory. Should I use PBCatSearch, or should I use indexed PBGetCatInfo or PBGetFInfo requests?

A The "Cat" in PBCatSearch stands for "Catalog" and that's what PBCatSearch searches: the whole volume catalog. You can specify that matches found by PBCatSearch be limited to a specific directory by setting the fsSBFlParID bit in the ioSearchBits field of the parameter block, and then specify the directory to match on by setting ioFlParID in ioSearchInfo1 and ioSearchInfo2 to the directory ID you're interested in. However, PBCatSearch may not be what you want to use, for a couple of reasons:

• The matches PBCatSearch finds by matching based on ioFlParID are only in that one directory, not in any of that directory's subdirectories.
• Because the whole catalog file is searched, this is usually not the fastest way to look through a specific directory's contents.

If you need matches in both the directory and its subdirectories and you don't want to search the whole volume, there's a routine in the MoreFiles sample code named IndexedSearch that's compatible with PBCatSearch's parameter blocks, except that IndexedSearch lets you specify what directory you want to search. It uses indexed PBGetCatInfo calls to search a directory and its subdirectories.

If you need matches from only a single directory (and not from that directory's subdirectories), you can use the MoreFiles routine named GetDirItems. This routine uses PBGetCatInfo to index through a directory's entries and returns FSSpecs to the entries found. In this case, making indexed PBGetCatInfo calls is much faster than searching the whole catalog with PBCatSearch.

Q I need to nest two CustomGetFile dialogs, but I'm running into trouble. Under some circumstances after the user dismisses the second dialog (usually via the Cancel button), I lose all of the custom controls in the first dialog. What's happening?

A The Standard File Package is not reentrant, so there really isn't a way to nest standard file dialogs that will work right. The real problem is in the resources that the Standard File Package uses for the dialog items. When the second, nested dialog closes, it releases resources that the first dialog is still using; that's why your items are getting messed up.

There's a kludgy workaround, but it will break under future systems. You could, however, use sequential calls to the Standard File Package instead of nesting them. This is a bit of a pain, but should accomplish what you want. Here's how: Put up the first dialog. In your filter routine, when the user clicks the control that is to bring up the nested dialog, set a flag in your application signifying "bring up other," and tell the Standard File Package that you're done with the first dialog by passing item 1 or 2 back. After you put up the second dialog and process it, bring the original dialog back. This will be a little messy cosmetically as the dialogs open and close, but it's the only way to do it in a manner that will remain compatible.

Q What's the best way to remove an attached leech?

A The best way we know of is to rub a freshly cut lemon or lime on it. Most leeches will detach immediately, and die a writhing, horrible death shortly afterward. Fire and salt are also said to be effective.

These answers are supplied by the technical gurus in Apple's Developer Support Center.

Have more questions? See the Macintosh Technical Q&As on this issue's CD. (Older Q&As can be found in the Macintosh Q&A Technical Notes on the CD.)