æ








							
							QuickDraw» 3D Release Notes for Version 1.5.3

Wireframe Renderer: Clipping error

The WireFrame renderer would occasionally render incorrectly or crash, if the frame contained geometric primitives which stretched from in front of the camera to behind it.


Interactive Renderer:  Clipping error

If the hither and yon planes specified in the camera setup differ too greatly, the Interactive renderer occasionally clipped incorrectly, or would crash. Crashes have been eliminated in such situations; however, excessive differences between the hither and yon values may still cause parts of primitives to fail to be drawn. 

To alert applications to situations in which they have set the hither and yon planes too far apart, a warning has been added to the camera API calls (debug library only) that such a condition exists.

Application developers should take care to heed these warnings, or there will be a risk of non-display of some primitives (depends upon position of the object within the viewing frustum, etc.)


Picking: Window point pick sometimes missed

A window point pick could sometimes not return a pick hit on a geometric primitive that clearly should have been hit. This may have been particularly severe with cones, cylinders, ellipsoids, and tori.


Mesh: Performance optimization

For purposes of rendering, the mesh primitive is converted to a simpler type. This conversion may have happened more often than necessary, in some fairly common situations. The conversion function has been modified to avoid excessive re-conversion when appropriate, which may lead to a significant performance increase in affected usage scenarios.


Cylinder: Performance optimization.

For purposes of rendering, the faces of cylinder primitives were decomposed into a grid of quadrilaterals.  This resulted in a larger data footprint as well as non-optimal rendering and picking performance. Now, the cylinder is decomposed into a number of quads, each of which stretch from bottom to top. Note that this is the case even for uniform subdivision where the v-direction subdivision is specified as other than 1.


Draw Context: Per-frame overhead optimization

The per-frame overhead due to draw context setup has been significantly reduced. This will be most noticeable in less complex frames, for whom setup is not dwarfed by rendering proper.


MacDrawContext: Panes, masks, clip regions, and SetOrigin()

Prior to 1.5.3:

1.  Clip regions were ignored.
2.  SetOrigin() calls were ignored.
3.  Panes had to be entirely contained inside the window.
4.  Various other bugs existed, which resulted in a variety of visual artifacts in some circumstances.

All of these known bugs and shortcomings have been fixed:
1.  Clip regions are always honored.

2.  Since SetOrigin was being ignored, when an application that used SetOrigin() created a MacDrawContext in a pane, the image would not appear where they expected.  As a work around for this problem, some developers would adjust the coordinates of the pane to compensate.  This causes a problem for backwards compatibility.  If QD3D honors SetOrigin() the pane  will again be in the wrong place for these applications that used this work around.  To solve this problem, new applications that want SetOrigin() to be honored should set the field library in TQ3MacDrawContextData to kQ3Mac2DLibraryQuickDraw.  They must also set the field grafPort to the window that contains the draw context.

When library is set to kQ3Mac2DLibraryNone, SetOrigin() calls are ignored; this is to keep backwards compatibility with applications that used the above work around.

When library is set to kQ3Mac2DLibraryQuickDraw, SetOrigin() calls are honored. Also, grafPort must be set instead of window.

3.  Panes can now lie partly or entirely outside of the window.

4.  Various other bugs have been fixed.


Windows:  No way to weak link against the QD3D DLLs

The solution was to create a static link library that loads the QD3D DLL at Q3Initialize time and name binds against the functions. If the libraries are not present then an error is returned. The developer then links aginst this libarary instead of the QD3D libs. This libarary is distributed with the SDK only.

If the libraries are not present, Q3Initialize (in the glue code) automatically returns kQ3Failure; if they are present, it will return whatever thre real Q3Initialize returns. In either case, the application will still launch.


RAVE: Asynchronous engines drew over menus and windows

