Global - Riffle docs

Methods

Riffle(optionsopt) → {RiffleCanvas}

Description:

Creates a Riffle viewer canvas.

The returned value is the canvas itself with viewer methods and getters mixed in. Riffle imposes no DOM wrapper or layout styling; the consumer decides how the canvas is positioned, scrolled, and decorated.

Source:

Riffle.js, line 42

Parameters:

Name	Type	Attributes	Default	Description
`options`	RiffleOptions	<optional>	`{}`	Viewer options.

Returns:

Canvas element with the public viewer API.

Type: RiffleCanvas

RifflePageStrip(viewer) → {HTMLDivElement}

Description:

Creates a thumbnail page strip bound to a Riffle viewer.

The returned element is an empty div populated with one thumbnail per page as the source loads. The strip emits class names only; consumers own all layout and styling.

Source:

RifflePageStrip.js, line 13

Parameters:

Name	Type	Description
`viewer`	RiffleCanvas \| BookViewer	Viewer canvas returned by `Riffle`, or a `BookViewer`.

Returns:

Page strip element. It also has pageStrip and refresh properties.

Type: HTMLDivElement

applyPaperPreset(display, presetId) → {Partial.<Display>}

Description:

Applies preset-derived paper colors to a display object.

Source:

model/paper.js, line 126

Parameters:

Name	Type	Description
`display`	Partial.<Display>	Display object to mutate.
`presetId`	string	Paper preset id.

Returns:

The mutated display object.

Type: Partial.<Display>

computeContentScale(layout, containerW, containerH) → {number}

Description:

Computes a scale that fits one page inside a container.

Source:

rendering/layout.js, line 141

Parameters:

Name	Type	Description
`layout`	Layout	Page layout.
`containerW`	number	Container width in pixels.
`containerH`	number	Container height in pixels.

Returns:

Render scale.

Type: number

computeLayoutValues(layout) → {Object}

Description:

Computes unscaled layout values.

Source:

rendering/layout.js, line 7

Parameters:

Name	Type	Description
`layout`	Layout	Page layout.

Returns:

Unscaled derived layout values.

Type: Object

computeMargins(layout, scale) → {Object}

Description:

Computes scaled margin and page dimensions.

Source:

rendering/layout.js, line 41

Parameters:

Name	Type	Description
`layout`	Layout	Page layout.
`scale`	number	Render scale.

Returns:

Scaled margin values.

Type: Object

computeScale(layout, containerW, containerH) → {number}

Description:

Computes a scale that fits a two-page spread inside a container.

Source:

rendering/layout.js, line 129

Parameters:

Name	Type	Description
`layout`	Layout	Page layout.
`containerW`	number	Container width in pixels.
`containerH`	number	Container height in pixels.

Returns:

Render scale.

Type: number

downscaleCanvasToMaxEdgeSync(source, maxEdge) → {HTMLCanvasElement|CanvasImageSource|null}

Description:

Synchronously downscales a canvas image source on the main thread.

Source:

loading/downscaleCanvas.js, line 24

Parameters:

Name	Type	Description
`source`	CanvasImageSource	Source image/canvas/bitmap.
`maxEdge`	number	Maximum output edge in pixels.

Returns:

Downscaled canvas, original source, or null.

Type: HTMLCanvasElement | CanvasImageSource | null

getPageGeometry(margins, sideName, page, pageRectXopt) → {Object}

Description:

Computes page, text block, overlay, and content placement rectangles for one side of a spread.

Source:

rendering/layout.js, line 67

Parameters:

Name	Type	Attributes	Default	Description
`margins`	Object			Scaled margins from `computeMargins`.
`sideName`	"left" \| "right"			Spread side.
`page`	ViewerPage \| Object \| null			Page metadata or viewer page.
`pageRectX`	number	<optional>	`0`	X coordinate for the page rectangle.

Returns:

Page geometry for rendering and overlays.

Type: Object

getPaperPresetIdForColor(paperColor) → {string}

Description:

Finds the paper preset id matching a paper color.

Source:

model/paper.js, line 114

Parameters:

Name	Type	Description
`paperColor`	string	CSS hex paper color.

Returns:

Matching preset id, or the default preset id.

Type: string

