vg 0.9.3 · OCaml Package

Image renderers.

Renderers renders finite rectangular regions of images on rectangular targets. The following renderers are distributed with the library:

Vgr_pdf, renders sequence of images as a multi-page PDF 1.7 document.
Vgr_svg, renders a single image as an SVG 1.1 document.
Vgr_htmlc, renders sequence of images on an HTML canvas via js_of_ocaml.
Vgr_cairo, renders images using the Cairo library.

Render warnings

Renderers do their best to support Vg's rendering model and semantics. However they may sometimes lack capabilities provided by Vg's rendering model.

Whenever a renderer encounters an unsupported capability it ignores it and calls the warn callback specified at renderer creation time. The documentation of renderers indicate which warnings they report.

type warning = [

| `Unsupported_cut of P.area * I.t
| `Unsupported_glyph_cut of P.area * I.t
| `Textless_glyph_cut of I.t
| `Other of string

]

The type for render warnings.

val pp_warning : Format.formatter -> warning -> unit

pp_warning ppf w prints a textual representation of w on ppf.

type warn = warning -> unit

The type for warning callbacks.

Render metadata

Some renderers support the specification of metadata as an XML XMP metadata packet (ISO 16684-1). The following convenience function returns a well-formed, correctly escaped, metadata packet according to the information you provide.

val xmp : 
  ?title:string ->
  ?authors:string list ->
  ?subjects:string list ->
  ?description:string ->
  ?rights:string ->
  ?creator_tool:string ->
  ?create_date:float ->
  unit ->
  string

xmp title authors creator_tool subject description create_date is an XML XMP metadata packet.

title is mapped to dc:title.
authors is mapped to dc:creator.
subjects is mapped to dc:subject.
description is mapped to dc:description.
rights is mapped to dc:rights.
creator_tool is mapped to xmp:CreatorTool.
create_date (a POSIX timestamp in seconds) is mapped to xmp:CreateDate.

Note. All strings must be UTF-8 encoded. Unicode characters that are not legal XML characters are replaced by the Unicode replacement character

Renderable

A renderable specifies a finite view rectangle and a physical size for an image render. It implicitly defines the mapping between Vg's coordinate space and the render target, see this section for more information.

type renderable = Gg.size2 * Gg.box2 * image

The type for renderables. The physical size on the render target in millimeters, the view rectangle and the image to render.

Rendering

type dst_stored = [

| `Buffer of Buffer.t
| `Channel of out_channel
| `Manual

]

The type for stored renderer destination. With a `Manual destination the client must provide output storage see Manual.dst.

type dst = [

| dst_stored
| `Other

]

The type for renderer destinations. Either a stored destination or an `Other destination, usually denoting some kind of interactive renderer.

type 'a target constraint 'a = [< dst ]

The type for render targets. The type parameter specifies the supported type of destinations. Values of this type are provided by concrete renderer implementation.

type t = renderer

The type for renderers.

val create : 
  ?limit:int ->
  ?warn:warn ->
  [< dst ] as 'dst target ->
  'dst ->
  renderer

create limit warn target dst is a renderer using target to render images to dst. warn is called whenever the renderer lacks a capability, see warnings.

limit limits the time spent in the render function (defaults to max_int, unlimited). The cost model may change in a future version of the library. For now each image combinator costs one unit, when the limit is reached render returns with `Partial.

val render : 
  renderer ->
  [< `Image of renderable | `Await | `End ] ->
  [ `Ok | `Partial ]

render r v is:

`Partial iff r has a `Manual destination and needs more output storage or if r has a limit. In the first case the client must use Manual.dst to provide a new buffer. In both cases the client should then call render with `Await until `Ok is returned.
`Ok when the encoder is ready to encode a new `Image (if the renderer supports it) or `End.

For `Manual destinations, encoding `End always returns `Partial the client should as usual use Manual.dst and continue with `Await until `Ok is returned at which point Manual.dst_rem r is guaranteed to be the size of the last provided buffer (i.e. nothing was written).

Semantics of multiple images render. The semantics of multiple image renders are left to the backend.

raises Invalid_argument
if `Image or `End is encoded after a `Partial encode. Or if multiple `Images are encoded in a renderer that doesn't support them.

val renderer_dst : renderer -> dst

render_dst r is r's destination.

val renderer_limit : renderer -> int

renderer_limit r is r's limit.

Manual render destinations

module Manual : sig ... end

Manual render destinations.

Implementing renderers

module Private : sig ... end

Private functions for implementing renderers.