automap 	- Function to perform a planar projection on a faceted surface
bilerp  	- Function to a linear interpolation between four values
cylinmap	- Function to perform a cylindrical projection
decalmap	- General function to perform projection mapping
planemap	- Function to perform a planar projection
sphermap	- Function to perform a spherical projection

SYNOPSIS

float s,t;
float ss, tt;
float maptype;
point p, maporigin, xaxis, yaxis, zaxis;
float s1,t1,s2,t2,s3,t3,s4,t4;

decalmap(p,s,t,ss,tt,maptype,maporigin,xaxis,yaxis,zaxis,s1,t1,s2,t2,s3,t3,s4,t4);

float uu, vv; point p, maporigin, xaxis, yaxis, zaxis, n;

sphermap(p,uu,vv,maporigin,xaxis,yaxis,zaxis);

cylinmap(p,uu,vv,maporigin,xaxis,yaxis,zaxis);

planemap(p,uu,vv,maporigin,xaxis,yaxis);

automap(p,uu,vv,maporigin,yaxis,n);

float x1, x2, x3, x4; float uu, vv;

bilerp(uu,vv,x1,x2,x3,x4);

DESCRIPTION

This file is not a shader, but rather a set of texture mapping functions written in the RenderMan Shading Language to be used by other shaders. The shader file maps.sl must be compiled -- producing decalmap.slo, sphermap.slo, cylinmap.slo, planemap.slo, automap.slo, and bilerp.slo -- before any shader using these functions can be compiled.

sphermap performs a spherical projection. The point p on the surface of an object is projected onto the surface of a sphere to determine uu and vv coordinates, which can later be used in the same way as real u and v surface parameters. This might be used, for example, to parameterize the surface of a strangely-shaped polygonal object in order to map a texture onto it. Polygons normally do not parameterize well, so this function is a way to calculate reasonable surface parameters. Of course this works best on objects that are close to spherical.

Imagine a sphere of very large radius centered around an object. The surface of the object can be parameterized by drawing a line from the center through a point on the surface and continuing it out to the sphere. Then the parameters of the resulting point on the sphere are used for the point on the surface.

The parameters maporigin, xaxis, yaxis, and zaxis describe the coordinate system of the projection sphere. The maporigin is naturally the center point of the sphere. The xaxis, yaxis, and zaxis are points describing the 3 coordinate axes relative to maporigin. The actual direction vectors are determined by subtracting maporigin from each of these values.

The uu coordinate that results from this mapping is very similar to the u coordinate of a “real” sphere: it is the longitudinal coordinate and ranges from 0 to 1 around the z axis of the sphere, with the “seam” on the sphere's positive x axis. The vv or latitudinal coordinate ranges from 0 to 1 along the z axis of the sphere (0 is at the minimum z value or “bottom” of the sphere and 1 is at the top).

cylinmap performs a cylindrical projection in a manner similar to sphermap. The surface point p is projected onto the surface of a cylinder to determine uu and vv coordinates.

The parameters maporigin, xaxis, yaxis, and zaxis describe the coordinate system of the projection cylinder in the same way as in sphermap. The cylinder's central axis is along the resulting z axis, and the uu coordinate will thus range from 0 to 1 around this axis, again with the “seam” on the positive x axis. The vv coordinate is not restricted to values from 0 to 1: it is equal to the distance of the surface point along this axis relative to maporigin. You will therefore need to be careful with using this value as a texturing parameter because it may fall outside the 0-to-1 range.

planemap performs a planar projection in a manner similar to sphermap and cylinmap. The surface point p is projected onto a plane to determine uu and vv coordinates.

automap performs a planar projection onto a faceted object. Each face will automatically have a separate direction of projection, eliminating the need to manually calculate many planar projections. Thus only one surface shader for an entire object is necessary instead of one per polygon. The orientation of each projection is determined by using the normal to the surface (the n parameter) as the direction of projection and yaxis-maporigin for the “up” direction of the plane. The “right-hand” direction will be calculated automatically. This breaks down when the surface normal is parallel to the “up” direction. For such faces, the shader will make a usually-reasonable “guess” at a direction to use as “up”.

This function works best with repeating patterns on polygonal surfaces, like a periodic brick texture map on a hexagonal room. It has no facility for control of texture placement on an individual-polygon basis, so it is difficult to use with non-periodic texture maps. It will also have strange results on curved primitives.

The parameters maporigin, xaxis, and yaxis describe the coordinate system of the projection plane in the same way as sphermap and cylinmap. Note that there is no z axis to this map. Neither the uu nor the vv coordinate is restricted to fall between 0 and 1, but are equal to the distance of the surface point from maporigin along the projection's x and y axes respectively. Again this means you will need to be careful using these values as texturing parameters because they may fall outside the 0-to-1 range. In particular, note that only the positive quadrant (relative to maporigin) of the surface will have positive values of uu and vv.

bilerp performs a bilinear interpolation between the four given values x1-4 at the 0 and 1 corners of uu-vv space, and returns the single value at the point (uu,vv).

The decalmap function is an “umbrella” function that calls one of the other four mapping functions. If the maptype parameter is 0 the function does a planar projection, if maptype is 1 it does a cylindrical projection, if maptype is 2 it does a spherical projection, and if maptype is 4 it does a “automap” projection. All of these projections are performed by calling the appropriate projection function described above, passing along the parameters p, maporigin, xaxis, yaxis, zaxis and n accordingly.

The uu and vv coordinates calculated by these projections are then passed to bilerp, along with the texture-space corner values s1-4 and t1-4, to calculate texture coordinates ss and tt in exactly the same way as RenderMan uses the u and v coordinates of a surface in a bilinear interpolation to calculate s and t.

However, if maptype is 3 there is no projection performed and the ss and tt coordinates returned are simply equal to the “standard” texture coordinates, passed in as s and t. Note that in this case there is no bilinear interpolation, so all the values passed in s1-4 and t1-4 are ignored.

SEE ALSO

texmap(3s) diaknurl(3s) sinknurl(3s) threads(3s) intro(3s)