A RAVE rasterization engine may be asynchronous with respect to the client application. In single-buffered mode, the window may be rendered to at any time, and in double-buffered mode, the rendered image may be copied to the window at any time. If a menu or other window is placed in front of such a window after rendering is begun, the rendering to the window (single-buffered) or the copying of the rendered image (double-buffered) may then overwrite the menu or obscuring window.

To prevent this problem, two new RAVE API calls have been added, which asynchronous RAVE engines need to use. These API calls allow the RAVE engine to be notified if and when the window's visibility has been changed. These are:

    QARegisterDrawNotificationProc()

and

    QAUnregisterDrawNotificationProc()

A more detailed explanation of this can be found on the SDK.


RAVE software rasterizer: Pixel drop-outs 

RAVE Software engine was not calculating edge parameters consistently. When drawing a set of triangles that share vertices, pixel drop-outs occurred. 


System: QD3D crashed when MoviePlayer opened movie with 3D track

Applications which use QuickDraw 3D and QuickTime, like the MoviePlayer, 
sometimes crashed prior to 1.5.3 after opening and closing several movies 
that contained 3D tracks.

This was evident when a QuickDraw 3D client located in the system heap, 
like QuickTime, called Q3Exit and Q3Initialize, which happens when movies 
with 3D tracks are closed and opened.  A fix was made in QuickDraw 3D to 
properly release the code fragment for an extension or "plug-in", for 
example the QuickDraw 3D Interactive Renderer.  Again, this problem only 
occurred for QuickDraw 3D clients residing in the system heap..


Viewer: Undesirable re-rendering when using non-interactive renderers

The viewer resets the subdivision level if it takes beyond a certain amount of time to draw a frame.  If the renderer is a non-interactive type renderer, this may be undesirable as resulted in a re-rendering that may have beeen slow due to the non-interactive nature of the renderer. So, for non-interactive renderers, this feature has been disabled.


Viewer: Failed to display control buttons when using 8 bit mode.

When the viewer is in 8 bit mode and using its own offscreen Gworld, and a call to Viewer_DrawControlStrip() is made, the buttons are drawn into the viewer's offscreen, but were not blitted into the final destination port.


Viewer: Offscreen not erased when using 8-bit mode

When this function created a new GWorld, it didn't erase it. This was most noticeable in the edges around the content area in the Viewer, which resembled lines made out of multi-colored dots. This only occurred when the viewer was using its own offscreen (i.e., 8 bit)


Vewer: No offscreen blit in 8-bit mode

If the viewer was drawing into an 8 bit port, an offscreen created that the viewer drew into was not being blitted to the screen.


Viewer: Once viewer is set to 8-bit mode, its internal state did not change.

When you create a viewer that draws into an 8 bit port (whether that be screen or GWorld) it sets a flag internally that it is drawing into an 8 bit port. If you change the viewer to draw into a port of a greater depth, that flag did not get updated.


Viewer: In SimpleText, couldn't select text if 3DMF is open in background.

It was impossible to select text from a Simpletext document when a 3DMF is opened in Simpletext in the background. Trying to select text only moved and rotated the 3DMF behind the active document window.


Viewer:  Didn't use clear image color read from ViewHints.

If a 3DMF file contained a ViewHints object with an image background color, the Viewer ignored that information.


Viewer: When using in SimpleText, a displayed image would brighten and dim

When typing text into SimpleText, the 3DMF file would dim or brighten. The Viewer thought that the key presses belong to it. The "d" key would dim, and the "b" key would make it get brighter.



Viewer: SimpleText File-Open of 3DMF file w/ Balloon Help caused redraw problem

The problem was that Q3ViewerEvent() was sucking up update events and sending them down a black hole.  The app never knew that it needed to do an update.


Viewer:  In Scrapbook or SimpleText, could get into "no button selected state"

This happened under the following scenario:

1. Open the Scrapbook with the Scrapbook file as installed by QD3D.
2. Scroll to the 2nd item in the Scrapbook.
3. Choose Top View from the Camera pop-up menu.
4. Notice that the Viewer buttons were all now deselected, and clicking within the model content area did nothing. The Viewer appeared to no longer be working at this point.

