Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# `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 must be balanced with a corresponding `popClip`.

Instance methods

fillPath(path, evenOdd, transform, colorspace, color, alpha, colorParams)

  Fill a path.

  Arguments:

    - path – `Path` object.

    - evenOdd – The even odd rule to use.

    - transform – `[a,b,c,d,e,f]`. The transform matrix.

    - colorspace – The ColorSpace.

    - color – The color value.

    - alpha – The alpha value.

    - colorParams – The color parameters object.

  EXAMPLE

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

strokePath(path, stroke, transform, colorspace, color, alpha, colorParams)

  Stroke a path.

  Arguments:

    - path – `Path` object.

    - stroke – `StrokeState` The stroke state object.

    - transform – `[a,b,c,d,e,f]`. The transform matrix.

    - colorspace – The ColorSpace.

    - color – The color value.

    - alpha – The alpha value.

    - colorParams – The color parameters object.

  EXAMPLE

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

clipPath(path, evenOdd, transform)

  Clip a path.

  Arguments:

    - path – `Path` object.

    - evenOdd – The even odd rule to use.

    - transform – `[a,b,c,d,e,f]`. The transform matrix.

  EXAMPLE

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

clipStrokePath(path, stroke, transform)

  Clip & stroke a path.

  Arguments:

    - path – `Path` object.

    - stroke – `StrokeState` The stroke state object.

    - transform – `[a,b,c,d,e,f]`. The transform matrix.

  EXAMPLE

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

fillText(text, transform, colorspace, color, alpha, colorParams)

  Fill a text object.

  Arguments:

    - text – `Text` object.

    - transform – `[a,b,c,d,e,f]`. The transform matrix.

    - colorspace – The ColorSpace.

    - color – The color value.

    - alpha – The alpha value.

    - colorParams – The color parameters object.

  EXAMPLE

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

strokeText(text, stroke, transform, colorspace, color, alpha, colorParams)

  Stroke a text object.

  Arguments:

    - text – `Text` object.

    - stroke – `StrokeState` The stroke state object.

    - transform – `[a,b,c,d,e,f]`. The transform matrix.

    - colorspace – The ColorSpace.

    - color – The color value.

    - alpha – The alpha value.

    - colorParams – The color parameters object.

  EXAMPLE

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

clipText(text, transform)

  Clip a text object.

  Arguments:

    - text – `Text` object.

    - transform – `[a,b,c,d,e,f]`. The transform matrix.

  EXAMPLE

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

clipStrokeText(text, stroke, transform)

  Clip & stroke a text object.

  Arguments:

    - text – `Text` object.

    - stroke – `StrokeState` The stroke state object.

    - transform – `[a,b,c,d,e,f]`. The transform matrix.

  EXAMPLE

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

ignoreText(text, transform)

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

  Arguments:

    - text – `Text` object.

    - transform – `[a,b,c,d,e,f]`. The transform matrix.

  EXAMPLE

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

fillShade(shade, transform, alpha, colorParams)

  Fill a shade (a.k.a. gradient).

  Note

  The details of gradient fills are not exposed to JavaScript yet.

  Arguments:

    - shade – The gradient.

    - transform – `[a,b,c,d,e,f]`. The transform matrix.

    - alpha – The alpha value.

    - colorParams – The color parameters object.

  EXAMPLE

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

