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 SpecificationParameters 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 Specificationuses the pad_width parameter of
draw()
padding height, determines vertical padding
uses the
height
field of the Render Format Specificationuses 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 Specificationuses the h_align parameter of
draw()
vertical alignment, determines the vertical position
uses the
v_align
field of the Render Format Specificationuses 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, withoutthreshold
orbgcolor
uses the alpha parameter of
draw()
, set toNone
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
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 Specificationuses 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 exclusivityfields within
[ ]
are optionalfields within
{ }
are required, though subject to any enclosing[ ]
if the
.
is present, then at least one ofv_align
andheight
must be present
h_align
→ horizontal alignment<
→ left|
→ center>
→ rightdefault → center
width
→ padding widthpositive integer
default: terminal width
if less than or equal to the rendered width, it has no effect
v_align
→ vertical alignment^
→ top-
→ middle_
→ bottomdefault → middle
height
→ padding heightpositive integer
default: terminal height minus two (
2
)if less than or equal to the rendered height, it has no effect
#
→ transparency settingdefault: transparency is enabled with the default alpha threshold
threshold
→ alpha thresholda 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), ORa hex color e.g
ffffff
,7faa52
if neither
threshold
norbgcolor
is present, but#
is present, transparency is disabled i.e alpha channel is ignored
style
→ style-specific format specifierSee each render style in Image Classes for its own specification, if it defines.
style
can be broken down into[ <parent> ] [ <current> ]
, wherecurrent
is the spec defined by a render style andparent
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.