Material Contour Shaders

After the contour contrast shaders have decided where contours should be drawn, contour shaders decide on the contour color and width (and optionally motion, normal, material tag, and label).

Simple

A material gets a simple contour of constant color and width if it references the contour_shader_simple contour shader.

contour_shader_simple

"contour_shader_simple" (
    color           "color",
    scalar          "width")

color: is the color of the contour.
width: is the width of the contour, in percent of the image width. Percentages allow scaling of the image without changing the relative contour width.

Silhouette

This shader only puts contours at the silhouette of objects - even if the contour contrast function has decided that there might also be contours internally on objects.

contour_shader_silhouette

"contour_shader_silhouette" (
    color           "color",
    scalar          "width")

color: is the color of the contour lines.
width: is the width of the contour.

Maximum Material Color

This shader takes the maximum (in each color band) of the two material colors on each side of the contour.

contour_shader_maxcolor

"contour_shader_maxcolor" (
    scalar          "width")

width: is the width of the contour lines.

Curvature-dependent Width

This shader draws contours whose width depends on the curvature (the difference in surface orientation). If φ is the angle between two surface normals, the width is computed by the formula ½(W−w)(1−cosφ)+w, where w is the parameter min_width and W is the parameter max_width. So if two normals are in nearly opposite directions, there is a contour of width close to max_width between them. When the angle between them decreases, the width of the contour decreases down to nearly min_width. (The width will never reach min_width completely, since the contour contrast function will not create any contours where the surface curvature is less than ndelta degrees, and ndelta can not be set to zero without getting contours in the interior of all objects.

At the edge of an object, where the depth difference is large, the maximum contour width is used. The minimum width would theoretically occur at 0 degrees and the maximum width at 180 degrees.

contour_shader_curvature

"contour_shader_curvature" (
    color           "color",
    scalar          "min_width",
    scalar          "max_width")

color: is the color of the contour.
min_width: is the minimum contour width, in percent of the image size.
max_width: is the maximum contour width, in percent of the image size.

Color-dependent Width

With the contour_shader_widthfromcolor contour shader, a material gets contours whose thickness depends on material color. The thickness depends on the maximum m of the red, green, and blue color bands. (m is clamped to 1 if it is larger than 1.) The width is computed as (W−w)(1−m)+w, where w is the parameter min_width and W is the parameter max_width. When the color is bright no contour is visible, and when the color gets darker the contour gets wide. The minimum width is used at bright colors and the maximum width is used at black.

contour_shader_widthfromcolor

"contour_shader_widthfromcolor" (
    color           "color",
    scalar          "min_width",
    scalar          "max_width")

color: is the color of the contour.
min_width: is the minimum contour width, in percent of the image size.
max_width: is the maximum contour width, in percent of the image size.

For example, to get black contours that are thick where the material is in shadow and thin where the material is brightly illuminated, specify

contour "contour_shader_widthfromcolor" (
    "color"         0 0 0 1,  # solid black
    "min_width"     0.5,      # min width
    "max_width"     1.5)      # max width

Note that for semitransparent materials, the material color is not just the color of the object material under the given illumination; the color of the objects behind the material is also taken into account.

Color from Material Color

This shader draws a contour whose color matches the color of the object being contoured, only with a different brightness (usually much darker).

contour_shader_factorcolor

"contour_shader_factorcolor" (
    scalar          "factor",
    scalar          "width")

factor: is the multiplier for the material color. If the factor is 0, a black contour results. If the factor is between 0 and 1, a dark contour (of the same hue as the material) results. If the factor is 1, the contour gets the same color as the material at that point. If the factor is larger than 1, bright contours of the same hue as the material result.
width: is the contour width, in percent of the image size.

For example, to get contours that are half the material color and two percent wide, specify:

contour "contour_shader_factorcolor" (
    "factor"        0.5,      # factor of material color
    "width"         2.0)      # contour width (in %)

Like the previous shader, this shader takes the color of objects behind semitransparent materials into account.

Depth-fading Contours

Contours are drawn whose color and width are linearly interpolated between two values as specified with the near and far parameter sets. If a contour point is more distant than far_z, the contour gets color far_color and width far_width. If a point is nearer than near_z, the contour gets color near_color and width near_width. If the depth is in between, the color and width are linearly interpolated.

contour_shader_depthfade

"contour_shader_depthfade" (
    scalar          "near_z",
    color           "near_color",
    scalar          "near_width",
    scalar          "far_z",
    color           "far_color",
    scalar          "far_width")

near_z: is the minimum distance.
near_color: is the color at and below the minimum distance.
near_width: is the width at and below the minimum distance.
far_z: is the maximum distance.
far_color: is the color at and below the maximum distance.
far_width: is the width at and below the maximum distance.

For example, to get contours that are interpolated between two percent wide red at depth -10 and half a percent wide blue at depth -25, specify

contour "contour_shader_depthfade" (
    "near_z"        -10,
    "near_color"    1 0 0 1,
    "near_width"    2,
    "far_z"         -25,
    "far_color"     0 0 1 1,
    "far_width"     0.5)

Animated Contours

This shader draws contours with a color and width that depends linearly on the frame number. Two frame numbers, colors, and widths are specified. If the frame number is less than the first frame number, the first color and width is used. If the frame number is higher than the last frame number, the last color and width are used. If the frame number is in between, a linear interpolation of the two colors and widths are used.

contour_shader_framefade

"contour_shader_framefade" (
    integer         "frame1",
    color           "color1",
    scalar          "width1",
    integer         "frame2",
    color           "color2",
    scalar          "width2")

frame1: is the minimum frame number.
color1: is the color at and below the minimum frame number.
width1: is the width at and below the minimum frame number.
frame2: is the maximum frame number.
color2: is the color at and below the maximum frame number.
width2: is the width at and below the maximum frame number.

In the following example, the contour will be fully opaque white before frame 3, and then disappear gradually until frame 10. After frame 10 the contour is completely transparent.

contour "contour_shader_framefade" (
    "frame1"        3,
    "color1"        1 1 1 1,
    "width1"        1,
    "frame2"        10,
    "color2"        0 0 0 0,
    "width2"        0.2)

Width from Light Direction

Contours are drawn whose width depends on the angle φ between the surface normal and the direction to a light source. The width is computed by the formula ½(W−w)(1−cosφ)+w, where w is a parameter min_width and W is a parameter max_width. Therefore the thickness increases gradually from min_width when the surface is directly facing the light direction to max_width when the surface is facing exactly opposite the light direction.

contour_shader_widthfromlight

"contour_shader_widthfromlight" (
    color           "color",
    scalar          "min_width",
    scalar          "max_width",
    light           "light")

color: is the color of the contour lines.
min_width: is the minimum width of the contour.
max_width: is the maximum width of the contour.
light: is the light.

For example, consider the case where the name of the light source is light_0. To get black contours that are two percent wide where the surface is facing away from the light source, decreasing down to zero width where the surface is facing the light source directly, specify:

contour "contour_shader_widthfromlight" (
    "color"         0 0 0 1,       # contour color
    "min_width"     0.0,           # min width (%)
    "max_width"     2.0,           # max width (%)
    "light"         "light_0")     # light name

Width from Light Direction

This shader is a variation of the previous one. It accepts a direction directly, instead of a light that implicitly provides the direction.

contour_shader_widthfromlightdir

"contour_shader_widthfromlightdir" (
    color           "color",
    scalar          "min_width",
    scalar          "max_width",
    vector          "light_dir")

color: is the color of the contour lines.
min_width: is the minimum width of the contour.
max_width: is the maximum width of the contour.
light_dir: is the direction to the main light source.

Width from Layer

With this contour shader, the width of a contour will change depending on how many levels of materials are on top of it. If the material is on top, its contour will be of a width specified by a parameter. For each material on top of it, its width will decrease by a factor that is also controllable with a parameter.

contour_shader_layerthinner

"contour_shader_layerthinner" (
    color           "color",
    scalar          "width",
    scalar          "factor")

color: is the color of the contour lines.
width: is the width of the contour at the top layer.
factor: is the factor to make the contour thinner for each layer.

For example, to get red contours that are 2 percent wide when the material is on top, 1 percent wide when the material is behind one other (semitransparent) material, 0.5 percent wide when the material is behind two materials, and so on, use the following:

contour "contour_shader_layerthinner" (
   "color"         1 0 0 1,       # contour color
   "width"         2.0,           # width at top layer (%)
   "factor"        0.5)           # factor pr. layer

Combination

This is a combination of the depthfade, layerthinner, and widthfromlight contour shaders. The width of the contour fades into the background (from near_width to far_width), and the color fades from near_color to far_color. The contour width and color changes with a ramp function between distances near_z and far_z. For each layer the ray has passed through, a factor is multiplied on to the width. If no factor is specified, the width will not depend on the layer. If a light source is specified, the width also depends on the surface normal relative to the light source direction.

contour_shader_combi

"contour_shader_combi" (
    scalar          "near_z",
    color           "near_color",
    scalar          "near_width",
    scalar          "far_z",
    color           "far_color",
    scalar          "far_width",
    scalar          "factor",
    light           "light",
    scalar          "light_min_factor")

near_z: is the minimum distance.
near_color: is the color at and below the minimum distance.
near_width: is the width at and below the minimum distance.
far_z: is the maximum distance.
far_color: is the color at and below the maximum distance.
far_width: is the width at and below the maximum distance.
factor: is the factor to make the contour thinner for each layer. Leave this undefined to disable layer dependency.
light: is the light source; leave undefined for no light dependency.
light_min_factor: specifies the minimum factor that the light-dependency decreases the contour width.

For example, for contours that are interpolated between two percent wide red at depth -12 and one percent wide blue at depth -18, and get half as wide for each layer of material above this material, and where the width also depends on the direction to the light source named mylight, specify

contour "contour_shader_combi" (
                                  # interpolate from
   "near_z"        -12,           # this depth,
   "near_color"    1 0 0 1,       # color (red),
   "near_width"    2,             # and width (in %)
                                  # to
   "far_z"         -18,           # this depth
   "far_color"     0 0 1 1,       # color (blue)
   "far_width"     1,             # and width (in %).
                                  # optional:
   "factor"        0.5,           # factor pr. layer
   "light"         "mylight",     # light name
   "light_min_factor" 0.5)