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%\BgRaster, %LocalAppData%\BgRaster, and %AppData%\BgRaster. 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. BgRaster cycles through array elements per output index using array[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).

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:

1. Field substitution is applied first (see Substitution tokens).
2. Environment variables are expanded.
3. If the value is an absolute URI (including pack://), it is used as-is.
4. If the value is an absolute filesystem path, it is used as-is.
5. 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].image empty disables background image rendering, and [logo].source empty suppresses logo rendering).

[text]

Global text rendering settings. Array values are resolved by rendered slice sequence with wraparound.

Key	Type	Default	Description
format	string[]	["${MachineName} output ${OutputIndexPlusOne}<br>","slice ${SliceLetter}<br>","${SliceWidth}x${SliceHeight}"]	Text lines. Each array element gets its own color/size index and accumulates on the same visual line until the next element starts. Use <br> for explicit linebreaks. Supports substitution tokens detailed in the Substitution tokens table.
text-align	enum	"center"	Internal text alignment within the block. Allowed enum values: start, end, center.
anchor-x	enum or number	"center"	Horizontal block anchoring. Accepts float values (0 to 1). Allowed enum values: left, center, right.
anchor-y	enum or number	"center"	Vertical block anchoring. Accepts float values (0 to 1). Allowed enum values: top, center, bottom.
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

---

[network]

See the sections below for a full explanation of filtering, formatting, substitution tokens, and address origins.

Key	Type	Default	Description
render	boolean	false	Set to true to enable the dedicated network block. The ${Network} token in text blocks always works regardless.
x	string[]	["10vw"]	Horizontal text block position.
y	string[]	["75vh"]	Vertical text block position.
size	string[]	["3vh","2vh","2vh","4vh"]	Text height per rendered item. Index 0 applies to adapter name, index 1 to each IP.
color	string[]	["transparent"]	Text color. Set to a valid color to enable rendering.
require_adapter_type	string[]	["Wireless80211","Ethernet"]	Adapter types to include. Accepts .NET names, IANA short names, or integers. See network interface types.
exclude_adapter_type	string[]	[]	Adapter types to exclude. If require_adapter_type is non-empty, exclude_adapter_type is skipped.
require_up	boolean	true	If true, interfaces that are down will be dropped.
require_family	string	"IPv4"	IP address family filter: IPv4, IPv6, or empty for both.
require_mac_address	string[]	[]	Only include adapters with MAC addresses in this list.
require_subnet	string[]	[]	CIDR subnets to filter IP addresses by (e.g. 192.168.1.0/24). See CIDR notation.
minimum_address_count	integer	1	Number of matches from require_subnet required for adapter to be included
require_name	string[]	[]	Wildcard expressions for adapter names. See wildcard matching. Matching adapters pass immediately; non-matching are dropped.
require_description	string[]	[]	Wildcard expressions for adapter descriptions. See wildcard matching. Matching adapters pass immediately; non-matching are dropped.
ip_address_format	string[]	[" →${Address}/${CidrBits}"," (${Origin})<br>"]	Format strings for each IP address entry, one per array element. Each element gets its own color/size index. Use <br> for explicit linebreaks. See substitution tokens.
adapter_format	string[]	["${Name}<br>"," ${MacAddress}<br>"," ${Speed}<br>"," ${IpAddresses}<br>"]	Format strings for each network adapter entry, one per array element. Each element gets its own color/size index. Use <br> for explicit linebreaks. See substitution tokens.
text-align	enum	"start"	Internal text alignment for the network block. Allowed enum values: start, end, center.
anchor-x	enum or number	"left"	Horizontal block anchoring for the network block. Accepts float values (0 to 1). Allowed enum values: left, center, right.
anchor-y	enum or number	"bottom"	Vertical block anchoring for the network block. Accepts float values (0 to 1). Allowed enum values: top, center, bottom.

---

