Skip to content
Back to top

# Device

All built-in devices have the methods listed below. Any function that accepts a device will also accept a Javascript object with the same methods. Any missing methods are simply ignored, so you only need to create methods for the device calls you care about.

Many of the methods take graphics objects as arguments: Path, Text, Image and Shade.

Colors are specified as arrays with the appropriate number of components for the color space.

The methods that clip graphics, e.g. `Device.prototype.clipPath()`, `Device.prototype.clipStrokePath()`, `Device.prototype.clipText()`, etc., must be balanced with a corresponding `Device.prototype.popClip()`.

## Constructors

class Device(callbacks)

  Create a Device which calls back to Javascript.

  The callback object may provide functions matching the methods on the Device class. Any device calls that don’t have a corresponding function will simply be ignored.

  Arguments:

    - callbacks – object containing callback functions

You can create other devices with DrawDevice and DisplayListDevice.

## Constants

Blend mode constants for use with `Device.prototype.beginGroup`:

Device.BLEND_NORMAL

Device.BLEND_MULTIPLY

Device.BLEND_SCREEN

Device.BLEND_OVERLAY

Device.BLEND_DARKEN

Device.BLEND_LIGHTEN

Device.BLEND_COLOR_DODGE

Device.BLEND_COLOR_BURN

Device.BLEND_HARD_LIGHT

Device.BLEND_SOFT_LIGHT

Device.BLEND_DIFFERENCE

Device.BLEND_EXCLUSION

Device.BLEND_HUE

Device.BLEND_SATURATION

Device.BLEND_COLOR

Device.BLEND_LUMINOSITY

## Instance methods

Device.prototype.close()

  Tell this device that we are done, and flush any pending output.

  Before closing, ensure that there have been as many calls to `popClip()` as there have been to the clipping functions: `clipPath()`, `clipStrokePath()`, `clipText()`, etc.

      device.close()

### Line art

Device.prototype.fillPath(path, evenOdd, ctm, colorspace, color, alpha)

  Fill a path.

  Arguments:

    - path (`Path`) – Path object.

    - evenOdd (`boolean`) – Use even-odd rule or non-zero winding number rule to fill the path.

    - ctm (`Matrix`) – The transform to apply.

    - colorspace (`ColorSpace`) – The colorspace of the color to fill with.

    - color (`Color`) – The color to fill the path with.

    - alpha (`number`) – The opacity.

      device.fillPath(path, false, mupdf.Matrix.identity, mupdf.ColorSpace.DeviceRGB, [1, 0, 0], true)

Device.prototype.strokePath(path, stroke, ctm, colorspace, color, alpha)

  Stroke a path.

  Arguments:

    - path (`Path`) – Path object.

    - stroke (`StrokeState`) – Stroke state.

    - ctm (`Matrix`) – The transform to apply.

    - colorspace (`ColorSpace`) – Colorspace.

    - color (`Color`) – The color to stroke the path with.

    - alpha (`number`) – The opacity.

      device.strokePath(path,
              {dashes: [5, 10], lineWidth: 3, lineCap: 'Round' },
              mupdf.Matrix.identity,
              mupdf.ColorSpace.DeviceRGB,
              [0, 1, 0],
              0.5
      )

Device.prototype.clipPath(path, evenOdd, ctm)

  Clip a path.

  Arguments:

    - path (`Path`) – Path object.

    - evenOdd (`boolean`) – Use even-odd rule or non-zero winding number rule to fill the path.

    - ctm (`Matrix`) – The transform to apply.

      device.clipPath(path, true, mupdf.Matrix.identity)

Device.prototype.clipStrokePath(path, stroke, ctm)

  Clip & stroke a path.

  Arguments:

    - path (`Path`) – Path object.

    - stroke (`StrokeState`) – Stroke state.

    - ctm (`Matrix`) – The transform to apply.

      device.clipStrokePath(path, true, mupdf.Matrix.identity)

### Text

Device.prototype.fillText(text, ctm, colorspace, color, alpha)

  Fill a text object.

  Arguments:

    - text (`Text`) – Text object.

    - ctm (`Matrix`) – The transform to apply.

    - colorspace (`ColorSpace`) – Colorspace

    - color (`Color`) – The color used to fill the text.

    - alpha (`number`) – The opacity.

      device.fillText(text, mupdf.Matrix.identity, mupdf.ColorSpace.DeviceRGB, [1, 0, 0], 1)

