Shader Class

Note

These interface classes are not intended for direct usage; rather they should be inherited by your own subclass. (See Anatomy of a LightWave Python Plug-in)

Handler

class lwsdk.IShader(self)

Bases: lwsdk.lwsdk.IHandlerFuncs, lwsdk.lwsdk.IInterfaceFuncs, lwsdk.lwsdk.IGizmoFuncs, lwsdk.lwsdk.IItemFuncs, lwsdk.lwsdk.IRenderFuncs

Proxy of C++ PCore::IShader class

 evaluate(LWShaderAccess arg0)

This is where the shader does its work. At each time step in the animation, the evaluation function is called for each pixel affected by the shader's surface. The LWShaderAccess instance (described below) contains information about the spot to be colored.

 flags() → unsigned int

Returns an int that tells the renderer which surface attributes the shader will modify and whether it will call the raytracing functions. The flags are bits combined using bitwise-or. They correspond to members of the shader access structure described below. For efficiency reasons, the renderer may ignore changes to any surface attributes that weren't indicated by the bit flags returned from this function, and it won't provide access to the raytracing functions unless the lwsdk.LWSHF_RAYTRACE bit is set. The possible flags values are:

lwsdk.LWSHF_NORMAL
lwsdk.LWSHF_COLOR
lwsdk.LWSHF_LUMINOUS
lwsdk.LWSHF_DIFFUSE
lwsdk.LWSHF_SPECULAR
lwsdk.LWSHF_MIRROR
lwsdk.LWSHF_TRANSP
lwsdk.LWSHF_ETA
lwsdk.LWSHF_ROUGH
lwsdk.LWSHF_TRANSLUCENT
lwsdk.LWSHF_RAYTRACE
lwsdk.LWSHF_DIFFUSE_SHADE
lwsdk.LWSHF_SPECULAR_SHADE
lwsdk.LWSHF_REFRACT_SHADE
lwsdk.LWSHF_REFLECT_SHADE

Access

class lwsdk.LWShaderAccess(self, LWShaderAccess source_)

Bases: object

Proxy of C++ PCore::LWShaderAccess class

 ResourceContextIndex → int

Current CPU thread running.

 addTransparency → double

Additive transparency. An additively transparent surface adds its own color to the colors of surfaces seen through it. This usually has the effect of lightening the color of the underlying surfaces.

 bounces → int

The number of times the viewing ray has branched, or bounced, before reaching this spot. This value can be used to limit recursion, particularly the shader's own calls to the raytracing functions.

 bumpDropoff → double

!! NOT DOCUMENTED !!

 bumpHeight → double

The relative height of peaks in the bump map. Increasing this value makes the bump mapping appear more pronounced. Currently this is used solely as a texture input. If no texture is applied to the bump channel of the surface, it will be 0, and values you write will be ignored.

 color → double[3]

The RGB components of the base color of the spot.

 colorFL → double

Color filtering amount. This controls how strongly the light passing through a transparent surface is colored by that surface, which affects the color of other surfaces illuminated by this light.

 colorHL → double

 cosine → double

The cosine of the angle between the raw surface normal and a ray pointing from the spot back toward the LWShaderAccess::raySource. This is the same as the dot product of LWShaderAccess::gNorm and the unit vector (raySource - wPos) / rayLength. Low values correspond to high angles and therefore glancing views. This is also a measure of how approximate the spot size is.

 difSharpness → double

Diffuse sharpness level. This controls how the shading varies with the angle of the light. Higher values make the brightness of illuminated areas more uniform and increase the sharpness of the transition between lit and dark areas (the terminator of a planet, for example).

 diffuse → double

Diffuse reflection level.

 diffuse_shade → double[3]

The RGB components of the diffuse shading color. The flag lwsdk.LWSHF_DIFFUSE_SHADE needs to be set for this to affect the shading.

 eta → double

Index of refraction. In the real world this ranges between 1.0 and about 3.5, depending on the material, but values outside that range are also valid here.

 flags → int

Bit fields describing the nature of the call. The lwsdk.LWRT_SHADOW bit tells you when the evaluation function is being called during shadow computations, which you might want to treat differently from "regular" shader evaluation.

 gNorm → double[3]

Geometric normal in world coordinates. This is the raw polygonal normal at the spot, unperturbed by smoothing or bump mapping.

 getSample1D(LWSamplerState arg1, unsigned int arg2) → float

Request a sample from the renderer. The index should range between the start and end range provided by LWShaderAccess::getSamplerRange().

 getSample2D(LWSamplerState arg1, unsigned int arg2) → float[2]

