Module Vg.Vgr
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 : Stdlib.Format.formatter -> warning -> unit
pp_warning ppf w
prints a textual representation ofw
onppf
.
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 Stdlib.Buffer.t
|
`Channel of Stdlib.out_channel
|
`Manual
]
The type for stored renderer destination. With a
`Manual
destination the client must provide output storage seeManual.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 usingtarget
to render images todst
.warn
is called whenever the renderer lacks a capability, see warnings.limit
limits the time spent in the Rendering function (defaults tomax_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 Rendering returns with`Partial
.
val render : renderer -> [< `Image of renderable | `Await | `End ] -> [ `Ok | `Partial ]
render r v
is:`Partial
iffr
has a`Manual
destination and needs more output storage or ifr
has a limit. In the first case the client must useManual.dst
to provide a new buffer. In both cases the client should then call Rendering 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 useManual.dst
and continue with`Await
until`Ok
is returned at which pointManual.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_limit : renderer -> int
renderer_limit r
isr
's limit.
Manual render destinations
module Manual : sig ... end
Manual render destinations.
Implementing renderers
module Private : sig ... end
Private functions for implementing renderers.