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. Thecontext
is a context ID returned bycontextCreate
, or NULL if you don't want to add any input parameters for the texture. Theuserdata
is any data you'd like to associate with the texture. You can retrieve it using theuserdata
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 infopntVLookup
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
andnext
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 theo
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 tocontextAddParam
for this parameter. Thepindex
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 thecontextAddParam
function, 2 for the second parameter, and so on. The 0 index is reserved for the Previous Layer parameter, which always exists. Themicropol
is the micropolygon passed to the texture. Thepdata
argument is the user data you returned from yourparamTime
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. Theuserdata
is the same as that returned by theuserdata
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 ); } }