Also happened in SimpleText:

1.  Open any model.
2.  Choose any view.

All buttons are dim. If you pressed any other buttons (including the rotate button that is already selected) before step 2 the problem did NOT occur. If you clicked in the gray area beside the buttons before step 2 the problem did NOT occur. If you rotate the model before step 2 the problem DID occur.


Error messages:  Unreadable in MacsBug

Because the error message was too long to read. It was filled with a long pathname and, one assumes, the actual error ran off the right side of the screen. The pathname has been trucated, so as to allow the message to be visible.


Icon definitions: Missing

In the QD3D init, icons were defined for things of creator type 'QD3D' but not for either 'Q3XT' (QD3D extensions) or 'tnsl' (RAVE engines).  We have changed the BNDL resource and added the proper FREF resources along with an additional set of icons, so that if a developer doesn't define a custom icon, the user still sees that this has something to do with QuickDraw 3D.

The QuickDraw 3D INIT is a file of creator type 'QD3D' - thus it can only define icons for files with this same creator type.  Extensions have the creator type 'Q3XT'. Thus, we have:

- Set up a BNDL resource to map files of type 'shlb' with creator type 'Q3XT' (which automatically creates the needed FREF and signature resources) to a set of icons.  QD3D extensions without custom icons should end up using these icons.

- Added custom icons to the Apple 3D hardware accelerator card driver and engine.


Resources: Missing CCIȾresources for QuickDraw 3D components

Currently ExtensionsManager 4 has an informational database installed with the OS which contains more detailed file information for control panels and extensions in the System folder. This file information contains a more detailed description of the file than balloon help.  In EM4, this text is displayed in the "Show Item Information" field.


Interface Files: Unused identifiers

The following identifiers in QD3D.h have been removed, as they are not used anywhere in the library:

				#define kQ3ElementTypeName   34
				#define kQ3ElementTypeURL    35


Interface Files:  Erroneous method prototype definition

In QD3DRenderer.h, we had:

typedef TQ3Status (QD3D_CALLBACK *TQ3XRendererUpdateShaderMethod)(
				TQ3ViewObject      view,
				void               *rendererPrivate,
    TQ3Object          shaderObject);

but the third parameter is passed in by QD3D to the method as a pointer to a shader object, instead of the object itself, which was inconsistent with the above definition.

The solution was to change the definition in the header file to:

typedef TQ3Status (QD3D_CALLBACK *TQ3XRendererUpdateShaderMethod)(
				TQ3ViewObject       view,
				void                *rendererPrivate,
 			TQ3Object           *shaderObject);


Interface Files: Obsoleted routines and identifiers removed

All macros, functions, structures, and other identifiers previously marked "QD3D_OBSOLETE" have been removed from the interface files. The entry points in the shared libraries are still present, to preserve compatibility with existing older application binaries. However, applications should now only use identifiers explicitly defined in the current interface files, because these API calls will, in some future release of QuickDraw 3D, no longer be exported and thus cease to function.

The changes are as follows:

           OLD																																						NEW
-------------------------------------------------------------------------
TQ3ObjectClass																											TQ3XObjectClass
TQ3MethodType																											 TQ3XMethodType

kQ3MethodTypeObjectUnregister												kQ3XMethodTypeObjectUnregister
kQ3MethodTypeObjectFileVersion											kQ3XMethodTypeObjectFileVersion
kQ3MethodTypeObjectTraverse														kQ3XMethodTypeObjectTraverse
kQ3MethodTypeObjectTraverseData										kQ3XMethodTypeObjectTraverseData
kQ3MethodTypeObjectWrite																	kQ3XMethodTypeObjectWrite
kQ3MethodTypeObjectReadData														kQ3XMethodTypeObjectReadData

TQ3FunctionPointer																					  TQ3XFunctionPointer
TQ3MetaHandler																							    TQ3XMetaHandler

