ThermalLabel SDK: Why Is My ZPL Full of ^GFA? Native Commands vs. Graphic Mode

A question we often get from ThermalLabel SDK for .NET users: "I printed to my ZPL printer and the output is all ^GFA commands. Can I get plain ZPL instead?" In most cases, yes. This post explains why it happens and what you can change. All the details are in the new help topic Native Commands vs. Graphic Mode.

Two ways to print an item

When the SDK generates printer commands, it decides item by item how to send each one to the printer:

  • Native mode. The item uses the printer language's own commands: resident fonts, boxes, lines, ellipses and barcode commands. The output is small, readable and fast to print.
  • Graphic mode. The SDK renders the item as a monochrome bitmap and sends it as an image (^GFA in ZPL, GW in EPL, PRBUF in Fingerprint). What prints matches the on-screen preview pixel for pixel, but the output is larger.

The SDK uses native mode whenever the printer can reproduce the item exactly. When the item uses a feature the printer can't draw on its own, the SDK switches it to graphic mode so the label still matches your design.

See the commands the SDK generates

Call PrintJob.GetNativePrinterCommands() to get the raw commands as a string without sending anything to the printer:

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);

Use GetBinaryNativePrinterCommands() if you need a byte[] instead.

The most common reasons an item becomes a graphic

  • TrueType fonts. Text in Arial, Calibri or any other TrueType font is always a graphic, because the printer doesn't have that font. For native ZPL text, use NativePrinterFontA, NativePrinterFontB or NativePrinterFontS, ZPL Font 0 or Swiss 721, or a font already stored on the printer through Font.NameAtPrinterStorage.
  • Text effects. Rich text (BBCode, HTML or RTF), any Sizing other than None, middle vertical alignment, scaling, stroke, character spacing, right-to-left text and rounded corners all force graphic mode.
  • Barcode settings. Examples include a human-readable font that isn't a NativePrinterFont, artistic (Art*) settings, an extra Text caption and rounded corners.
  • Shapes. Shapes with dashed or dotted strokes, rounded corners, or a rotation that isn't a multiple of 90° become graphics. In ZPL and EPL, diagonal lines do too.
  • PrintAsGraphic = true or UseCache = true on any item.
  • Images are always graphics. The exception is an ImageItem with NameAtPrinterStorage set, which only recalls a graphic already stored on the printer.

Note also that ESC/POS and PCL always send the whole label as a single image.

A note on resident barcodes

In ZPL, you can set BarcodeItem.PrintAsResidentElement = true to print barcodes with the printer's own commands (^BC, ^BQ, ^BX, ...). The printer firmware then encodes the symbol with its own encoder. As a result, a QR Code, a Data Matrix or a GS1-128 barcode may look different from the preview or from the exported image, PDF or HTML, although it decodes to exactly the same data. If you need the printed label to match the preview exactly, keep the default mode. By default, the SDK encodes the symbol itself and draws it with native ^GB boxes.

Printers that emulate ZPL

Many non-Zebra printers emulate ZPL. If a label prints correctly on a Zebra printer but not on an emulating one, check the following:

  • Size of the ^GFA data. The SDK sends ^GFA data uncompressed, so jobs with many graphic items can be large. Reducing the number of graphic items usually helps.
  • The Swiss 721 font. Swiss 721 maps to Zebra's resident font file TT0003M_, which may not exist on other brands.
  • Supported commands. Compare the output of GetNativePrinterCommands() against the list of commands your printer vendor says the emulation supports.

More information

ThermalLabel SDK for .NET
Product page & Quick Start

 Subscribe via RSS

← All posts