Globals: Surface Functions

Surface Functions

Availability  LightWave 6.0
Component  Layout, Modeler
Header  lwsurf.h

This global allows you to get information about surfaces and surface parameters.

Global Call

   LWSurfaceFuncs *surff;
   surff = global( LWSURFACEFUNCS_GLOBAL, GFUSE_TRANSIENT );

The global function returns a pointer to an LWSurfaceFuncs.

   typedef struct st_LWSurfaceFuncs {
      LWSurfaceID   (*create)      (const char *objName,
                                      const char *surfName);
      LWSurfaceID   (*first)       (void);
      LWSurfaceID   (*next)        (LWSurfaceID);
      LWSurfaceID * (*byName)      (const char *name, const char *obj);
      LWSurfaceID * (*byObject)    (const char *name);
      const char *  (*name)        (LWSurfaceID);
      const char *  (*sceneObject) (LWSurfaceID);
      int           (*getInt)      (LWSurfaceID, const char *channel);
      double *      (*getFlt)      (LWSurfaceID, const char *channel);
      LWEnvelopeID  (*getEnv)      (LWSurfaceID, const char *channel);
      LWTextureID   (*getTex)      (LWSurfaceID, const char *channel);
      LWImageID     (*getImg)      (LWSurfaceID, const char *channel);
      LWChanGroupID (*chanGrp)     (LWSurfaceID);
      const char *  (*getColorVMap)(LWSurfaceID surf);
      void          (*setColorVMap)(LWSurfaceID surf,
                                      const char *vmapName, int type);
   } LWSurfaceFuncs;

surf = create( objname, surfname )

Create a new surface. The object name is the filename, which you can get from the Object Info filename function and Modeler's State Query object function, given the object's item ID.

surf = first()

Returns the ID of the first surface in the surfaces list.

surf = next( surf )

Returns the ID of the next surface in the surfaces list (the one following the argument).

surfarray = byName( surfname, objname )

Returns the IDs of the (possibly many) surfaces with a given name. Different objects can have surfaces of the same name. If objname is NULL, the array will contain every surface ID named surfname, regardless of which object it belongs to. The array of surface IDs is terminated by an ID of NULL.

surfarray = byObject( objname )

Returns the surfaces belonging to the object. The object name is the filename.

surfname = name( surf )

Returns the name of a surface.

scenename = sceneObject( surf )

Returns the filename of the object to which the surface belongs.

val = getInt( surf, channel )

Returns the value of the surface parameter (evaluates the channel) at the current time. Use this function for integer parameters and getFlt for floating-point parameters. The channel is one of the channel names listed in lwsurf.h.

valarray = getFlt( surf, channel )

Returns the value of the surface parameter. The return value in most cases points to one double, but for colors, it points to three.

envelope = getEnv( surf, channel )

Returns the envelope ID for the surface parameter. This can be used with the Animation Envelopes global.

texture = getTex( surf, channel )

Returns a texture ID for the surface parameter that can be used with the Texture Functions global.

image = getImg( surf, channel )

Returns the image associated with the surface parameter. This function is limited to use with surface channels that refer directly to images, e.g. SURF_RIMG and SURF_TIMG (reflection and refraction maps). Images that are part of textures have to be obtained through the Texture Functions global.

group = chanGrp( surf )

Returns the channel group for the surface. This is the parent group for envelopes associated with the surface's parameters. It can be used with the Channel Info global. Note: because of a bug, this field may be NULL in some builds of LightWave 6.

name = getColorVMap( surf )

Returns the name of the vertex color map for the surface.

setColorVMap( surf, vmapname, type )

Set the surface's vertex color map. The type can be LWVMAP_RGB (the vmap has a dimension of 3 and contains red, green and blue levels) or LWVMAP_RGBA (dimension of 4, with RGB and alpha levels).

Example

The scenscan SDK sample includes a getObjectSurfs function that collects surface information for all of an object's surfaces.

For some parameters, you'll want to consult the object file format specification, since the form of the data returned by the get functions is in some cases the same as its binary image in the object file. This code fragment reads and interprets the reflection options.

   #include <lwserver.h>
   #include <lwsurf.h>

   LWSurfaceFuncs *surff;
   LWSurfaceID surfid;
   LWImageID rimg;
   double refl, rsan, *dval;
   int rfop;

   ... assume surff and surfid have been initialized ...

   dval = surff->getFlt( surfid, SURF_REFL );        // reflectivity
   refl = *dval;
   if ( refl > 0.0f ) {
      rfop = surff->getInt( surfid, SURF_RFOP );     // options
      switch ( rfop ) {
         case 0:  /* backdrop only */       ... break;
         case 1:  /* raytrace + backdrop */ ... break;
         case 2:  /* spherical map */       ... break;
         case 3:  /* raytrace + map */      ... break;
      }
      if ( rfop == 2 || rfop == 3 ) {
         rimg = surff->getImg( surfid, SURF_RIMG );  // image map
         dval = surff->getFlt( surfid, SURF_RSAN );  // seam angle
         rsan = *dval;
      }
   }