Trait DeviceDriver

pub trait DeviceDriver: Sized {
    const USE_RASTER: bool = true;
    const USE_CAPTURE: bool = true;
    const USE_LOCATOR: bool = true;
    const USE_PLOT_HISTORY: bool = false;
    const CLIPPING_STRATEGY: ClippingStrategy = ClippingStrategy::DeviceAndEngine;
    const ACCEPT_UTF8_TEXT: bool = true;

    // Provided methods
    fn activate(&mut self, dd: DevDesc) { ... }
    fn circle(
        &mut self,
        center: (f64, f64),
        r: f64,
        gc: R_GE_gcontext,
        dd: DevDesc,
    ) { ... }
    fn clip(&mut self, from: (f64, f64), to: (f64, f64), dd: DevDesc) { ... }
    fn close(&mut self, dd: DevDesc) { ... }
    fn deactivate(&mut self, dd: DevDesc) { ... }
    fn line(
        &mut self,
        from: (f64, f64),
        to: (f64, f64),
        gc: R_GE_gcontext,
        dd: DevDesc,
    ) { ... }
    fn char_metric(
        &mut self,
        c: char,
        gc: R_GE_gcontext,
        dd: DevDesc,
    ) -> TextMetric { ... }
    fn mode(&mut self, mode: i32, dd: DevDesc) { ... }
    fn new_page(&mut self, gc: R_GE_gcontext, dd: DevDesc) { ... }
    fn polygon<T: IntoIterator<Item = (f64, f64)>>(
        &mut self,
        coords: T,
        gc: R_GE_gcontext,
        dd: DevDesc,
    ) { ... }
    fn polyline<T: IntoIterator<Item = (f64, f64)>>(
        &mut self,
        coords: T,
        gc: R_GE_gcontext,
        dd: DevDesc,
    ) { ... }
    fn rect(
        &mut self,
        from: (f64, f64),
        to: (f64, f64),
        gc: R_GE_gcontext,
        dd: DevDesc,
    ) { ... }
    fn path<T: IntoIterator<Item = impl IntoIterator<Item = (f64, f64)>>>(
        &mut self,
        coords: T,
        winding: bool,
        gc: R_GE_gcontext,
        dd: DevDesc,
    ) { ... }
    fn raster<T: AsRef<[u32]>>(
        &mut self,
        raster: Raster<T>,
        pos: (f64, f64),
        size: (f64, f64),
        angle: f64,
        interpolate: bool,
        gc: R_GE_gcontext,
        dd: DevDesc,
    ) { ... }
    fn capture(&mut self, dd: DevDesc) -> Robj { ... }
    fn size(&mut self, dd: DevDesc) -> (f64, f64, f64, f64) { ... }
    fn text_width(&mut self, text: &str, gc: R_GE_gcontext, dd: DevDesc) -> f64 { ... }
    fn text(
        &mut self,
        pos: (f64, f64),
        text: &str,
        angle: f64,
        hadj: f64,
        gc: R_GE_gcontext,
        dd: DevDesc,
    ) { ... }
    fn on_exit(&mut self, dd: DevDesc) { ... }
    fn new_frame_confirm(&mut self, dd: DevDesc) -> bool { ... }
    fn holdflush(&mut self, dd: DevDesc, level: i32) -> i32 { ... }
    fn locator(&mut self, x: *mut f64, y: *mut f64, dd: DevDesc) -> bool { ... }
    fn eventHelper(&mut self, dd: DevDesc, code: i32) { ... }
    fn create_device<T: DeviceDriver>(
        self,
        device_descriptor: DeviceDescriptor,
        device_name: &'static str,
    ) -> Device { ... }
}

A graphic device implementation.

Safety

To implement these callback functions, extreme care is needed to avoid any panic!() because it immediately crashes the R session. Usually, extendr handles a panic gracefully, but there’s no such protect on the callback functions.

Provided Associated Constants

const USE_RASTER: bool = true

Whether the device accepts the drawing operation of a raster. By default, the default implementation, which just ignores the raster, is used so this can be left true. If there’s a necessity to explicitly refuse the operation, this can be set false.

const USE_CAPTURE: bool = true

Whether the device accepts a capturing operation. By default, the default implementation, which just returns an empty capture, is used so this can be left true. If there’s a necessity to explicitly refuse the operation, this can be set false.

const USE_LOCATOR: bool = true

Whether the device has a locator capability, i.e., reading the position of the graphics cursor when the mouse button is pressed. It works with X11, windows and quartz devices.

const USE_PLOT_HISTORY: bool = false

Whether the device maintains a plot history. This corresponds to displayListOn in the underlying DevDesc.

const CLIPPING_STRATEGY: ClippingStrategy = ClippingStrategy::DeviceAndEngine

To what extent the device takes the responsibility of clipping. See ClippingStrategy for the details.

const ACCEPT_UTF8_TEXT: bool = true

Set this to false if the implemented strWidth() and text() only accept ASCII text.

Provided Methods

fn activate(&mut self, dd: DevDesc)

A callback function to setup the device when the device is activated.

fn circle(&mut self, center: (f64, f64), r: f64, gc: R_GE_gcontext, dd: DevDesc)

A callback function to draw a circle.

The header file¹ states:

• The border of the circle should be drawn in the given col (i.e. gc.col).
• The circle should be filled with the given fill (i.e. gc.fill) colour.
• If col is NA_INTEGER then no border should be drawn.
• If fill is NA_INTEGER then the circle should not be filled.

