Macintosh Q & A

Q My application animates moving geometries in QuickDraw 3D. Recently I've been seeing a lot of screen flicker, and faces of geometries that should be behind other faces are showing through. What's going on?

A The flickering problem is probably happening because double buffering is turned off (call Q3DrawContext_SetDoubleBufferState to turn it on) or because double buffer bypass is set on the interactive renderer and the scene is taking longer than a screen refresh to render. See page 12-8 of 3D Graphics Programming With QuickDraw 3D for more information.

Your second problem is likely the result of having an excessively large difference between hither and yon (and, as a result, not having enough z resolution to resolve depth differences). Experiment with greater hither values and smaller yon values to see if the bleed-through goes away.

Q We're using QuickDraw 3D and applying UV attributes to our geometries so that we can texture-map them. There are, however, two sorts of UVs: surface UVs and shading UVs. Which one should we use to get the textures to map correctly and what does the other one do?

A At the time of this writing (QuickDraw 3D 1.5), only the surface UVs are supported. The shading UVs will be used in a future version to support advanced shading renderers.

Q What are view hints in the QuickDraw 3D metafile format (3DMF)?

A The concept of view hints was included early on in the development of QuickDraw 3D. It became apparent that the settings for determining how a scene should be rendered aren't always transportable from one application to another (for example, settings such as the camera location, lighting, and camera type). The idea of a view hint is that it sets up a series of hints that tell the reading application how the author of a metafile intended the geometries within the metafile to be rendered. The fact that these are hints implies that the reading application can ignore them.

Rather than writing out the lighting information to the metafile as absolute objects, we recommend creating a view in the normal manner, adding lighting, camera, renderer, and other information as usual, and then extracting the view hints from the view with Q3ViewHints_New(theView). You pass in a view object to this function, and it returns a view hints object that includes the view configuration for the view you pass in. The Tumbler and Podium sample code that comes with the QuickDraw 3D release illustrates how to use view hints read from a metafile to configure a view. Look in the file Tumbler_document.c for details.

Q What's the best way to do collision detection in QuickDraw 3D?

A QuickDraw 3D doesn't directly provide collision detection, but you can use the bounding boxes or bounding spheres of the geometries to determine whether the bounds intersect. You can easily calculate bounding boxes and spheres on either individual geometries or groups of geometries. If the bounds intersect, you can either assume the objects have collided or test further, depending on your application.

Q In the TQ3CameraData record, is the position of the point of interest relative to the camera location used for anything other than the view direction of the camera?

A The point of interest is an absolute position -- it's not relative to anything. As the camera's location changes, the camera "turns" to keep the point of interest in view.

Q TQ3HitData's distance field is described for window-point picking as "the distance from window point's location on the camera frustum (in world space) to the point of intersection with the picked object." Does this refer to the center of the intersection of the pixel's frustum with the hither plane, or maybe the yon plane? Or is it the camera location?

A TQ3HitData's distance field is the world space distance from the origin of the picking ray to the intersection point. Effectively, this is the distance from the camera's location to the geometry intersection point in world coordinates.

Q When I print with background printing enabled, and PrintMonitor fires up and tries to post an error, my application hangs, and no dialog ever appears. What can I do?

A Make sure the bits in your SIZE resource are set correctly. This behavior appears when you've got your "MultiFinder aware" bit set but don't have your "accepts Suspend/Resume events" bit set.

Q I can't figure out how to get the default settings for the features in a given QuickDraw GX font. Any ideas?

A A routine to do this, GXGetFontDefaultFeatures, was added after the release of QuickDraw GX 1.0. This routine will retrieve those layout features defined as default by a given font. It's fully documented in Technote 1028, "Inside Macintosh: GX Series Addenda."

Q I want to turn my font (generated with a third-party font design program) into a true QuickDraw GX font with a customized features menu. How do I do this? What programs are available for GX font design? Will I be able to add a features menu to my font after generating it with a non-GX font design program?

A For custom design of QuickDraw GX features in a font, you should use TrueEdit, which is available (along with other font tools) in the QuickDraw GX folder on the Mac OS SDK edition of the Developer CD Series.

