~SD - Set Darkness
Sets the base print darkness level.
~SD sets the printhead heat level outright. It is the ZPL equivalent of the
darkness setting on the printer's control panel, and the value that ^MD
adjusts. The guide writes the argument as two digits, so older documentation and
older formats use ~SD05 rather than ~SD5.
Syntax
~SDdSupport
Accepted and skipped, because it configures the printer rather than the label. It cannot change the rendered output, and Labelary skips it too.
As with ^MD, there is no darkness to set in a monochrome raster. The renderer does not parse this command. It reports IGNORED_COMMAND at info severity, which does not reach X-Warnings. Labelary is also silent, so the rendered label is identical in both engines. — not pinned by a test
Labelary renders this command.
Parameters
dDarknessoptional · integerPrinthead heat level, in two digits. Higher is darker on thermal media.
- Default
- the previously set value
- Accepted range
- 0 to 30
- Invalid value
- not documented, and we have not measured it. The renderer does not parse or measure this command.
- Test coverage
- No test at the minimum, maximum or one step outside the range.
Behavior
The ~ prefix makes it immediate. On a printer it takes effect as it arrives,
not at the end of a format. A format therefore sends it on its own line before
^XA. It has no per-command default: without an argument, the last permanently
saved value stands.
The printer adds ^MD on top of what this command sets, and counts ^MD
against the configured value rather than against a previous ^MD. Use ~SD for
the base level and ^MD for a per-media correction.
The output is a monochrome raster with no heat to change. The renderer does not
parse this command. It reports IGNORED_COMMAND at info severity, which does
not reach X-Warnings. Labelary is also silent, so the rendered label is
identical in both engines.
Differences from the specification
Labelary against the ZPL II guide
Where Labelary — our compatibility target — behaves differently from the printed specification.
- Labelary documents this as a whole number. The guide's own examples pass tenths, such as
~SD8.3, because the XiIIIPlus takes darkness in increments of 0.1. — not pinned by a test
Example
Base darkness set immediately, before the format begins:
~SD20
^XA
^FO50,50^A0N,40,40^FDBase darkness 20^FS
^XZ
Related commands
^MDMedia DarknessAdjusts print darkness up or down from the level `~SD` set.^PRPrint RateSets the speed of the media during print, slew and backfeed.