An Air point cloud is a simple binary file with a short header followed by a list of records, one record for each point.  Here’s the header:

typedef struct {
  char diName[48];
  int diType, diNarr, diIndex, diSize;
} DataInfo;

typedef struct {
  char id[4];
  unsigned int hsize;
  float gbound[6];
  float world2camera[16], world2ndc[16];
  int xres, yres;
  float par, fov;
  int flags;
  int maxdepth, maxleafsize;
  int nbrick, bricksize;
  int nbiv,npts;
  unsigned int ptoffset;
  float minwidth, maxwidth;
  int pad[256];
  int ndata,datasize;
  DataInfo di[64];
} AirPointHeader;

The ptoffset field gives the file position where the actual data begins.  The data for each point is stored as a binary array of floats with little-endian byte order.

Surface "ShowPosition"
 "float UnitSize" [1]
 "float[3] Origin" [0 0 0]
 "float Clamp" [0]
 "float Cyclic" [0]
 "string ShadingSpace" ["world"]

Here’s a rendering with the default parameter values.  The output color is the world-space x,y,z position of the current shading location:

It doesn’t normally make sense to filter position values, so this image was rendered with only 1 pixel sample (PixelSamples 1 1 in the RIB file) and no filtering.

The position values may well be greater than 1 or less than 0, so a full-precision position image should be saved in a file format such as HDR, EXR, or TIFF that supports floating-point data.

The ShowPosition shader also allows the position values to be scaled to lie in the unit interval, which allows the data to be recorded in an 8-bit or 16-bit image.  The scaling is performed by mapping the position into a cube with one corner defined by the Origin parameter and each side of length UnitSize.  In this image the UnitSize is set to 10:

Position values that lie outside of the box defined by the Origin and UnitSize value will be clamped to the unit interval if the Clamp parameter is set to 1.  If the Cyclic parameter is set to 1, out of range values will be wrapped to form a periodic pattern.  Here’s the same model with UnitSize set to 1 and Cyclic set to 1:

This new capability provides a simple solution to several common shading tasks that would otherwise require complex custom shaders:

• Decals:  apply an arbitrary number of texture maps to an object’s color and feed the result into any surface shader.

• Extra output variables:  add an arbitrary number of additional shaders to an object to produce extra output values without affecting the normal shading of the object.

• Assign different shaders to specific regions:  simple shader compositing allows existing surface shaders to be selectively applied to sections of a surface.

• Replicate application shader networks:  create arbitrary shader networks by connecting pre-compiled components.

Further, the implementation of networked and layered shaders does not require existing shaders to be re-written to take advantage of these new features.

This article describes how to use multiple shaders to address each of these tasks.  Sample shaders and rib files are included in the AIR distribution in:

$AIRHOME/examples/layers

Simple Color Layers

Here’s a simple RIB fragment that assigns multiple surface shaders to an object:

Surface "ColorMap" "string ColorMapName" "grid.tx"
Surface "+VMarble"

Prepending the shader name with “+” tells Air to append the shader to the list of shaders assigned to the object. The shaders are executed in the order in which they are assigned. Subsequent shaders inherit the current shading state (including the values of global variables) from shaders previously executed. Here’s a ColorMap shader that uses a texture map to set the object’s color value:

generic ColorMap(
  string ColorMapName = "";
  float SetColor = 1;
  output varying color __Color = 0;
)
{
  if (ColorMapName!="") {
    __Color = color texture(ColorMapName,s,t);
    if (SetColor!=0) Cs = __Color;
  }
}

In the RIB fragment given above, the VMarble shader will use the color map result as one of the input colors for the marble pattern. No modification of the VMarble shader is required.

The new generic shader type is compatible with any other shader type.  Generic shaders can be used to construct re-usable components for layered and networked shaders.

Sample scene: colormap.rib

Decals

The layers example directory includes a LayerDecal shader that applies a masked color to a surface. Simple sequential shader assignment allows an arbitrary number of decals to be applied to a surface without constructing a complex custom surface shader:

Surface "LayerDecal"
  "ColorMapName" "sitex.tx"
  "OriginXY" [.3 .67]
  "SizeXY" [-.3 -.3]
  "DecalColor" [1 1 1]
Surface "+LayerDecal"
  "ColorMapName" "sitex.tx"
  "OriginXY" [.25 .6]
  "SizeXY" [-.25 -0.25]
  "DecalColor" [1 0 0]
Surface "+plastic"

Sample scene: decals.rib

Extra Passes

Another task made easy with multiple shaders is adding extra output values to a rendering pass.   Air 11 includes a new generic shader that adds an occlusion output value to any surface (stored in a __occlusion output variable).   Sample usage:

 Display "extrapass.tif" "framebuffer" "rgba,color __occlusion"
