Trait Backend 

pub trait Backend {
    // Required methods
    fn begin_page(&mut self, engine: &Engine, width: i32, height: i32);
    fn glyph(&mut self, engine: &Engine, font: u32, chr: u32, x: i32, y: i32);
    fn rule(&mut self, x: i32, y: i32, width: i32, height: i32);
    fn literal(&mut self, mode: u8, data: &[u8], x: i32, y: i32);
    fn end_page(&mut self, engine: &Engine);
    fn finish(&mut self, engine: &mut Engine) -> Option<Finished>;

    // Provided methods
    fn glyph_expanded(
        &mut self,
        engine: &Engine,
        font: u32,
        chr: u32,
        x: i32,
        y: i32,
        ef: i32,
    ) { ... }
    fn print(&mut self, mode: u8, data: &[u8], x: i32, y: i32) { ... }
    fn save(&mut self, x: i32, y: i32) { ... }
    fn restore(&mut self, x: i32, y: i32) { ... }
    fn set_matrix(&mut self, x: i32, y: i32, matrix: &[u8]) { ... }
    fn suspend(&mut self) -> Result<()> { ... }
    fn resumable(&self) -> bool { ... }
    fn fingerprint(&mut self) -> u64 { ... }
    fn prefix(&mut self) -> Option<Vec<u8>> { ... }
    fn output_file(&self) -> Option<(PathBuf, PathBuf)> { ... }
    fn divert(&mut self, _to: &Path) -> Result<()> { ... }
    fn splice(
        &mut self,
        _prefix: &[u8],
        _from: &Path,
        _saved: &[u8],
        _cut: u64,
        _to: &Path,
    ) -> Result<()> { ... }
    fn resume(&mut self) -> Result<()> { ... }
    fn abandon(&mut self, _remove: bool) { ... }
    fn begin_object(&mut self, _engine: &Engine) { ... }
    fn current_page_object(&self) -> Option<i32> { ... }
    fn close_page_contents(&mut self, _engine: &Engine, _items: &PageItems) { ... }
    fn page_items(&mut self, _engine: &Engine, _items: &PageItems) { ... }
    fn begin_box_form(
        &mut self,
        _engine: &Engine,
        _index: u32,
        _size: (i32, i32, i32),
        _attr: &[u8],
        _resources: &[u8],
    ) { ... }
    fn end_box_form(&mut self, _engine: &Engine) { ... }
    fn close_box_form_resources(&mut self, _engine: &Engine) { ... }
    fn close_page_resources(&mut self, _engine: &Engine) { ... }
    fn box_form(
        &mut self,
        _engine: &Engine,
        _index: u32,
        _x: i32,
        _y: i32,
        _width: i32,
        _height: i32,
    ) { ... }
    fn write_image(&mut self, _engine: &Engine, _index: u32) { ... }
    fn image(
        &mut self,
        _engine: &Engine,
        _index: u32,
        _x: i32,
        _y: i32,
        _width: i32,
        _height: i32,
    ) { ... }
    fn written_images(&mut self) -> Option<Vec<u32>> { ... }
    fn write_object(&mut self, _engine: &Engine, _obj: &PdfObject) { ... }
}

A destination for shipped pages (the PDF writer). Coordinates are in scaled points from the lower-left corner of the page, y upwards.

Required Methods

fn begin_page(&mut self, engine: &Engine, width: i32, height: i32)

Starts a page of the given size.

fn glyph(&mut self, engine: &Engine, font: u32, chr: u32, x: i32, y: i32)

Draws character chr of font font with its origin at (x, y).

fn rule(&mut self, x: i32, y: i32, width: i32, height: i32)

Draws a filled rule with its lower-left corner at (x, y).

fn literal(&mut self, mode: u8, data: &[u8], x: i32, y: i32)

Emits a literal (\pdfextension literal) at (x, y).

fn end_page(&mut self, engine: &Engine)

Finishes the page.

fn finish(&mut self, engine: &mut Engine) -> Option<Finished>

Finishes the document.

Provided Methods

fn glyph_expanded( &mut self, engine: &Engine, font: u32, chr: u32, x: i32, y: i32, ef: i32, )

