R: Set up multiple figure layouts in rgl.

mfrow3d {rgl} | R Documentation

## Set up multiple figure layouts in rgl.

### Description

The `mfrow3d` and `layout3d` functions provide functionality in rgl similar to `par("mfrow")` and `layout` in classic R graphics.

### Usage

    subsceneList(value, window = rgl.cur())

    mfrow3d(nr, nc, byrow = TRUE, parent = NA, sharedMouse = FALSE, ...)
    layout3d(mat, widths = rep.int(1, ncol(mat)),
                  heights = rep.int(1, nrow(mat)),
                  parent = NA, sharedMouse = FALSE,
                  ...)
    next3d(current = NA, clear = TRUE, reuse = TRUE)
    clearSubsceneList(delete = currentSubscene3d() %in% subsceneList(),
                      window = rgl.cur())

### Arguments

`value` | A new subscene list to set. If missing, return the current one (or `NULL`).
`window` | Which window to operate on.
`nr, nc` | Number of rows and columns of figures.
`byrow` | Whether figures progress by row (as with `par("mfrow")`) or by column (as with `par("mfcol")`).
`mat, widths, heights` | Layout parameters; see `layout` for their interpretation.
`parent` | The parent subscene. `NA` indicates the current subscene. See Details below.
`sharedMouse` | Whether to make all subscenes `par3d("listeners")` to each other.
`...` | Additional parameters to pass to `newSubscene3d` as each subscene is created.
`current` | The subscene to move away from. `NA` indicates the current subscene.
`clear` | Whether the newly entered subscene should be cleared upon entry.
`reuse` | Whether to skip advancing if the current subscene has no objects in it.
`delete` | If `TRUE`, delete the subscenes in the current window.

### Details

rgl can maintain a list of subscenes; the `mfrow3d` and `layout3d` functions create that list. When the list is in place, `next3d` causes rgl to move to the next scene in the list, or cycle back to the first one.

Unlike the classic R graphics versions of these functions, these functions are completely compatible with each other. You can mix them within a single rgl window.

In the default case where `parent` is missing, `mfrow3d` and `layout3d` will call `clearSubsceneList()` at the start.

By default `clearSubsceneList()` checks whether the current subscene is in the current subscene list; if so, it will delete all subscenes in the list, and call `gc3d` to delete any objects that are no longer shown. The subscene list will be set to a previous value if one was recorded, or `NULL` if not.

If `parent` is specified in `mfrow3d` or `layout3d` (even as `NA`), the new subscenes will be created within the parent.

### Value

`mfrow3d` and `layout3d` return a vector of subscene id values that have just been created. If a previous subscene list was in effect and was not automatically cleared, it is attached as an attribute `"prev"`.

### Author(s)

Duncan Murdoch

### See Also

`newSubscene3d`, `par`, `layout`.

### Examples

    shapes <- list(Tetrahedron = tetrahedron3d(), Cube = cube3d(), Octahedron = octahedron3d(),
                   Icosahedron = icosahedron3d(), Dodecahedron = dodecahedron3d(),
                   Cuboctahedron = cuboctahedron3d())
    col <- rainbow(6)
    open3d()
    mfrow3d(3, 2)
    for (i in 1:6) {
      next3d()   # won't advance the first time, since it is empty
      shade3d(shapes[[i]], col = col[i])
    }
    highlevel(integer()) # To trigger display as rglwidget

    open3d()
    mat <- matrix(1:4, 2, 2)
    mat <- rbind(mat, mat + 4, mat + 8)
    layout3d(mat, height = rep(c(3, 1), 3), sharedMouse = TRUE)
    for (i in 1:6) {
      next3d()
      shade3d(shapes[[i]], col = col[i])
      next3d()
      text3d(0, 0, 0, names(shapes)[i])
    }
    highlevel(integer())

[Package rgl version 0.99.9 Index]