Expose vips_text to create an image containing rendered text (#3252)

docs/api-composite.md

@@ -29,6 +29,18 @@ and [https://www.cairographics.org/operators/][2]
             *   `images[].input.create.height` **[Number][7]?** 
             *   `images[].input.create.channels` **[Number][7]?** 3-4
             *   `images[].input.create.background` **([String][6] | [Object][4])?** parsed by the [color][8] module to extract values for red, green, blue and alpha.
+        *   `images[].input.text` **[Object][4]?** describes a new text image to be created.
+
+            *   `images[].input.text.text` **[string][6]?** text to render as a UTF-8 string. It can contain Pango markup, for example `<i>Le</i>Monde`.
+            *   `images[].input.text.font` **[string][6]?** font name to render with.
+            *   `images[].input.text.fontfile` **[string][6]?** absolute filesystem path to a font file that can be used by `font`.
+            *   `images[].input.text.width` **[number][7]** integral number of pixels to word-wrap at. Lines of text wider than this will be broken at word boundaries. (optional, default `0`)
+            *   `images[].input.text.height` **[number][7]** integral number of pixels high. When defined, `dpi` will be ignored and the text will automatically fit the pixel resolution defined by `width` and `height`. Will be ignored if `width` is not specified or set to 0. (optional, default `0`)
+            *   `images[].input.text.align` **[string][6]** text alignment (`'left'`, `'centre'`, `'center'`, `'right'`). (optional, default `'left'`)
+            *   `images[].input.text.justify` **[boolean][9]** set this to true to apply justification to the text. (optional, default `false`)
+            *   `images[].input.text.dpi` **[number][7]** the resolution (size) at which to render the text. Does not take effect if `height` is specified. (optional, default `72`)
+            *   `images[].input.text.rgba` **[boolean][9]** set this to true to enable RGBA output. This is useful for colour emoji rendering, or support for pango markup features like `<span foreground="red">Red!</span>`. (optional, default `false`)
+            *   `images[].input.text.spacing` **[number][7]** text line height in points. Will use the font line height if none is specified. (optional, default `0`)
     *   `images[].blend` **[String][6]** how to blend this image with the image below. (optional, default `'over'`)
     *   `images[].gravity` **[String][6]** gravity at which to place the overlay. (optional, default `'centre'`)
     *   `images[].top` **[Number][7]?** the pixel offset from the top edge.

docs/api-constructor.md

@@ -51,6 +51,18 @@ Implements the [stream.Duplex][1] class.
             *   `options.create.noise.type` **[string][12]?** type of generated noise, currently only `gaussian` is supported.
             *   `options.create.noise.mean` **[number][14]?** mean of pixels in generated noise.
             *   `options.create.noise.sigma` **[number][14]?** standard deviation of pixels in generated noise.
+    *   `options.text` **[Object][13]?** describes a new text image to be created.
+
+        *   `options.text.text` **[string][12]?** text to render as a UTF-8 string. It can contain Pango markup, for example `<i>Le</i>Monde`.
+        *   `options.text.font` **[string][12]?** font name to render with.
+        *   `options.text.fontfile` **[string][12]?** absolute filesystem path to a font file that can be used by `font`.
+        *   `options.text.width` **[number][14]** integral number of pixels to word-wrap at. Lines of text wider than this will be broken at word boundaries. (optional, default `0`)
+        *   `options.text.height` **[number][14]** integral number of pixels high. When defined, `dpi` will be ignored and the text will automatically fit the pixel resolution defined by `width` and `height`. Will be ignored if `width` is not specified or set to 0. (optional, default `0`)
+        *   `options.text.align` **[string][12]** text alignment (`'left'`, `'centre'`, `'center'`, `'right'`). (optional, default `'left'`)
+        *   `options.text.justify` **[boolean][15]** set this to true to apply justification to the text. (optional, default `false`)
+        *   `options.text.dpi` **[number][14]** the resolution (size) at which to render the text. Does not take effect if `height` is specified. (optional, default `72`)
+        *   `options.text.rgba` **[boolean][15]** set this to true to enable RGBA output. This is useful for colour emoji rendering, or support for pango markup features like `<span foreground="red">Red!</span>`. (optional, default `false`)
+        *   `options.text.spacing` **[number][14]** text line height in points. Will use the font line height if none is specified. (optional, default `0`)
 
 ### Examples
 
@@ -127,6 +139,29 @@ await sharp({
 }).toFile('noise.png');
 ```
 
+```javascript
+// Generate an image from text
+await sharp({
+  text: {
+    text: 'Hello, world!',
+    width: 400, // max width
+    height: 300 // max height
+  }
+}).toFile('text_bw.png');
+```
+
+```javascript
+// Generate an rgba image from text using pango markup and font
+await sharp({
+  text: {
+    text: '<span foreground="red">Red!</span><span background="cyan">blue</span>',
+    font: 'sans',
+    rgba: true,
+    dpi: 300
+  }
+}).toFile('text_rgba.png');
+```
+
 *   Throws **[Error][17]** Invalid parameters
 
 Returns **[Sharp][18]** 

docs/api-output.md

@@ -22,6 +22,7 @@ A `Promise` is returned when `callback` is not provided.
     `info` contains the output image `format`, `size` (bytes), `width`, `height`,
     `channels` and `premultiplied` (indicating if premultiplication was used).
     When using a crop strategy also contains `cropOffsetLeft` and `cropOffsetTop`.
+    May also contain `textAutofitDpi` (dpi the font was rendered at) if image was created from text.
 
 ### Examples
 
@@ -61,6 +62,7 @@ See [withMetadata][1] for control over this.
 
 `channels` and `premultiplied` (indicating if premultiplication was used).
 When using a crop strategy also contains `cropOffsetLeft` and `cropOffsetTop`.
+May also contain `textAutofitDpi` (dpi the font was rendered at) if image was created from text.
 
 A `Promise` is returned when `callback` is not provided.