Globals: Texture Functions

Texture Functions

Availability LightWave® 6.0
Component Layout, Modeler
Header lwtxtr.h

The Texture Functions global gives plug-ins access to LightWave®'s texture engine. A plug-in can create and use textures to modulate its parameters, and it can read and modify the settings of existing textures.

Global Call

   LWTextureFuncs *txfunc;
   txfunc = global( LWTEXTUREFUNCS_GLOBAL, GFUSE_TRANSIENT );

The global function returns a pointer to an LWTextureFuncs.

   typedef struct st_LWTextureFuncs {
      LWTxtrContextID (*contextCreate)(LWTxtrParamFuncs);
      void          (*contextDestroy) (LWTxtrContextID);
      void          (*contextAddParam)(LWTxtrContextID,
                                         LWTxtrParamDesc);
      LWTextureID   (*create)       (int returnType, const char *name,
                                       LWTxtrContextID, void *userdata);
      void          (*destroy)      (LWTextureID);
      void          (*copy)         (LWTextureID to, LWTextureID from);
      void          (*newtime)      (LWTextureID, LWTime, LWFrame);
      void          (*cleanup)      (LWTextureID);
      void          (*load)         (LWTextureID, const LWLoadState *);
      void          (*save)         (LWTextureID, const LWSaveState *);
      double        (*evaluate)     (LWTextureID, LWMicropolID, double *);
      void          (*setEnvGroup)  (LWTextureID, LWChanGroupID);
      LWTLayerID    (*firstLayer)   (LWTextureID);
      LWTLayerID    (*lastLayer)    (LWTextureID);
      LWTLayerID    (*nextLayer)    (LWTextureID, LWTLayerID);
      LWTLayerID    (*layerAdd)     (LWTextureID, int type);
      void          (*layerSetType) (LWTLayerID, int type);
      int           (*layerType)    (LWTLayerID);
      double        (*layerEvaluate)(LWTLayerID, LWMicropolID, double *);
      LWChanGroupID (*layerEnvGrp)  (LWTLayerID);
      int           (*setParam)     (LWTLayerID, int tag, void *data);
      int           (*getParam)     (LWTLayerID, int tag, void *data);
      void          (*evaluateUV)   (LWTLayerID, int wAxis, int oAxis,
                                       double oPos[3], double wPos[3],
                                       double uv[2]);
      double        (*noise)        (double p[3]);
      void *        (*userData)     (LWTextureID);

      LWChanGroupID (*envGroup)     (LWTextureID);
      LWTextureID   (*texture)      (LWTLayerID);
      const char *  (*name)         (LWTextureID);
      int           (*type)         (LWTextureID);
      LWTxtrContextID (*context)    (LWTextureID);
   } LWTextureFuncs;

It's helpful to divide these functions into three categories according to whether they deal with contexts, handler calls, or texture settings. Plug-ins that use textures to modify their own parameters will mostly use functions in the first two groups, since typically the texture settings are supplied by the user through the Texture Editor. The last group is more often useful when plug-ins want to query or modify existing textures.

Contexts

Some texture layer types use additional parameters to modify the texture value. Currently this is a gradient thing. The texture context is used to populate and support the Input Parameter menu for gradient layers in the Texture Editor.

context = contextCreate( paramfuncs ): Create a texture context. The Texture Editor uses the callbacks in the paramfuncs argument to get the value of the parameters.
: Free resources allocated by contextCreate. A texture context may only be destroyed after all textures using the context have been destroyed.
: Add a parameter to the context. For gradient layers, this parameter will be added to the Input Parameter menu.

Handler Calls

The functions in this group call the texture's handler callbacks. See the document for the procedural texture plug-in class for more information about the other side of these calls. In most cases, you'll call these from within your own plug-in's handler callbacks. In all cases, however, these functions must be called in proper handler order. The newtime function, for example, must be called before calling evaluate.

texture = create( returntype, name, context, userdata ): Create a texture. The LWTextureID returned by this function is a container that will hold one or more texture layers. The final value of the texture is a combination of the values calculated for each layer. The data type of the texture value can be one of the following.
destroy( texture ): Free the texture.
: Copy a texture.
: Prepare the texture to be evaluated at a new render time. This allows the texture to do time-dependent precalculations.
: Call this when calculations using the texture are completed, typically after the last frame has been rendered.
: Read the texture from a file.
: Write the texture to a file.
: Evaluate the texture. You must initialize the LWMicropol structure, described later. The result is returned in value.

