Printer Native Commands vs. Graphic Mode: How ThermalLabel SDK Generates Printer Commands
When ThermalLabel SDK converts a label to printer commands (ZPL, EPL, Fingerprint, Direct Protocol, ESC/POS or PCL), it decides item by item how that item will be sent to the printer. Each item can go one of two ways:
- Native mode: the item is expressed with the printer language's own commands: resident fonts, boxes, lines, ellipses, barcode commands, and so on. The output is small, easy to read and fast to print.
- Graphic mode: the SDK renders the item to a monochrome bitmap and sends it as an image (
^GFAin ZPL,GWin EPL,PRBUFin Fingerprint/Direct Protocol). The printout matches the on-screen preview pixel for pixel, but the output is bigger and can't be read as text.
The SDK uses native mode whenever the printer language can reproduce the item exactly. When an item uses a feature the printer can't draw on its own (a TrueType font, rounded corners, rich text, a rotation angle that isn't a multiple of 90°, and so on), the SDK switches that item to graphic mode so the printed label still matches the design.
This article lists, for each item type and each programming language, which conditions keep an item native and which ones force it to graphic mode.
Tip
Inspect the generated commands.** To see the raw commands the SDK produces, call PrintJob.GetNativePrinterCommands(). It returns a string; GetBinaryNativePrinterCommands() returns a byte[]. Neither one sends anything to the printer, so you can save the output to a file or paste it into a viewer such as ZPLPrinter Emulator SDK or EPLPrinter Emulator SDK to check which items came out as graphic-mode.
var pj = new PrintJob();
pj.ProgrammingLanguage = ProgrammingLanguage.ZPL;
pj.Dpi = 203;
pj.ThermalLabel = myLabel;
string zpl = pj.GetNativePrinterCommands();
System.IO.File.WriteAllText("label.zpl", zpl);
1. Rules that apply to every item
These settings send any visual item (text, barcode, shape or image) to graphic mode, whatever the language:
| Setting | Effect |
|---|---|
Item.PrintAsGraphic = true |
Always graphic. This is the explicit way to force it. |
Item.UseCache = true |
The item is rendered as an image once, downloaded to printer memory and recalled on each label (ZPL ~DG + ^XG, EPL GK/GM + GG, Fingerprint IMAGE LOAD + PM). This is still graphic mode, but the image is transferred only once. It applies to shapes too, so a cached rectangle is no longer a native ^GB. |
Language-level rules:
- ESC/POS and PCL have no native mode at all. The whole label is rendered as one image (see section 5).
- Fingerprint and Direct Protocol produce identical item commands. Only the job header differs.
2. ZPL
2.1 TextItem
A TextItem produces native ZPL text (^A / ^A@ + ^FD) only if all of the conditions in Group A hold, and the font meets one of the options in Group B. If either check fails, the text is rendered as ^GFA.
Group A: conditions that force graphic mode when not met
| Property | Required for native output |
|---|---|
PrintAsGraphic |
false |
UseCache |
false |
Text |
Plain text. BBCode ([b]…[/b], [i]…[/i], [u]…[/u]), HTML (<html>…</html>) and RTF ({\rtf1…}) content is always graphic. |
Sizing |
None. AutoSize, OverflowSplit, Stretch, FontSizeScaling, ParagraphScaling*, Arc, OuterArc and Vertical all force graphic mode. |
TextVerticalAlignment |
Top or Bottom (Middle forces graphic mode) |
ScaleX / ScaleY |
1 |
RotationAngle |
A multiple of 90° (0, 90, 180, 270) |
RightToLeft |
false |
CornerRadius |
Zero |
StrokeThickness |
0 (outlined text forces graphic mode) |
CharSpacing |
0 |
Group B: the font must be one of these
| Font | ZPL output |
|---|---|
NativePrinterFontA |
Resident bitmap font D (203 dpi) or F (300/600 dpi): ^AD / ^AF |
NativePrinterFontB |
Resident scalable font 0: ^A0 |
NativePrinterFontS |
Resident font B (203 dpi) or D (300/600 dpi) |
ZPL Font 0 |
^A0 with ^FB (field block) |
Swiss 721 / Swiss721BT / Swis721 BT |
^A@…,TT0003M_ (Zebra's resident Swiss 721 font file) with ^FB |
Any font with Font.NameAtPrinterStorage set |
^A@…,<NameAtPrinterStorage> with ^FB, using a font already stored on the printer |
Any other font (Arial, Calibri, Roboto, a custom TTF file, etc.) is always printed in graphic mode, because the printer doesn't have that font. This is by far the most common reason a ZPL label contains only ^GFA commands.
Other details of native text output:
BackColor = BlackandBorderThicknessare drawn with^GBboxes, so they don't affect the choice of mode.ForeColor = Whiteadds^FR(field reverse).- Non-ASCII characters add
^CI(code page) and^FH(hex escapes). Real-time clock tokens such as{yyyy}or{H}become^FC. - With the
NativePrinterFont*fonts, text is single-line. If it is wider than the box, it is trimmed one character at a time until it fits. If the font is taller than the box, the text is not printed at all, so make the box tall enough for the font. - With
ZPL Font 0,Swiss 721or a printer-stored font, text can span several lines (^FB), andTextAlignmentandLineSpacingare honored. When the text contains RTL characters,^PAis added.
2.2 BarcodeItem
In ZPL a barcode can come out in one of three ways.
a) Resident barcode commands (^BC, ^BQ, ^BX, ^B7, and so on)
You opt in by setting PrintAsResidentElement = true. The SDK then checks the settings with PrintAsResidentElementIsSupported(out string error), which you can also call yourself to get a description of anything that blocks it. The main requirements:
- The symbology must be one the printer supports natively: Code 128/GS1-128, Code 39, Code 93, Code 11, Codabar, Interleaved 2 of 5, Industrial 2 of 5, MSI, Plessey, EAN-8/13, UPC-A/E, EAN/UPC add-ons, Postnet, Planet, USPS Intelligent Mail, PDF417 (including Compact, Macro and Micro PDF417), Codablock F, Code 49, TLC39, QR Code, Data Matrix, Aztec, MaxiCode and GS1 DataBar/RSS. Composite symbologies (
…CCA,…CCB,…CCC) are not supported. Sizing = AutoSize(settingPrintAsResidentElement = truesets this automatically).- No
RightToLeft,CornerRadius,Text, border, bearer bars, ITF-14 H-marks or…Justifycode alignment. - 2D symbologies must have
QuietZone = 0. - GS1 DataBar: the bar height must match the printer's fixed ratio to the bar width.
- MaxiCode:
RotationAngle = 0, and the data must start with[)>. - No artistic (
Art*) settings.
If the check fails, the SDK quietly falls back to option b) or c) below.
Important
Resident barcodes may not look exactly like the preview.
With PrintAsResidentElement = true, the SDK doesn't encode the barcode. It sends the data with a resident command (^BQ, ^BX, ^BC, …) and the printer firmware's own barcode encoder builds the symbol. Everywhere else (the on-screen preview and exports to image, PDF or HTML), the symbol comes from the SDK's encoder. The two encoders can make different, equally valid, choices, so the printed barcode may not match the preview module for module or bar for bar:
- 2D symbologies (QR Code, Data Matrix, Aztec, PDF417, etc.): the same data can be encoded in different ways, for example with different encodation modes or segmentation (numeric, alphanumeric, byte), or a different version/size, mask pattern or error-correction choice. Two QR codes can look completely different and still decode to exactly the same data.
- Code 128 / GS1-128: the encoder chooses the start code set (A, B or C) and where to switch code sets in the middle of the data, so the bar pattern, and even the overall barcode width, can differ.
This does not mean either output is wrong. Both the printer's barcode and the SDK's barcode are valid and are read and decoded correctly by barcode scanners. They simply aren't guaranteed to be visually identical.
If the printed label must match the preview and the exported image, PDF or HTML exactly, leave PrintAsResidentElement = false and use native shapes (option b) or graphic mode (option c). In both modes the symbol is encoded by the SDK itself, so the printer reproduces exactly what you see on screen. The trade-off is a larger print job, especially in graphic mode.
b) Native shapes (the default)
When resident mode is off or not supported, the SDK draws the symbol itself out of native primitives: each bar or module becomes a ^GB box, DotCode dots become ^GE ellipses, and the human-readable text becomes native text (section 2.1). The printout still matches the preview exactly and nothing is rasterized, but you won't see ^BC-style commands in the output, only many ^GB commands.
c) Graphic mode (^GFA)
The barcode is sent as an image when any of these is true:
| Condition | |
|---|---|
PrintAsGraphic = true or UseCache = true |
|
Any artistic setting: ArtBarImagePattern, ArtLogoImage, ArtModuleShape ≠ Rect, ArtFinderShape ≠ Rect |
|
Font (the human-readable text font) is not a NativePrinterFont* font |
Applies even when DisplayCode = false |
RightToLeft = true |
|
CornerRadius not zero |
|
Sizing = Fill |
|
Symbology is MaxiCode (when not resident), SwissQRCode, DINSpecQRCode or DINSpecDataMatrix |
|
Text (extra caption) is not empty |
|
BackColor = Black and BarColor = White |
|
DisplayCode = true and CodeAlignment is one of the Above… values or BelowJustify |
|
| ITF-14 / DUN-14 with left or right H-marks |
2.3 Shapes
| Item | Native ZPL when… | Native command | Otherwise |
|---|---|---|---|
LineShapeItem |
Orientation is Horizontal or Vertical, and StrokeStyle = Solid, and not cached or forced to graphic |
^GB |
^GFA. Diagonal lines, dashed lines and dotted lines are always graphic. |
RectangleShapeItem |
RotationAngle is a multiple of 90°, and CornerRadius is zero, and StrokeStyle = Solid, and not cached or forced to graphic |
^GB (fill + stroke) |
^GFA |
EllipseShapeItem / CircleShapeItem |
RotationAngle is a multiple of 90°, and StrokeStyle = Solid, and not cached or forced to graphic |
^GE |
^GFA |
TableShapeItem |
Same rules as RectangleShapeItem |
Broken down into ^GB boxes and lines |
^GFA |
StrokeColor/FillColor = White on a black background uses ^FR.
2.4 ImageItem
Images are always graphic: ^GFA, or ~DG + ^XG when UseCache = true.
The one exception: if ImageItem.NameAtPrinterStorage is set (for example E:LOGO.GRF), the SDK sends no image data at all, only ^XG to recall a graphic that is already stored on the printer.
2.5 Other items
| Item | ZPL output |
|---|---|
LiteralItem |
The Text is sent unchanged. Use it to inject your own raw ZPL. |
RFIDTagItem |
^RS, ^RB, ^RFW, ^RLB, ^RLM (never graphic) |
RepeaterItem |
Produces no commands of its own. Each repeated child follows its own rules. |
3. EPL
EPL follows the same logic as ZPL, with these differences.
TextItem
- Native output (
Acommand) is possible only withNativePrinterFontA(EPL font 2),NativePrinterFontB(EPL font 4) orNativePrinterFontS(EPL font 1). EPL has noSwiss 721,ZPL Font 0orNameAtPrinterStoragepath, so every other font is graphic (GW). - All the Group A conditions from section 2.1 apply, plus
LineSpacing = 0. - Native text is single-line and is trimmed to fit, as described for ZPL.
BarcodeItem
- There is no resident-element mode in EPL;
PrintAsResidentElementonly applies to ZPL. - Native-shapes mode (bars as
LOlines, human-readable text as native text) is used unless one of the graphic-mode conditions in section 2.2 c) applies, in which case the barcode is sent withGW.
Shapes
| Item | Native EPL | Otherwise |
|---|---|---|
LineShapeItem |
Horizontal or vertical, solid: LO |
GW |
RectangleShapeItem |
Same rules as ZPL: LO (fill) and X (box) |
GW |
EllipseShapeItem / CircleShapeItem |
Never. EPL has no ellipse command. | Always GW |
TableShapeItem |
Same rules as ZPL | GW |
ImageItem: always GW, or GG with UseCache / NameAtPrinterStorage.
LiteralItem: sent unchanged, with a line feed appended if missing.
RFIDTagItem: not supported in EPL (no output).
4. Fingerprint and Direct Protocol (Intermec/Honeywell)
Both languages share the same item logic. Graphic output is sent as an RLL image with PRBUF, or as IMAGE LOAD + PM when cached.
TextItem: native output (FT + PX, a text box) requires the Group A conditions from section 2.1, plus:
TextVerticalAlignment = Top(bothMiddleandBottomforce graphic mode)TextAlignmentis notJustifyBorderThicknessandTextPaddingare uniform (the same on all four sides)- Not white text on a black background (
BackColor = BlackwithForeColor = White) LineSpacing = 0- The font is one of:
- a
NativePrinterFont*font (mapped to CG Triumvirate Condensed Bold, Monospace 821 Bold BT and Andale Mono) - a font the printer has built in: CG Triumvirate Condensed Bold, Swiss 721 (BT), Univers, Andale Mono, CG Times, Dutch 801, Futura Light, Monospace 821 or Century Schoolbook
ZPL Font 0, as long as the text contains no hyphen- any font with
NameAtPrinterStorageset
- a
BarcodeItem: always graphic in Fingerprint and Direct Protocol (PRBUF, or PM when cached). Resident barcode commands and native-shape decomposition aren't available in these languages.
Shapes
| Item | Native FP/DP when… | Command |
|---|---|---|
LineShapeItem |
StrokeStyle = Solid and not cached or forced to graphic. Diagonal lines are native here too. |
PL (horizontal/vertical), PD (diagonal) |
RectangleShapeItem |
Same rules as ZPL | PL (fill), PX (box) |
EllipseShapeItem / CircleShapeItem |
Same rules as ZPL | PRELLIPSE |
TableShapeItem |
Same rules as ZPL | Broken down into PL/PX |
ImageItem: always graphic (PRBUF), or PM with UseCache / NameAtPrinterStorage.
LiteralItem: sent unchanged, with CRLF appended if missing.
RFIDTagItem: TAGFIELD, TAGFORMAT and TAGWRITE.
5. ESC/POS and PCL
These languages have no per-item native mode. The entire label is rendered as one bitmap at the job's DPI and sent as a raster image (ESC/POS graphics commands or PCL raster graphics). No item settings change this. LiteralItem and RFIDTagItem have no effect in these languages.
6. Quick reference
✅ native when its conditions are met · 🖼️ always graphic · — not applicable
| Item | ZPL | EPL | Fingerprint / DP | ESC/POS · PCL |
|---|---|---|---|---|
| Text: NativePrinterFont A/B/S | ✅ | ✅ | ✅ | 🖼️ |
| Text: Swiss 721 / ZPL Font 0 | ✅ | 🖼️ | ✅ | 🖼️ |
Text: font stored on printer (NameAtPrinterStorage) |
✅ | 🖼️ | ✅ | 🖼️ |
| Text: any other TrueType font | 🖼️ | 🖼️ | 🖼️ | 🖼️ |
| Barcode | ✅ (resident or native shapes) | ✅ (native shapes) | 🖼️ | 🖼️ |
| Line, horizontal or vertical | ✅ | ✅ | ✅ | 🖼️ |
| Line, diagonal | 🖼️ | 🖼️ | ✅ | 🖼️ |
| Rectangle / Table | ✅ | ✅ | ✅ | 🖼️ |
| Ellipse / Circle | ✅ | 🖼️ | ✅ | 🖼️ |
| Image | 🖼️ (or ^XG with a stored image) |
🖼️ | 🖼️ | 🖼️ |
| Literal | raw | raw | raw | — |
| RFID | ✅ | — | ✅ | — |
7. How to get the leanest native output (ZPL)
- Use printer-resident fonts. Choose
NativePrinterFontA/B/S,ZPL Font 0orSwiss 721, or upload your TrueType font to the printer and setFont.NameAtPrinterStorage. - Avoid text effects that the printer can't reproduce: rich text,
Sizingother thanNone, middle vertical alignment, scaling, stroke, character spacing, RTL and rounded corners. - For barcodes, set
PrintAsResidentElement = trueand checkPrintAsResidentElementIsSupported()to find out what is blocking it. Keep in mind that the printer then encodes the symbol itself, so it may not look identical to the preview, although it will scan to the same data (see section 2.2). If you need an exact match with the preview, keep native-shapes mode instead and use aNativePrinterFont*font for the human-readable text. - Keep shapes simple: solid strokes, rotation in multiples of 90° and no rounded corners.
- For logos, store them on the printer once and reference them with
ImageItem.NameAtPrinterStorage, or useUseCache = trueso the image is transferred only once. - Don't set
PrintAsGraphicunless you need it.
8. Troubleshooting non-Zebra printers that emulate ZPL
Many printers from other brands (Printronix, SATO, Honeywell, TSC, and others) provide ZPL emulation. A few things to check when a label prints correctly on a Zebra printer but not on an emulating one:
^GFAis part of core ZPL and is widely supported, but the SDK sends it uncompressed (ASCII hex). Large or numerous^GFAfields mean big jobs, which some emulations handle less well (memory, buffer or timeout limits). Reducing graphic items (section 7) usually helps.- The
Swiss 721mapping uses Zebra's resident font fileTT0003M_, which may not exist on emulating printers. PreferNativePrinterFont*/ZPL Font 0, or a font loaded underNameAtPrinterStorage. UseCacherelies on~DG/^XGand the printer'sR:memory. If cached items don't appear, try turningUseCacheoff.- Always compare the output of
GetNativePrinterCommands()against the emulation's supported-command list from the printer vendor.