TweetFollow Us on Twitter

3D World Plug-Ins

Volume Number: 14 (1998)
Issue Number: 10
Column Tag: Plugging-In

3D Made Easy Using 3D World Plug-Ins

by Robin Landsbert
Edited by Steve and Patricia Sheets

How to write QuickDraw 3D plug-ins for 3D World


Creating an entire 3D application from scratch is a difficult task, even for an experienced Macintosh developer. Many of the concepts and user interface guidelines learned with 2D applications do not apply. To solve this problem, 3D World is available for developers to use as an 3D Graphic Shell program. 3D World provides an open and easy architecture for users to create and edit QuickDraw 3D data. For developers, 3D World is a method to quickly create QuickDraw 3D solutions. A developer can tailor 3D World for their specific market.

This article will explain how to develop 3D applications without starting from scratch. By using 3D World as an application shell you can easily add custom features for your specific market in the form of plug-ins. These could be import or export plug-ins for specific custom data sets or data formats, or whole vertical market applications like Interior Design. Thus, 3D World provide a standard way for the users to enter the data, while a third party developer can provide a plug-in which manipulates the data in a unique way.

3D World can be used by a developer to create custom applications such as: Modeling, Architecture, Interior Design, 3D Logos, 3D Charting, Contour mapping, Mathematics graphing, Educational Programming and many others. Developers can also export and import data in new and unique ways. Export examples include QuickTime tween movies, QuickTime VR panoramic and QuickTime VR object). On the input side, 3D World plug-ins can be created to communicate with 3D input devices, digitizers, 3D mice or data gloves. Although 3D World plug-ins do not need to use QuickDraw 3D, most do.

Additionally, the 3D World QuickDraw 3D Shared Library can be used by application developers to build their own QuickDraw 3D applications. This provides C++ wrappers to the QuickDraw 3D calls (with all C++'s advantages), and numerous extra utility routines to aid QuickDraw 3D development. The C++ headers are available on request from Microspot.

Figure 1. 3D World Application.

3D World

3D World was started at a QuickDraw 3D kitchen at Nice, France back in March 1995 when QuickDraw 3D 1.0 was in alpha. From the start, 3D World was designed to sit solely on top of QuickDraw 3D and was written entirely in object oriented C++ using Metrowerks PowerPlant as its application framework. All of the QuickDraw 3D calls where wrapped in C++ classes using the same object hierarchy as QuickDraw 3D uses.

Soon after that kitchen, it was decided a plug-in architecture was needed for 3D World. This was not only so we could extend 3D World's functionality and also allow third parties to write 3D World plug-ins, but also to allow us to tailor 3D World's functionality to the specific features needed. We did not want 3D World to succumb to bloatware as we wrote more and more features. Also junior programmers could work on plug-ins without affecting or needing to understand the main program. Plug-ins became a good training ground for QuickDraw 3D programming without needing to learn to write a whole 3D application.

Later it was decided to remove most of the functionality from 3D World and leave it as an application shell on which to build features. Plug-ins became hot-loadable by double clicking them. The plug-in architecture was also extended to allow more categories of plug-ins; No longer were you limited to just geometry entry tools and geometry modifier tools but now you could have plug-in commands, import and export plug-ins, and maybe the most powerful of all, plug-in palette windows. The application also became a shared library, exporting a number of routines for the plug-ins to use. Even the QuickDraw 3D C++ classes were shifted into a shared library so the application and all its plug-ins could share common code, thus reducing the memory overhead of having the same code in each of the plug-ins. This rearchitecting allows 3rd parties to use 3D World as a customizable vertical market 3D application shell. Developers can write the specific feature they need using plug-ins without having to write an entire 3D application.

3D World Plug-ins

There are currently 7 types of 3D World plug-ins - Entry, Modifier, Command, Import, Export, Palette and Idler. A plug-in may register itself as one or more of these types. The Entry and Modifier plug-ins are installed in the main Tools palette as a clickable icon. When the associated icon is selected and the user clicks in the main 3D window, the plug-in is invoked. At that time, entry tools create geometries and modifier tools change the attributes of the object clicked on. The Command plug-ins are similar to PhotoShop filters and are installed in the Plug-ins menu. When their menus are selected, the plug-in usually act on the selected objects. They can also set a mode. Import and Export plug-ins get installed as sub-menus in the File menu. Selecting their menu items import or export the entire document into or from the appropriate format. Palette plug-ins get installed in the Palettes menu and create their own palettes for the user to play with. Selecting the palette's menu shows the palette and clicking on any items within the palette executes its functionality. Idler plug-ins have no interface at all. They periodically get called by 3D World and just do background tasks like garbage collection, mode setting or animation. All plug-ins have full access to 3D World's retained mode QuickDraw 3D object hierarchy, so they may change that data at any time using QuickDraw 3D's routines. 3D World has no knowledge of what the plug-ins are doing and simply tells QuickDraw 3D to redraw the objects.

3D World plug-ins usually reside in the Plug-ins Folder which is located in the same folder as the 3D World application. Plug-ins can be put anywhere, but they will only be loaded automatically on launching 3D World if they are in the Plug-ins folder or any sub-folder within it. Other plug-ins can be "Hot-loaded" after launch just by double-clicking on them or dragging them into 3D World's main window (a bit like OpenDoc).

How to write a 3D World Plug-in

A 3D World plug-in is a standard Shared Library with a single exported entry point with the following prototype:

#pragma export on
extern "C" OSErr DoPlugInMessage(
   TPlugInMessage message,   // a series of messages from 3D World
   TIOParams* ioParams,      // info about the document, and callback routines
   long* refcon);            // a long for the plug-in to use to store its globals
#pragma export off

The main part of the plug-in is a big switch statement on the message parameter passed in by 3D World. There should always be a default case which should return notHandledErr so future plug-in messages are flagged as not implemented. The first message 3D World will pass in is the whatSortOfPlugInAreYou message and the routine is required to answer it to be loaded. This will occur as the application loads your plug-in, either at startup or when the user hot loads the plug-in after startup. The reply is passed back in ioParams->ioParam and can be one or multiple of the following enumerated types ORed together:

enum TPlugInType {
   geometryEntry      = 1,
   geometryModifier   = 1 << 1,
   palette            = 1 << 2,
   menuCommand        = 1 << 3,
   importPlugin       = 1 << 4,
   exportPlugin       = 1 << 5,
   idlerPlugin        = 1 << 6 };

The plug-in must also set the ioParams->paramRecVersion to the minimum version of 3D World it is willing to work with. In most cases this will be 0x00030000. All 3D World version information holds the major version in the top word, the minor version in the next byte and the bug-fix version in the last byte. So version 1.5.2 would be 0x00010502.

If the plug-in does not want to be loaded, it can return any non-zero error like notHandledErr and 3D World will not load the plug-in. For example, if 3D World was running in Demo mode, (ioParams->entryMask & eDemo) == eDemo) would be true. This is a good location to check for any libraries or environments that may be required. If they are not there, notHandledErr is returned. Otherwise return noErr, and 3D World will call the plug-in back with an initialize message. (Because 3D World is written in England, variable names will usually be "spelt the English way").

