~DG - Download Graphic

~DG stores a bitmap under a name, and

^XG draws it. ^GF repeats the whole raster on every label that needs it, and ~DG sends it once, so a logo used on a thousand labels belongs here. ~DG draws nothing. It is a tilde command and acts the moment the parser reads it, not at ^XZ. It belongs before the ^XA of the label that recalls it, not inside a field.

Syntax

~DGd:o.x,t,w,data

Support

Supportedparsed: full · state: full · rendered: full

Every documented parameter renders the same output Labelary produces.

Labelary renders this command.

Parameters

dStorage deviceoptional · one of a set

Where the object is stored.

Default: R:
Invalid value: discarded, and the default applies. This service keeps one object store, so the parser reads the device letter but does not use it.
Test coverage: No documented value is exercised by a test (R:, E:, B:, A:). The invalid-value rule is not pinned by a test.

R:: Volatile DRAM (default)
E:: Non-volatile flash
B:: Optional memory card
A:: Optional memory card

oObject nameoptional · text

Name the graphic is stored under, 1 to 8 alphanumeric characters. ^XG recalls it by this name.

Default: UNKNOWN
Invalid value: not possible — any value is accepted
Test coverage

xExtensionoptional · one of a set

Object extension. Always .GRF for a graphic.

Default: .GRF
Invalid value: discarded, and the default applies. The extension is fixed; the renderer treats anything else as .GRF.
Test coverage: No documented value is exercised by a test (.GRF). The invalid-value rule is not pinned by a test.

.GRF: The only extension a downloaded graphic can have (default)

tTotal bytesrequired · integer

Total number of bytes in the graphic: bytes per row times number of rows.

Invalid value: enough to stop the field being printed
Test coverage: The invalid-value rule is pinned by 1 test.

wBytes per rowrequired · integer

Number of bytes in one row of the raster. The graphic is 8 × w dots wide.

Invalid value: enough to stop the field being printed
Test coverage: The invalid-value rule is pinned by 1 test.

dataImage datarequired · hexadecimal

The raster as ASCII hexadecimal, one bit per pixel, 1 meaning black.

Invalid value: enough to stop the field being printed
Test coverage: The invalid-value rule is pinned by 1 test, including the diagnostic it emits.

Behavior

The two counts are the only source for the raster's shape. w bytes make one row, so the graphic is 8 × w dots wide, and t / w gives the number of rows. A width that is not a multiple of eight needs a pad to the next whole byte, and t must count the pad.

The payload is ASCII hexadecimal, one bit per pixel, and 1 is black. Each hex digit is a horizontal nibble of four dots. The decoder ignores a line break, so one source line per raster row reads well. ~DG also accepts the compression operators of

^GF — ,, !, :, the repeat letters, and the :Z64: and :B64: wrappers — because the two commands share one decoder.

Names are not scoped. A second download under one name replaces the first graphic, as the guide states, and a format concatenated with another does this by accident. Do not put a space or a full stop in the name.

No printer holds the object, so it lives for one conversion request only. A ~DG sent in one API call is gone in the next, so every format must carry the graphics it recalls.

Tested behavior

Differences from the specification

Labelary against the ZPL II guide

Where Labelary — our compatibility target — behaves differently from the printed specification.

Labelary's reference gives bytes-per-row a default of 1, and calls it "almost always incorrect". The guide states no default, and computes the value from the graphic's width. — not pinned by a test

zpl.tools against the ZPL II guide

Where our renderer behaves differently from the specification.

Objects live for one conversion request; nothing persists between API calls, because no printer exists to persist to. — not pinned by a test
The renderer stores an object under its bare name: the parser reads the device letter and the extension, then drops them. So ^XGR:LOGO.GRF and ^XGLOGO.PNG both recall ~DGB:LOGO.GRF. — not pinned by a test

Example

An 80 × 8 dot checkerboard stored as SAMPLE.GRF, then recalled twice on the label — t is 80 bytes and w is 10, which is eight rows of 80 dots:

~DGR:SAMPLE.GRF,00080,010,
FFFFFFFFFFFFFFFFFFFF
8000FFFF0000FFFF0001
8000FFFF0000FFFF0001
8000FFFF0000FFFF0001
FFFF0000FFFF0000FFFF
FFFF0000FFFF0000FFFF
FFFF0000FFFF0000FFFF
FFFFFFFFFFFFFFFFFFFF
^XA
^FO50,50^XGR:SAMPLE.GRF^FS
^FO50,120^XGR:SAMPLE.GRF^FS
^XZ

Open in viewer

^XG Recall GraphicDraws a previously downloaded graphic, optionally magnified.
^GF Graphic FieldDraws a bitmap sent inline with the label.
~DN Abort Download GraphicCancels a graphic download that is in progress.
^ID Image DeleteDeletes a stored object from printer memory.

~DG - Download Graphic

On this page