December 96 - Macintosh Q & A
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.)*