When the initialize message is received, the plug-in must initialize its global variables, open its resource fork (if needed) using ioParams->yourFileSpec, set up any palettes (if necessary), and return noErr. Again, if the plug-in can not, or is not to initialize its environment, return a non-zero error and the plug-in will not be loaded. From now on the shared library will remain loaded until it receives a dispose message, when it should dispose of any memory allocated in the initialize message.

After the initialize message, the plug-in will receive a doYouIdle message. This message is the application's way of asking the plug-in which idle times it requires. The reply should be in ioParams->ioParam and is a combination of TIdleFlags listed below:

enum TIdleFlags {
   kBeforeEvent            = 1L,
   kAfterEvent             = 1L <<  1,
   kBeforeDraw             = 1L <<  2,
   kAfterDraw              = 1L <<  3,
   kDuringDraw             = 1L <<  4,
   kAfterStartRender       = 1L <<  5,
   kBeforeEndRender        = 1L <<  6,
   kAfterStartWrite        = 1L <<  7,
   kBeforeEndWrite         = 1L <<  8,
   kBeforeAddObject        = 1L <<  9,
   kAfterAddObject         = 1L << 10,
   kBeforeDeleteObject     = 1L << 11,
   kAfterDeleteObject      = 1L << 12,
   kAfterSetUpWidgets      = 1L << 13,
   kPreAnimate             = 1L << 14,
   kAnimate                = 1L << 15,
   kPostAnimate            = 1L << 16,
   kSelectionChanged       = 1L << 17,
   kEndOfRenderLoop        = 1L << 18,
   kBeforeRevert           = 1L << 19,
   kAfterRevert            = 1L << 20 };

If idles are also requested before or after standard Macintosh events, the plug-in needs to return the event types they need in ioParams->theEvent.what. This is in the form of a standard Macintosh event mask. The plug-in will always get nullEvents. However the doYouIdle message is optional and the plug-in can just return a notHandledErr. More on idle messages later in this article.

This is the end of the sequence of messages a plug-in will receive when it is loaded during the launch of 3D World. Other messages will arrive when certain things happen in 3D World like user actions or updates or idles.

General Plug-in Messages

The plug-in may receive a giveAboutInfo message at any time when the user selects that plug-in from the About Plug-ins menu. The ioParams->ioParam field is used as a pointer to a TAboutInfo record which should be filled in so that it may be displayed to the user. This structure contains information associated with the plug-in needs to be displayed. If the plug-in provides a picture in AboutPtr->returnPict, the picture should contain all the information, as the other strings will not be used. The picture will be displayed in a dialog which will be dismissed when the user clicks on it. Otherwise a standard dialog will be displayed with the information strings displayed in it. It is suggested that these strings be stored in a STR# resource ID 32000. In fact all plug-in resources should be ID 32000 or over.