Texture Data

These functions are used to get and set the data that defines a texture.

setEnvGroup( texture, changroup ): Set the channel group to be used by the texture. Envelopes created for parameters in the texture's layers will belong to this group.
: Enumerate the texture's layers. The layer ID returned by these functions can be passed to functions that return the layer's data.
: Add a texture layer. The type is one of the following.
: Change the layer type.
: Returns the layer type.
: Evaluate the layer. Like the evaluate function, but it calculates the texture value only for the specified layer.
: Returns the channel group for the layer's enveloped parameters.
: Set or get a layer parameter. The tag identifies the parameter and its data type.

For texture layers that use one of the implicit image mapping projections (planar, cubic, cylindrical, spherical), returns the UV coordinates for a given position. If the texture uses an explicit UV mapping, the UV coordinates can be obtained directly from the vertex map through mesh info or MeshEditOp functions.

The w arguments are in world coordinates, and the o arguments are in object coordinates. The axis arguments are the dominant axis for cubic mapping and can be 0, 1 or 2 for the X, Y or Z axis. This is usually chosen as the polygon normal component that's largest in absolute value. For projections other than cubic, these arguments are ignored. The position arguments specify the position for which the UV should be returned.
value = noise( pos ): Easy access to a noise function.
: Returns whatever was passed as the user data argument to the create function.
: Returns the channel group for the texture.
: Returns the texture ID, given any layer in the texture.
: These return information about the texture. The information is the same as that supplied in the first three arguments to the create function.

Parameter Callbacks

The argument to the contextCreate function is an LWTxtrParamFuncs, which contains callbacks for evaluating the input parameters. These callbacks are functions in your plug-in that determine the value of the parameter.

   typedef struct st_LWTxtrParamFuncs {
      double     (*paramEvaluate)(LWTxtrParamDesc *, int paramnum,
                                    LWMicropol *, gParamData);
      gParamData (*paramTime)    (void *userData, LWTxtrParamDesc *,
                                    int paramnum, LWTime, LWFrame);
      void       (*paramCleanup) (LWTxtrParamDesc *, int paramnum,
                                    gParamData);
   } LWTxtrParamFuncs;

value = paramEvaluate( pdesc, pindex, micropol, pdata ): Returns the value of the parameter. The pdesc is the parameter description you passed to contextAddParam for this parameter. The pindex is an integer identifying the parameter by the order in which it was created. It's 1 for the parameter created by your first call to the contextAddParam function, 2 for the second parameter, and so on. The 0 index is reserved for the Previous Layer parameter, which always exists. The micropol is the micropolygon passed to the texture. The pdata argument is the user data you returned from your paramTime callback.
: The init function for the parameter. This is called before paramEvaluate so that you can perform precalculations for your parameter. The userdata is the same as that returned by the userdata function.
: The cleanup function for the parameter. This allows you to free any resources allocated in your paramTime.

Parameter Descriptor

The second argument to contextAddParam is a description of the parameter contained in an LWTxtrParamDesc structure. This structure is also passed to your parameter callbacks.

   typedef struct st_LWTxtrParamDesc{
      char     *name;
      double    start;
      double    end;
      int       type;
      int       flags;
      int       itemType;
      LWItemID  itemID;
      char     *itemName;
   } LWTxtrParamDesc;

