Module Vg.Vgr

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 = [
| `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.