rgl (version 1.2.8)

mfrow3d: Set up multiple figure layouts

Description

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

Usage

subsceneList(value, window = cur3d())
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 = cur3d())

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

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.

Author

Duncan Murdoch

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.

The next3d() function first finds out if the current subscene is in the current list. If not, it moves to the previous list, and looks there. Once it finds a list containing the current subscene, it moves to the next entry in that list. If it can't find one, it creates a length one list containing just the current subscene.

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