---

1. https://github.com/wch/r-source/blob/9f284035b7e503aebe4a804579e9e80a541311bb/src/include/R_ext/GraphicsDevice.h#L205-L210 ↩

fn clip(&mut self, from: (f64, f64), to: (f64, f64), dd: DevDesc)

A callback function to clip.

fn close(&mut self, dd: DevDesc)

A callback function to free device-specific resources when the device is killed. Note that, self MUST NOT be dropped within this function because the wrapper that extendr internally generates will do it.

fn deactivate(&mut self, dd: DevDesc)

A callback function to clean up when the device is deactivated.

fn line( &mut self, from: (f64, f64), to: (f64, f64), gc: R_GE_gcontext, dd: DevDesc, )

A callback function to draw a line.

fn char_metric(&mut self, c: char, gc: R_GE_gcontext, dd: DevDesc) -> TextMetric

A callback function that returns the TextMetric (ascent, descent, and width) of the given character in device unit.

The default implementation returns (0, 0, 0), following the convention described in the header file:

If the device cannot provide metric information then it MUST return 0.0 for ascent, descent, and width.

fn mode(&mut self, mode: i32, dd: DevDesc)

A callback function called whenever the graphics engine starts drawing (mode=1) or stops drawing (mode=0).

fn new_page(&mut self, gc: R_GE_gcontext, dd: DevDesc)

A callback function called whenever a new plot requires a new page.

fn polygon<T: IntoIterator<Item = (f64, f64)>>( &mut self, coords: T, gc: R_GE_gcontext, dd: DevDesc, )

A callback function to draw a polygon.

fn polyline<T: IntoIterator<Item = (f64, f64)>>( &mut self, coords: T, gc: R_GE_gcontext, dd: DevDesc, )

A callback function to draw a polyline.

fn rect( &mut self, from: (f64, f64), to: (f64, f64), gc: R_GE_gcontext, dd: DevDesc, )

A callback function to draw a rect.

fn path<T: IntoIterator<Item = impl IntoIterator<Item = (f64, f64)>>>( &mut self, coords: T, winding: bool, gc: R_GE_gcontext, dd: DevDesc, )

A callback function to draw paths.

nper contains number of points in each polygon. winding represents the filling rule; true means “nonzero”, false means “evenodd” (c.f. https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/fill-rule).

fn raster<T: AsRef<[u32]>>( &mut self, raster: Raster<T>, pos: (f64, f64), size: (f64, f64), angle: f64, interpolate: bool, gc: R_GE_gcontext, dd: DevDesc, )

A callback function to draw a Raster.

pos gives the bottom-left corner. angle is the rotation in degrees, with positive rotation anticlockwise from the positive x-axis. interpolate is whether to apply the linear interpolation on the raster image.

fn capture(&mut self, dd: DevDesc) -> Robj

A callback function that captures and returns the current canvas.

This is only meaningful for raster devices.

fn size(&mut self, dd: DevDesc) -> (f64, f64, f64, f64)

A callback function that returns the current device size in the format of (left, right, bottom, top) in points.

• If the size of the graphic device won’t change after creation, the function can simply return the left, right, bottom, and top of the DevDesc (the default implementation).
• If the size can change, probably the actual size should be tracked in the device-specific struct, i.e. self, and the function should refer to the field (e.g., cbm_Size() in the cairo device).

Note that, while this function is what is supposed to be called “whenever the device is resized,” it’s not automatically done by the graphic engine. The header file states:

This is not usually called directly by the graphics engine because the detection of device resizes (e.g., a window resize) are usually detected by device-specific code.

fn text_width(&mut self, text: &str, gc: R_GE_gcontext, dd: DevDesc) -> f64

A callback function that returns the width of the given string in the device units.

The default implementation use char_metric() on each character in the text and sums the widths. This should be sufficient for most of the cases, but the developer can choose to implement this. The header file¹ suggests the possible reasons:

• for performance
• to decide what to do when font metric information is not available

---

1. https://github.com/wch/r-source/blob/9bb47ca929c41a133786fa8fff7c70162bb75e50/src/include/R_ext/GraphicsDevice.h#L67-L74 ↩

fn text( &mut self, pos: (f64, f64), text: &str, angle: f64, hadj: f64, gc: R_GE_gcontext, dd: DevDesc, )

A callback function to draw a text.

angle is the rotation in degrees, with positive rotation anticlockwise from the positive x-axis.

fn on_exit(&mut self, dd: DevDesc)

A callback function called when the user aborts some operation. It seems this is rarely implemented.

fn new_frame_confirm(&mut self, dd: DevDesc) -> bool

A callback function to confirm a new frame. It seems this is rarely implementad.

fn holdflush(&mut self, dd: DevDesc, level: i32) -> i32

A callback function to manage the “suspension level” of the device. R function dev.hold() is used to increase the level, and dev.flush() to decrease it. When the level reaches zero, output is supposed to be flushed to the device. This is only meaningful for screen devices.

fn locator(&mut self, x: *mut f64, y: *mut f64, dd: DevDesc) -> bool

A callback function that returns the coords of the event

fn eventHelper(&mut self, dd: DevDesc, code: i32)

A callback function for X11_eventHelper.

fn create_device<T: DeviceDriver>( self, device_descriptor: DeviceDescriptor, device_name: &'static str, ) -> Device

Create a Device.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors