Classes Handlers Table of Contents

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


Layout

Modeler



Backdrop Info
Bone Info
Camera Info
Comp Info
Dopetrack Proxy
Fog Info
Global Memory
Interface Info
Item Info
Layout Monitor
Object Info
Particle Services
Scene Info
Time Info
Viewport Info
Volume Evaluation
List Info
Timer
Dynamic Monitor
Font List
State Query

Common


Animation Envelopes
Channel Info
Color Picker
Communication Ring
Context Menu Services
Directory Info
Dynamic Conversion
Dynamic Request
File I/O
File Request
File Request 2
File Type Pattern
Host Display Info
Image List
Image Utility
Info Messages
Instance Update
Light Info
Locale Info
Multithreading Utilities
Node Editor Func
Panels
Preview Functions
Product Info
Raster Services
Scene Objects
Server Info
Shelf Functions
Surface Editor
Surface Functions
System ID
Texture Editor
Texture Functions
Variant Parameters
XPanels
 

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.