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.

contextDestroy( context )

Free resources allocated by contextCreate.

contextAddParam( context, param )

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.

TRT_VECTOR
TRT_COLOR
TRT_PERCENT
TRT_SCALAR
TRT_DISPLACEMENT

The name is used to identify the texture in the user interface. The context is a context ID returned by contextCreate, or NULL if you don't want to add any input parameters for the texture. The userdata is any data you'd like to associate with the texture. You can retrieve it using the userdata function.

destroy( texture )

Free the texture.

copy( to, from )

Copy a texture.

newtime( texture, time, frame )

Prepare the texture to be evaluated at a new render time. This allows the texture to do time-dependent precalculations.

cleanup( texture )

Call this when calculations using the texture are completed, typically after the last frame has been rendered.

load( texture, loadstate )

Read the texture from a file.

save( texture, savestate )

Write the texture to a file.

alpha = evaluate( texture, micropol, value )

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.

tlayer = firstLayer( texture )
tlayer = lastLayer( texture )
tlayer = nextLayer( texture, tlayer )

Enumerate the texture's layers. The layer ID returned by these functions can be passed to functions that return the layer's data.

tlayer = layerAdd( texture, type )

Add a texture layer. The type is one of the following.

TLT_IMAGE

An image map.

TLT_PROC

A procedural texture.

TLT_GRAD

A gradient.

layerSetType( tlayer, type )

Change the layer type.

type = layerType( tlayer )

Returns the layer type.

alpha = layerEvaluate( tlayer, micropol, value )

Evaluate the layer. Like the evaluate function, but it calculates the texture value only for the specified layer.

changroup = layerEnvGroup( tlayer )

Returns the channel group for the layer's enveloped parameters.

result = setParam( tlayer, tag, value )
result = getParam( tlayer, tag, value )

Set or get a layer parameter. The tag identifies the parameter and its data type.

TXTAG_POSI (double [3])
TXTAG_ROTA (double [3])
TXTAG_SIZE (double [3])

The origin, rotation and scale of the texture layer.

TXTAG_FALL (double [3])

Falloff, an amount per unit distance.

TXTAG_PROJ (int *)

Projection type for image maps, which can be one of the following.

TXPRJ_PLANAR
TXPRJ_CYLINDRICAL
TXPRJ_SPHERICAL
TXPRJ_CUBIC
TXPRJ_FRONT
TXPRJ_UVMAP

TXTAG_AXIS (int *)

The texture axis, for image map projections that require one.

TXTAG_WWRP (double *)
TXTAG_HWRP (double *)

Width and height wrap amount. Some projection types use this to tile the texture image.

TXTAG_COORD (int *)

The coordinate system. This is 1 for world coordinates (the texture doesn't move with the object), and 0 for object coordinates.

TXTAG_IMAGE (LWImageID *)

The image for image mapped layers. The value is a pointer to an image ID, typically obtained from the Image List load function.

TXTAG_VMAP (VMapID *)

The vertex map used, for example, by UV mapped and weight mapped textures. The value is the opaque pointer returned by the MeshEditOp pointVSet function or the mesh info pntVLookup function.

TXTAG_ROBJ (LWItemID *)

The reference object, from which the texture origin, rotation and scale will be taken. The item ID is typically obtained from the Item Info first and next functions.

TXTAG_OPAC (double *)

Layer opacity.

TXTAG_AA (int *)

Boolean, whether texture antialiasing is enabled for the layer.

TXTAG_AAVAL (double *)

Antialiasing threshold. The texture value will only be antialiased if it differs from adjacent values by an amount greater than this threshold.

TXTAG_PIXBLEND (int *)

Boolean, whether pixel blending is enabled. Pixel blending is a form of antialiasing that's active in regions where the texture resolution is lower than the output resolution.

TXTAG_WREPEAT (int *)
TXTAG_HREPEAT (int *)

Width and height repeat behavior.

TXRPT_RESET
TXRPT_REPEAT
TXRPT_MIRROR
TXRPT_EDGE

evaluateUV( tlayer, waxis, oaxis, opos, wpos, uv )

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.

data = userData( texture )

Returns whatever was passed as the user data argument to the create function.

changroup = envGroup( texture )

Returns the channel group for the texture.

id = texture( layer )

Returns the texture ID, given any layer in the texture.

tname = name( texture )
datatype = type( texture )
ctxt = context( 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.

pdata = paramTime( userdata, pdesc, pindex, time, frame )

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.

paramCleanup( pdesc, pindex, pdata )

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.

start, end

The nominal limits of the parameter's value. These form the endpoints of a gradient.

type

The data type of the parameter, which can be one of the following.

LWIPT_FLOAT
LWIPT_DISTANCE
LWIPT_PERCENT
LWIPT_ANGLE

flags

Parameter flags.

LWGF_FIXED_MIN

The minimum parameter value is fixed.

LWGF_FIXED_MAX

The maximum value is fixed.

LWGF_FIXED_START

The start value is fixed.

LWGF_FIXED_END

The end value is fixed.

itemType, itemID, itemName

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

LWGI_NONE
LWGI_OBJECT
LWGI_LIGHT
LWGI_CAMERA
LWGI_BONE
LWGI_VMAP

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;
   } 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.

ray

The direction of the incoming viewing ray.

txVal

The initial value that will be modified by the texture.

srfID

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

context

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.

TCC_ANY

All layers will be evaluated.

TCC_OBJECT

Only object coordinate layers will be evaluated.

TCC_WORLD

Only world coordinate layers will be evaluated.

History

In LightWave 7.0, the server name for this global (LWTEXTUREFUNCS_GLOBAL) was incremented from "Texture Functions" to "Texture Functions 2", and the texture, name, type and context functions 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 );
      }
   }