name: The name of the parameter as it should appear in the user interface.
: The nominal limits of the parameter's value. These form the endpoints of a gradient.
: The data type of the parameter, which can be one of the following.
flags: Parameter flags.
: If the parameter depends on a scene item, these fields describe the item. The type can be one of the following. (If the parameter doesn't use an item, the type should be LWGI_NONE.)

Micropolygon Descriptor

The micropolygon provides the geometry information used to evaluate a texture. You need to initialize one of these before calling evaluate or layerEvaluate. You also receive one of these in your parameter callbacks.

   typedef struct st_LWMicropol {
      double            oPos[3];
      double            wPos[3];
      double            oScl[3];
      double            gNorm[3];
      double            wNorm[3];
      double            ray[3];
      double            bumpHeight;
      double            txVal;        
      double            spotSize;
      double            raySource[3];         
      double            rayLength;         
      double            cosine;            
      double            oXfrm[9];
      double            wXfrm[9];
      LWItemID          objID;
      LWItemID          srfID;
      LWPntID           verts[4];
      float             weights[4];
      float             vertsWPos[4][3];
      int               polNum;
      int               oAxis;
      int               wAxis;
      int               context;
      LWIlluminateFunc *illuminate;
      LWRayTraceFunc   *rayTrace;
      LWRayCastFunc    *rayCast;
      LWRayShadeFunc   *rayShade;
      void             *userData;
      LWPolID           polygon;
      LWVertexIndexes  *VertexIndexes;
  } LWMicropol;

Almost all of the micropolygon fields correspond to fields of the same name in LWShaderAccess. See the shader page for descriptions of those fields.

oScl: Texture scale in object coordinates.
: The direction of the incoming viewing ray.
: The initial value that will be modified by the texture.
: The ID of the surface associated with the texture. (Note: This is incorrectly typed as an LWItemID. Just cast the LWSurfaceID to LWItemID when setting this field.)
: This will be TCC_ANY in most cases. The other two are used when the texture needs to be evaluated in two separate steps, which is unusual.
VertexIndexes (LW8.2+): This contains indexes to original polygon vertexes, perspective weights, along with spot size data. See the LWVertexIndexes structure in lwtxtr.h.

History

In LightWave® 8.2, the server name for this global (LWTEXTUREFUNCS_GLOBAL) was NOT incremented; although the VertexIndexes member was added to LWMicroPol. The TXTAG_INPUT, TXTAG_AUVN, TXTAG_AUVU, TXTAG_AUVC,and TXTAG_AUVO tags were also added to LWTextureFuncs.

In LightWave® 7.5, the server name for this global (LWTEXTUREFUNCS_GLOBAL) was incremented from "Texture Functions 2" to "Texture Functions 3", and the TXTAG_ACTIVE, TXTAG_INVERT and TXTAG_BLEND tags were added to LWTextureFuncs.

Example

The txchan sample contains motion, channel, image filter and environment plug-ins, all of which use a texture to modulate their data. The texture layers are defined by the user and evaluated through the Texture Functions global.

The following code fragment demonstrates how to extract UV values for image maps associated with a surface.

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

   LWSurfaceFuncs *surff;
   LWTextureFuncs *txtrf;
   LWSurfaceID surf;
   LWTextureID tex;
   LWTLayerID tlayer;
   int type;

As always, you need to get the globals before you can use them.

   surff = global( LWSURFACEFUNCS_GLOBAL, GFUSE_TRANSIENT );
   txtrf = global( LWTEXTUREFUNCS_GLOBAL, GFUSE_TRANSIENT );

Each surface has many channels (Color, Diffuse, Luminous, Specular, etc.), and each channel can be textured. If a channel is textured, the texture can have many layers. It's at the level of the texture layer that you want to look for UVs.

   tex = surff->getTex( surf, SURF_COLR );
   if ( tex ) {
      tlayer = txtrf->firstLayer( tex );
      while ( tlayer ) {
         type = txtrf->layerType( tlayer );
         if ( type == TLT_IMAGE ) {

Now you have an image texture layer. You can ask what the projection is.

            int proj;
            txtrf->getParam( tlayer, TXTAG_PROJ, &proj );
            if ( proj == TXPRJ_UVMAP ) {

If the projection type is UV, get the vmap.

               void *vmap;
               txtrf->getParam( tlayer, TXTAG_VMAP, &vmap );

Use this with the mesh edit pointVSet and pointVEval functions to get the UVs. (You can also use the mesh info pntVSet, pntVGet and pntVPGet functions.)

               edit->pointVSet( edit->state, vmap, 0, NULL );
               for each point
                  edit->pointVEval( edit->state, pntID, polID, uv );
            }
            else {

If the projection is not UV, use evaluateUV.

               for each point
                  txtrf->evaluateUV( tlayer, wAxis, oAxis, oPos, wPos,
                     uv );
            }
         }
         tlayer = txtrf->layerNext( tlayer );
      }
   }