Draws a glyph expanded horizontally by ef millionths of its width (font expansion; ef is never 0).

fn print(&mut self, mode: u8, data: &[u8], x: i32, y: i32)

Emits text written by pdf.print at (x, y): a literal without the newline after it (observed).

fn save(&mut self, x: i32, y: i32)

\pdfextension save at (x, y).

fn restore(&mut self, x: i32, y: i32)

\pdfextension restore at (x, y).

fn set_matrix(&mut self, x: i32, y: i32, matrix: &[u8])

\pdfextension setmatrix at (x, y).

fn suspend(&mut self) -> Result<()>

Before the process forks for a preamble snapshot: writes out what is buffered (see resume).

fn resumable(&self) -> bool

Whether a pass can resume from the snapshot taken at suspend: the output file is still there, at least as long as then (a failed build may have removed it).

fn fingerprint(&mut self) -> u64

A fingerprint of the state that decides what the backend writes from now on (see crate::fingerprint): not what it wrote.

fn prefix(&mut self) -> Option<Vec<u8>>

For --watch (see docs/design/incremental-rebuilds.md): what the output holds so far, flushed to the file, as an encoded retex_pdf::Prefix; None if there is no output file.

fn output_file(&self) -> Option<(PathBuf, PathBuf)>

The output file, and where it was first opened (it keeps that name once the run is over).

fn divert(&mut self, _to: &Path) -> Result<()>

Gives the output file the second name to, under which it goes on (its first name may then be given to another file).

fn splice( &mut self, _prefix: &[u8], _from: &Path, _saved: &[u8], _cut: u64, _to: &Path, ) -> Result<()>

Goes on in file to with another run’s prefix (see prefix), read from that run’s file from, followed by saved from cut on: this backend’s output up to the end (taken from its file before the other run changed it), the two runs being in the same state at that point.

fn resume(&mut self) -> Result<()>

In a process resumed from a preamble snapshot: reopens the output file opened before the snapshot, cut back to its length then (the forked processes share the file’s position otherwise).

fn abandon(&mut self, _remove: bool)

Gives up the output file: with remove, it is deleted (after a fatal error), otherwise left empty (no pages), as LuaTeX does.

fn begin_object(&mut self, _engine: &Engine)

Prepares for writing an object whose text is still to be made (allocates the object stream it will go into, as LuaTeX does).

fn current_page_object(&self) -> Option<i32>

The object number of the page begun last.

fn close_page_contents(&mut self, _engine: &Engine, _items: &PageItems)

Writes the page’s contents and dictionary: the page attributes and resources of items are final, and whether there are annotations.

fn page_items(&mut self, _engine: &Engine, _items: &PageItems)

Hands over the page’s annotations, links, destinations and referenced objects, just before end_page.

fn begin_box_form( &mut self, _engine: &Engine, _index: u32, _size: (i32, i32, i32), _attr: &[u8], _resources: &[u8], )

Starts writing box resource index (natural size size = width, height, depth) as a form XObject; drawing goes into the form until end_box_form.

fn end_box_form(&mut self, _engine: &Engine)

Finishes the box resource being written (its content stream).

fn close_box_form_resources(&mut self, _engine: &Engine)

Writes the resources of the box resource finished last, after the forms it uses.

fn close_page_resources(&mut self, _engine: &Engine)

Writes the resources of the page ended last, after the forms it uses.

fn box_form( &mut self, _engine: &Engine, _index: u32, _x: i32, _y: i32, _width: i32, _height: i32, )

Draws box resource index with its lower-left corner at (x, y), scaled to width × height (height + depth).

fn write_image(&mut self, _engine: &Engine, _index: u32)

Writes image resource index (its object number) now (\immediate).

fn image( &mut self, _engine: &Engine, _index: u32, _x: i32, _y: i32, _width: i32, _height: i32, )

Draws image resource index with its lower-left corner at (x, y), width wide and height (height + depth) tall.

fn written_images(&mut self) -> Option<Vec<u32>>

The images written (when the pages and forms using them were closed) since the last call, if the backend writes them that way; None to have them announced at the end of the page using them.

fn write_object(&mut self, _engine: &Engine, _obj: &PdfObject)

Writes an object created with \pdfextension obj.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors