ProceduralTextureHandler
ProceduralTextureInterface

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

Fundamentally, a procedural texture is a function of three variables. In other words, given three numbers x, y and z, a procedural texture calculates and returns a fourth number t.

The variables are usually the coordinates of a 3D position, either in world space or in some idealized texture space, and the number returned by the function is used to modulate a rendering parameter, typically one of the surface attributes. LightWave®'s built-in fractal noise is an example of a procedural texture.

Some procedural textures will also return a gradient. Roughly speaking, this is the direction of the texture at the sample point, or the direction in which the value of the texture function increases the fastest. If the texture is being used as a bump map, the renderer can infer a bump normal from the gradient.

If your texture function is analytical, you can compute the gradient from the partial derivative of the function with respect to each axis. You aren't required to form the gradient that way, or at all. If the texture doesn't return a gradient, the renderer will calculate a numerical approximation by calling your texture function at six neighboring points.

Textures can also return a color. This is useful when the texture will be applied to the color channel of a surface or will modulate some other color-valued parameter.

Handler Activation Function

   XCALL_( int ) MyTexture( int version, GlobalFunc *global,
      LWTextureHandler *local, void *serverData );

The local argument to a texture's activation function is an LWTextureHandler.

   typedef struct st_LWTextureHandler {
      LWInstanceFuncs *inst;
      LWItemFuncs     *item;
      LWRenderFuncs   *rend;
      double          (*evaluate) (LWInstance, LWTextureAccess *);
      unsigned int    (*flags)    (LWInstance);
   } LWTextureHandler;

The first three members of this structure are the standard handler functions. In addition to these, a procedural texture provides an evaluation function and a flags function.

The context argument to the inst->create function is the LWTextureID for the texture. LWTextureID is defined in the lwtxtr.h header file and is used by the texture functions and texture editor globals.

A procedural texture can be activated by Modeler as well as Layout. When activated by Modeler, the LWItemFuncs pointer in the local data is NULL. Be sure to test for this before filling in the useItems and changeID fields. Note too that if your texture relies on Layout-only globals, those won't be available when Modeler calls your callbacks.

txval = evaluate( instance, access )

Returns a texture value, given the information in the access structure, described below.

flagbits = flags( instance )

Returns an int that tells LightWave® about the texture. The return value can be any of the following flags combined using bitwise-or.

LWTEXF_GRAD

The texture returns a gradient (the evaluation function sets the value of the txGrad member of the access structure). If this flag isn't set, the texture engine ignores txGrad and, when necessary, calculates the gradient numerically (by evaluating 6 neighboring points).

LWTEXF_SLOWPREVIEW

Set this if the texture evaluates too slowly to be previewed in real time.

LWTEXF_AXIS

The texture uses an axis. The texture editor will allow the user to select an axis for the texture, and this selection will be found in the axis member of the access structure.

LWTEXF_AALIAS

The texture value is already antialiased. Currently ignored, but it may not be in the future.

LWTEXF_DISPLACE

Use the texture value for displacements. If this flag is set, the texture editor's axis selector is enabled and the displacement occurs along the selected axis. If this flag isn't set, but LWTEXF_GRAD is, the texture engine will use the gradient for displacements. If neither flag is set, no displacement will occur.

LWTEXF_HV_SRF

The texture is appropriate for use as a HyperVoxels surface texture. This basically means that the texture function is continuous and evaluates relatively quickly.

LWTEXF_HV_VOL

The texture is appropriate for use as a HyperVoxels volume texture. Efficiency is especially important for these textures.

LWTEXF_SELF_COLOR

The texture returns an RGBA color in addition to a value.

Interface Activation Function

   XCALL_( int ) MyInterface( int version, GlobalFunc *global,
      LWInterface *local, void *serverData );

This is the standard interface activation for handlers.

Texture Access

The access structure passed to the evaluation function contains parameters that can affect the texture value. The texture can return a gradient and a color through the txGrad and txRGBA fields. The other fields are read-only.

   typedef struct st_LWTextureAccess {
      double  wPos[3];
      double  tPos[3];
      double  size[3];
      double  amp;
      double  spotSize;
      double  txGrad[3];
      int     axis;
      int     flags;
      double  octaves;
      double  txRGBA[4];
   } LWTextureAccess;

wPos

The world coordinate position of the sample to be textured.

tPos

The position of the sample in texture coordinates.

size

The size of the texture. The size value is used to scale the texture spatially. The interpretation is up to the texture, but typically this is the size of a texture cell or the distance between repeating elements.

amp

The amplitude of the texture. This value is typically used to scale the magnitude or strength of the texture.

spotSize

The approximate diameter of the sample spot. This is useful when antialiasing the texture.

txGrad

Storage for the texture gradient at the sample. The evaluation function must fill this in when the flags function returns LWTEXF_GRAD. Otherwise it can be ignored.

axis

The texture axis selected by the user. Only valid if the flags function set the LWTEXF_AXIS or LWTEXF_DISPLACE flags.

flags

The access flags provide information about the context in which the evaluation function was called.

LWTXEF_VECTOR

Set when a bump is being evaluated.

LWTXEF_AXISX
LWTXEF_AXISY
LWTXEF_AXISZ

Which dimensions are used for evaluation. Currently, all three of these are always set, but in the future, the texture engine might evaluate the texture in 2D only, for example, and it would use these flags to allow the texture to switch to an evaluation optimized for 2D.

LWTXEF_DISPLACE

Set when a displacement is being evaluated.

LWTXEF_COLOR

Set when a color is being evaluated.

octaves

The number of octaves, or frequencies, that should be used by the texture. This affects the amount of structure the texture generates at different scales. This field is currently only initialized by HyperVoxels.

txRGBA

Storage for the texture color at the sample. The evaluation function must fill this in when the flags function returns LWTEXF_SELF_COLOR. Otherwise it can be ignored..

Example

The rapts sample contains 10 procedural textures.