Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# Render Formatting

Render formatting is simply the modification of a primary render output. This is provided via:

- Python’s string formatting protocol by using `format()`, `str.format()` or formatted string literals with the Render Format Specification

- Parameters of `draw()`

The following constitute render formatting:

## Padding

This adds whitespace around a primary render output. The amount of whitespace added is determined by two values (with respect to the rendered size):

- padding width, determines horizontal padding

  - uses the `width` field of the Render Format Specification

  - uses the pad_width parameter of `draw()`

- padding height, determines vertical padding

  - uses the `height` field of the Render Format Specification

  - uses the pad_height parameter of `draw()`

If the padding width or height is less than or equal to the width or height of the primary render output, then the padding has no effect on the corresponding axis.

## Alignment

This determines the position of a primary render output within it’s Padding. The position is determined by two values:

- horizontal alignment, determines the horizontal position

  - uses the `h_align` field of the Render Format Specification

  - uses the h_align parameter of `draw()`

- vertical alignment, determines the vertical position

  - uses the `v_align` field of the Render Format Specification

  - uses the v_align parameter of `draw()`

## Transparency

This determines how transparent pixels are rendered. Transparent pixels can be rendered in one of the following ways:

- Transparency disabled

  Alpha channel is ignored.

  - uses the `#` field of the Render Format Specification, without `threshold` or `bgcolor`

  - uses the alpha parameter of `draw()`, set to `None`

- Transparency enabled with an alpha threshold

  For Text-based Render Styles, any pixel with an alpha value above the given threshold is taken as opaque. For Graphics-based Render Styles, the alpha value of each pixel is used as-is.

  - uses the `threshold` field of the Render Format Specification

  - uses the alpha parameter of `draw()`, set to a `float` value

- Transparent pixels overlaid on a color

  May be specified to be a specific color or the default background color of the terminal emulator (if it can’t be determined, black is used).

  - uses the `bgcolor` field of the Render Format Specification

  - uses the alpha parameter of `draw()`, set to a string value

## Render Format Specification

    [ <h_align> ]  [ <width> ]  [ . [ <v_align> ] [ <height> ] ]  [ # [ <threshold> | <bgcolor> ] ]  [ + <style> ]

Note

- spaces are only for clarity and not included in the syntax

- `<...>` is a placeholder for a single field

- `|` implies mutual exclusivity

- fields within `[ ]` are optional

- fields within `{ }` are required, though subject to any enclosing `[ ]`

- if the `.` is present, then at least one of `v_align` and `height` must be present

- `h_align` → horizontal alignment

  - `<` → left

  - `|` → center

  - `>` → right

  - default → center

- `width` → padding width

  - positive integer

  - default: terminal width

  - if less than or equal to the rendered width, it has no effect

- `v_align` → vertical alignment

  - `^` → top

  - `-` → middle

  - `_` → bottom

  - default → middle

- `height` → padding height

  - positive integer

  - default: terminal height minus two (`2`)

  - if less than or equal to the rendered height, it has no effect

- `#` → transparency setting

  - default: transparency is enabled with the default alpha threshold

  - `threshold` → alpha threshold

    - a float value in the range `0.0` <= `threshold` < `1.0` (but starting with the `.` (decimal point))

    - applies to only Text-based Render Styles

    - e.g `.0`, `.325043`, `.999`

  - `bgcolor` → background underlay color

    - `#` → the terminal emulator’s default background color (or black, if undetermined), OR

    - a hex color e.g `ffffff`, `7faa52`

  - if neither `threshold` nor `bgcolor` is present, but `#` is present, transparency is disabled i.e alpha channel is ignored

- `style` → style-specific format specifier

  See each render style in Image Classes for its own specification, if it defines.

  `style` can be broken down into `[ <parent> ] [ <current> ]`, where `current` is the spec defined by a render style and `parent` is the spec defined by a parent of that render style. `parent` can in turn be recursively broken down as such.

See also

Formatted rendering tutorial.