 |
 |
 |
Compiling LightWave Plug-insLightWave plug-ins on all platforms are ordinary operating system objects (they're DLLs under Windows, for example), so building them is pretty straightforward. You'll need to define a couple of preprocessor symbols and export one variable name, and you'll need to compile and link with a bit of code supplied with the SDK. LightWave plug-ins are ordinarily given a ".p" filename extension, although this isn't required. Preprocessor Symbols The SDK header files rely on preprocessor symbols to identify the operating system and
CPU of the host system. These are currently used to define system- _WIN32 /* Microsoft Windows */ _MACOS /* Macintosh */ _XGL /* Unix */ and the CPU defines are. _X86_ /* Intel and Intel-compatible */ _ALPHA_ /* Alpha AXP */ _PPC_ /* PowerPC */ _MIPS_ /* MIPS */ You need one symbol from the first list and one from the second, and you need to pass them to the compiler as preprocessor defines. Exported Variable The linker needs to export the symbol _mod_descrip. LightWave looks for this module descriptor data structure by name when it attempts to load a plug-in. Symbol export is handled differently in different development environments, but it's often a linker command line option. SDK Library The SDK ships with source code files defining the _mod_descrip structure, default Startup and Shutdown functions, and a default names array. Each plug-in you create must include servmain.c and must be linked with server.lib. Before compiling any plug-ins, you'll need to build server.lib for your system. Create a statically linked library containing servdesc.c, username.c, startup.c, and shutdown.c, all of which you should find in the SDK/source directory. Name the library server.lib. Define the operating system and CPU preprocessor symbols described previously when compiling the library source. You may want to create more than one version of server.lib with different compiler settings (debug and release versions, for instance). Debugging Notes Don't forget that before you can run or debug your plug-in for the first time, you need to add it to the plug-in list in LightWave. In general, you must quit and restart LightWave each time you rebuild your plug-in and want to run it. Your plug-in is cached in memory for the life of a LightWave session, so LightWave won't see the changes to your plug-in until it quits and restarts. LightWave Modeler supports a debug command line switch. When started with the -d switch, Modeler adds an "Unload Plug-ins" command. (This appears in the Modeler/Plug-ins menu with the default configuration, but may not appear in custom menu configurations.) Activating this command forces Modeler to unload all unlocked plug-in modules, so that when you execute your plug-in again it will be reloaded from disk. Beginning in LightWave 6.5, Modeler's -d switch can take an argument (-dfilename) which tells it where to write debug information. This can be useful for figuring out why plug-ins aren't loading, or for looking at trace information generated by XPanels. Microsoft Windows Plug-in modules under Windows are Win32 dynamic link libraries (DLLs). You don't need to create an import library (.lib) or an export file (.exp) for plug-in DLLs, but you will need to export _mod_descrip. One way to do this is to include a module definition (.def) file containing an EXPORT _mod_descrip directive. You can use the default source\serv.def file provided with the SDK for this. Win32 DLLs have a standard entry point function named DllMain. You don't need to provide a DllMain for your LightWave plug-ins unless, for example, the user interface is built with Windows interface components that require the DLL's instance handle. (But consider building your interface using the platform-independent components provided with the plug-in SDK.) The alignment of structure members in your DLL must match LightWave's.
The recipes for specific compilers discuss what, if anything, you need to do to ensure that your plug-in's data is properly aligned. If you decide to use makefiles to build your plug-ins, they should contain lines resembling the following: LWSDK_FLAGS = -D_X86_ -D_WIN32
.c.obj:
$(CC) $(CFLAGS) $(LWSDK_FLAGS) $*.c $(LWSDK_SRC)servmain.c
.obj.p:
$(LINKER) -dll -out:$@ -def:$(LWSDK_INCL)serv.def $*.obj \
$(LWSDK_LIB)server.lib $(OTHER_LIBS)
In other words, define the symbols _X86_ (or _ALPHA_) and _WIN32, include servmain.c in the list of source code files, include the module definition file serv.def so that _mod_descrip is exported, and link with server.lib. Microsoft Visual C++ To build an MSVC version of the SDK library,
To create a plug-in,
Accept the default settings for the calling convention (__cdecl), alignment (8 byte) and runtime library (multithreaded or multithreaded debug, for the release and debug versions, respectively). If you've built both debug and release versions of server.lib (and this is recommended), make sure you list the appropriate one for the debug and release versions of your plug-in. You're ready to build your plug-in. To debug it,
Hit F5 to begin debugging. The debugger will warn you that the LightWave executable doesn't contain any debugging information, but that's okay. Your plug-in does have this information, which the debugger will find as soon as your plug-in is started by LightWave. Borland C++ 4.52 Before creating any plug-ins, you'll need to build a Borland version of the SDK library.
To build a plug-in,
GNU gcc/Mingw32 You can build LightWave plug-ins with Win32 GNU distributions. The procedure given here was developed and tested with the Mingw32 distribution. Before creating any plug-ins, you'll need to build a GNU version of the SDK library. (Some of the command lines below wrap to a second line here, but they should be entered on a single line.)
To build a plug-in,
An equivalent makefile would look like this: LWSDK_CFLAGS = -D_WIN32 -D_X86_ -O6
%.o: %.c
gcc $(LWSDK_CFLAGS) -I$(LWSDK_INCL) -c $<
myplug.p: myplug.o
dllwrap -o $@ --export-all --dllname $@ \
myplug.o $(LWSDK_LIB)servmain.o $(LWSDK_LIB)libserver.a
Watcom C++ 10.0a (On June 30, 1999, Sybase, Inc., sent an "end of life" letter to registered owners of Watcom C/C++ announcing that version 11.0 of the compiler would be its last. Watcom is therefore unlikely to play a role in future LightWave plug-in development. This section remains useful, however, as an illustration of the incompatibilities you may encounter with some compilers.) In Watcom terminology, plug-ins are NT DLLs, so that should be your target type. server.lib should also be built as an NT object. To build a plug-in,
There's an important mismatch in calling conventions that apparently can't be solved with a compiler switch or a pragma. When using the stack-based calling convention, which plug-ins must, Watcom 10.0a expects functions that return floating-point numbers to put them in specific registers, while LightWave's code leaves them at the top of the FPU stack. You'll encounter this whenever a plug-in compiled with Watcom needs to call a plug-in SDK function that returns a double. What happens can be illustrated with a little assembly-ish pseudocode. Given double routine( void ); double result; result = routine(); the different ways the function call is handled are Microsoft: call routine
fstp result ; pop ST(0) into result
Watcom: call routine
mov result, eax ; move edx:eax into result
mov result+4, edx
When compiled in Microsoft Visual C++, routine leaves its return value at the top of the FPU stack, which is popped into result. In Watcom 10.0a, routine leaves its return value in the register pair edx:eax, which is then moved into result. The workaround for this involves adding a bit of inline assembly language to each source file that contains a call to a LightWave function returning a double. At the beginning of each such file, put static double fac; /* floating point accumulator */
extern void sdk_fstp( void );
#pragma aux sdk_fstp = "fstp fac"
#define SDK_DBLRTN( x ) \
sdk_fstp(); \
x = fac;
This uses Watcom inline assembly to load the contents of ST(0) into a fixed memory location, from which the value can be copied. Calls that would look like this result = objInfo->dissolve( objID, t ); must be changed to objInfo->dissolve( objID, t ); SDK_DBLRTN( result ); The SDK function is called without assigning its return value. The assembly instruction fstp fac is inserted after the call to retrieve the return value, then fac is copied into result. Macintosh Plug-in modules on the Mac are PowerPC shared libraries of type shlb. Metrowerks CodeWarrior Before compiling any plug-ins, you'll need to build a CodeWarrior version of the SDK library.
To create a plug-in project,
You can globally define _MACOS and _PPC_ by putting them in a .h file and using that file as the C/C++ Language Prefix File (in Language Settings). To export _mod_descrip, you can create a text file containing simply "_mod_descrip". Call the file server.exp. In PPC PEF/Export Symbols, choose the "Use .exp file" method, and then add server.exp to the project. In later versions of CodeWarrior, you may find that the compiler won't accept any sort of conversion between char * and const char *. To work around this, you can add the following pragma: #pragma old_argmatch on Building plug-ins for OS X isn't much different from building them for previous operating systems on the Mac, but you must link with CarbonLib instead of InterfaceLib, and your code must be Carbon compliant. See the Carbon Porting Guide (an Adobe Acrobat PDF) at Apple's Developer website. CodeWarrior up to version 6.2 cannot debug on OS X. Debugging in MacOS 9 is sufficient in most cases, but if you need to debug in X, you can use gdb in a terminal window. As of this writing, LightWave for OS X is a CFM application. When a CFM app is run, OS X actually runs a mach-o wrapper app that loads the program. The wrapper is called LaunchCFMApp, located in /System/Library/Frameworks/Carbon.framework/Versions/A/Support/ LaunchCFMApp To begin debugging, use gdb to run LaunchCFMApp. localhost% gdb /System.../LaunchCFMApp In gdb, type run followed by the name and path for the LightWave component in which your plug-in runs. Macintosh Programmer's Workshop Before building any plugins, you'll need to build an MPW version of the SDK library:
To build a plugin:
Unix Plug-in modules under Unix are shared object modules, or DSO files. When compiling, remember to define both _XGL and the preprocessor symbol for your CPU. _mod_descrip must be exported from the DSO, and servmain.o must be among the objects passed to the linker. The link line should include any other libraries that the plug-in would need as a stand-alone program. .o.p:
ld -shared -exported_symbol _mod_descrip -L$(SDK_LIB) \
$(SDK_LIB)servmain.o $*.o -o $@ -lserver.lib $(OTHER_LIBS)
|