fillImage(image, transform, alpha, colorParams)

  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` object.

    - transform – `[a,b,c,d,e,f]`. The transform matrix.

    - alpha – The alpha value.

    - colorParams – The color parameters object.

  EXAMPLE

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

fillImageMask(image, transform, colorspace, color, alpha, colorParams)

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

  Arguments:

    - image – `Image` object.

    - transform – `[a,b,c,d,e,f]`. The transform matrix.

    - colorspace – The ColorSpace.

    - color – The color value.

    - alpha – The alpha value.

    - colorParams – The color parameters object.

  EXAMPLE

      device.fillImageMask(image, mupdf.Matrix.identity, mupdf.ColorSpace.DeviceRGB, 0xff00ff, true, {});

clipImageMask(image, transform)

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

  Arguments:

    - image – `Image` object.

    - transform – `[a,b,c,d,e,f]`. The transform matrix.

  EXAMPLE

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

popClip()

  Pop the clip mask installed by the last clipping operation.

  EXAMPLE

      device.popClip();

beginMask(area, luminosity, backdropColorspace, backdropColor, backdropAlpha, colorParams)

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

  Arguments:

    - area – `Path` 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.

    - backdropColorspace – The ColorSpace.

    - backdropColor – The color value.

    - backdropAlpha – The alpha value.

    - colorParams – The color parameters object.

  EXAMPLE

      device.beginMask(path, true, mupdf.ColorSpace.DeviceRGB, 0xff00ff, false, {});

endMask()

  Ends the mask.

  EXAMPLE

      device.endMask();

beginGroup(area, colorspace, isolated, knockout, blendmode, alpha)

  Push/pop a transparency blending group. See the PDF reference for details on `isolated` and `knockout`.

  Arguments:

    - area – `[ulx,uly,lrx,lry]` Rectangle. The blend area.

    - colorspace – ColorSpace.

    - isolated – `Boolean`.

    - knockout – `Boolean`.

    - blendmode – Blendmode is one of the standard PDF blend modes: “Normal”, “Multiply”, “Screen”, etc.

    - alpha – The alpha value.

  EXAMPLE

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

endGroup()

  Ends the blending group.

  EXAMPLE

      device.endGroup();

beginTile(areaRect, viewRect, xStep, yStep, transform, 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:

    - areaRect – `[ulx,uly,lrx,lry]` Rectangle.

    - viewRect – `[ulx,uly,lrx,lry]` Rectangle.

    - xStep – `Integer` representing `x` step.

    - yStep – `Integer` representing `y` step.

    - transform – `[a,b,c,d,e,f]`. The transform matrix.

    - id – `Integer` The purpose of `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 it assumed to uniquely identify this tile.

  EXAMPLE

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

endTile()

  Ends the tiling pattern.

  EXAMPLE

      device.endTile();

beginLayer(tag)

  Begin a marked-content layer with the given tag.

  Arguments:

    - tag – `String`.

  EXAMPLE

      device.beginLayer("my tag");

endLayer()

  End a marked-content layer.

  EXAMPLE

      device.endLayer();

renderFlags(set, clear)

  mutool only

  Set/clear device rendering flags. Both set and clear are arrays where each element is a flag name:

  `"mask"`, `"color"`, `"uncacheable"`, `"fillcolor-undefined"`, `"strokecolor-undefined"`, `"startcap-undefined"`, `"dashcap-undefined"`, `"endcap-undefined"`, `"linejoin-undefined"`, `"miterlimit-undefined"`, `"linewidth-undefined"`, `"bbox-defined"`, or `"gridfit-as-tiled"`.

  Arguments:

    - set – `[]`.

    - clear – `[]`.

  EXAMPLE

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

setDefaultColorSpaces(defaults)

  Change the set of default colorspaces for the device. See the DefaultColorSpaces object.

  Arguments:

    - defaults – `Object`.

  EXAMPLE

beginStructure(standard, raw, uid)

  mutool only

  Begin a standard structure element, the raw tag name and a unique identifier.

  Arguments:

    - standard – `String`. One of the standard PDF structure names: “Document”, “Part”, “BlockQuote”, etc.

    - raw – `String`. The tag name.

    - uid – `Integer`. A unique identifier.

  EXAMPLE

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

endStructure()

  mutool only

  End a standard structure element.

  EXAMPLE

      device.endStructure();

beginMetatext(type, text)

  mutool only

  Begin meta text information.

  Arguments:

    - type – `String`. The type (either of `"ActualText"`, `"Alt"`, `"Abbreviation"`, or `"Title"`)

    - text – `String`. The text value.

  EXAMPLE

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

endMetatext()

  mutool only

  End meta text information.

  EXAMPLE

      device.endMetatext();

close()

  Tell the device that we are done, and flush any pending output. Ensure that no items are left on the stack before closing.

  EXAMPLE

      device.close();