TOML Schema Reference¶
BgRaster reads its primary configuration from a TOML file. If --config is omitted, it searches for config.toml in this order: next to the executable, %ProgramData%\BgInfo, %LocalAppData%\BgInfo, and %AppData%\BgInfo. If --config is provided and the file does not exist, BgRaster uses built-in defaults for that run; after a successful execution, it writes a seeded config.toml template at the requested path using effective global defaults and detected output targets. Every key is optional — missing keys fall back to the documented defaults. CLI flags override the corresponding TOML values; per-output overrides take precedence over globals; per-slice overrides take precedence over per-output.
Conventions¶
- All multi-value globals are arrays.
BgRastercycles through array elements per output index usingarray[index % array.Length]. Specifying a single-element array applies the value to every output. - Dimension strings accept the units listed under Units.
- color strings accept the formats listed under colors.
- Field substitution is applied to text and path-bearing values — see Path resolution and Substitution tokens.
- TOML keys use kebab-case (e.g.
border-color,grid-coordinates); the C# model uses PascalCase (BorderColor,GridCoordinates).
Root scalars¶
Top-level scalar values (outside section tables):
| Key | Type | Default | Description |
|---|---|---|---|
machine-name |
string |
"" |
Override the framework-supplied host name used by ${MachineName} substitutions. Empty uses Environment.MachineName. |
Path resolution¶
The following properties share the same path resolution behavior:
[background].image[logo].source[render].output[[output]].background.image[[output]].logo.source[[output.slice]].background.image[[output.slice]].logo.source
Resolution order:
- Field substitution is applied first (see Substitution tokens).
- Environment variables are expanded.
- If the value is an absolute URI (including
pack://), it is used as-is. - If the value is an absolute filesystem path, it is used as-is.
- Otherwise, it is treated as a relative path.
Relative-path base directory:
- For TOML-sourced values, the path is resolved against the directory of the TOML file that contains that relative path.
- For CLI-provided values (for example
--background-image,--logo-source,--render-output), the path is resolved against the current working directory.
Notes:
- Empty values remain empty.
- Property-specific semantics still apply after resolution (for example,
[background].imageempty disables background image rendering, and[logo].sourceempty suppresses logo rendering).
[text]¶
Global text rendering settings. Array values are resolved by rendered slice sequence with wraparound.
| Key | Type | Default | Description |
|---|---|---|---|
text |
string[] |
["${MachineName} output ${OutputIndexPlusOne}","slice ${SliceLetter}","${SliceWidth}x${SliceHeight}"] |
Text lines, supports ${MachineName}, ${OutputWidth}, ${OutputHeight}, ${OutputIndex}, ${OutputIndexPlusOne}, ${OutputLetter}, ${OutputName}, ${SliceWidth}, ${SliceHeight}, ${SliceIndex}, ${SliceIndexPlusOne}, ${SliceLetter} |
size |
string[] |
["3vh","2vh","4vh"] |
Per-line text heights with units (px, vh, vw, vmin, vmax) |
color |
string[] |
"#fff" |
Per-line text colors |
x |
string[] |
"75vw" |
Text anchor x-coordinate |
y |
string[] |
"75vh" |
Text anchor y-coordinate |
[background]¶
Background rendering settings. Array values are resolved by rendered slice sequence with wraparound.
| Key | Type | Default | Description |
|---|---|---|---|
color |
string[] |
["#FF0000","#00FF00","#0000FF"] |
Base fill color, cycles by rendered slice sequence with wraparound. Supports #RRGGBB, #RRGGBBAA, rgb(), rgba(), hsl(), hsla() |
image |
string[] |
"" |
Optional path to background image (SVG or PNG), rendered over color layer. Relative paths resolve against the config file directory. Field substitution is applied. Empty = no image. |
fit |
string[] |
"CropToFill" |
Background image fit mode. CropToFill and BestFit use uniform scaling; crop modes do not scale. Allowed values: CropTL, CropTR, CropC, CropBL, CropBR, BestFit, CropToFill. |
alternating |
boolean[] |
false |
Enable checkerboard alternating pixel pattern (renders over grid) |
border |
boolean[] |
false |
Enable 1-pixel border at viewport edge |
border-color |
string[] |
"#FFFFFF" |
Border color |
[grid]¶
Grid rendering settings. Array values are resolved by rendered slice sequence with wraparound.
| Key | Type | Default | Description |
|---|---|---|---|
size |
string[] |
"100px" |
Checker cell size with units |
odd-color |
string[] |
"#00000080" |
Color for odd-indexed grid squares |
even-color |
string[] |
"transparent" |
Color for even-indexed grid squares |
stroke |
string[] |
"0" |
Grid line width. 0 = filled cells, non-zero = line width |
offset-x |
string[] |
"0" |
Horizontal grid phase offset |
offset-y |
string[] |
"0" |
Vertical grid phase offset |
coordinates |
boolean[] |
false |
Enable pixel coordinate display in each grid square |
[circle]¶
Circle rendering settings. Array values are resolved by rendered slice sequence with wraparound.
| Key | Type | Default | Description |
|---|---|---|---|
x |
string[] |
"50vw" |
Circle center X coordinate with units |
y |
string[] |
"50vh" |
Circle center Y coordinate with units |
size |
string[] |
"100vmin" |
Circle diameter with units |
color |
string[] |
"#ffffff40" |
Circle fill/stroke color |
stroke |
string[] |
"0" |
Circle stroke width. 0 = fill only, non-zero = stroke width |
[crosshair]¶
Crosshair rendering settings. Array values are resolved by rendered slice sequence with wraparound.
| Key | Type | Default | Description |
|---|---|---|---|
x |
string[] |
"50vw" |
Crosshair center X coordinate with units |
y |
string[] |
"50vh" |
Crosshair center Y coordinate with units |
length |
string[] |
"5vmin" |
Crosshair arm length (total, not radius) |
color |
string[] |
"#ffffff80" |
Crosshair color |
stroke |
string[] |
"1px" |
Crosshair line thickness |
[labeled-edges]¶
Labeled edges rendering settings. Array values are resolved by rendered slice sequence with wraparound.
| Key | Type | Default | Description |
|---|---|---|---|
text-size |
string[] |
"10px" |
Label text height with units |
tail-length |
string[] |
"10px" |
Length of the arrow tail, excluding the head |
thickness |
string[] |
"3px" |
Arrow stem thickness with units |
head-scale |
number[] |
1.0 |
Multiplier applied to the arrowhead dimensions |
scope |
string[] |
"Desktop" |
Scope used when resolving viewport-unit measurements and displayed numbers Allowed values: Desktop, Output, Slice. |
side |
string[] |
["TL","T","TR","R","BR","B","BL","L"] |
Sides or corners to label; values may not repeat Allowed values: TL, T, TR, R, BR, B, BL, L. |
[logo]¶
Logo rendering settings. Array values are resolved by rendered slice sequence with wraparound.
| Key | Type | Default | Description |
|---|---|---|---|
source |
string[] |
"pack://application:,,,/GameshowPro.BgRaster;component/resources/gsp.svg" |
Path to logo image file (SVG or PNG), pack URI to embedded resource, or empty string to suppress. Relative file paths resolve against the config file directory. Field substitution is applied. Pack URIs use format: pack://application:,,,/GameshowPro.BgRaster;component/path/to/resource. If path is invalid/missing, falls back to embedded logo. |
x |
string[] |
"85vw" |
Logo center X position |
y |
string[] |
"15vh" |
Logo center Y position |
width |
string[] |
"20vw" |
Logo fit rectangle width |
height |
string[] |
"20vh" |
Logo fit rectangle height |
opacity |
number[] |
1.0 |
Additional opacity multiplier (0 = transparent, 1 = opaque) |
[render]¶
Render and output settings
| Key | Type | Default | Description |
|---|---|---|---|
no-assignment |
boolean |
false |
Generate PNGs without assigning wallpaper |
no-discovery |
boolean |
false |
Skip display discovery and render only configured [[output]] entries using [output.hardware_output]. Implies no-assignment. |
outputs-skip-unspecified |
boolean |
false |
When false, discovered outputs without matching [[output]] entries are still rendered with global settings |
output |
string |
"" |
Output path template for generated PNGs (directory + filename stem). Relative paths resolve against the config file directory. Field substitution is applied. Supports {now}, {index}, and {friendlyName}. Empty = %TEMP%/BgRaster/{now}_{index}. |
force |
boolean |
false |
Continue rendering even when run-skipped-unchanged would normally short-circuit |
verbosity |
string |
"normal" |
Logging verbosity level Allowed values: quiet, normal, verbose. |
[[output]] (array of tables)¶
Per-output configuration. Optional; outputs without an entry use global values resolved by slice sequence.
| Key | Type | Description |
|---|---|---|
target |
integer\|string |
Output matcher: zero-based OS index (integer) or stable OS unique ID (string) |
text |
object |
Per-output or per-slice text override. Only text lines are arrays; other fields are scalar. |
background |
object |
Per-output or per-slice background override. Scalar values only. |
grid |
object |
Per-output or per-slice grid override. Scalar values only. |
circle |
object |
Per-output or per-slice circle override. Scalar values only. |
crosshair |
object |
Per-output or per-slice crosshair override. Scalar values only. |
labeled-edges |
object |
Per-output or per-slice labeled edges override. |
logo |
object |
Per-output or per-slice logo override. Scalar values only. |
slice |
object |
Per-output slice subdivisions |
hardware_output |
object |
- |
[[output.slice]] (nested array of tables)¶
Rectangular sub-region of an output. Each slice gets its own substitution context.
| Key | Type | Description |
|---|---|---|
x |
string |
Slice left position in parent output coordinates |
y |
string |
Slice top position in parent output coordinates |
width |
string |
Slice width |
height |
string |
Slice height |
text |
object |
Per-output or per-slice text override. Only text lines are arrays; other fields are scalar. |
background |
object |
Per-output or per-slice background override. Scalar values only. |
grid |
object |
Per-output or per-slice grid override. Scalar values only. |
circle |
object |
Per-output or per-slice circle override. Scalar values only. |
crosshair |
object |
Per-output or per-slice crosshair override. Scalar values only. |
labeled-edges |
object |
Per-output or per-slice labeled edges override. |
logo |
object |
Per-output or per-slice logo override. Scalar values only. |
Units¶
| Suffix | Meaning |
|---|---|
px |
Pixels (literal). |
vw |
1 % of viewport width. |
vh |
1 % of viewport height. |
vmin |
1 % of min(width, height). |
vmax |
1 % of max(width, height). |
colors¶
| Format | Example |
|---|---|
| 6-digit hex | #FF8800 |
| 8-digit hex with alpha | #FF8800CC |
| rgb(r, g, b) | rgb(255, 136, 0) |
| rgba(r, g, b, a) | rgba(255, 136, 0, 0.8) |
| hsl(h, s%, l%) | hsl(30, 100%, 50%) |
| hsla(h, s%, l%, a) | hsla(30, 100%, 50%, 0.8) |
| keyword | transparent |
Substitution tokens¶
These tokens are expanded inside text, background.image, logo.source, and render.output values:
| Token (machine scoped) | Token (output scoped) | Token (slice scoped) | Description |
|---|---|---|---|
${MachineName} |
${OutputName} |
`` | Configured machine name when set, otherwise Environment.MachineName. |
| `` | ${OutputWidth} |
${SliceWidth} |
Output or slice width in pixels. |
| `` | ${OutputHeight} |
${SliceHeight} |
Output or slice height in pixels. |
| `` | ${OutputIndex} |
${SliceIndex} |
Zero-based output or slice index. |
| `` | ${OutputIndexPlusOne} |
${SliceIndexPlusOne} |
One-based output or slice index. |
| `` | ${OutputLetter} |
${SliceLetter} |
Alphabetic output or slice index starting at A. |
| `` | ${OutputLetterMinusOne} |
${SliceLetterMinusOne} |
Alphabetic index with the first position rendered as #. |