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.