...
Surface "VMarble"
Surface "+genOcclusion" "setshaderoutput" 0

Sample scene: extrapass.rib

Shader Compositing

Air’s multi-shader support includes an option to composite one shader on top of another. Here’s an example that adds a plastic decal to a metallic surface:

Surface "VMetal"
Surface "*VPlastic" "OpacityMapName" "sitex.tx" "ColorMapName" "square.tx"

The * before the shader name tells Air to blend the output color from the VPlastic shader with the output color of the VMetal shader using the output opacity from the VPlastic shader. Any output variables shared by the two shaders will also be composited using the output opacity.

Sample scene: compshaders1.rib

The above example shows how to composite a shader with controls for its output opacity. For surface shaders without opacity controls, an auxiliary shader can be used to control the opacity. Here is a simple generic shader that sets the global input opacity value:

generic OpacityMap(
  string OpacityMapName = "";
  output varying color __Opacity = 1;
)
{
  if (OpacityMapName!="") {
    __Opacity = color texture(OpacityMapName,s,t,"fill",-1);
    if (comp(__Opacity,1)==-1) __Opacity=comp(__Opacity,0);
    Os = __Opacity;
  }
}

This shader allows any surface shader that modulates its output color by the input opacity to be composited over another shader.  Most surface shaders modulate their output color in this way.

Here is how the OpacityMap shader might be used to add a marble decal to a 2D grid:

Surface "VGrid2D"
Surface "+OpacityMap" "OpacityMapName" "sitex.tx"
Surface "*VMarble"

To optimize the evaluation of composited shaders, Air will skip any shader layer whose input opacity value is 0.

Sample scene: compshaders2.rib

Shader Networks

Multiple shaders can be used to re-construct a general shader network by defining connections among the shaders assigned to an object. Connections are defined by including additional parameters in the shader declaration. First, each shader declaration is assigned a name using:

“string layername” “componentname“

Naturally layername does not need to be an actual parameter of the shader.

Each connection is defined with an additional string parameter:

“string connect:toparametername” “fromlayer:fromparametername“

The connection transfers the value of fromparametername in layer fromlayer to the target parameter in the current shader.  The source parameter must be an output variable of the source shader or a global shader variable.  The target parameter is normally one of the shader’s input parameters, but it can also be the global input color (Cs) or input opacity (Os).  The source and target parameters must have the same type.

Sample usage:

Surface "ColorMap"
  "string ColorMapName" "grid.tx"
  "float SetColor" [0]
  "layername" "gridlayer"
Surface "+VMarble"
  "connect:VeinColor" "gridlayer:__Color"

In this example, the marble vein color is taken from the ColorMap shader’s __Color output variable.

Applications

The Air Stream plug-in for Maya uses the new shader network capability in Air 11 to translate Maya’s shader networks for rendering with Air.  This approach also easily allows:

• Air shader parameters to be driven by a Maya shading network
• Air shaders and Maya shaders to be mixed in a single network
• Air custom shading language functions to be incorporated in a Maya shading network using generic shaders

We need a function that allows us to look up a set of values based on a name, like looking up a word’s definition in a dictionary.   We can add such a function to Air’s shading language by implementing a dynamic shadeop, or DSO for short, which will be loaded by Air automatically and used to evaluate our new function.

The dictionary DSO adds the following new functions to the shading language:

float dictionary(string dictname, string keyname, float fvalue);
float dictionary(string dictname, string keyname, color cvalue);
float dictionary(string dictname, string keyname, string svalue);

The dictionary function looks for a text file named dictname and tries to load a list of token value pairs, one per line.  The token values should look like

Seattle 47.45 -122.3 -8

The functions return 0 if they succeed.  If an error occurs, the functions return one of the following error codes:

-1:  unable to find or read dictionary file
-2:  key name not found
-3:  unable to convert value to the requested type

Since Air 11 has not yet been released, here are a couple other uses for the dictionary function that you can try with the current Air release.

The first example uses the dictionary function to allow the base surface color to be specified using a name instead of r,g,b values.  The Air distribution includes a list of named colors in $AIRHOME/vizools/colors.txt (used by the Air Space tool).  Here’s the source code for a simple NamedColor shader:

surface NamedColor(
 float Ambient = 1;
 float Diffuse = 1;
 string ColorName = "";
 string ColorList = "$AIRHOME/viztools/colors.txt"
)
{
  color Ct = Cs;
  if (ColorName!="") dictionary(ColorList,ColorName,Ct);
  normal Nf = faceforward (normalize(N),I);
  Oi = Os;
  Ci = Oi * Ct * (Ambient * ambient() + Diffuse * diffuse(Nf));
}

