Deprecating the rgl.* interface

Duncan Murdoch

2024-11-18

Source: vignettes/deprecation.Rmd

Introduction

Since at least 2004, rgl has had two interfaces for many of the primitive functions: rgl.* and *3d. For example, to draw points you could use rgl.points() or points3d(). With the upcoming version 1.0.0 release of rgl, most of the duplication will be removed. The first step will be to deprecate a large number of rgl.* functions so they give warnings when they are called, and a few months later they will be removed from the package exports.

This document describes the differences and changes needed by users of the rgl.* interface.

Differences between the interfaces

Opening a window

The rgl.open() function has a single argument, useNULL. If set to TRUE, the NULL rgl device will be used. The par3d() settings will be set to their defaults.

The open3d() function has arguments

function(..., 
         params = getr3dDefaults(), 
         useNULL = rgl.useNULL(), 
         silent = FALSE )

and allows par3d() values to be specified, and uses the r3dDefaults variable to set default values for par3d(), material3d(), and bg3d(). Initially r3dDefaults is defined as

list(userMatrix = rotationMatrix(290*pi/180, 1, 0, 0),
     mouseMode = c("none", "trackball", "zoom", "fov", "pull"),
     FOV = 30,
     family = "sans",
     bg = list(color="white",
               fogtype = "none"),
     material = list(color="black", fog = TRUE)
)

Users can create their own default lists; e.g. to get the same result as rgl.open() would give, use

open3d(params = list())

or

r3dDefaults <- list()
open3d()

Material properties

The rgl.material() function has a large number of parameters. The pre-deprecation arguments were:

function(
  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,
  ...
)

Thus a call like rgl.material(color = "black") will set the color to black, and will also set all of the other parameters to the default values listed above.

On the other hand, the arguments to material3d() are

function (..., id = NULL)

Calling material3d(color = "black") will set the color to black and leave all other parameters unchanged.

Primitive shapes

The primitive shapes (points etc.) can be set using calls like rgl.points(x, y, z, color = "black") or points3d(x, y, z, color = "black").

The first difference is that rgl.* primitives will call rgl.material() to set the material properties: in this example color will be set to black, and all other parameters will be set to their defaults. The *3d versions of the primitives use material3d() to set material properties, so only those that were specified will be changed, and the original values will be restored afterwards.

The second difference is what happens if there is no window already open. The rgl.* functions will call rgl.open() (ignoring r3dDefaults), whereas the *3d functions will call open3d().

Why deprecate rgl.*?

Both of the systems worked, but they do not work together. For example, calling rgl.points() will have carry-on effects on later points3d() calls, whereas each points3d() call will just draw the points, it won’t affect future calls.

Users have found this confusing, and it makes their code hard to debug, and the rgl package hard to maintain. The *3d interface is more flexible, and more similar to the base graphics interface in R, so I’ve decided it will be the only one available going forward.

Some rgl.* functions are not deprecated

There will still be some rgl.* functions in the package. These are functions that are mainly intended for programming, such as rgl.attrib() and rgl.user2window(), and a few legacy functions like rgl.Sweave() supporting older approaches of using rgl.

In a few cases both function versions are identical (rgl.cur, rgl.ids, and rgl.pop are identical to cur3d, ids3d and pop3d respectively), and for those the rgl.* versions will be kept, but the documentation will concentrate on the *3d functions.

My package uses rgl.*. What do I need to do?

If your package is using rgl.* functions, the first step is to just make the substitutions suggested by the deprecation warning message. For example, if you use rgl.points(rnorm(10), rnorm(10), rnorm(10)) try using points3d(rnorm(10), rnorm(10), rnorm(10)) instead. In most cases this will give you what you want. In some cases more changes will be needed.

rgl.open and rgl.material

See above if you were using these.

Textures

The default color after rgl.open() was white, whereas with open3d() the default color is black, with a white background. Textures multiplicatively modify the color of the object, so after open3d(), a texture on an object will still appear black. Explicitly specifying color = "white" when a texture is used will fix this.

rgl.surface()

The arguments to rgl.surface() and surface3d() functions are different. The argument lists are

rgl.surface( x, z, y, 
             coords = 1:3,  ..., 
             normal_x = NULL, normal_y = NULL, normal_z = NULL,
             texture_s = NULL, texture_t = NULL)
surface3d(x, y = NULL, z = NULL,
          ...,
          normal_x = NULL, normal_y = NULL,
          normal_z = NULL,
          texture_s = NULL, texture_t=NULL)

Notice that the arguments are in a different order. Another difference is that rgl.surface() expects the surface to be defined in the y coordinate and viewed in the orientation produced by rgl.open(), not the one produced by open3d(). Up until very recently, surface3d() didn’t allow both x and z to be vectors.

The excellent rayshader package used the convention that the y argument held the surface, so the y direction should point up. Using view3d(theta = 45, phi = 45) (which it was already doing) gives a reasonable view.

Lists of material names and par3d properties

Many functions in rgl and other packages use ... to set material or par3d properties in a call, and for some, ... will contain other optional arguments. Some packages used the argument list of rgl.material() to identify the material property names. Going forward, packages should use the variables

rgl.material.names
rgl.material.readonly

These are character variables holding all the material property names. (rgl.material.names contains all names; rgl.material.readonly is the read-only subset of that list.) There are also variables

rgl.par3d.names
rgl.par3d.readonly

which give the same information for par3d.

Since these variables are recently added, you will need to add a dependence on rgl (>= 0.111.5) if you use them.

Others

If you have particular problems adapting other rgl.* to the *3d interface, please post them as issues on https://github.com/dmurdoch/rgl/issues . I’ll explain how to get what you want or fix things in rgl so you can do it.