rgl.material {rgl} | R Documentation

## Generic Appearance setup

### Description

Set material properties for geometry appearance.

### Usage

    rgl.material(
      color        = c("white"),
      alpha        = c(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        = "fill",
      back         = "fill",
      size         = 3.0,
      lwd          = 1.0,
      fog          = TRUE,
      point_antialias = FALSE,
      line_antialias = FALSE,
      depth_mask   = TRUE,
      depth_test   = "less",
      ...
    )
    material3d(...)

### Arguments

`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 Gouraud shading (smooth) or flat shading should be used.
`texture` | path to a texture image file. Supported formats: png.

`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

`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
`point_antialias, line_antialias` | logical, specifying if points and lines should be antialiased
`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"`.
`...` | Any of the arguments above can be passed to `material3d`; see Details below. `rgl.material` will ignore others.

### Details

Values can be queried by specifying their names in a character vector, e.g. `material3d("color")`. There is one read-only property that can be queried but not set:

isTransparent

  Is the current colour transparent?

Only one side at a time can be culled.

`material3d` is an alternate interface to the material properties, modelled after `par3d`: rather than setting defaults for parameters that are not specified, they will be left unchanged. `material3d` may also be used to query the material properties; see the examples below.

The current implementation does not return parameters for textures.

If `point_antialias` is `TRUE`, points will be drawn as circles; otherwise, they will be drawn as squares. Lines tend to appear heavier with `line_antialias == TRUE`.

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

The `...` parameter to `rgl.material` is ignored.

### Value

`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.

Users should use `material3d()` to 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.

### See Also

`rgl.primitive`, `rgl.bbox`, `rgl.bg`, `rgl.light`

### Examples

    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

[Package rgl version 0.99.16 Index]