module Vgr:sig
..end
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.
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.
typewarning =
[ `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 ]
val pp_warning : Format.formatter -> warning -> unit
pp_warning ppf w
prints a textual representation of w
on ppf
.typewarn =
warning -> unit
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
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.
typerenderable =
Gg.size2 * Gg.box2 * Vg.image
typedst_stored =
[ `Buffer of Buffer.t | `Channel of Pervasives.out_channel | `Manual ]
`Manual
destination the client must provide output storage see
Vg.Vgr.Manual.dst
.typedst =
[ `Buffer of Buffer.t | `Channel of Pervasives.out_channel | `Manual | `Other ]
`Other
destination, usually denoting some kind of
interactive renderer.type [< dst ]
target
typet =
Vg.renderer
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:
`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 Vg.Vgr.Manual.dst
to provide
a new buffer. In both cases the client should then
call Vg.Vgr.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
.`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 `Image
s 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.module Manual:sig
..end
module Private:sig
..end