Request two samples from the renderer. The index should range between the start and end range provided by LWShaderAccess::getSamplerRange().

 getSamplerRange(LWSamplerState arg1, unsigned int arg2, unsigned int arg3) → float

The range of samples being requested by the renderer. This is relative to the current adaptive pass, if any. Returns the weight of the sample.

 getVal(LWRenderData rd, int type, int num, double arg1)

!! NOT IMPLEMENTED !!

 illuminate(LWItemID light, LWDVector position) → int

This function obtains the light ray (color and direction) hitting the given position from the given light at the current time step. The return value is zero if the light does not illuminate the given world coordinate position at all. The color includes effects from shadows (if any), falloff, spotlight cones and transparent objects between the light and the point.

 illuminateNormal(LWItemID light, LWRenderData rd, LWDVector position, LWDVector direction, LWDVector normal_vec, LWDVector color) → int

This new illumination function behaves the same way as their older counterparts, only it accepts a normal direction which is used by light evaluators to determine if any illumination from lights or shadow rays are to be cast for the spot.

 illuminateSample(LWItemID light, Vector pos, PyObject function, PyObject data) → PyObject

Illumination function, which calls the sampler function for each of the light rays. The sampler function receives the direction, color of the sample and the specified userdata.

 illuminateSampleNormal(LWItemID light, LWRenderData rd, LWDVector pos, LWDVector normal_vec, LightSampleFunc sampler, void data) → double

This new illumination function behaves the same way as their older counterparts, only it accepts a normal direction which is used by light evaluators to determine if any illumination from lights or shadow rays are to be cast for the spot.

 incomingEta → double

Incoming refraction index.

 instanceID → LWItemInstanceID

The instanceID will only be valid if the shader is being evaluated when an instance is being evaluated.

 luminous → double

Luminosity level. Higher values add more of the base color to the final color of the spot. This component is unaffected by lighting and shading.

 mirror → double

Mirror reflection level.

 oPos → double[3]

Spot position in object (Modeler) coordinates.

 oXfrm → double[9]

Object to world transformation matrix. The nine values in this array form a 3 x 3 matrix that describes the rotation and scaling of the object. This is useful primarily for transforming direction vectors (bump gradients, for example) from object to world space.

 objID → LWItemID

The object being shaded. It's possible for a single shader instance to be shared between multiple objects, so this may be different for each call to the shader's evaluation function. For sample sphere rendering the ID will refer to an object not in the current scene.

 polNum → int

An index identifying the polygon that contains the spot. It may represent other sub-object information in non-mesh objects. See also the polygon field.

 polygon → LWPolID

The polygon ID of the polygon containing the spot.

 randomData → RandomFloatData

This represents the internal state of the random number generator, and must be passed as the first argument to the LWShaderAccess::randomFloat() method.

 randomFloat(RandomFloatData arg1) → float

The function generates a random number on [>0, <1] interval.

 rayCast(LWDVector position, LWDVector direction) → double

This is a quicker version of the rayTrace function which only returns the distance to the nearest surface (or -1.0). It performs neither shading nor recursive raytracing.

 rayDir → LWDVector

The incoming ray direction.

 rayLength → double

The distance the viewing ray traveled in free space to reach this spot (ordinarily the distance between LWShaderAccess::raySource and LWShaderAccess::wPos).

 rayShade(LWDVector position, LWDVector direction, st_LWShaderAccess LWShaderAccess_rayShade_shader_access) → double

Trace a ray to the nearest surface and evaluate the basic surface parameters and any shaders on that surface. The LWShaderAccess structure passed (and owned) by the caller is filled in with the result and no more processing is done.

 raySource → double

Origin of the incoming viewing ray in world coordinates. This is often the camera, but it can also, for example, be a point on a reflective surface.

 rayTrace(LWDVector position, LWDVector direction) → double

Trace a ray from the given location in the given direction in world coordinates. The return value is the length of the ray (or -1.0 if infinite) and the color coming from that direction. The direction argument is the outgoing direction and must be normalized (a unit vector).

 rayTraceData(LWRenderData arg1, arg2)

Trace a ray using the data provided in the LWRayTraceData structure. This data is then used with LWShaderAccess::rayTraceShade() to shade the spot hit by the previous call to LWShaderAccess::rayTraceData(). Only distance, reflection and refraction rays are available for this function.

 rayTraceMode(LWDVector position, LWDVector direction, double eta, int rtmode) → double

