Compiling LightWave® Plug-ins
LightWave® 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.
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-
_MSWIN /* 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.
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.
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).
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.
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_MSWIN .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 _MSWIN, 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.
There are additional defines usually setup by the compiler for Windows 64bit support such as _AMD64_ (for AMD 64bit) or _IA64_ (for Intel Itanium). The LWSDK is compatible with 64bit compilers by Intel and Microsoft.
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,
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_MSWIN -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.
There are two binary formats of LightWave ® available: PEF (often refered to as CFM) and Mach-O (often refered to as a universal binary). The binary format of plug-in modules must match the binary format of LightWave ® you wish to support; this means the CFM version of LightWave does not load Mach-O plug-ins, and the Mach-O version of LightWave does not currently load CFM plug-ins.
Mach-O plug-ins should be created with the latest version XCode (which as of this writing is XCode 2.4).
CFM plug-ins should be created with MetroWerks CodeWarrior (preferably version 10, the latest and last version available).
CodeWarrior (preferrably version 10)
Before compiling any plug-ins, you may want to build a CodeWarrior version of the SDK library. Alternatively, you may add individual SDK files to your plug-in's project directly.
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 OS X using the native debugger, you can use gdb in a terminal window. CodeWarrior 10 debugs in OS X well.
When the CFM version of the LightWave ® application is run, OS X actually runs a Mach-O wrapper application that loads the program. The wrapper is called LaunchCFMApp, located in
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.
XCode only will build plugins for the Mach-O (or universal binary) architecture, not CFM. You must bundle your dylib so that you do not experience unloading problems, which may not be very apparent during basic testing. Also needed with your plug-in bundle is a proper "info.plist" property list file. This file must properly identify the plug-in type identifiers.
To create an XCode 2 project for your plug-in:
The XCode/GCC build environment provides several preprocessor definitions you will find useful if you intend to write plugin code that is cross-platform compatible:
Macintosh Programmer's Workshop
Before building any plugins, you'll need to build an MPW version of the SDK library:
To build a plugin:
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)