package vg

  1. Overview
  2. Docs

Module Vgr.PrivateSource

Private functions for implementing renderers.

Warning. Vg users should not use these definitions, they exposes Vg's internals for implementing renderers. This functionality is subject to change even between minor versions of the library.

In order to provide a consistant interface for Vg users, renderer writers should follow the guidelines below. You may want to drop an email to the maintainer for help and discussion.

  • If you render to "Bla", define you renderer in a module called Vgr_bla (lowercase).
  • The renderer target creation function must be named Vgr_bla.target.
  • Images must be rendered via the render function. If you are writing a batch renderer provide support for each of the dst types and especially the non-blocking interface.
  • Respect Vg's linear sRGB color model.
  • Whenever possible use an XMP metadata packet for metadata, see Vgr.xmp.
  • The renderer should implement the rendering cost model, see the limit parameter of render.
  • Follow Vg's coordinate system conventions to specify the relationship between a target and the view rectangle to render.
  • If the renderer doesn't support Vg's full rendering model or diverges from its semantics it must ignore unsupported features and warn the client via the warn function.

Internal data

Sourcemodule Data : sig ... end

Internal data.

Sourcemodule Font : sig ... end

Font helpers.

Sourcemodule P : sig ... end

Paths helpers.

Sourcemodule I : sig ... end

Image helpers

Renderers

Sourcetype renderer

The type for renderers.

Sourcetype k = renderer -> [ `Ok | `Partial ]

The type for renderer continuations.

Sourcetype render_fun = [ `End | `Image of Gg.size2 * Gg.box2 * Data.image ] -> k -> k

The type for rendering functions.

Sourcetype 'a render_target = renderer -> 'a -> bool * render_fun constraint 'a = [< dst ]

The type for render targets. The function takes a created renderer and its destination. It should return a boolean indicating whether multiple images can be rendered on the target, and a function that is invoked by the renderer to render a new image or end the rendering sequence.

Sourceval create_target : 'a render_target -> 'a target

create_target t makes an end-user render target from t.

Sourceval renderer : t -> renderer

renderer r is r's internal representation.

Sourceval limit : renderer -> int

limit r is r's render limit.

Sourceval warn : renderer -> warning -> unit

warn r w reports the warning w on r.

Sourceval partial : k -> renderer -> [> `Partial ]

partial k r suspends the renderer r and returns `Partial. Rendering will continue with k r, on render `Await.

Writing dst_stored destinations

Sourceval flush : k -> renderer -> [ `Ok | `Partial ]

flush k r flushes the renderer r. If r writes on a stored destination this function must be called by the rendering function on `End.

Sourceval writeb : int -> k -> renderer -> [ `Ok | `Partial ]

writeb b k r writes the byte b and kontinues.

Sourceval writes : string -> int -> int -> k -> renderer -> [ `Ok | `Partial ]

writes s j l k r writes l bytes from s starting at j and kontinues.

Sourceval writebuf : Buffer.t -> int -> int -> k -> renderer -> [ `Ok | `Partial ]

writebuf buf j l k r write l bytes from buf starting at j and kontinues.

Miscellaneous

Sourceval add_xml_data : Buffer.t -> string -> unit

add_xml_data b s adds s to b, escapes '<', '>', '&' and '"' (but not single quotes) and maps illegal XML unicode characters to the replacement character U+FFFD.