Get or set material properties

Get or set material properties for geometry appearance.

material3d(..., id = NULL)

rgl.material.names
rgl.material.readonly

Arguments

...

Material properties to set or query.

id

the rgl id of an object to query, or NULL to query or set the defaults.

Details

In an rgl scene, each object has “material properties” that control how it is rendered and (in the case of tag) that can be used to store a label or other information. material3d sets defaults for these properties and queries the defaults or specific values for an individual object.

To set values, use name = value settings, e.g. material3d(color = "red"). To query values, specify the property or properties in a character vector, e.g. material3d("color").

Only one side at a time can be culled.

The material member of the r3dDefaults list may be used to set default values for material properties.

Material Properties

The rgl.material.names variable contains the full list of material names. The following read-write material properties control the appearance of objects in an rgl scene.

color

vector of R color characters. Represents the diffuse component in case of lighting calculation (lit = TRUE), otherwise it describes the solid color characteristics.

lit

logical, specifying if lighting calculation should take place on geometry

ambient, specular, emission, shininess

properties for lighting calculation. ambient, specular, emission are R color character string values; shininess represents a numerical.

alpha

vector of alpha values between 0.0 (fully transparent) .. 1.0 (opaque).

smooth

logical, specifying whether smooth shading or flat shading should be used. For smooth shading, Gouraud shading is used in rgl windows, while Phong shading is used in WebGL.

texture

path to a texture image file. See the Textures section below for details.

textype

specifies what is defined with the pixmap

"alpha"

alpha values

"luminance"

luminance

"luminance.alpha"

luminance and alpha

"rgb"

color

"rgba"

color and alpha texture

Note that support for these modes is slightly different in the display within R versus the WebGL display using rglwidget(). In particular, in WebGL textype = "alpha" will always take the alpha value from the luminance (i.e. the average of the R, G and B channels) of the texture, whereas the R display bases the choice on the internal format of the texture file.

texmode

specifies how the texture interacts with the existing color

"replace"

texture value replaces existing value

"modulate"

default; texture value multiplies existing value

"decal"

for textype = "rgba", texture is mixed with existing value

"blend"

uses the texture to blend the existing value with black

"add"

adds the texture value to the existing. May not be available in the R display with very old OpenGL drivers.

texmipmap

Logical, specifies if the texture should be mipmapped.

texmagfilter

specifies the magnification filtering type (sorted by ascending quality):

"nearest"

texel nearest to the center of the pixel

"linear"

weighted linear average of a 2x2 array of texels

texminfilter

specifies the minification filtering type (sorted by ascending quality):

"nearest"

texel nearest to the center of the pixel

"linear"

weighted linear average of a 2x2 array of texels

"nearest.mipmap.nearest"

low quality mipmapping

"nearest.mipmap.linear"

medium quality mipmapping

"linear.mipmap.nearest"

medium quality mipmapping

"linear.mipmap.linear"

high quality mipmapping

texenvmap

logical, specifies if auto-generated texture coordinates for environment-mapping should be performed on geometry.

front, back

Determines the polygon mode for the specified side:

"filled"

filled polygon

"lines"

wireframed polygon

"points"

point polygon

"culled"

culled (hidden) polygon

size

numeric, specifying the size of points in pixels

lwd

numeric, specifying the line width in pixels

fog

logical, specifying if fog effect should be applied on the corresponding shape. Fog type is set in bg3d.

point_antialias, line_antialias

logical, specifying if points should be round and lines should be antialiased, but see Note below.

depth_mask

logical, specifying whether the object's depth should be stored.

depth_test

Determines which depth test is used to see if this object is visible, depending on its apparent depth in the scene compared to the stored depth. Possible values are "never", "less" (the default), "equal", "lequal" (less than or equal), "greater", "notequal", "gequal" (greater than or equal), "always".

polygon_offset

A one or two element vector giving the factor and units values to use in a glPolygonOffset() call in OpenGL. If only one value is given, it is used for both elements. The units value is added to the depth of all pixels in a filled polygon, and the factor value is multiplied by an estimate of the slope of the polygon and then added to the depth. Positive values “push” polygons back slightly for the purpose of depth testing, to allow points, lines or other polygons to be drawn on the surface without being obscured due to rounding error. Negative values pull the object forward. A typical value to use is 1 (which is automatically expanded to c(1,1)). If values are too large, objects which should be behind the polygon will show through, and if values are too small, the objects on the surface will be partially obscured. Experimentation may be needed to get it right. The first example in ?persp3d uses this property to add grid lines to a surface.