The dictionary function will expand the reference to the $AIRHOME environment variable in the ColorList value.

In a RIB file, we can then specify a named color as:

Surface "NamedColor"
 "string ColorName" "neon pink"

Another application for the dictionary function is to allow simple text files to be used to define “preset” values for a shader’s parameters.  Here’s an extended version of the standard paintedplastic surface shader with an option to use a file with preset values:

surface paintedplasticpreset(
 float Ka = 1;
 float Kd = .5;
 float Ks = .5;
 float roughness = .1;
 color specularcolor = 1;
 string texturename = "";
 string preset = "";
)
{
 float preKa=Ka;
 float preKd=Kd;
 float preKs=Ks;
 float preroughness = roughness;
 color prespecularcolor=specularcolor;
 string pretexturename=texturename;

 if (preset!="") {
  dictionary(preset,"Ka",preKa);
  dictionary(preset,"Kd",preKd);
  dictionary(preset,"Ks",preKs);
  dictionary(preset,"roughness",preroughness);
  dictionary(preset,"specularcolor",prespecularcolor);
  dictionary(preset,"texturename",pretexturename);
 }
 Ci = Cs;
 if (pretexturename != "")     Ci *= color texture(pretexturename);
 normal Nf = faceforward (normalize(N),I);
 Oi = Os;
 Ci = Oi * Ci * (preKa*ambient() + preKd*diffuse(Nf)) + prespecularcolor * preKs*specular(Nf,-normalize(I),preroughness);
}

A sample preset file might look like:

Kd 0.4
Ks 0.6
roughness 0.2
specularcolor = 1 1 0
texturename = grid.tx

The new dictionary shadeop can found in this archive.  Unzip the archive to the AIRHOME directory, and the new shadop will automatically be added to the shaders directory of your Air installation (where Air can find it).  Examples and source code for the shadeop can be found in $AIRHOME/examples/dictionary.

surface RenderTangentNormalMap(
 float ReverseZ = 1;
)
{
 normal NN=normalize(faceforward(N,I));
 if (ReverseZ!=0) setzcomp(NN,-zcomp(NN));
 NN=0.5+0.5*NN;
 Ci = NN;
 Oi = 1;
}

Here’s an archive with the source code and a pre-compiled binary for Air.  Air users can install the shader by unzipping the archive to the shaders directory of their Air installation.

To generate a normal map, first be sure the output image gamma is set to 1 (RhinoAir users can find this control on the Air Display page in the Rhino Options dialog).  Assign the above shader to your objects, then render an orthographic viewport.  You should see an image with colors similar to those in this sample:

To apply the normal map to an object for rendering, assign the VTangentNormalMap shader as the displacement shader for the object, and set the shader’s TextureName parameter to the file name of the previously generated normal map.  Here’s a simple rendering using the above map:

You can use Air’s outline capability to view the individual polygons in a mesh:

One way Air detects edges for outlines is based on a toon id value that is assigned to each element.  By default each geometric primitive is assigned a unique id.  Where two primitives abut in the rendered image, the toon id value changes, and Air will draw an outline.

The toon id for an object can be explicitly specified with:

Attribute "toon" "float id" [n]

If the toon id is set to the special value -2, Air automatically assigns a unique id to each face in the rendering mesh.

So to view the rendering mesh, we just need to enable outlines and to set the toon id to -2 for the objects whose mesh we wish to view.  We can do that by placing a few commands in a small text file:

Option "toon" "maxinkwidth" [0.5]
Attribute "toon" "inkwidth" [0.5]
Attribute "toon" "float id" [-2]

Save the above commands to a file named viewmesh.rib.  Then render with:

air -d viewmesh.rib myscene.rib

We can achieve the same result using a couple of Air’s command line options:

air -d -inkw 0.5 -at toon id -2 myscene.rib

Here are a few images showing the effect of adjusting the flatness tessellation criterion for a blobby object (from 8 to 4 to 2).

If we were rendering each pass with a separate invocation of the renderer, we could use one of Air’s command filtering options to override the surface shader assignments with a shader that computes the desired value, occlusion in this case:

air -surf occlusionpass myscene.rib

However, if we’re trying to record all output values in a single rendering, we need to preserve the existing shader assignments.  There are at least two ways to add additional passes to the output mix without clobbering the existing shaders:

Method 1:

Add an additional output variable with the desired value to the surface shaders.  For shaders built with the Vshade user interface, the VPlastic surface shader can serve as a model.  It includes extra blocks that compute an occlusion value exported as a __occlusion output variable.  In the Vshade source network, the occlusion code and output variables are just two blocks which can easily be copied to other Vshade surface shaders.

