^XG - Recall Graphic

^XG draws a graphic that ~DG or ~DY put into memory. It is the recall half of the store-once-draw-often pattern, and a format can recall one object many times at different positions and sizes. The renderer does not apply the magnification factors. It always draws the graphic at its stored size, and Labelary scales it. Check this before a port of a format that sizes graphics with ^XG.

Syntax

^XGd:o.x,mx,my

Support

Supportedparsed: full · state: full · rendered: full

Every documented parameter renders the same output Labelary produces.

The renderer recalls the graphic and applies both magnification factors, replicating each stored dot into a block of that width and height. A factor outside 1 to 10 resets to 1, matching Labelary. — not pinned by a test

Labelary renders this command.

Parameters

dStorage deviceoptional · single character

Which memory device the graphic was stored on.

Default: search priority — R:, then E:, B:, A:
Invalid value: discarded, and the default applies. This service keeps one object store, so the device letter does not narrow the search.
Test coverage: The invalid-value rule is not pinned by a test.

oObject nameoptional · text

Name ~DG downloaded the graphic under.

Default: UNKNOWN
Invalid value: enough to stop the field being printed. The renderer reports RESOURCE_MISSING for a name never downloaded, and draws nothing.
Test coverage: The invalid-value rule is not pinned by a test.

xExtensionoptional · text

Extension of the stored graphic.

Default: .GRF
Invalid value: discarded, and the default applies. The extension takes no part in the lookup, because the renderer stores objects under their bare name. So ^XGR:LOGO.PNG finds the graphic downloaded as LOGO.GRF.
Test coverage: The invalid-value rule is not pinned by a test.

mxHorizontal magnificationoptional · integer

Whole-number magnification applied across the graphic.

Default: 1
Accepted range: 1 to 10 ×
Invalid value: discarded, and the default applies. A factor below 1 or above 10 resets to the default of 1 rather than clamping to the violated bound. Measured on live Labelary 2026-08-18: ,11,11 reports Value 11 is greater than maximum value 10; used 1 instead and draws at stored size. A non-numeric factor is ignored, and a numeric prefix is kept, so 2.7 reads as 2.
Test coverage: Bounds pinned: above the maximum (4294967295). No test at the minimum or maximum. The invalid-value rule is not pinned by a test.

myVertical magnificationoptional · integer

Whole-number magnification applied down the graphic.

Default: 1
Accepted range: 1 to 10 ×
Invalid value: discarded, and the default applies. A factor below 1 or above 10 resets to the default of 1 rather than clamping to the violated bound. Measured on live Labelary 2026-08-18: ,11,11 reports Value 11 is greater than maximum value 10; used 1 instead and draws at stored size. A non-numeric factor is ignored, and a numeric prefix is kept, so 2.7 reads as 2.
Test coverage: No test at the minimum, maximum or one step outside the range. The invalid-value rule is not pinned by a test.

Behavior

^XG is a field. It takes its position from the preceding ^FO or ^FT and ends at ^FS. ^FO places the top-left corner of the graphic.

A recall of a name that no download stored is not fatal. The renderer ignores the field and reports a RESOURCE_MISSING diagnostic, so the rest of the label prints with a hole where the graphic belongs. Watch for this, because a format that downloads its logo in a separate API call renders exactly this way.

The renderer stores an object under its bare name, so neither the device letter nor the extension narrows the lookup: ^XGR:LOGO.GRF and ^XGLOGO.PNG both find a graphic downloaded as ~DGB:LOGO.GRF. On a printer the device letter selects a real memory bank, and an omitted letter searches R:, E:, B:, A: in turn.

Magnification, where a printer honors it, replicates whole pixels and does not resample. At 4× each stored dot becomes a 4 × 4 block, so an enlarged small graphic is visibly blocky and keeps sharp edges. No factor shrinks a graphic, because the factors start at 1.

Tested behavior

Differences from the specification

zpl.tools against the ZPL II guide

Where our renderer behaves differently from the specification.

The renderer looks objects up by their bare name, so neither the device letter nor the extension narrows the search. — not pinned by a test

Example

The same 80 × 8 dot graphic recalled at its stored size and at 4×:

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

Open in viewer

~DG Download GraphicDownloads an ASCII-hex bitmap into printer memory as a `.GRF` object.
^GF Graphic FieldDraws a bitmap sent inline with the label.
^ID Image DeleteDeletes a stored object from printer memory.
^FO Field OriginSets the top-left corner of the next field.

^XG - Recall Graphic

On this page