The general process of designing a QuickDraw GX font starts with building all the glyphs you're interested in and hinting them, just as you would for a non-GX font. Once you have the glyph repertoire, use TrueEdit to add all the GX tables. You should be able to add the tables for the various menu features with TrueEdit just fine after you've built the font with another font design program.

Q I read somewhere that you don't have to call CloseOpenTransport if you're writing an application. Is this true?

A Yes and no. The original Open Transport programming documentation stated that calling CloseOpenTransport was optional for applications. There is, however, a bug in Open Transport 1.1 and earlier whereby native PowerPC applications aren't properly cleaned up when they terminate unless CloseOpenTransport is called.

Here are some rules of thumb:

• Nonapplication code must always call CloseOpenTransport when it terminates.

• It's best if 680x0 applications call CloseOpenTransport, but they'll be cleaned up automatically even if they don't.

• Make sure that PowerPC applications running under Open Transport 1.1 or earlier call CloseOpenTransport when terminating.

One way of ensuring that you comply with the third item is to use a CFM terminate procedure in your main application fragment, like this:

static Boolean gOTInited = false;
void CFMTerminate(void)
{
   if (gOTInited) {
      gOTInited = false;
      (void) CloseOpenTransport();
   }
}

void main(void)
{
   OSStatus err;
   err = InitOpenTransport();
   gOTInited = (err == noErr);

   ...   // the rest of your application

   if (gOTInited) {
      (void) CloseOpenTransport();
      gOTInited = false;
   }
}

In general, when the Mac OS provides an automatic cleanup mechanism, it's normally intended as a "safety net." It's always a good idea to do your own cleanup, at least for normal application termination.

Q I'm using OTScheduleSystemTask to schedule a task to run at non-interrupt time. Will this be cleaned up automatically when I call CloseOpenTransport?

A No. You must explicitly clean up any pending system tasks by calling the routine OTDestroySystemTask. See Technote 1059, "On Improving Open Transport Network Server Performance," for a good discussion of this.

Q How do I map Open Transport error numbers to their names?

A There are two ways to do this. The first is the OTErr MacsBug dcmd that ships with the debugging version of Open Transport. This dcmd allows you to quickly map an error number to a (hopefully) meaningful error name. Once you install it in your Debugger Prefs file, you can type, for example, "oterr -3271" in MacsBug and get the name for that error.

The second solution is to read the latest OpenTransport.h header (for Open Transport version 1.1.1 or later), where the error numbers are now spelled out in an easy-to-read format.

Q I'm writing an Open Transport server product and will be implementing hand-off endpoints. What is the maximum qlen value that limits the number of hand-off endpoints that can be implemented?

A There's a maximum qlen value for each protocol, but maximum values that are true today for Open Transport may change in the future, so we recommend that you set the qlen value to a desired value. If the desired value is greater than the number of hand-off endpoints that the underlying protocol can support, the protocol can specify its own maximum qlen value for the server endpoint. After making the OTBind call, take a look at the qlen field of the TBind structure to see whether the protocol imposed a limit on the qlen value.