For text-based shaders, we can copy-and-paste the necessary code fragments.  First, add two new arbitrary output variables (AOVs):

surface mysurf(...;
   output varying color __occlusion = 0;
   output varying vector __bent_normal = 0;
)

then include code to compute the occlusion values:

if (raylevel()==0) {
  if ((isshadowray()+isindirectray())==0) {
    float doOcclusion = 0;
    option("display:__occlusion", doOcclusion);

    if (doOcclusion!=0) {
       normal Nf = faceforward(normalize(Normal),I);
       __occlusion = occlusion(Position,Nf,PI*0.5,__bent_normal);
       __bent_normal = vtransform("current","world",__bent_normal);
     }
   }
}

This code only computes the __occlusion value when it is being saved in an output image.

With this method of computing occlusion, the occlusion quality parameters must be set using the corresponding indirect attributes, which are documented in the Air user manual in the Indirect Lighting section of the Lighting chapter.

Method 2:

Use a volume shader that emits the desired value, and assign the volume shader as the Atmosphere shader for the desired objects.  Atmosphere shaders are normally used for volumetric effects.  For scenes that do not require atmospheric effects, we can use a “fake” atmosphere shader (that does not modify the main output color or opacity) as a container for additional output variables.

As an example, I’ve converted to the massive_occlusionpass surface shader included with Air to a volume shader – massive_occlusion_layer:

http://www.sitexgraphics.com/massive_occlusion_layer.zip

The converted shader provides a __occlusion output variable with the occlusion result; the shader does not alter the output color or opacity from the surface shader.

To assign a volume shader as an atmosphere shader, use the Atmosphere RIB statement:

Atmosphere "massive_occlusion_layer"

If you are rendering with Massive, you can assign the above shader to all objects by placing the above text in a small file  and either specifying that file as the rib options file in Massive, or including it on the command line when rendering from a command shell:

air addocc.rib myscene.rib

Although the above discussion focused on occlusion, the same techniques can be used to compute and export any desired value for inclusion in a multi-layer EXR file or other storage format.

Procedural “type” [arguments] [minx maxx miny maxy minz maxz]

The array of 6 floats at the end defines a bounding box for all objects that might be created by the procedural.  The procedural prim acts a placeholder in the scene.  The procedural e is evaluated only when and if the renderer needs to access the interior of the bounding box.  If the bound is never encountered by the renderer – because say the bounding box is off-screen or occluded by other objects – the procedural primitive is never evaluated.

Because of the on-demand manner in which a procedural primitive is created, it is important that the bounding box be accurate.  If the bound is too large, the renderer may unnecessarily evaluate a procedural prim whose contents are hidden.  If the bound is too small, objects of created by the procedural primitive may be rendered incorrectly (usually appearing to be clipped along bucket boundaries or the boundaries of the bounding box).

Here is a small RIB filter plugin to aid in visualizing the bounding box for a procedural primitive:

http://www.sitexgraphics.com/showprocbd.zip

Unzip the archive to the procedurals directory of your Air installation, and Air will be able to find the showprocbd plugin without a path reference.

You can use the -rif command line switch to apply the showprocbd RIB filter to a scene:

air -rif showprocbd myscene.rib

Here’s an example showing a small group of agents from the Massive crowd simulation program.  Massive uses a procedural primitive to generate agents geometry at render time.

By default the showprocbd filter replaces each procedural primitive with a box representing the procedural bound. This can be help accelerate preview rendering in cases where the full expanded geometry is not needed.

Showprocbd has a number of options for customizing its behavior.  For example, you can set the alpha and color for the box:

air -rif “showprocbd boxalpha 0.5 boxcolor 1 .8 .6″ myscene.rib

Including a “replace 0″ in the argument list retains the contents of the procedural primitive:

air -rif “showprocbd boxalpha 0.5 replace 0″ myscene.rib

In this scene we can see that for some agents the elbows protrude slightly outside the bounding box.

The box can be represented by lines instead of or in addition to polygons:

air -rif “showprocbd boxalpha 0 linewidth 3 linecolor .7 .8 .5″ myscene.rib

Box corners can also be rendered:

air -rif “showprocbd boxalpha 0 cornerwidth 20 cornercolor 1 0 0 linewidth 5″ myscene.rib

Finally, instead of applying the filter as a command line option, you can define the current filter for an object as a RIB attribute:

Attribute “render” “rifilter” “showprocbd replace 0 boxalpha 0.5″

]]> http://sitexgraphics.com/blog/?feed=rss2&p=13 0