getPaperPresetOptions() → {Array.<{id: string, label: string}>}

Description:

Returns the available paper presets.

Source:

model/paper.js, line 92

Returns:

Preset options.

Type: Array.<{id: string, label: string}>

getPdfPageAspectRatio(pdfDoc, pageNum) → {Promise.<number>}

Description:

Returns a PDF page aspect ratio.

Source:

loading/pdfLoader.js, line 244

Parameters:

Name	Type	Description
`pdfDoc`	Object	Worker document handle.
`pageNum`	number	One-based PDF page number.

Returns:

Page width divided by page height.

Type: Promise.<number>

getPdfPageLinkAnnotations(pdfDoc, pageNum) → {Promise.<Object>}

Description:

Returns link annotations for a PDF page.

Source:

loading/pdfLoader.js, line 283

Parameters:

Name	Type	Description
`pdfDoc`	Object	Worker document handle.
`pageNum`	number	One-based PDF page number.

Returns:

Page viewport info and link annotations.

Type: Promise.<Object>

getPdfPageRasterSourceInfo(pdfDoc, pageNum) → {Promise.<Object>}

Description:

Returns raster source information for a PDF page.

Source:

loading/pdfLoader.js, line 255

Parameters:

Name	Type	Description
`pdfDoc`	Object	Worker document handle.
`pageNum`	number	One-based PDF page number.

Returns:

Raster source information.

Type: Promise.<Object>

getPdfPageTextContent(pdfDoc, pageNum) → {Promise.<Object>}

Description:

Returns selectable text content for a PDF page.

Source:

loading/pdfLoader.js, line 266

Parameters:

Name	Type	Description
`pdfDoc`	Object	Worker document handle.
`pageNum`	number	One-based PDF page number.

Returns:

Page viewport info and text items.

Type: Promise.<Object>

loadHocr(input) → {Promise.<Array.<Object>>}

Description:

Reads and parses hOCR markup.

Source:

loading/hocr.js, line 99

Parameters:

Name	Type	Description
`input`	string \| Document \| Blob	hOCR markup, parsed document, File, or Blob.

Returns:

Parsed text content pages.

Type: Promise.<Array.<Object>>

loadImageFile(file) → {Promise.<ImageBitmap>}

Description:

Loads an image file as an ImageBitmap.

Source:

loading/imageLoader.js, line 23

Parameters:

Name	Type	Description
`file`	Blob	Image file or blob.

Returns:

Loaded image bitmap.

Type: Promise.<ImageBitmap>

loadImagePreview(file, maxEdge) → {Promise.<{canvas: ImageBitmap, width: number, height: number}>}

Description:

Loads a downscaled image preview.

Source:

loading/imageLoader.js, line 34

Parameters:

Name	Type	Description
`file`	Blob	Image file or blob.
`maxEdge`	number	Maximum preview edge in pixels.

Returns:

Preview bitmap plus original dimensions.

Type: Promise.<{canvas: ImageBitmap, width: number, height: number}>

loadPdfDocument(buffer) → {Promise.<Object>}

Description:

Loads a PDF document in the worker.

Source:

loading/pdfLoader.js, line 224

Parameters:

Name	Type	Description
`buffer`	ArrayBuffer	PDF data.

Returns:

Worker document handle.

Type: Promise.<Object>

normalizePaperPreset(presetId) → {string}

Description:

Returns a valid paper preset id, falling back to the default.

Source:

model/paper.js, line 102

Parameters:

Name	Type	Description
`presetId`	string	Preset id to normalize.

Returns:

Valid preset id.

Type: string

parseHocr(hocr) → {Array.<Object>}

Description:

Parses hOCR markup into Riffle text-layer pages.

Source:

loading/hocr.js, line 73

Parameters:

Name	Type	Description
`hocr`	string \| Document	hOCR markup or a parsed document.

Returns:

Text content pages compatible with Riffle's text layer.

Type: Array.<Object>

renderPdfPage(pdfDoc, pageNum, scale, optionsopt) → {Promise.<ImageBitmap>}

Description:

Renders a PDF page at a scale.

Source:

loading/pdfLoader.js, line 304

Parameters:

Name Type Attributes Default Description

pdfDoc

Object

Worker document handle.

pageNum

number

One-based PDF page number.