Q I'm developing a plug-in (let's call it MyPlugIn) for an application (let's say CoolApp). I'd like to create a special icon for the documents my plug-in creates, but they're really CoolApp documents. However, if I add a BNDL resource to MyPlugIn, all other CoolApp plug-ins become MyPlugIn documents. What can I do?

A Just register a new, unique creator code and use that for the BNDL, but not for the plug-in. Contrary to popular belief, the owner code for a BNDL doesn't have to match the creator code of the file it's in.

Another possibility is to create custom icons for documents you create, but this has a couple of drawbacks: it takes the Finder longer to display them, and you'd be storing redundant data if the icons are all the same.

Finally, you should also add 'STR ' resources with IDs -16396 and -16397 so that the Finder can display a meaningful message if an application can't be found to open the file. (See Inside Macintosh: Macintosh Toolbox Essentials, pages 7-27 to 7-30.)

Q I'm using MPW and MacApp from E.T.O. 20. Where are the 411 help files?

A Starting with E.T.O. 20, the 411 files have been converted to QuickView^(TM) format and can be accessed through the Info menu of the MPW Shell.

Q Why is Apple now making the latest versions of MacApp available under a "release" approach, instead of the previous "product" approach?

A In response to the many messages we received from developers requesting early access to new framework features and timely support for new technologies, Apple has implemented a release approach with MacApp that allows us to get new improvements and features in our frameworks into your hands more quickly than was possible with the product approach.

Previously, our product approach required that we implement all planned features before the MacApp product was considered final. We found that this was keeping us from getting new features to you simply because other more time-consuming work was delaying the completion of the product. Under the new approach, each framework release will be made up of features at various levels of certification. Most features will be of final quality, while others may be of beta or alpha quality. You can choose the features to build your MacApp-based application with, and by doing so you'll choose the quality level of the resulting application. Our build tools will indicate the quality level you've chosen from the build flags you've passed to them. The release notes that accompany each MacApp release will list the features included in the framework and their quality status.

Over the course of multiple releases, every feature will proceed through alpha, beta, and final quality phases. Some features will move rapidly from development into final quality, perhaps in as little time as one release, while other features may require several releases. This approach ensures that the software features Apple provides to you are of the highest possible quality, while still allowing you to experiment with new, unproved features. Apple will create a new release version of MacApp approximately once every six to nine months, and the MacApp product will ship once each E.T.O. delivery cycle. Releases of MacApp that occur between E.T.O. shipment dates will be posted to the Web at http://www.devtools.apple.com/macapp/.

Note that for each MacApp release, you should always refer to the release notes for the quality status. For some releases, we recommend that you don't build applications that you intend to rely on as final-quality applications. Releases that have final-quality status are suitable for building final-quality MacApp-based applications.

Q When linking my application in MPW, I get this error message:

### Link: Error: Can't open object file for input. (Error 32)
ETO#19:Libraries:CLibraries:CSANELib.o is not an object file.

Why am I getting this message?

A If you look at the CSANELib.o itself, you'll see that it's really just a text file containing this:

The library "CSANELib.o" is obsolete beginning with the PreRelease
environment of ETO 18 and the Latest environment on MPW Pro 19.

Use the "{Libraries}MathLib.o" library instead.

"CSANELib.o" is incompatible with the SC/SCpp compilers,
and is incompatible with the new FPCE floating point model.
See the header file <fp.h> for more details.

Please read the release notes.

You may safely delete this file when you are sure that all of your
Make files have been updated.

In fact, as of E.T.O. 20, all of the following libraries are obsolete: Runtime.o, Complex.o, Complex881.o, CPlusLib881.o, CPlusOldStreams881.o, CPlusOStreams.o, CSANELib.o, CSANELib881.o, Math.o, Math881.o, AppleScriptLib.xcoff, CPlusLib.o, InterfaceLib.xcoff, MathLib.xcoff, ObjectSupportLib.xcoff, QuickTimeLib.xcoff, SpeechLib.xcoff, and StdCLib.xcoff. These "libraries" are now text documents, similar to the above. Each of them contains information about the libraries you should use instead.

Q I understand how to use PrGeneral with the getRslDataOp opcode to get the resolutions that a printer supports, but when I ask the LaserWriter driver about resolutions, it always tells me I'm talking to a 300 dpi printer, even when I know the printer is, say, 600 dpi. I want to print at the maximum resolution available. How can I do that?

A Currently, the LaserWriter driver always returns a range of 25 to 1500 dpi for valid resolutions, and a fixed resolution of 300 dpi. The range of 25 to 1500 means that your application can ask for any resolution in that range, and the driver will allow it, as explained in Technote PR 07, "PrGeneral." However, given that LaserWriters and other PostScript printers can support only a limited number of resolutions, you may not get optimal results if you pick the wrong resolution for a printer, even if the driver lets you. You'll also end up sending more data than is needed if you're generating bitmaps at a higher resolution than the printer can print, which can slow printing down significantly. Furthermore, some extremely high-resolution devices may be able to print at a resolution higher than 1500 dpi, but the range returned by PrGeneral was chosen quite a while ago and hasn't been changed for application compatibility reasons.

Currently, the only way to get the actual resolution(s) supported by a PostScript printer (short of querying the printer directly) is to ask the LaserWriter driver for the PPD file and parse it yourself, looking for the valid resolutions. To get the PPD file, call PrGeneral with the PSPrimaryPPDOp opcode, which is 15. This is documented in the Macintosh Technical Q&A QD 01, "PPDs." When Apple makes the functions in LaserWriter 8.4's PPD Library public, you'll also be able to use those functions to get the information from the PPD, but the API to that library hasn't yet been made available as of this writing.

To parse the PPD file, you'll need to consult the PPD specification maintained by Adobe. That document can be found at Adobe's ftp site, at the location ftp://ftp.adobe.com/pub/adobe/devrelations/devtechnotes/psfiles/.

Rather than go to all that work, however, a better approach might be to change your code so that you don't need to know the printer's resolution in order to generate high-quality output. Some of the various ways to solve this problem are listed below; the approach you take will depend on your application requirements. Also, see the Print Hints column in this issue of develop, which discusses this very problem (among others).

• If your application is such that you require a PostScript printer, you could generate your own PostScript code to achieve high-quality results.

• You could generate your own PostScript code but also use a QuickDraw representation so that images will print correctly to StyleWriters and other QuickDraw printers. This solution is recommended if you're writing a program that draws curves, such as a graphing program. For best results, break down the curves you need to draw into small portions that can be accurately represented by the QuickDraw primitives you have at your command.

• You could use QuickDraw only, but draw in such a way that you'll get high-resolution results. To do this, use objects such as lines, ovals, and arcs rather than bitmaps. The endpoints of the objects will be limited by the resolution at which you draw, but the objects will be drawn at device resolution.

Q I noticed that several QuickTime Music Architecture routines (TuneResume, TuneFlush, TuneGetState) are missing in the latest headers. What gives?

A The routines TuneResume, TuneFlush, and TuneGetState were poorly defined, and in fact were unimplemented in QuickTime 2.0 and 2.1. They've been removed from the headers.

Q _StuffXNoteEvent, a QuickTime Music Architecture macro, has vanished from the latest headers. Why?

A Whoops. A mistake was made, and _StuffXNoteEvent didn't make it into the final release header. You can copy the macro from the older header file if you need it, but for consistency you should rename it qtma__StuffXNoteEvent. Here it is as well:

#define qtma_StuffXNoteEvent(w1, w2, instrument, pitch, volume, \
        duration) \
   w1 = (kXNoteEventType << kXEventTypeFieldPos) \
   |   ((long)(instrument) << kXEventInstrumentFieldPos) \
   |   ((long)(pitch) << kXNoteEventPitchFieldPos), \
   w2 =   (kXEventLengthBits << kEventLengthFieldPos) \
   |   ((long)(duration) << kXNoteEventDurationFieldPos) \
   |   ((long)(volume) << kXNoteEventVolumeFieldPos)