Trace a ray from the given location in the given direction in world coordinates. The return value is the length of the ray (or -1.0 if infinite) and the color coming from that direction. The direction argument is the outgoing direction and must be normalized (a unit vector). The eta is the outgoing ray refraction index, and is only used when rtmode is lwsdk.RTMODE_REFRACTION. The rtmode parameter defines the outgoing ray type.

 rayTraceShade(arg1)

!! NOT DOCUMENTED !!

 reflect_shade → double[3]

The RGB components of the reflection shading color. The flag lwsdk.LWSHF_REFLECT_SHADE needs to be set for this to affect the shading. Reflectivity needs to be above 0 for this value to have effect. The color is multiplied by the reflectivity amount of the surface.

 reflectionBlur → double

The amount of blurring applied to reflections.

 refract_shade → double[3]

The RGB components of the refraction/transparency shading color. The flag lwsdk.LWSHF_REFRACT_SHADE needs to be set for this to affect the shading. Transparency needs to be above 0 for this value to have effect. The color is multiplied by the transparency amount of the surface.

 refractionBlur → double

The amount of blurring applied to refractions.

 render → LWRenderData

An internal state that must be passed as the first argument to the LWShaderAccess::setVal() and LWShaderAccess::getVal() methods.

 replacement_color → double[3]

Use this together with LWShaderAccess::replacement_percentage to set a color for the surface that will be unaffected by subsequent shading and lighting calculations. This is typically used by plug-ins that partially replace LightWave's lighting model.

 replacement_percentage → double

Use this together with LWShaderAccess::replacement_color to set a color for the surface that will be unaffected by subsequent shading and lighting calculations. This is typically used by plug-ins that partially replace LightWave's lighting model.

 roughness → double

Surface roughness, the inverse of the exponent in the Phong specular highlight formula. The corresponding user parameter is called Glossiness. The roughness is approximately 2^(10g+2).

 samplerState → LWSamplerState

!! NOT DOCUMENTED !!

 setVal(LWRenderData rd, int type, int num, double arg1)

Set a value for one of the render buffers.

 sourceID → LWItemID

The item ID of the source of the viewing ray.

 specular → double

Specular reflection level.

 specular_shade → double[3]

The RGB components of the specular shading color. The flag lwsdk.LWSHF_SPECULAR_SHADE needs to be set for this to affect the shading.

 spotSize → double

Approximate spot diameter, useful for texture antialiasing. The diameter is only approximate because spots in general aren't circular. On a surface viewed on edge, they're long and thin.

 subsx → double

The pixel coordinates at which the spot is visible in the rendered image with sub-pixel precision.

 subsy → double

The pixel coordinates at which the spot is visible in the rendered image with sub-pixel precision.

 sx → int

The pixel coordinates at which the spot is visible in the rendered image.

 sy → int

The pixel coordinates at which the spot is visible in the rendered image.

 translucency → double

Translucency level. This determines how much the brightness of a surface is affected by the brightness of the environment behind it.

 transparency → double

Transparency level.

 verts → LWPntID[4]

The four vertices surrounding the spot, useful for interpolating vertex-based surface data.

 vertsWPos → float[4][3]

The world coordinate position of the neighboring vertices.

 wNorm → double[3]

The average normal of the polygon normals of the polygons surrounding the currently evaluated vertex.

 wNorm0 → double[3]

The interpolated normal in world coordinates. This is the same as LWShaderAccess::gNorm, but after smoothing.

 wPos → double[3]

Spot position in world coordinates. This is the position after transformation and the effects of bones, displacement and morphing.

 wXfrm → double[9]

World to object transformation matrix (the inverse of LWShaderAccess::oXfrm).

 weights → float[4]

The weights assigned to the four neighboring vertices.

Factory

class lwsdk.ShaderFactory(name, klass)

Bases: lwsdk.lwsdk.IShaderFactory

Default Python Factory for IShader

 create(context)

 destroy(instance)

name()

Example

class blotch(lwsdk.IShader):
    def __init__(self, context):
        super(blotch, self).__init__()
        self._surface = context     # LWSurfaceID

        self._r2      = radius * radius;
        self._piOverR = math.pi / radius;
[...]
    # LWShader --------------------------------------------
    def flags(self):
        return lwsdk.LWSHF_COLOR

    def evaluate(self, sa):
        r2 = 0.0
[...]
ServerRecord = { lwsdk.ShaderFactory("LW_PyBlotch", blotch) : ServerTagInfo }