// ioParams->ioParam will be a pointer to a clear TAboutInfo record.
// Fill in as necessary although you may decide not to do anything.
case giveAboutInfo: {
   TAboutInfo* AboutPtr = (TAboutInfo*)(ioParams->ioParam);
   AboutPtr->version = GetVersion ();
   AboutPtr->returnPict =
   GetIndString (AboutPtr->author, kBaseID, 1);
   GetIndString (AboutPtr->company, kBaseID, 2);
   GetIndString (AboutPtr->address, kBaseID, 3);
   GetIndString (AboutPtr->phone, kBaseID, 4);
   GetIndString (AboutPtr->fax, kBaseID, 5);
   GetIndString (AboutPtr->eMail, kBaseID, 6);
   GetIndString (AboutPtr->aboutMessage, kBaseID, 7);
   return noErr ; }

A plug-in may also receive a userWantsToChangeOptions message. If the plug-in has any global options, this is the time to put up any modal dialog for the user to manipulate. Finally, just before the dispose message the plug-in will receive a savePrefs message. Save the preferences in a named resource of a particular type so that the plug-in can retrieve its globals again during the initialize message. When the savePrefs message and the initialize message are received, the current resource file is the 3D World Preferences file.

Geometry Entry and Modifier Plug-ins

If the plug-in sets the geometryEntry or geometryModifier bits in ioParams->ioParam in the whatSortOfPlugInAreYou message, it will receive a drawIcon message whenever the tool needs drawing in the Tools palette. It should draw the icon in a 24x24 icon at ioParams->theRect. The plug-in can also draw any help messages about the tool in the Help palette by calling ioParams->messageProc(message).

The clicked, doubleClicked and unclicked messages are very similar to the drawIcon message. When receiving these messages, the plug-in should draw its icon as in the drawIcon message, but it may also invoke some other functionality like show or hide a palette. For example, when the clicked message is received, the user has just clicked on the icon. When the user double clicks on an icon, the doubleClicked message will be sent immediately.

The plug-in receives an activate and deactivate message from 3D World when the tool gets revealed or hidden in a stack of plug-in tools in the Tool palette. At this time, the plug-in can open or close its resource file. Even if the plug-in has been deactivated, it will still receive idle messages if they are requested.

If the plug-in tool is selected, while the user moves the cursor over the main 3D window, the plug-in will constantly get an adjustCursor message. It can just return a notHandledErr in order to show the default cursor, or the plug-in can return noErr after having set its own cursor. This can depend on what object the cursor is over.

If the user presses a key while the plug-in tool is selected, it will get a keyPressed message. The event will be in ioParams->theEvent and the plug-in may either deal with the event and return noErr, or return notHandledErr and 3D World will deal with the key stroke itself. This message is useful if the plug-in handles arrow keys.

When the user clicks in the main 3D window with a plug-in selected, it will get different messages depending on whether it is an entry or a modifier tool.

If you are programming an entry tool, the first message the tool will get as the user clicks is a doCompleteEntry message. Most geometry entry plug-ins will return notHandledErr. If noErr is returned, the plug-in must handle the entire entry at this time. Otherwise the next message the plug-in will get is a multipleClickEntry message. To enter geometries using only a click and drag method, return notHandledErr and WaitMouseMoved will be called. Otherwise return noErr and the tool will immediately get the next message.

The next message the plug-in will get is a doYouNeedUndo message. To handle the undoing, return noErr, otherwise return notHandledErr and 3D World will immediately execute the default undo method for the tool type. Next the plug-in will get an addGeometryToGroup message in which the plug-in adds a complete QuickDraw 3D geometry object into ioParams->theGroup. The geometry must be scaled to fit within 0,0,0 and 1,1,1. However, if (ioParams->entryMask & eRadiusMode) == eRadiusMode, the geometry must be within a 2x2x2 cube centered around the origin. The geometry should also be colored using ioParams->curColor. A call to Q3Group_AddObject (ioParams->theGroup, myNewGeometryObject) adds the plug-in's geometry into 3D World's group. On returning noErr, 3D World will handle all the dragging out, resizing and shift key constrainer code until the user lets go of the mouse button. Otherwise if the plug-in set ioParams->ioParam != 0, the geometry should be placed at ioParams->mousePoint3D and sized according to ioParams->unitsPerMeter, and the user will not stretch the object during entry.