Q Why did the old _EventLength(x) macro get split into two macros, qtma_EventLengthForward(xP, ulen) and qtma_EventLengthBackward(xP, ulen)?

A _EventLength(x) had to be changed because of some new event types. We needed separate macros to determine the length from the first long word of a music event and from the last one. Typically, you'll be using qtma_EventLengthForward.

Q Inside Macintosh: QuickTime Components states that the limit on data transfer rates for the base media handler (and therefore all media handlers derived from it) is 32 kilobits per second. Is that true?

A Starting with QuickTime 2.0, when the data handler API became publicly available, that statement is no longer accurate. In fact, QuickTime imposes no limitation on performance at all; the hardware you're using is the only limiting factor.

Q I heard at Apple's Worldwide Developers Conference last May that the QuickTime for Windows installer can be customized through a ".INI" file. Where can I get more information about this?

A Following is the format for the optional configuration file that can be used with the installer for QuickTime for Windows version 2.1.2. If used, the file must be named QTINSTAL.INI, and it must be located in the same directory as the installer, QTINSTAL.EXE. (The 32-bit installer is called QT32INST.EXE, and the corresponding ".INI" file must be called QT32INST.INI.)

For all of the options listed except DialogStyle, a value of 1 enables the option and a value of 0 disables it. The default for all values is 1, unless otherwise noted. Although all combinations of options are designed to work (that is, the program will run correctly), not all combinations will yield a viable result. For example, creating a program group without unpacking the files would probably not be a good idea.

