Get or set material properties for geometry appearance.
material3d(..., id = NULL)rgl.material(
color = "white",
alpha = 1.0,
lit = TRUE,
ambient = "black",
specular = "white",
emission = "black",
shininess = 50.0,
smooth = TRUE,
texture = NULL,
textype = "rgb",
texmipmap = FALSE,
texminfilter = "linear",
texmagfilter = "linear",
texenvmap = FALSE,
front = "filled",
back = "filled",
size = 3.0,
lwd = 1.0,
fog = TRUE,
point_antialias = FALSE,
line_antialias = FALSE,
depth_mask = TRUE,
depth_test = "less",
polygon_offset = c(0.0, 0.0),
margin = "",
floating = FALSE,
tag = "",
blend = c("src_alpha", "one_minus_src_alpha"),
col,
...
)
rgl.material.names
rgl.material.readonly
Users should use material3d() to set and query material properties. It returns values similarly
to par3d as follows:
When setting properties, it returns the previous values in a named list. A named list is also
returned when more than one value is queried. When a single value is queried it is returned
directly.
rgl.material() is called for the side effect of setting the material properties.
It returns a value invisibly which is not intended for use by the user.
material3d passes these to rgl.material; rgl.material ignores unrecognized arguments. See Details below.
the rgl id of an object to query, or NULL
to query or set the defaults.
vector of R color characters. Represents the diffuse component in case of lighting calculation (lit = TRUE), otherwise it describes the solid color characteristics.
logical, specifying if lighting calculation should take place on geometry
properties for lighting calculation. ambient, specular, emission are R color character string values; shininess represents a numerical.
vector of alpha values between 0.0 (fully transparent) .. 1.0 (opaque).
logical, specifying whether Gouraud shading (smooth) or flat shading should be used.
path to a texture image file. Supported formats: png.
specifies what is defined with the pixmap
alpha values
luminance
luminance and alpha
color
color and alpha texture
Logical, specifies if the texture should be mipmapped.
specifies the magnification filtering type (sorted by ascending quality):
texel nearest to the center of the pixel
weighted linear average of a 2x2 array of texels
specifies the minification filtering type (sorted by ascending quality):
texel nearest to the center of the pixel
weighted linear average of a 2x2 array of texels
low quality mipmapping
medium quality mipmapping
medium quality mipmapping
high quality mipmapping
logical, specifies if auto-generated texture coordinates for environment-mapping should be performed on geometry.
Determines the polygon mode for the specified side:
filled polygon
wireframed polygon
point polygon
culled (hidden) polygon
numeric, specifying the size of points in pixels
numeric, specifying the line width in pixels
logical, specifying if fog effect should be applied on the corresponding shape. Fog type is set in bg3d.
logical, specifying if points should be round and lines should be antialiased, but see Note below.
logical, specifying whether the object's depth should be stored.
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".
If non-zero, offsets are added to the recorded depth of filled polygons. See Details below.
Used mainly for text to
draw annotations in the margins, but supported by
most kinds of objects: see mtext3d.
A length 1 string value. These may be used to identify objects, or encode other meta data about the object.
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; color has no effect.
One; color is added to the other term.
Multiply by source color or its opposite.
Multiply by destination color or its opposite.
Multiply by source alpha or its opposite. Default values.
Multiply by destination alpha or its opposite.
These are allowed, but to be useful they require other settings which rgl doesn't support.
An allowed abbreviation of color.
Values can be queried by specifying their names
in a character vector, e.g. material3d("color").
The rgl.material.names variable contains the
full list of material names.
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:
Is the current color transparent?
Only one side at a time can be culled.
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.
The color is set to the emission property
of the object.
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.
The polygon_offset property is a 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.
material3d is the recommended interface to the material properties, modelled after
par3d: unspecified parameters,
will be left unchanged, whereas rgl.material
will set them to the defaults shown above.
material3d may also be used to query the material
properties; see the examples below.
The material member of the r3dDefaults list may be used to
set default values for material properties.
The ... parameter to rgl.material is ignored.
bbox3d,
bg3d,
light3d
save <- material3d("color")
material3d(color = "red")
material3d("color")
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"))
Run the code above in your browser using DataLab