logo

Trait extendr_api::graphics::device_driver::DeviceDriver

source · [−]
pub trait DeviceDriver: Sized {
    const USE_RASTER: bool;
    const USE_CAPTURE: bool;
    const USE_LOCATOR: bool;
    const USE_PLOT_HISTORY: bool;
    const CLIPPING_STRATEGY: ClippingStrategy;
    const ACCEPT_UTF8_TEXT: bool;

Show 24 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 { ... }

}
Expand description

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.

Associated Constants

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.

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.

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.

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

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

source

const ACCEPT_UTF8_TEXT: bool

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

Provided methods

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

A callback function to draw a circle.

The header file1 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 ↩

A callback function to clip.

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.

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

A callback function to draw a line.

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.

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

source

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

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

A callback function to draw a polygon.

A callback function to draw a polyline.

A callback function to draw a rect.

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

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.

A callback function that captures and returns the current canvas.

This is only meaningful for raster devices.

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.

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 file1 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 ↩

A callback function to draw a text.

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

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

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

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.

A callback function that returns the coords of the event

A callback function for X11_eventHelper.

Create a Device.

Implementors