Show / Hide Table of Contents

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 (^GFA in ZPL, GW in EPL, PRBUF in 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 = Black and BorderThickness are drawn with ^GB boxes, so they don't affect the choice of mode.
  • ForeColor = White adds ^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 721 or a printer-stored font, text can span several lines (^FB), and TextAlignment and LineSpacing are honored. When the text contains RTL characters, ^PA is 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 (setting PrintAsResidentElement = true sets this automatically).
  • No RightToLeft, CornerRadius, Text, border, bearer bars, ITF-14 H-marks or …Justify code 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 (A command) is possible only with NativePrinterFontA (EPL font 2), NativePrinterFontB (EPL font 4) or NativePrinterFontS (EPL font 1). EPL has no Swiss 721, ZPL Font 0 or NameAtPrinterStorage path, 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; PrintAsResidentElement only applies to ZPL.
  • Native-shapes mode (bars as LO lines, 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 with GW.

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 (both Middle and Bottom force graphic mode)
  • TextAlignment is not Justify
  • BorderThickness and TextPadding are uniform (the same on all four sides)
  • Not white text on a black background (BackColor = Black with ForeColor = 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 NameAtPrinterStorage set

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)

  1. Use printer-resident fonts. Choose NativePrinterFontA/B/S, ZPL Font 0 or Swiss 721, or upload your TrueType font to the printer and set Font.NameAtPrinterStorage.
  2. Avoid text effects that the printer can't reproduce: rich text, Sizing other than None, middle vertical alignment, scaling, stroke, character spacing, RTL and rounded corners.
  3. For barcodes, set PrintAsResidentElement = true and check PrintAsResidentElementIsSupported() 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 a NativePrinterFont* font for the human-readable text.
  4. Keep shapes simple: solid strokes, rotation in multiples of 90° and no rounded corners.
  5. For logos, store them on the printer once and reference them with ImageItem.NameAtPrinterStorage, or use UseCache = true so the image is transferred only once.
  6. Don't set PrintAsGraphic unless 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:

  • ^GFA is part of core ZPL and is widely supported, but the SDK sends it uncompressed (ASCII hex). Large or numerous ^GFA fields mean big jobs, which some emulations handle less well (memory, buffer or timeout limits). Reducing graphic items (section 7) usually helps.
  • The Swiss 721 mapping uses Zebra's resident font file TT0003M_, which may not exist on emulating printers. Prefer NativePrinterFont* / ZPL Font 0, or a font loaded under NameAtPrinterStorage.
  • UseCache relies on ~DG / ^XG and the printer's R: memory. If cached items don't appear, try turning UseCache off.
  • Always compare the output of GetNativePrinterCommands() against the emulation's supported-command list from the printer vendor.
Back to top Copyright © 2003- Neodynamic SRL
http://www.neodynamic.com