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.

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-specific versions of the XCALL_ macro and the HostDisplayInfo structure (don't worry if you don't know what those are yet), and they determine what is stored in the system identification fields of the module descriptor. The operating system defines are

   _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.

Data type	*Address must be...*
`char`	any
`short (16-bit)`	even
`int, long (32-bit)`	divisible by 4
`float`	divisible by 4
`double`	divisible by 8
`structures`	aligned for the largest member
`unions`	aligned for the first member

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,

Create a new project workspace, or insert a new project into an existing workspace. The project type should be "Static Library." Name the project "server".
Settings dialog, C/C++ tab, add _X86_ (or _ALPHA_) and _WIN32 to the preprocessor definitions field.
In the field for additional include directories, type the path to the plug-in SDK include directory.
Add servdesc.c, username.c, startup.c, and shutdown.c to the project. These are located in the SDK\source directory.
Build server.lib.

To create a plug-in,

Create a new project workspace, or insert a new project into an existing workspace. The project type should be "Dynamic-Link Library."
Settings dialog, C/C++ tab, add _X86_ (or _ALPHA_) and _WIN32 to the preprocessor definitions field.
In the field for additional include directories, type the path to the plug-in SDK include directory.
Add your source files to the project. Also add servmain.c, server.lib and serv.def.

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,

Settings dialog, Debug tab, enter the full path to lightwav.exe or modeler.exe, as appropriate, in the field labeled "Executable for debug session."
Set the working directory to the directory containing the LightWave executables.
Build a debug version of your plug-in.

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

Information provided by Michal Koc.

Before creating any plug-ins, you'll need to build a Borland version of the SDK library.

Create a new project
Set the Target Type to Static Library (for .dll) [.lib]
In Standard Libraries, mark Static
Set the Platform to Win32
Set the Target Model to GUI
Add nodes with the files servdesc.c, username.c, startup.c, and shutdown.c
Options/Project/Directories, set the include and lib paths
Options/Project/Compiler/Defines, add _X86_ and _WIN32
Options/Project/Compiler/Code Generation, set fastthis
Options/Project/32-bit Compiler, set Processor and Data alignment to 8 bytes
Compile

To build a plug-in,

Create a new project
Set the Target Type to Dynamic Library [.dll]
In Standard Libraries, mark Dynamic
Set the Platform to Win32
Set the Target Model to GUI
Add nodes with servmain.c, server.lib, and your source files; remove unused nodes
Options/Project/Directories, set include and lib paths
Options/Project/Compiler/Defines, add _X86_ and _WIN32
Options/Project/Compiler/Code Generation, set fastthis
Options/Project/32-bit Compiler, set Processor and Data aligment to 8 bytes
Compile

GNU gcc/Mingw32

Information provided by Dan Maas

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.)

cd to the SDK source directory.
Compile the library sources.
gcc -c -D_WIN32 -D_X86_ -O6 -I$(LWSDK_INCL) servmain.c servdesc.c username.c startup.c shutdown.c
Assemble the library.
ar r libserver.a servdesc.o username.o startup.o shutdown.o

To build a plug-in,

Compile your source files.
gcc -c -D_WIN32 -D_X86_ -O6 -I$(LWSDK_INCL) myplug.c
Link to the SDK library and generate a DLL.
dllwrap -o myplug.p --export-all --dllname myplug.p myplug.o $(LWSDK_LIB)servmain.o $(LWSDK_LIB)libserver.a

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,

Add the SDK include directory to the include path [-i]
Disable stack depth checking [-s]
Add macro definitions [-d] _X86_ and _WIN32
Change char default to signed [-j]
Use 8-byte structure alignment [-zp8]
Use the 32-bit flat memory model [-mf] (the default)
Use the stack-based calling convention [-5s]
Export [exp] _mod_descrip

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.

Create a new, empty project.
Target Settings/Linker, choose Mac OS PPC Linker.
PPC Target/Project Type, choose Library.
PPC Target, name the file server.lib.
PPC Processor, set alignment to PowerPC (the default).
Define the _MACOS and _PPC_ preprocessor symbols.
Access Paths/Systems Paths, add the SDK include directory.
Add servdesc.c, username.c, startup.c, and shutdown.c. These are located in the SDK source directory.
Build.

To create a plug-in project,

Create a new, empty project.
Target Settings/Linker, choose Mac OS PPC Linker.
PPC Target/Project Type, choose Shared Library.
Define the _MACOS and _PPC_ preprocessor symbols.
Access Paths/Systems Paths, add the SDK include directory.
PPC PEF/Export Symbols, choose the method you'll use to export _mod_descrip. See the CodeWarrior shared library documentation for an explanation of the available methods.
C/C++ Language, turn on Relaxed Pointer Type Rules and Enums Always Int.
Add your source code files to the project, along with servmain.c.
Add server.lib and MSL Runtime-PPC.Lib to the project. If the plug-in calls Mac Toolbox routines, you'll also need to add InterfaceLib (or CarbonLib if you're compiling for OS X), but consider building your interface using the platform-independent components provided with the plug-in SDK instead.

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

Information provided by Mark Nutter

Before building any plugins, you'll need to build an MPW version of the SDK library:

In the MPW worksheet, select "Set Directory..." from the Directory menu and set the working directory to the source directory of the SDK.
Select "Create Build Commands..." from the Build menu.
Enter server.lib as the Program Name.
Select "Static Library" as the Program Type.
Check "PowerPC Only" as the Target.
Add servdesc.c, startup.c, shutdown.c and username.c as the Source Files. These are in the SDK source directory.
Click the Include Search Paths button and Add the SDK include directory.
Click the PowerPC Options button and enter -d _MACOS -d _PPC_ in the "C Options" field.
Click the Create Make button to generate a makefile for server.lib.
Select Build (Cmd-B) from the Build menu. The program name should come up as server.lib by default. Click OK to build server.lib. You will get a warning that "serverData" is not used within function "Shutdown", which you can ignore.

To build a plugin:

Select "Set Directory..." from the Directory menu and set the working directory to the directory containing your plug-in's source files.
Select "Create Build Commands..." from the Build menu.
Enter your plug-in's name as the Program Name.
Select "Shared Library" as the Program Type.
Check "PowerPC Only" as the Target.
Add the source files for your plug-in. Also add servmain.c (in the SDK source directory) and the server.lib you created.
Click the Include Search Paths button and Add the SDK include directory.
Click the PowerPC Options button and enter -d _MACOS -d _PPC_ -typecheck relaxed in the "C Options" field.
Click the Exported Symbols button and enter _mod_descrip in the Export Symbols box.
Click the CreateMake button to create your makefile.
Build (Cmd-B).

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)