Keywords: main

Next: 3.4 Contour Output Shaders Up: 3. Contour Shaders Previous: 3.2 Contour Contrast Shaders

# 3.3 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 contours: contour_shader_simple

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

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

The following parameters are available:

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.

Curvature-dependent Width: contour_shader_curvature

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)/2 + 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" (
            color           "color",
            scalar          "min_width",
            scalar          "max_width"
        )

The following parameters are available:

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: contour_shader_widthfromcolor

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" (
            color           "color",
            scalar          "min_width",
            scalar          "max_width"
        )

The following parameters are available:

color is the color of the contour.

min_width is the minimum contour width, in percent of the image size.

max_width is the minimum 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: contour_shader_factorcolor

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" (
            scalar          "factor",
            scalar          "width"
        )

The following parameters are available:

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: contour_shader_depthfade

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" (
            color           "color",
            scalar          "near_z",
            color           "near_color",
            scalar          "near_width",
            scalar          "far_z",
            color           "far_color",
            scalar          "far_width"
        )

The following parameters are available:

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: contour_shader_framefade

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" (
            integer         "frame1",
            color           "color1",
            scalar          "width1",
            integer         "frame2",
            color           "color2",
            scalar          "width2"
        )

The following parameters are available:

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: contour_shader_widthfromlight

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)/2 + 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_widthfromlightdir" (
            color           "color",
            scalar          "min_width",
            scalar          "max_width",
            light           "light"
        )

The following parameters are available:

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: contour_shader_widthfromlightdir

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" (
            color           "color",
            scalar          "min_width",
            scalar          "max_width",
            vector          "light_dir"
        )

The following parameters are available:

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: contour_shader_layerthinner

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" (
            color           "color",
            scalar          "width",
            scalar          "factor"
        )

The following parameters are available:

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: contour_shader_combi

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" (
            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"
        )

The following parameters are available:

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
         )

Contours only on Silhouette: contour_shader_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" (
            color           "color",
            scalar          "width"
        )

The following parameters are available:

color is the color of the contour lines.

width is the width of the contour.

Contours with Maximum Material Color: contour_shader_maxcolor

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

        "contour_shader_maxcolor" (
            scalar          "width"
        )

The following parameter is available:

width is the width of the contour lines.

Next: 3.4 Contour Output Shaders Up: 3. Contour Shaders Previous: 3.2 Contour Contrast Shaders