vg 0.8.2 · OCaml Package

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 Daniel Bünzli <daniel.buenzl i@erratique.ch> 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

module Data : sig ... end

Internal data.

module Font : sig ... end

Font helpers.

module P : sig ... end

Paths helpers.

module I : sig ... end

Image helpers

Renderers

type renderer

The type for renderers.

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

The type for renderer continuations.

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

The type for rendering functions.

type '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.

val create_target : 'a render_target -> 'a target

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

val renderer : t -> renderer

renderer r is r's internal representation.

val limit : renderer -> int

limit r is r's render limit.

val warn : renderer -> warning -> unit

warn r w reports the warning w on r.

val 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

val 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.

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

writeb b k r writes the byte b and kontinues.

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

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

val 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

val 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.

package vg

Internal data

Renderers

Writing dst_stored destinations

Miscellaneous

Writing `dst_stored` destinations