3D World Plug-Ins
Volume Number: 14
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 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,