margin, floating

Used mainly for text to draw annotations in the margins, but supported by most kinds of objects: see mtext3d.

tag

A length 1 string value. These may be used to identify objects, or encode other meta data about the object.

blend

Two string values from the list below describing how transparent objects are blended with colors behind them. The first determines the coefficient applied to the color of the current object (the source); the second determines the coefficient applied to the existing color (the destination). The resulting color will be the sum of the two resulting colors. The allowed strings correspond to OpenGL constants:

"zero"

Zero; color has no effect.

"one"

One; color is added to the other term.

"src_color", "one_minus_src_color"

Multiply by source color or its opposite.

"dst_color", "one_minus_dst_color"

Multiply by destination color or its opposite.

"src_alpha", "one_minus_src_alpha"

Multiply by source alpha or its opposite. Default values.

"dst_alpha", "one_minus_dst_alpha"

Multiply by destination alpha or its opposite.

"constant_color", "one_minus_constant_color", "constant_alpha", "one_minus_constant_alpha", "src_alpha_saturate"

These are allowed, but to be useful they require other settings which rgl doesn't support.

col

An allowed abbreviation of color.

The rgl.material.readonly variable contains the subset of material properties that are read-only so they can be queried but not set. Currently there is only one:

isTransparent

Is the current color transparent?

Value

material3d() returns values similarly to par3d: When setting properties, it returns the previous values invisibly in a named list. When querying multiple values, a named list is returned. When a single value is queried it is returned directly.

Textures

The texture material property may be NULL or the name of a bitmap file to be displayed on the surface being rendered. Currently only PNG format files are supported.

By default, the colors in the bitmap will modify the color of the object being plotted. If the color is black (a common default), you won't see anything, so a warning may be issued. You can suppress the warning by specifying the color explicitly, or calling options{rgl.warnBlackTexture = FALSE}.

Other aspects of texture display are controlled by the material properties textype, texmode, texmipmap, texmagfilter, texminfilter and texenvmap described above.

For an extensive discussion of textures, see the Textures section of the rgl Overview vignette.

Display of objects

Object display colors are determined as follows:

• If lit = FALSE, an element of the color vector property is displayed without modification. See documentation for individual objects for information on which element is chosen.

• If lit = TRUE, the color is determined as follows.

  1. The color is set to the emission property of the object.

  2. For each defined light, the following are added:

     • the product of the ambient color of the light and the ambient color of the object is added.

     • the color of the object is multiplied by the diffuse color of the light and by a constant depending on the angle between the surface and the direction to the light, and added.

     • the specular color of the object is multiplied by the specular color of the light and a constant depending on the shininess of the object and the direction to the light, and added. The shininess property mainly determines the size of the shiny highlight; adjust one or both of the specular colors to change its brightness.

If point_antialias is TRUE, points will be drawn as circles in WebGL; otherwise, they will be drawn as squares. Within R, the behaviour depends on your graphics hardware: for example, I see circles for both settings on my laptop.

Within R, lines tend to appear heavier with line_antialias == TRUE. There's no difference at all in WebGL.

See also

bbox3d, bg3d, light3d

Examples

save <- material3d("color")
material3d(color = "red")
material3d("color")
#> [1] "#FF0000"
material3d(color = save)

# this illustrates the effect of depth_test
x <- c(1:3); xmid <- mean(x)
y <- c(2, 1, 3); ymid <- mean(y)
z <- 1
open3d()
tests <- c("never", "less", "equal", "lequal", "greater", 
                  "notequal", "gequal", "always")
for (i in 1:8) {
  triangles3d(x, y, z + i, col = heat.colors(8)[i])
  texts3d(xmid, ymid, z + i, paste(i, tests[i], sep = ". "), depth_test = tests[i]) 
}
highlevel()  # To trigger display



# this illustrates additive blending
open3d()
bg3d("darkgray")
quad <- cbind(c(-1, 1, 1, -1), 1, c(-1, -1, 1, 1))
quads3d(rbind(translate3d(quad, -0.5, 0, -0.5),
              translate3d(quad, 0.5,  0.5, -0.5),
              translate3d(quad, 0, 1, 0.5)), 
        col = rep(c("red", "green", "blue"), each = 4),
        alpha = 0.5, 
        blend = c("src_alpha", "one"))