[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	enum[]	["CropToFill"]	Background image fit mode. CropToFill and BestFit use uniform scaling; crop modes do not scale. Allowed enum 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	enum[]	["Desktop"]	Scope used when resolving viewport-unit measurements and displayed numbers. Allowed enum values: Desktop, Output, Slice.
side	enum[]	["TL","T","TR","R","BR","B","BL","L"]	Sides or corners to label; values may not repeat. Allowed enum 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/BgRaster.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 anchor Y position
anchor-x	enum or number	"center"	Horizontal block anchoring. Accepts float values (0 to 1). Allowed enum values: left, center, right.
anchor-y	enum or number	"center"	Vertical block anchoring. Accepts float values (0 to 1). Allowed enum values: top, center, bottom.
width	string[]	[]	Logo fit rectangle width. If unset, computed from height and the logo source's natural aspect ratio.
height	string[]	["20vh"]	Logo fit rectangle height. If unset, computed from width and the logo source's natural aspect ratio.
opacity	number[]	[1.0]	Additional opacity multiplier (0 = transparent, 1 = opaque)

---

[render]

Render and output settings. Some settings are required for simulating output, such as when generating samples.

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 tokens and {now}, {index}, {friendlyName} file-naming tokens are both supported. Empty = %TEMP%/BgRaster/{now}_{index}.
force	boolean	false	Continue rendering even when run-skipped-unchanged would normally short-circuit
verbosity	enum	"normal"	Logging verbosity level. Allowed enum values: quiet, normal, verbose.
machine-name	string	""	Override the framework-supplied host name used by ${MachineName} substitutions. Empty uses Environment.MachineName.
simulate-network	boolean	false	If true, uses a built-in network simulator instead of querying real network interfaces. Useful for testing and sample generation.

---

[[output]] (array of tables)

Per-output configuration. Optional; outputs without an entry use global values resolved by slice sequence.

Key	Type	Description
target	integer or 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. See [text].
background	object	Per-output or per-slice background override. Scalar values only. See [background].
grid	object	Per-output or per-slice grid override. Scalar values only. See [grid].
circle	object	Per-output or per-slice circle override. Scalar values only. See [circle].
crosshair	object	Per-output or per-slice crosshair override. Scalar values only. See [crosshair].
labeled-edges	object	Per-output or per-slice labeled edges override. See [labeled-edges].
logo	object	Per-output or per-slice logo override. Scalar values only. See [logo].
network	object	Per-output or per-slice network override. Scalar values only. See [network].
slice	object	Per-output slice subdivisions
hardware_output	object	Fixed hardware dimensions for no-discovery mode. When set, BgRaster uses these values instead of querying Windows display APIs (EnumDisplayDevices, EnumDisplaySettingsEx, GetDpiForMonitor). See [output.hardware_output].

---

[output.hardware_output]

Fixed hardware dimensions for no-discovery mode. When set, BgRaster uses these values instead of querying Windows display APIs (EnumDisplayDevices, EnumDisplaySettingsEx, GetDpiForMonitor).

Key	Type	Description
id	string	Stable monitor identifier from EnumDisplayDevices (monitor DeviceID). Optional for fixed no-discovery samples.
index	integer	Zero-based output index, assigned by BgRaster during discovery.
desktopX	integer	Virtual desktop X position in pixels. From EnumDisplaySettingsEx DEVMODE.dmPosition.x.
desktopY	integer	Virtual desktop Y position in pixels. From EnumDisplaySettingsEx DEVMODE.dmPosition.y.
widthPx	integer	Output width in physical pixels. From EnumDisplaySettingsEx DEVMODE.dmPelsWidth.
heightPx	integer	Output height in physical pixels. From EnumDisplaySettingsEx DEVMODE.dmPelsHeight.
dpiX	integer	Horizontal logical DPI. From GetDpiForMonitor or GetDpiForWindow at the output's desktop position.
dpiY	integer	Vertical logical DPI. From GetDpiForMonitor or GetDpiForWindow at the output's desktop position.
rotation	enum	Display rotation in degrees. From EnumDisplaySettingsEx DEVMODE.dmDisplayOrientation (DMDO_0/DMDO_90/DMDO_180/DMDO_270). Allowed enum values: 0, 90, 180, 270.
adapterName	string	Display adapter device name. From EnumDisplayDevices adapter-level DeviceName (e.g. \\.\DISPLAY1).
friendlyName	string	Human-readable monitor name. From EnumDisplayDevices monitor-level DeviceString. In no-discovery mode, this value also feeds ${OutputName} in text substitution and {friendlyName} in render.output path templates.

---

[[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. See [text].
background	object	Per-output or per-slice background override. Scalar values only. See [background].
grid	object	Per-output or per-slice grid override. Scalar values only. See [grid].
circle	object	Per-output or per-slice circle override. Scalar values only. See [circle].
crosshair	object	Per-output or per-slice crosshair override. Scalar values only. See [crosshair].
labeled-edges	object	Per-output or per-slice labeled edges override. See [labeled-edges].
logo	object	Per-output or per-slice logo override. Scalar values only. See [logo].
network	object	Per-output or per-slice network override. Scalar values only. See [network].

---

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}		Machine-level: configured machine name (Environment.MachineName fallback). Output-level: friendly output name from display discovery or hardware_output.friendlyName.
	${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 #.
${Network}			Network adapter information -- IPs, MACs, speeds, names. Configurable via [network] section.

Substitution tokens - per IP address

Token	Description	Example
${CidrBits}	The number of bits in the network suffix of the IP address. See CIDR notation.	24
${Origin}	The origin of the IP address. See about address origins.	DHCP, Manual, Router advertisement-Random
${Address}	The address in standard string form - decimal for IPv4, hex for IPv6.	198.51.100.14, fd6a:9a22:b579:8244:df24:fba6:eb71:2b09

Substitution tokens - per network interface

Token	Description	Example
${Name}	The name of the network interface.	Ethernet 6
${Description}	The description of the network interface.	Realtek Gaming 2.5GbE Family Controller
${ID}	A GUID representing the network adapter, generated by Windows when it's installed, and remaining consistent until you uninstall it.	1BFD6D92-B38E-11EF-9376-00D861D55AAB
${Type}	The network interface type expressed as a short string. Details.	propVirtual
${TypeLong}	The network interface type expressed as a longer string from the IANA IF Type enumeration.	proprietary virtual/internal
${Status}	The operational status of the network interface.	Up, Down
${Speed}	The speed of the interface with units. The largest magnitude prefix yielding a value >1 is selected.	100Mb/s, 2.5Gb/s
${PhysicalAddress} or ${MacAddress}	The MAC address of the adapter.	02:DE:AD:BE:EF:00
${IpAddresses}	A list of IP addresses assigned to the interface, formatted per ip_address_format and adapter_format in the Network configuration below.	198.51.100.14 (DHCP)<br> fd6a:9a22:b579:8244:df24:fba6:eb71:2b09 (Router-random)

About wildcard expression matching

Anywhere that filtering by string expressions is supported, the same rules are used. * matches any number of characters, ? matches any single character, and \ escapes * or ? so they can be used as literals.

About network interface types

Microsoft provides an incomplete enumeration of interface types in .NET. For example, type 53 is commonly used for VPNs and virtual network adapters, but this enumeration does not include an entry for that. To get the best of both, the ${Type} token will fall back to short names provided in the IANA IF Type enumeration when it's missing from the Microsoft enumeration. ${TypeLong} always comes from the IANA list. require_adapter_type and exclude_adapter_type filters accept the .NET names, IANA short names, or integers.

About address origins

IPv4 addresses are assigned to the adapter by one of these methods:

• Unknown
• Manual - manually configured on the host.
• Well known - specified by convention.
• DHCP - supplied by a DHCP server.
• Link layer - the address is derived from the physical address.
• Random - randomly assigned by the host.

IPv6 addresses are more complicated because the prefix (the network part) can be from a different origin than the suffix (host part):

• Unknown
• Manual - manually configured on the host. A manual suffix is virtually guaranteed.
• Well known
• DHCP - supplied by a DHCP server. A DHCP suffix is virtually guaranteed.
• Router - the prefix was supplied by the router.

BgRaster treats IPv6 address origins as two parts, e.g. Router advertisement-Random. If the two parts are the same, they are collapsed into a single string, e.g. DHCP, Manual.