; All QTW installer options must be in the following section:
[Options]
; The QuickTime background can be suppressed when QTINSTAL is to be 
; called from another program:
;   1 - shows a background window with QuickTime banner.
;   0 - shows no background window.
StandAlone=1
; A Dialog style may be specified by one of the following values:
;   1 - Thin frame
;   2 - System menu
;   3 - Thin frame and system menu (default)
DialogStyle=3
; If the following option is set, the client area of all dialogs will
; have a 3-D look.
Ctl3D=1
; If the following option is set, the installer will display the QTW
; end-user license agreement, with Agree/Disagree buttons.
DisplayLicenseAgreement=1
; If the following option is set, an opening dialog will prompt the
; user whether to begin the installation or to exit.
PromptToBegin=1
; If the following option is set, existing-version checking will be 
; enabled and the installer will evaluate the PromptToDeleteVersions
; option.  If CheckExistingVersions is set to zero, the installer
; will not check for existing versions.
CheckExistingVersions=1
; If CheckExistingVersions and the following option are set, the 
; installer will prompt the user before doing a search operation for
; all out-of-date QTW installations on the machine.  For each
; installation found, a dialog will ask the user whether to mark it
; for deletion.  If this option is set to zero, the search will be
; unconditional and all installations found will be marked for
; deletion.
PromptToDeleteVersions=1
; If the following option is set, a "do you want to continue" dialog
; will appear before any files are deleted or the hard disk is
; modified in any way.
PromptToComplete=1
; If the following option is set, all files will be unpacked from the 
; executable and written to disk.  Care and consideration should be
; used before setting this option to zero, since a zero value means
; no files will be installed.
UnpackFiles=1
; If the following option is set, the Windows INI files will be
; updated.
UpdateIniFiles=1
; If the following option is set, Program Manager groups will be
; created.
CreateGroups=1
; If CreateGroups is set and the following option is used, the
; specified name will be used as the group name (that is, the name;
; as it displays in the window titlebar, not the group filename)
; that the installer will use when installing the QuickTime icons.
; For example, the option shown would use the group name "My Group."
; If the group does not exist it will be created.  This option can
; be used to add the QuickTime applications to an existing group
; file.  The string used to specify a group name should be tested
; in actual use, since there is a practical upper limit to the number
; of characters Windows will use in a window title.
GroupName=My Group
; If the following option is set, a success dialog will indicate
; whether the installation has completed successfully.
SuccessDialog=1
; If SuccessDialog and the following option are both set, the
; installer will launch Movie Player with a sample movie to verify
; that QTW has been installed successfully.
PlaySampleMovie=1
The Installer also always creates a file in the Windows directory
called RESULT.QTW that looks like this:
[QTW Install 16]
Complete=1
[QTW Install 32]
Complete=1

If Complete equals 0, the installation didn't finish for some reason (any reason, such as the user canceling, or running out of disk space, or whatever). This enables the title installer to tell whether the QuickTime for Windows installation was successful and to respond appropriately.

Q I'm playing four QuickTime movies simultaneously from a Director project. Each movie has a single music track with no other video or sound tracks, and two of the movies use more than one instrument. The Director project lets the user control the volume level of each movie independently. The application works great on the Macintosh with QuickTime 2.1, but under Windows with QuickTime 2.11 only one music track plays at a time. Is it possible to hear all four music tracks at once under QuickTime for Windows 2.11?

A You can do live mixing of your four QuickTime movies only if your Windows system has four MIDI output devices. Most systems have only one. All Windows applications suffer from this limitation unless they're clever enough to mix the tracks on the fly, but none seem to do this.

For now, you must pre-mix the four music tracks from the four movies into one music track in one movie. You won't be able to do live mixing unless you write your own MIDI sequencer.

Q Why do my eyes water when I chop onions?

A Onions contain sulfur compounds, and when you cut into them they release sulfur dioxide. When the sulfur dioxide gas dissolves in your tears (which are mostly water), sulfurous acid is produced: SO2 + H2O --> H2SO3. The acid burns your eyes, which respond by generating more tears in an attempt to flush away the acid. See http://www.superscience.com/onions.html as well.

---

These answers are supplied by the technical gurus in Apple's Developer Support Center. For more answers, see the Technical Q&As on the World Wide Web at http://www.devworld.apple.com/dev/techqa.shtml. (Older Q&As can be found in the Q&A Technotes, which are those numbered in the 500s.)*