Module `Vg.I`

Images.

Consult their semantics.

The |> operator is used to compose images. For this reason image combinators always take the image to use as the last argument.

Images

type t = image: The type for images.

val void : image: void is const Gg.Color.void, an invisible black image. void is an identity element for Blending images.

Primitive images

val const : Gg.color -> image

const c is an image of color c.

[const c]_pt = c for any pt.

val axial : Gg.Color.stops -> Gg.p2 -> Gg.p2 -> image

axial stops pt pt' is an image with an axial color gradient varying between pt and pt' according to color stops stops.

[axial stops pt pt']_q = [stops]_t if q is on the line perpendicular to the line pt and pt' at the point pt + t * (pt' - pt).

val radial : Gg.Color.stops -> ?⁠f:Gg.p2 -> Gg.p2 -> float -> image

radial stops ~f c r is an image with a color gradient varying according to color stops stops on circles whose center are on the segment from f to c and radius vary, respectively, from 0 to r. The focus f defaults to c, it must be inside the circle (c, r).

[radial stops ~f c r]_p = [stops]_t if t is the smallest value such that p is on the circle defined by radius t * r and center f + t * (c - f).

Cutting images

val cut : ?⁠area:P.area -> path -> image -> image

cut area p i is i with the area outside [a, p] cut out, i.e. mapped to Gg.Color.void. area defaults to `Anz.

[cut area p i]_pt = [i]_pt if [a, p]_pt
[cut area p i]_pt = Gg.Color.void otherwise.

Warning. For outline cuts most renderers support only cutting into const axial and radial images. Consult the individual renderer documentation.

val cut_glyphs : ?⁠area:[ `O of P.outline ] -> ?⁠text:string -> ?⁠blocks:(bool * (int * int) list) -> ?⁠advances:Gg.v2 list -> font -> glyph list -> image -> image

WARNING. The interface and specifics of glyph rendering are still subject to change in the future.

cut_glyphs area text blocks advances font glyphs i is like Cutting images except the path cut is the union of all the paths of the glyphs glyphs of the font font.

The origin of the first glyph is set to P2.o, the origin of each subsequent glyph in glyphs is offset by the advance vector of the previous glyph as provided by font. Advance vectors for each glyph can be overriden by providing their value in advances, if the length of advances is smaller than glyphs the rendering results are undefined.

If provided the text parameter indicates the UTF-8 text corresponding to the sequence of glyphs. This may be used by certain renderer to allow text search in the result or to draw the text if it lacks control over glyph rendering (in which case an empty list of glyphs may be passed).

If provided blocks is used to specify a sequential map between glyphs and the characters of text. The number of elements in the list defines the number of blocks. Starting at the head of each sequence, each block (char_adv, glyph_adv) indicates the number of characters and glyphs that make the next block (one or the other may be 0). If the boolean is true the glyph sequence is reversed for peforming the map. If blocks is unspecified a one to one map between glyphs and characters is assumed with undefined results if the number of glyphs and characters differ.

If area is provided, the outline area of the glyphs are cut as specified, otherwise the area of the glyphs is determined as mandated by the font. Warning. Backend support is poor this may be removed in the future.

Blending images

val blend : image -> image -> image

blend src dst is src blended over dst using source over destination alpha blending.

[blend src dst]_p = Color.blend [src]_p [dst]_p

Transforming images

val move : Gg.v2 -> image -> image

move v i is i translated by v.

[move v i]_pt = [i]_pt-v for any pt

val rot : float -> image -> image

rot a i is i rotated by a.

[rot a i]_pt = [i]_m⋅pt for any pt and with m = M2.rot -a.

val scale : Gg.v2 -> image -> image

scale s i is i scaled by s.

[scale s i]_(x,y) = [i]_{(x/s_x,y/s_y)} for any (x,y)

val tr : Gg.m3 -> image -> image

tr m i is the affine transform in homogenous 2D space of each point of i by m (see Gg.P2.tr).

[tr m i]_pt = [i]_m^-1⋅pt for any pt

Predicates and comparisons

Note. These predicates consider the structure of image values not their denotational interpretation; a single denotational interpretation can have many structural representations.

val is_void : image -> bool: is_void i is i == void.

val equal : image -> image -> bool: equal i i' is i = i'.

val equal_f : (float -> float -> bool) -> image -> image -> bool

equal eq i i' is like equal but uses eq to test floating point values.

Note. Raster images are tested with Gg.Raster.equal.

val compare : image -> image -> int: compare i i' is Stdlib.compare i i'.

val compare_f : (float -> float -> int) -> image -> image -> int

compare_f cmp i i' is like compare but uses cmp to compare floating point values.

Note. Raster images are tested with Gg.Raster.compare.

Printers

val to_string : image -> string: to_string i is a textual representation of i.

val pp : Stdlib.Format.formatter -> image -> unit: pp ppf i prints a textual representation of i on ppf.

val pp_f : (Stdlib.Format.formatter -> float -> unit) -> Stdlib.Format.formatter -> image -> unit: pp_f pp_float ppf i prints i like pp but uses pp_float to print floating point values.