• Home

• Introduction
• Compiling
• Common Elements
• Compatibility
• Classes
• Globals
• Handlers
• Commands

• DynaValues
• File I/O
• Image I/O
• Mesh Info
• Raytracing

• File Formats
• Change History
• Articles
• Tables

Globals

Globals are services that any plug-in can request by calling the global function. This is passed as the second argument to every plug-in's activation function. Global services allow you to construct platform-independent user interfaces for your plug-ins and to query and modify LightWave's internal state.

Index

The Global Function

The second argument to every activation function is a GlobalFunc.

   typedef void * GlobalFunc (const char *serviceName, int useMode);

The service name is a string that tells the global function which global service is being requested. It can be any of the globals supplied with LightWave and listed in the table above, or a custom global provided by a Global class plug-in.

The SDK header files define symbolic names for the service name strings of globals supplied with LightWave. The string for the current version of the Scene Info global, for example, is "LW Scene Info 2", but rather than use this string literal in your source code, you can use the symbolic name LWSCENEINFO_GLOBAL, defined in lwrender.h.

   LWSceneInfo *sceneinfo;
   sceneinfo = global( LWSCENEINFO_GLOBAL, GFUSE_TRANSIENT );

Using the symbolic name helps to ensure that your code is always synchronized with the headers you're currently compiling with. They're also a little easier to remember, since in most cases the symbolic name is the same as the type of the data object returned by the global function.

The use mode tells LightWave whether to lock the code module that supplies the global service. It can be GFUSE_ACQUIRE or GFUSE_TRANSIENT.

During routine housekeeping, LightWave may free memory by unloading plug-ins that haven't been called recently, and this can include Global class plug-ins. If you've requested a service provided by a Global class plug-in, the data and function pointers returned by the global function would become invalid if the Global plug-in were allowed to disappear from memory. The GFUSE_ACQUIRE mode locks the module, ensuring that it won't be unloaded from memory before you use it.

Globals obtained with GFUSE_ACQUIRE should be unlocked when they're no longer needed. You unlock them by calling the global function with a use mode of GFUSE_RELEASE.

   global( LWSCENEINFO_GLOBAL, GFUSE_RELEASE );

Failing to unlock a global usually isn't fatal, but it prevents LightWave from optimizing its use of memory. And locking a module doesn't prevent other plug-ins from using it.

Use the GFUSE_TRANSIENT mode when the global doesn't have to be locked. GFUSE_TRANSIENT is safe to use for the global services built into LightWave and when the services provided by Global class plug-ins are used immediately.

If the call to the global function succeeds, the return value is data, typically a pointer to a structure, that's specific to the requested global service. The documentation of the globals supplied with LightWave describes what each global returns. If the global call fails, a possibility that callers should always be prepared for, the return value is NULL.