scale

number

Render scale.

options

Object

{}

Render options.

Properties

Name	Type	Attributes	Default	Description
`downscaleTo`	number	<optional>	`0`	If positive, downscale to this maximum edge before transfer.
`priority`	boolean	<optional>	`false`	If true, queue ahead of low-priority renders.

Returns:

Rendered page bitmap.

Type: Promise.<ImageBitmap>

requestPdfDocumentCleanup(pdfDoc) → {void}

Description:

Requests worker cleanup for a PDF document.

Source:

loading/pdfLoader.js, line 318

Parameters:

Name	Type	Description
`pdfDoc`	Object	Worker document handle.

Returns:

Type: void

Type Definitions

BookViewerOptions

Description:

Options for BookViewer.

Source:

BookViewer.js, line 14

Properties:

Name	Type	Attributes	Default	Description
`spreadCanvas`	HTMLCanvasElement			Canvas the renderer draws into.
`viewport`	HTMLElement \| null	<optional>	`null`	Element used for zoom measurement and scroll preservation.
`rendererClass`	function			Renderer constructor, usually `WebGPUSpreadRenderer` or `SpreadRenderer`.
`source`	PageSource \| null	<optional>	`null`	Initial page source.
`layout`	Partial.<Layout> \| null	<optional>	`null`	Initial layout overrides.
`display`	Partial.<Display> \| null	<optional>	`null`	Initial display overrides.
`paperPreset`	string	<optional>	`"natural"`	Paper preset id.
`contentBlendMode`	string	<optional>	`"multiply"`	Blend mode for page content.
`paperThickness`	number	<optional>	`0.5`	Paper edge and turn-lighting strength from 0 to 1.
`paperTextureStrength`	number	<optional>	`0.18`	Paper texture/normal strength from 0 to 1.
`showPageBorder`	boolean	<optional>	`true`	Whether to render the page edge treatment.
`maxHighResPages`	number	<optional>	`8`	High-resolution page bitmap LRU capacity.
`renderScale`	number	<optional>	`1`	Pixel supersampling multiplier for the rendered spread canvas.

Options for BookViewer.

Type:

Object

ImagePageSourceOptions

Description:

Options for ImagePageSource.

Source:

sources/ImagePageSource.js, line 18

Properties:

Name	Type	Attributes	Default	Description
`getPageCount`	function			Returns viewer page count.
`getPageMetadata`	function			Returns page metadata.
`getPagePreview`	function	<optional>	`null`	Optional preview loader.
`getPageHighRes`	function	<optional>	`null`	Optional high-resolution loader.
`internalBook`	Object \| null	<optional>	`null`	Optional mutable book object used directly by Riffle's lazy loader.

Options for ImagePageSource.

Type:

Object

RiffleOptions

Description:

Options for Riffle.

Source:

Riffle.js, line 13

Properties:

Name	Type	Attributes	Default	Description
`renderer`	"auto" \| "webgpu" \| "2d" \| function	<optional>	`"auto"`	Renderer selection. `auto` uses WebGPU when available.
`source`	PageSource \| null	<optional>	`null`	Initial page source.
`layout`	Partial.<Layout> \| null	<optional>	`null`	Initial layout overrides.
`display`	Partial.<Display> \| null	<optional>	`null`	Initial display overrides.
`paperPreset`	"natural" \| "ivory" \| "bright-white"	<optional>		Named paper preset.
`contentBlendMode`	string	<optional>	`"multiply"`	Blend mode for page content.
`paperThickness`	number	<optional>		Paper edge and turn-lighting strength from 0 to 1.
`paperTextureStrength`	number	<optional>		Paper texture/normal strength from 0 to 1.
`showPageBorder`	boolean	<optional>	`true`	Whether to render the page edge treatment.
`maxHighResPages`	number	<optional>	`8`	High-resolution page bitmap LRU capacity.
`viewport`	HTMLElement \| null	<optional>	`null`	Element used for zoom measurement and scroll preservation.
`selectablePdfText`	boolean	<optional>	`true`	Whether to overlay selectable PDF text on settled spreads.
`renderScale`	number	<optional>	`1`	Pixel supersampling multiplier for the rendered spread canvas.

Options for Riffle.

Type:

Object