Device.prototype.strokeText(text, stroke, ctm, colorspace, color, alpha)

  Stroke a text object.

  Arguments:

    - text (`Text`) – Text object.

    - stroke (`StrokeState`) – Stroke state.

    - ctm (`Matrix`) – The transform to apply.

    - colorspace (`ColorSpace`) – Colorspace

    - color (`Color`) – The color used to stroke the text.

    - alpha (`number`) – The opacity.

      device.strokeText(text,
              { dashes: [5, 10], lineWidth: 3, lineCap: 'Round' },
              mupdf.Matrix.identity,
              mupdf.ColorSpace.DeviceRGB,
              [1, 0, 0],
              1
      )

Device.prototype.clipText(text, ctm)

  Clip a text object.

  Arguments:

    - text (`Text`) – Text object.

    - ctm (`Matrix`) – The transform to apply.

      device.clipText(text, mupdf.Matrix.identity)

Device.prototype.clipStrokeText(text, stroke, ctm)

  Clip & stroke a text object.

  Arguments:

    - text (`Text`) – Text object.

    - stroke (`StrokeState`) – stroke state.

    - ctm (`Matrix`) – The transform to apply.

      device.clipStrokeText(text,
              { dashes: [5, 10], lineWidth: 3, lineCap: 'Round' },
              mupdf.Matrix.identity
      )

Device.prototype.ignoreText(text, ctm)

  Invisible text that can be searched but should not be visible, such as for overlaying a scanned OCR image.

  Arguments:

    - text (`Text`) – Text object.

    - ctm (`Matrix`) – The transform to apply.

      device.ignoreText(text, mupdf.Matrix.identity)

### Shadings

Device.prototype.fillShade(shade, ctm, alpha)

  Fill a shading, also known as a gradient.

  Arguments:

    - shade (`Shade`) – The gradient.

    - ctm (`Matrix`) – The transform to apply.

    - alpha (`number`) – The opacity.

      device.fillShade(shade, mupdf.Matrix.identity, true, { overPrinting: true })

### Images

Device.prototype.fillImage(image, ctm, alpha)

  Draw an image. An image always fills a unit rectangle [0, 0, 1, 1], so must be transformed to be placed and drawn at the appropriate size.

  Arguments:

    - image (`Image`) – Image object.

    - ctm (`Matrix`) – The transform to apply.

    - alpha (`number`) – The opacity.

      device.fillImage(image, mupdf.Matrix.identity, false, { overPrinting: true })

Device.prototype.fillImageMask(image, ctm, colorspace, color, alpha)

  An image mask is an image without color. Fill with the color where the image is opaque.

  Arguments:

    - image (`Image`) – Image object.

    - ctm (`Matrix`) – The transform to apply.

    - colorspace (`ColorSpace`) – Colorspace

    - color (`Color`) – The color to be used.

    - alpha (`number`) – The opacity.

      device.fillImageMask(image, mupdf.Matrix.identity, mupdf.ColorSpace.DeviceRGB, [0, 1, 0], true)

Device.prototype.clipImageMask(image, ctm)

  Clip graphics using the image to mask the areas to be drawn.

  Arguments:

    - image (`Image`) – Image object.

    - ctm (`Matrix`) – The transform to apply.

      device.clipImageMask(image, mupdf.Matrix.identity)

### Clipping and masking

Device.prototype.popClip()

  Pop the clip mask installed by the last clipping operation.

      device.popClip()

Device.prototype.beginMask(area, luminosity, colorspace, color)

  Create a soft mask. Any drawing commands between `beginMask` and `endMask` are grouped and used as a clip mask.

  Arguments:

    - area (`Rect`) – Mask area.

    - luminosity (`boolean`) – If luminosity is `true`, the mask is derived from the luminosity (grayscale value) of the graphics drawn; otherwise the color is ignored completely and the mask is derived from the alpha of the group.

    - colorspace (`ColorSpace`) – Colorspace

    - color (`Color`) – The color to be used.

      device.beginMask([0, 0, 100, 100], true, mupdf.ColorSpace.DeviceRGB, [1, 0, 1])

Device.prototype.endMask()

  Ends the mask.

      device.endMask()

### Groups and transparency

