### Constructor

# Vips Image text

#### Declaration [src]

    int
    vips_text (
      VipsImage** out,
      const char* text,
      ...
    )

#### Description [src]

Draw the string `text` to an image.

`out` is normally a one-band 8-bit unsigned char image, with 0 for no text and 255 for text. Values between are used for anti-aliasing.

Set `rgba` to enable RGBA output. This is useful for colour emoji rendering, or support for pango markup features like `<span foreground="red">Red!</span>`.

`text` is the text to render as a UTF-8 string. It can contain Pango markup, for example `<i>The</i>Guardian`.

`font` is the font to render with, as a fontconfig name. Examples might be `sans 12` or perhaps `bitstream charter bold 10`.

You can specify a font to load with `fontfile`. You’ll need to also set the name of the font with `font`.

`width` is the number of pixels to word-wrap at. By default, lines of text wider than this will be broken at word boundaries. Use `wrap` to set lines to wrap on word or character boundaries, or to disable line breaks.

Set `justify` to turn on line justification. `align` can be used to set the alignment style for multi-line text to the low (left) edge centre, or high (right) edge. Note that the output image can be wider than `width` if there are no word breaks, or narrower if the lines don’t break exactly at `width`.

`height` is the maximum number of pixels high the generated text can be. This only takes effect when `dpi` is not set, and `width` is set, making a box. In this case, `vips_text()` will search for a `dpi` and set of line breaks which will just fit the text into `width` and `height`.

You can use `autofit_dpi` to read out the DPI selected by auto fit.

`dpi` sets the resolution to render at. “sans 12” at 72 dpi draws characters approximately 12 pixels high.

`spacing` sets the line spacing, in points. It would typically be something like font size times 1.2.

You can read the coordinate of the top edge of the character from `Xoffset` / `Yoffset`. This can be helpful if you need to line up the output of several `vips_text()`.

Optional arguments

- `font`: `gchararray`, font to render with
- `fontfile`: `gchararray`, load this font file
- `width`: `gint`, image should be no wider than this many pixels
- `height`: `gint`, image should be no higher than this many pixels
- `align`: `VipsAlign`, set justification alignment
- `justify`: `gboolean`, justify lines
- `dpi`: `gint`, render at this resolution
- `autofit_dpi`: `gint`, output, auto-fitted DPI
- `rgba`: `gboolean`, enable RGBA output
- `spacing`: `gint`, space lines by this in points
- `wrap`: `VipsTextWrap`, wrap lines on characters or words

See also

`vips_bandjoin()`, `vips_composite()`.

This constructor is not directly available to language bindings.

#### Parameters

`out`

  Type: `VipsImage`

  Output image.

  The argument will be set by the function.
  The caller of the function takes ownership of the returned data, and is responsible for freeing it.

`text`

  Type: `const char*`

  Utf-8 text string to render.

  The data is owned by the caller of the function.
  The value is a NUL terminated UTF-8 string.

`...`

  Type: ``

  `NULL`-terminated list of optional named arguments.

#### Return value

Type: `int`

0 on success, -1 on error.