TQ3ObjectUnregisterMethod                TQ3XObjectUnregisterMethod
Q3ObjectClass_Unregister												     Q3XObjectHierarchy_UnregisterClass
TQ3ObjectTraverseMethod																		TQ3XObjectTraverseMethod	
TQ3ObjectWriteMethod																					TQ3XObjectWriteMethod
TQ3DataDeleteMethod																						TQ3XDataDeleteMethod
Q3View_SubmitWriteData																			Q3XView_SubmitWriteData
TQ3ObjectReadDataMethod																		TQ3XObjectReadDataMethod

Q3Quaternion_SetRotateXYZ																Q3Quaternion_SetRotate_XYZ
Q3Quaternion_SetRotateX																		Q3Quaternion_SetRotate_X
Q3Quaternion_SetRotateY																		Q3Quaternion_SetRotate_Y
Q3Quaternion_SetRotateZ																		Q3Quaternion_SetRotate_Z

Q3Pick_GetHitData																							 Q3Pick_GetPickDetailData
TQ3HitData																															TQ3PickDetailMasks
Q3Hit_EmptyData																										N/A																									

Q3Renderer_Flush																									Q3View_Flush
Q3Renderer_Sync																										Q3View_Sync

kQ3AttributeType_ConstructiveSolidGeometryID
																																							  kQ3AttributeTypeConstructiveSolidGeometryID

kQ3MethodTypeElementCopyAdd														kQ3XMethodTypeElementCopyAdd
kQ3MethodTypeElementCopyReplace									 kQ3XMethodTypeElementCopyReplace
kQ3MethodTypeElementCopyGet														kQ3XMethodTypeElementCopyGet
kQ3MethodTypeElementCopyDuplicate								kQ3XMethodTypeElementCopyDuplicate
kQ3MethodTypeElementDelete															kQX3MethodTypeElementDelete

TQ3ElementCopyAddMethod																		TQX3ElementCopyAddMethod
TQ3ElementCopyReplaceMethod														TQX3ElementCopyReplaceMethod
TQ3ElementCopyGetMethod																		TQX3ElementCopyGetMethod
TQ3ElementCopyDuplicateMethod												TQX3ElementCopyDuplicateMethod
TQ3ElementDeleteMethod																			TQX3ElementDeleteMethod

Q3ElementClass_Register																		Q3XElementClass_Register
Q3ElementType_GetElementSize													Q3XElementType_GetElementSize

kQ3MethodTypeAttributeInherit												kQ3XMethodTypeAttributeInherit
kQ3MethodTypeAttributeIsDefault										kQ3XMethodTypeAttributeIsDefault
kQ3MethodTypeAttributeCopyInherit								kQ3XMethodTypeAttributeCopyInherit
kQ3MethodTypeAttributeDefault												kQ3XMethodTypeAttributeDefault

TQ3AttributeInheritMethod																TQ3XAttributeInheritMethod
TQ3AttributeCopyInheritMethod												TQ3XAttributeCopyInheritMethod
TQ3AttributeDefaultMethod																TQ3XAttributeDefaultMethod
TQ3AttributeIsDefaultMethod														TQ3XAttributeIsDefaultMethod

Q3AttributeClass_Register																Q3XAttributeClass_Register

                      ´    ´    ´    ´    ´    ´    ´    ´    ´    ´    ´    ´    ´    ´    ´    ´    ´    ´    ´    ´    ´    ´    ´    ´

Copyright ©1997 Apple Computer, Inc.

Apple, the Apple logo, Macintosh, and Mac OS are trademarks of Apple Computer, Inc., registered in the U.S. and other countries. QuickDraw is a trademark of Apple Computer, Inc. All other product names are trademarks or registered trademarks of their respective holders. Mention of non-Apple products is for informational purposes and constitutes neither an endorsement nor a recommendation. Apple assumes no responsibility with regard to the selection, performance, or use of these products.