Device.prototype.beginGroup(area, colorspace, isolated, knockout, blendmode, alpha)

  Begin a transparency blending group. See knockout and isolation and blend mode in the glossary for a cursory overview of the concepts.

  Arguments:

    - area (`Rect`) – The blend area.

    - colorspace (`ColorSpace`) – Colorspace

    - isolated (`boolean`) – Whether the group is isolated.

    - knockout (`boolean`) – Whether the group is knockout.

    - blendmode (`string`) – The blend mode used when compositing this group with its backdrop.

    - alpha (`number`) – The opacity.

  The blendmode is one of these string values or the corresponding enum constants: Normal, Multiply, Screen, Overlay, Darken, Lighten, ColorDodge, ColorBurn, HardLight, SoftLight, Difference, Exclusion, Hue, Saturation, Color, Luminosity.

  You can also use the `Device.BLEND_NORMAL` constant:

      device.beginGroup(
              [0, 0, 100, 100],
              mupdf.ColorSpace.DeviceRGB,
              true,
              true,
              "Multiply",
              0.5
      )

Device.prototype.endGroup()

  Ends the blending group.

      device.endGroup()

### Tiling

Device.prototype.beginTile(area, view, xstep, ystep, ctm, id, doc_id)

  Draw a tiling pattern. Any drawing commands between `beginTile` and `endTile` are grouped and then repeated across the whole page. Apply a clip mask to restrict the pattern to the desired shape.

  Arguments:

    - area (`Rect`) – Area

    - view (`Rect`) – View

    - xstep (`number`) – x step.

    - ystep (`number`) – y step.

    - ctm (`Matrix`) – The transform to apply.

    - id (`number`)

    - doc_id (`number`) – The purpose of id/doc_id is to allow for efficient caching of rendered tiles. If id is 0, then no caching is performed. If it is non-zero, then id/doc_id are assumed to uniquely identify this tile.

      device.beginTile([0, 0, 100, 100], [100, 100, 200, 200], 10, 10, mupdf.Matrix.identity, 0)

Device.prototype.endTile()

  Ends the tiling pattern.

      device.endTile()

### Render flags

Device.prototype.renderFlags(set, clear)

  only mutool run

  The specified rendering flags are set, and some others are cleared.

  Both set and clear are arrays where each element one of these flag names:

  - “mask”

  - “color”

  - “uncacheable”

  - “fillcolor-undefined”

  - “strokecolor-undefined”

  - “startcap-undefined”

  - “dashcap-undefined”

  - “endcap-undefined”

  - “linejoin-undefined”

  - “miterlimit-undefined”

  - “linewidth-undefined”

  - “bbox-defined”

  - “gridfit-as-tiled”

  Arguments:

    - set (`Array of string`) – Rendering flags to set.

    - clear (`Array of string`) – Rendering flags to clear.

      device.renderFlags(["mask", "startcap-undefined"], [])

### Device colorspaces

Device.prototype.setDefaultColorSpaces(defaultCS)

  only mutool run

  Change the set of default device colorspaces to one given.

  Arguments:

    - defaultCS (`DefaultColorSpaces`) – The new set of default colorspaces.

      var defaultCS = new DefaultColorSpaces()
      defaultCS.setDefaultRGB(defaultCS.getDefaultGray())
      device.setDefaultColorSpaces(new DefaultColorSpaces())

### Layers

Device.prototype.beginLayer(name)

  Begin a marked-content layer with the given name.

  Arguments:

    - name (`string`) – Name of this marked-content layer.

      device.beginLayer("my tag")

Device.prototype.endLayer()

  End a marked-content layer.

      device.endLayer()

### Structures

Device.prototype.beginStructure(structure, raw, index)

  only mutool run

  Begin a standard structure type with the raw tag name and a unique identifier.

  Arguments:

    - structure (`string`) – One of the pre-defined structure types in PDF.

    - raw (`string`) – The tag name.

    - index (`number`) – A unique identifier.

      device.beginStructure("Document", "my_tag_name", 123)

Device.prototype.endStructure()

  only mutool run

  End a standard structure element.

      device.endStructure()

### Metatext

Device.prototype.beginMetatext(meta, text)

  only mutool run

  Begin meta text where meta is either of:

  - “ActualText”

  - “Alt”

  - “Abbreviation”

  - “Title”

  Arguments:

    - meta (`string`) – The meta text type

    - text (`string`) – The text value.

      device.beginMetatext("Title", "My title")

Device.prototype.endMetatext()

  only mutool run

  End meta text information.

      device.endMetatext()