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
const USE_RASTER: bool
const USE_RASTER: bool
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
const USE_CAPTURE: bool
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
const USE_LOCATOR: bool
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
const USE_PLOT_HISTORY: bool
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.
const ACCEPT_UTF8_TEXT: bool
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
isNA_INTEGER
then no border should be drawn. - If
fill
isNA_INTEGER
then the circle should not be filled.
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)
fn deactivate(&mut self, dd: DevDesc)
A callback function to clean up when the device is deactivated.
A callback function to draw a line.
fn char_metric(&mut self, c: char, gc: R_GE_gcontext, dd: DevDesc) -> TextMetric
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.
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)
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
)
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
)
fn polyline<T: IntoIterator<Item = (f64, f64)>>(
&mut self,
coords: T,
gc: R_GE_gcontext,
dd: DevDesc
)
A callback function to draw a polyline.
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
)
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).
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
, andtop
of theDevDesc
(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
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
file1 suggests the possible reasons:
- for performance
- to decide what to do when font metric information is not available
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.
fn new_frame_confirm(&mut self, dd: DevDesc) -> bool
fn new_frame_confirm(&mut self, dd: DevDesc) -> bool
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
fn eventHelper(&mut self, dd: DevDesc, code: i32)
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
fn create_device<T: DeviceDriver>(
self,
device_descriptor: DeviceDescriptor,
device_name: &'static str
) -> Device
Create a Device.