case addGeometryToGroup: {
   if (ioParams->theGroup)   {
      TQ3BoxData boxData;
      boxData.orientation.x = boxData.orientation.z = 0;
      boxData.minorAxis.y = boxData.minorAxis.z = 0;
      boxData.majorAxis.x = boxData.majorAxis.y = 0;
      if ((ioParams->entryMask & eRadiusMode) == eRadiusMode)
// create box size 2, centered about the origin
         boxData.origin.x = boxData.origin.y =
         boxData.origin.z = -1;
         boxData.orientation.y = boxData.minorAxis.x =
         boxData.majorAxis.z = 2;
      else { 
// create unit box at origin
         boxData.origin.x = boxData.origin.y =
         boxData.origin.z = 0;
         boxData.orientation.y = boxData.minorAxis.x =
         boxData.majorAxis.z = 1;
      boxData.faceAttributeSet = nil;
      boxData.boxAttributeSet = Q3AttributeSet_New ();
// add current color
      if (boxData.boxAttributeSet) 
          kQ3AttributeTypeDiffuseColor, &ioParams->curColor);
// create box object
      TQ3BoxObject boxObject = Q3Box_New (&boxData);
      Q3Object_Dispose (boxData.boxAttributeSet);
      if (boxObject) {
// add the box to the group
         Q3Group_AddObject (ioParams->theGroup, boxObject);
         Q3Object_Dispose (boxObject);
         return noErr;
   return notHandledErr;

A geometry modifier tool will first get a giveSelectedGroup message. If noErr is returned, the tool will get the selected group in ioParams->hitObject in the following canYouDoAnythingToThisGeometry message. Otherwise during the canYouDoAnythingToThisGeometry message, the plug-in will get the geometry or group that the user clicked on in ioParams->hitObject. During the canYouDoAnythingToThisGeometry message, the plug-in should return noErr if it can modify the geometry in some way. If the plug-in returns an error, the user action will be aborted. The next message the plug-in receives is the doYouNeedUndo message. If the plug-in handles the undoing, return noErr; otherwise return notHandledErr and 3D World will immediately execute the default undo method for the tool type. When the plug-in receives the final modifyGeometry message, it should act on the ioParams->hitObject. The hit object usually is a group object, so if plug-in needs to modify the data of all the geometries in the group, it will have to iterate through the group. This can be done using the something like the following routine:

void IterateGroup (TQ3GroupObject theGroup)
TQ3GroupPosition pos;
if (Q3Group_GetFirstPosition(theGroup, &pos) == kQ3Success)
   do {
      TQ3Object theObject;
      if (Q3Group_GetPositionObject(theGroup,pos,&theObject)
         == kQ3Success) {
         if (Q3Shared_GetType(theObject)==kQ3SharedTypeShape)
            TQ3ObjectType theType=Q3Shape_GetType(theObject);
            if (theType == kQ3ShapeTypeGroup)
            else if (theType == kQ3ShapeTypeGeometry)
               theType = Q3Shape_GetLeafType (theObject);
               switch (theType) {
// modify the geometry in some way
         Q3Object_Dispose (theObject);
   while ((Q3Group_GetNextPosition (theGroup, &pos) ==
                              kQ3Success) && pos);

A geometry modifier plug-in may actually want to modify the camera object and not a geometry, much as the Orbit, Walkthrough, VR and Teleport plug-ins do. In this case the modifyGeometry message might look like this:-

case modifyGeometry: {
   TQ3CameraObject theCamera;
   if (Q3View_GetCamera (ioParam->theView, &theCamera)
               == kQ3Success) && theCamera) {
      TQ3CameraData theData;
      if (Q3Camera_GetData(theCamera, &theData)==kQ3Success){
         while (StillDown ()) {
            Point theMouse;
            GetMouse (&theMouse);
// modify the camera data in some way based on the mouse position
            Q3Camera_SetData(theCamera, &theData);
//update the camera
            ioParams->drawProc (); // draws the main 3D view
      Q3Object_Dispose (theCamera);

Import And Export Plug-ins

Import plug-ins are also easy to program. The first message the plug-in will get on selecting the command is doYouNeedUndo. Most import plug-ins will not implement this message and will let 3D World implement the default import undo method. The only other message the plug-in will get is an addGeometryToGroup message. When this occurs, the plug-in should put its own StandardGetFile to select the file to import. If a user selects a file, then the data is added as QuickDraw 3D objects into ioParams->theGroup using Q3Group_AddObject(ioParam->theGroup, myImportedDataObject). Any error returned will cause 3D World to cancel adding the group to the document.

Export Plug-ins are even easier. They will get a modifyGeometry message and should call StandardPutFile. If the user selects a file, the contents of ioParams->theGroup are saved into this file in the appropriate format using a routine similar to IterateGroup.

Menu Command Plug-ins

Menu Command plug-ins are similar to geometry modifier plug-ins except they always apply to the entire selected group, and therefore their actions can be applied to more than one item at a time. Often plug-ins register themselves as both (geometryModifier + menuCommand), and show up in the tool palette and the plug-in menu. When a menu command plug-in is selected by the user, it will only get a doYouNeedUndo message followed by a modifyGeometry message where ioParams->theGroup is the selected group. However the plug-in will get a canYouDoAnythingToThisGeometry message whenever the user clicks on the menu bar. After examining ioParams->theGroup, if the plug-in returns noErr, its menu item will be enabled. If it returns notHandledErr, the menu item will be greyed out. If ioParams->ioParam is set to 1, the menu item will get a checkmark next to it. Otherwise if ioParams->ioParam is not 1 or 0, then ioParams->ioParam is assumed to be the character to be used as a checkmark for the plug-in's menu item.

Idler Plug-ins

If the plug-in returned noErr from the doYouIdle message, it will be called periodically when certain things happen in 3D World depending on the flags it passed back in ioParams->ioParam. An idle message handler should look something like this:

case idle: {
   if (ioParams->ioParam & kSelectionChanged) {
      TQ3GroupObject selectedGroup =
// display info on new selection
   else if (ioParams->ioParam & kBeforeEvent) {
// look at ioParams->theEvent.what and act on it
// You can modify the event record and 3D World will deal with the new values
   ioParams->ioParam = 6;
// return number of tick before next nullEvent callback
   return noErr;

For any given call of the idle message, only one bit of ioParams->ioParam will be set. Each bit will signify a different time the idle message is being called. The plug-in can act appropriately depending on what the idle message is. At the end of each idle message, set the ioParams->ioParam to the number of ticks the plug-in is willing to wait until it receives another nullEvent event. The plug-in can also return an error of kDirtyViewErr and this will cause 3D World to refresh the window. However, returning kDirtyViewErr after a kBeforeDraw idle will cause 3D World to draw using GWorlds. This is useful to save a picture or record to a QuickTime movie as ioParams->thePort will actually be the rendered GWorld in the kAfterDraw idle.

case idle: {
   if (ioParams->ioParam & kBeforeDraw)
      return kDirtyViewErr; 
// causes 3D World to use GWorlds
   if (ioParams->ioParam & kAfterDraw) {
// save contents of ioParam->thePort which is a GWorld
   ioParams->ioParam = 6;
// return number of tick before next nullEvent callback
   return noErr;

The idle messages can be used to monitor things like changes in the camera position, and then update the camera palette to reflect those changes. NaviCam uses this type of code:

case idle: {
   if (ioParams->ioParam & kAfterDraw) {
      TQ3CameraObject theCamera;
      if (Q3View_GetCamera (ioParam->theView,
                 &theCamera) == kQ3Success) && theCamera)
         TQ3CameraData theData;
         if (Q3Camera_GetData (theCamera,
                 &theData) == kQ3Success)
            static TQ3CameraData sOldCameraData;
            if (theData != sOldCameraData) {
// update the palette based on the new camera data
               UpdatePalette (&theData);
               sOldCameraData = theData; 
// save the current data
         Q3Object_Dispose (theCamera);
   ioParams->ioParam = 6;
// return number of tick before next nullEvent callback
   return noErr;

Palette Plug-ins

The most powerful of 3D World's plug-in types are the palette plug-ins; They are also the most complicated plug-ins to write. They do not rely on the standard message handling entry routine. Instead they install callback routines using the Plug-in API that 3D World exports from the application (just as if it were itself a shared library). All the plug-in API routines that 3D World exports start with PL_. A complete listing of the current routines available are in PluginAPI.h.

The following code shows how to program a palette plug-in. During the initialize message, or at any appropriate time, SetUpPaletteWindow should be executed:

Figure 2. Plug-in Palette Window.

TPLWindow gPalette = nil;

OSErr SetUpPaletteWindow (TIOParams* ioParams) {
   OSErr err = noErr;
   GrafPtr oldPort;
   GetPort (&oldPort);
   Rect globalBounds = {34, 4, 270, 180};
// set up some default rect
   Handle h = Get1Resource ('RECT', kBaseID);
   if (h) {
// read rect from resource
      BlockMoveData (*h, &globalBounds, sizeof (Rect));
      ReleaseResource (h);
   TPLWindowExtras extras = TPLWindowExtras (ePL_CloseBox |
   gPalette = PL_NewWindow (ePL_Palette, extras,
                  &globalBounds, &globalBounds,
                  Get1Resource ('DITL', kBaseID), 0);
   if (gPalette) {
      TPLWindowItem item = PL_GetIndexWindowItem (gPalette, kApplyButton);
      PL_InstallWindowItemCallBack (item, ePL_Clicked, ClickButton); 
// call this function when this item is clicked
      item = PL_GetIndexWindowItem (gPalette, kSliderItem);
      PL_InstallWindowItemCallBack (item, ePL_ValueChanged, ValueChanged); 
// call this function when this item's value changes
      PL_SetWindowItemMin (item, 0);
      PL_SetWindowItemMax (item, 100);
      PL_SetWindowItemValue (item, 0);
      item = PL_GetIndexWindowItem(gPalette,
      PL_SetWindowItemValue (item, 0) 
// displays as text the slider's value
      item = PL_GetIndexWindowItem (gPalette, kUserItem);
      PL_InstallWindowItemCallBack (item, ePL_Draw, DrawUserItem); 
// install this function to draw this item
      item = PL_GetIndexWindowItem (gPalette, kOnItem);
      PL_InstallWindowItemCallBack (item, ePL_Clicked, ClickRadio); 
// install this function when this item is clicked
      PL_SetWindowItemValue (item, 1);
      item = PL_GetIndexWindowItem (gPalette, kOffItem);
      PL_InstallWindowItemCallBack (item, ePL_Clicked, ClickRadio);
      PL_SetWindowItemValue (item, 0);
      err = notHandledErr;
   SetPort (oldPort);
   return err;

All the callbacks have the same prototype. They are passed two parameters (TPLWindowItem and TPLInheritedProcPtr) and return a long. TPLWindowItem is the item that the callback was installed in, while TPLInheritredProcPtr is the routine that provides the default behavior of 3D World.

long ClickButton (TPLWindowItem windowItem,
                        TPLInheritedProcPtr inheritedProc)
SysBeep (30);
return inheritedProc (windowItem);
// calls the default Click handler within 3D World

long ValueChanged (TPLWindowItem windowItem,
                        TPLInheritedProcPtr inheritedProc)
if (inheritedProc (windowItem)) {
// this handles the changing of the items value and returns true if 
// the value actually changed
   long val = PL_GetWindowItemValue (windowItem);
   TPLWindowItem item = PL_GetIndexWindowItem (gPalette, kSliderValueItem);
   PL_SetWindowItemValue (item, val);
// because this is a text item, 3D World converts the long to a string for you
   return true;
return false;

long DrawUserItem (TPLWindowItem windowItem,
// no need to call the InheritedProc as for user items as it does nothing
Rect r;
PL_GetWindowItemRect (windowItem, &r);
FrameRoundRect (&r, 16, 16);
return true;

long ClickRadio (TPLWindowItem windowItemHit,
                        TPLInheritedProcPtr inheritedProc)
if (inheritedProc (windowItemHit)) {
// this handles the tracking of the mouse while it is down 
// and returns true if the mouse was released over the radio
   long val = PL_GetWindowItemValue (windowItemHit);
// check to see if it was actually turned on
   if (val) {
      TPLWindowItem item;
      short itemHit = PL_GetWindowItemNumber (windowItemHit);
      if (itemHit == kOnItem)
         item = PL_GetIndexWindowItem (gPalette, kOffItem);
         item = PL_GetIndexWindowItem (gPalette, kOnItem);
      PL_SetWindowItemValue (item, 0); 
// turn the other radio button off
   return true;
return false;

Once the SetUpPaletteWindow routine has been executed, nothing more really needs to be done in the DoPlugInMessage routine except handling the standard messages that all plug-ins must handle (like dispose, giveAboutInfo, etc.). 3D World now controls the palette window depending on user actions. For example, whenever the user clicks the Apply button in the palette, the ClickButton function gets called. Whenever the scrollbar's value changes because the user has clicked it, the ValueChanged function gets called, so the corresponding text item value is set to correspond to the scrollbar's value. Whenever the user item needs to be drawn, the DrawUserItem function gets called and a rounded rectangle gets drawn around the bounds of the user item. Finally, whenever the user clicks in either the on or off radio buttons, the ClickRadio function gets called and it sets the other radio button.

A wealth of PL_Routines are available in 3D World; The most commonly used ones are used in the above sample code. Most are very self explanatory. Obviously this sample code implements very simplistic functions, and the user interface is terrible, but you could apply some quite complex routines to alter the nature of the QuickDraw 3D groups within 3D World in exactly the same way. Just run the demo version of 3D World included on the CD and see what can be done using palette plug-ins.

Object Approach to QuickDraw 3D

QuickDraw 3D is not an object oriented API. Mcrospot has wrapped a majority of the QuickDraw 3D calls into C++ objects. Most of the 3D World plug-ins have been written using these QuickDraw 3D C++ classes, which is much simpler than the sample code given. Although some of the more obscure functionality of the plug-in API has not been described here, all of the common and basic ideas needed to write a 3D World plug-in have been discussed. Example plug-in code and the two relevant header files (3DWorldPlugIn.h and PluginAPI.h) are provided on the CD along with a demo version of 3D World 3.0.


Microspot has been able to factor out most of the functionality of 3D World by using a plug-in architecture. Over 100 different plug-ins have all be written using this messaging system. If you want to know more about the 3D World plug-in API you can write to Robin Landsbert direct at You can also visit the 3D World API web page at For great example images of what can be done with 3D World 3.0 and the LightWorks renderers visit

Microspot USA Inc.
12380 Saratoga-Sunnyvale Road,
Saratoga, CA 95070
Tel: 408 253 2000
Fax: 408 253 2055

Microspot UK Ltd.
London House,
Suite 6, 5-11, London Road,
Maidstone, Kent. ME16 8HR
Tel: +44 (0)1622-687771 (drop zero outside UK)
Fax: +44 (0)1622-690801

Robin Landsbert has been programming Macintosh computers since 1985 and works for Microspot Ltd. He is the Project Manager of 3D World and can be reached at


Community Search:
MacTech Search:

Software Updates via MacUpdate

Microsoft Office 2016 16.11 - Popular pr...
Microsoft Office 2016 - Unmistakably Office, designed for Mac. The new versions of Word, Excel, PowerPoint, Outlook, and OneNote provide the best of both worlds for Mac users - the familiar Office... Read more
Adobe Photoshop CC 2018 19.1.2 - Profess...
Photoshop CC 2018 is available as part of Adobe Creative Cloud for as little as $19.99/month (or $9.99/month if you're a previous Photoshop customer). Adobe Photoshop CC 2018, the industry standard... Read more
Adobe Dreamweaver CC 2018 -...
Dreamweaver CC 2018 is available as part of Adobe Creative Cloud for as little as $19.99/month (or $9.99/month if you're a previous Dreamweaver customer). Adobe Dreamweaver CC 2018 allows you to... Read more
Adobe Flash Player - Plug-in...
Adobe Flash Player is a cross-platform, browser-based application runtime that provides uncompromised viewing of expressive applications, content, and videos across browsers and operating systems.... Read more
Drive Genius 5.2.0 - $79.00
Drive Genius features a comprehensive Malware Scan. Automate your malware protection. Protect your investment from any threat. The Malware Scan is part of the automated DrivePulse utility. DrivePulse... Read more
MegaSeg 6.0.6 - Professional DJ and radi...
MegaSeg is a complete solution for pro audio/video DJ mixing, radio automation, and music scheduling with rock-solid performance and an easy-to-use design. Mix with visual waveforms and Magic... Read more
ffWorks 1.0.7 - Convert multimedia files...
ffWorks (was iFFmpeg), focused on simplicity, brings a fresh approach to the use of FFmpeg, allowing you to create ultra-high-quality movies without the need to write a single line of code on the... Read more
Dash 4.1.5 - Instant search and offline...
Dash is an API documentation browser and code snippet manager. Dash helps you store snippets of code, as well as instantly search and browse documentation for almost any API you might use (for a full... Read more
Evernote 7.0.3 - Create searchable notes...
Evernote allows you to easily capture information in any environment using whatever device or platform you find most convenient, and makes this information accessible and searchable at anytime, from... Read more
jAlbum Pro 15.3 - Organize your digital...
jAlbum Pro has all the features you love in jAlbum, but comes with a commercial license. You can create gorgeous custom photo galleries for the Web without writing a line of code! Beginner-friendly... Read more

Latest Forum Discussions

See All

Around the Empire: What have you missed...
Oh hi nice reader, and thanks for popping in to check out our weekly round-up of all the stuff that you might have missed across the Steel Media network. Yeah, that's right, it's a big ol' network. Obviously 148Apps is the best, but there are some... | Read more »
All the best games on sale for iPhone an...
It might not have been the greatest week for new releases on the App Store, but don't let that get you down, because there are some truly incredible games on sale for iPhone and iPad right now. Seriously, you could buy anything on this list and I... | Read more »
Everything You Need to Know About The Fo...
In just over a week, Epic Games has made a flurry of announcements. First, they revealed that Fortnite—their ultra-popular PUBG competitor—is coming to mobile. This was followed by brief sign-up period for interested beta testers before sending out... | Read more »
The best games that came out for iPhone...
It's not been the best week for games on the App Store. There are a few decent ones here and there, but nothing that's really going to make you throw down what you're doing and run to the nearest WiFi hotspot in order to download it. That's not to... | Read more »
Death Coming (Games)
Death Coming Device: iOS Universal Category: Games Price: $1.99, Version: (iTunes) Description: --- Background Story ---You Died. Pure and simple, but death was not the end. You have become an agent of Death: a... | Read more »
Hints, tips, and tricks for Empires and...
Empires and Puzzles is a slick match-stuff RPG that mixes in a bunch of city-building aspects to keep things fresh. And it's currently the Game of the Day over on the App Store. So, if you're picking it up for the first time today, we thought it'd... | Read more »
What You Need to Know About Sam Barlow’s...
Sam Barlow’s follow up to Her Story is #WarGames, an interactive video series that reimagines the 1983 film WarGames in a more present day context. It’s not exactly a game, but it’s definitely still interesting. Here are the top things you should... | Read more »
Pixel Plex Guide - How to Build Better T...
Pixel Plex is the latest city builder that has come to the App Store, and it takes a pretty different tact than the ones that came before it. Instead of being in charge of your own city by yourself, you have to work together with other players to... | Read more »
Fortnite Will Be Better Than PUBG on Mob...
Before last week, if you asked me which game I prefer between Fortnite Battle Royale and PlayerUnknown’s Battlegrounds (PUBG), I’d choose the latter just about 100% of the time. Now that we know that both games are primed to hit our mobile screens... | Read more »
Siege of Dragonspear (Games)
Siege of Dragonspear 2.5.12 Device: iOS Universal Category: Games Price: $9.99, Version: 2.5.12 (iTunes) Description: Experience the Siege of Dragonspear, an epic Baldur’s Gate tale, filled with with intrigue, magic, and monsters.... | Read more »

Price Scanner via

Sunday Sales: $200 off 13″ Touch Bar MacBook...
Amazon has new 2017 13″ 3.1GHz Touch Bar MacBook Pros on sale this weekend for $200 off MSRP, each including free shipping: – 13″ 3.1GHz/256GB Space Gray MacBook Pro (MPXV2LL/A): $1599.99 $200 off... Read more
B&H drops prices on 15″ MacBook Pros up t...
B&H Photo has dropped prices on new 2017 15″ MacBook Pros, now up to $300 off MSRP and matching Adorama’s price drop yesterday. Shipping is free, and B&H charges sales tax for NY & NJ... Read more
Apple restocks Certified Refurbished 2017 13″...
Apple has restocked Certified Refurbished 2017 13″ 2.3GHz MacBook Pros for $200-$230 off MSRP. A standard Apple one-year warranty is included with each MacBook, models receive new outer cases, and... Read more
13″ Space Gray Touch Bar MacBook Pros on sale...
Adorama has new 2017 13″ Space Gray Touch Bar MacBook Pros on sale for $150 off MSRP. Shipping is free, and Adorama charges sales tax in NY & NJ only: – 13″ 3.1GHz/256GB Space Gray MacBook Pro (... Read more
Best deal of the year on 15″ Apple MacBook Pr...
Adorama has New 2017 15″ MacBook Pros on sale for up to $300 off MSRP. Shipping is free, and Adorama charges sales tax in NJ and NY only: – 15″ 2.8GHz Touch Bar MacBook Pro Space Gray (MPTR2LL/A): $... Read more
Save $100-$150+ on 13″ Touch Bar MacBook Pros...
B&H Photo has 13″ Touch Bar MacBook Pros on sale for $100-$150 off MSRP. Shipping is free, and B&H charges sales tax for NY & NJ residents only: – 13″ 3.1GHz/256GB Space Gray MacBook Pro... Read more
Current deals on 27″ Apple iMacs, models up t...
B&H Photo has 27″ iMacs on sale for up to $150 off MSRP. Shipping is free, and B&H charges sales tax for NY & NJ residents only: – 27″ 3.8GHz iMac (MNED2LL/A): $2149 $150 off MSRP – 27″ 3... Read more
Thursday Deal: 13″ 2.3GHz MacBook Pro for $11...
B&H Photo has the 13″ 2.3GHz/128GB Space Gray MacBook Pro on sale for $100 off MSRP. Shipping is free, and B&H charges sales tax for NY & NJ residents only: – 13-inch 2.3GHz/128GB Space... Read more
How to save $100-$190 on 10″ & 12″ iPad P...
Apple is now offering Certified Refurbished 2017 10″ and 12″ iPad Pros for $100-$190 off MSRP, depending on the model. An Apple one-year warranty is included with each model, and shipping is free: –... Read more
Silver 12″ 1.3GHz MacBook on sale at B&H...
B&H Photo has the 2017 12″ 1.3GHz Silver MacBook on sale for $1399.99 including free shipping plus sales tax for NY & NJ residents only. Their price is $200 off MSRP, and it’s the lowest... Read more

Jobs Board

Firmware Engineer - *Apple* Accessories - A...
# Firmware Engineer - Apple Accessories Job Number: 113452350 Santa Clara Valley, California, United States Posted: 28-Feb-2018 Weekly Hours: 40.00 **Job Summary** Read more
Automation and Performance Engineer, *Apple*...
# Automation and Performance Engineer, Apple Pay Job Number: 113557967 Santa Clara Valley, California, United States Posted: 09-Mar-2018 Weekly Hours: 40.00 **Job Read more
Hardware Systems Architect - *Apple* Watch...
# Hardware Systems Architect - Apple Watch Job Number: 113565323 Santa Clara Valley, California, United States Posted: 05-Mar-2018 Weekly Hours: 40.00 **Job Read more
Lead *Apple* Solution Consultant - Apple (U...
# Lead Apple Solution Consultant Chicago IL Job Number: 113560644 Chicago, Illinois, United States Posted: 10-Mar-2018 Weekly Hours: 40.00 **Job Summary** As a Lead Read more
Art Director, *Apple* Music + Beats1 Market...
# Art Director, Apple Music + Beats1 Marketing Design Job Number: 113258081 Culver City, California, United States Posted: 07-Mar-2018 Weekly Hours: 40.00 **Job Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.