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