Module Vg.Vgr

module Vgr: sig .. end
Image renderers.

Renderers renders finite rectangular regions of images on rectangular targets. The following renderers are distributed with the 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 = [ `Other of string
| `Textless_glyph_cut of Vg.I.t
| `Unsupported_cut of Vg.P.area * Vg.I.t
| `Unsupported_glyph_cut of Vg.P.area * Vg.I.t ]
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.

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


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 * Vg.image 
The type for renderables. The physical size on the render target in millimeters, the view rectangle and the image to render.


type dst_stored = [ `Buffer of Buffer.t | `Channel of Pervasives.out_channel | `Manual ] 
The type for stored renderer destination. With a `Manual destination the client must provide output storage see Vg.Vgr.Manual.dst.
type dst = [ `Buffer of Buffer.t | `Channel of Pervasives.out_channel | `Manual | `Other ] 
The type for renderer destinations. Either a stored destination or an `Other destination, usually denoting some kind of interactive renderer.
type [< dst ] target 
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 = Vg.renderer 
The type for renderers.
val create : ?limit:int ->
?warn:warn ->
([< dst ] as 'a) target -> 'a -> Vg.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 Vg.Vgr.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 Vg.Vgr.render returns with `Partial.

val render : Vg.renderer ->
[< `Await | `End | `Image of renderable ] -> [ `Ok | `Partial ]
render r v is: For `Manual destinations, encoding `End always returns `Partial the client should as usual use Vg.Vgr.Manual.dst and continue with `Await until `Ok is returned at which point Vg.Vgr.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 : Vg.renderer -> dst
render_dst r is r's destination.
val renderer_limit : Vg.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.