### 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`. A texture context may only be destroyed after all textures using the context have been destroyed. `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
`TXTAG_ACTIVE (int *)` Boolean, whether texture layer is active. `TXTAG_INVERT (int *)` Boolean, whether texture layer is inverted. `TXTAG_BLEND (int *)` Texture blending mode: `` `TXBLN_NORMAL` `TXBLN_SUBTRACT` `TXBLN_DIFFERENCE` `TXBLN_MULTIPLY` `TXBLN_DIVIDE` `TXBLN_ALPHA` `TXBLN_DISPLACE` `TXBLN_ADD` `TXTAG_INPUT (int *)` Input Parameter Index (value pointed to by data must be from 0 to 15) `TXTAG_AUVN (char *)` Anim UV Name `TXTAG_AUVU (char *)` Anim UV User `TXTAG_AUVC (int *)` Anim UV Plugin Options Array Byte Count `TXTAG_AUVO (char *)` Anim UV Plugin Options Array `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;
          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. `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. `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 );
          }
       }