Items Caching

ThermalLabel SDK generates native printer commands which are sent to the printer through a PrintJob object. Some items, like a company logo, can produce a lot of data (an image is sent as a bitmap), and sending it again and again for every label slows the job down. To improve printing performance, ThermalLabel SDK provides a caching mechanism that you enable on each Item of a ThermalLabel.

When you activate caching on an item:

  1. The item is rendered once to a monochrome bitmap and that bitmap is downloaded to the printer's memory (RAM), identified by an ID.
  2. For every label of the job, the item only sends a short command that recalls the stored bitmap by its ID, instead of its full content.
  3. When the job finishes, the SDK appends the commands that delete the cached items from the printer's memory.

The mechanism is automatic: you only set two properties, and the PrintJob takes care of downloading, recalling and cleaning up.

Note: this topic is about the printer-side cache used when generating native printer commands. It is not related to the SDK's internal render cache used when exporting to image/PDF (see Don't confuse it with...).

When does it pay off?

Caching is worth it when the same item is printed on many labels in one job (for example, a data-bound job with a DataSource, Counters or a Mask, or Copies > 1) and the item is expensive to send, mainly images and graphic-heavy items. For a single label with a single copy, caching doesn't save anything: the item is downloaded and recalled once.

Which items can be cached?

An item is eligible when its content/output does not change while the print job is processed. In other words, you can cache all those items that are "static". For instance, a company logo, industry symbols, or texts and legends that display fixed content are good candidates.

An item will be cached only if all these conditions are met:

Condition Why
UseCache = True Caching is opt-in.
DataField is empty A data-bound item changes on every record, so it can't be cached. If you set UseCache = True on a bound item it is silently ignored.
Visible = True Hidden items are not printed.

Also keep in mind:

  • Fixed content only. The cached bitmap is generated once at the start of the job. If the item's text, code or image changes later (for example through an Expression that depends on record data or on counters), the printer will keep printing the old bitmap.
  • Cached items are always graphics. Because the item is stored as a bitmap, items that normally generate native commands (barcodes, lines, rectangles, ellipses, text with printer fonts) are sent as graphics when UseCache is True. Output looks the same as with PrintAsGraphic, but you lose the benefits of native output (printer-generated barcode quality, smaller commands for simple shapes, etc.). For a simple text or a single barcode that is printed once, native commands are usually faster than a download.
  • The best candidates are therefore ImageItem (logos, icons), and complex static graphics such as big tables or QR/2D barcodes that never change. See Image Item, Shape Items and Barcode Item.
  • RepeaterItem is a layout helper that is expanded before the label is rendered, so mark the items it repeats, not the repeater itself. See Repeater Item.

Supported printer languages

ZPL, EPL, and Fingerprint / Direct Protocol. Other languages (ESC/POS, PCL) don't use the printer-side item cache.

How to enable items caching?

After you identify which items in the thermal label are eligible, enable caching by setting the UseCache property to True on the item. To identify the item in the printer's memory you can specify a unique ID with the CacheItemId property.

The ID must be 1 to 8 alphanumeric characters (A-Z, 0-9) long and unique for each item. If you don't specify one, a random 8-character ID is assigned automatically at runtime.

Tip: use uppercase letters and digits only. Don't use a drive prefix or an extension (R:LOGO.GRF): the SDK adds them for you.

VB.NET

Dim tl As New ThermalLabel(UnitType.Inch, 4, 3)

'A static company logo: a great candidate for caching
Dim logo As New ImageItem()
logo.SourceFile = "C:\images\logo.png"
logo.X = 0.1
logo.Y = 0.1
logo.Width = 1.5
logo.Height = 0.8
logo.UseCache = True
logo.CacheItemId = "LOGO"      'optional, a random ID is used if omitted

'A dynamic item: it must NOT be cached
Dim name As New TextItem(0.1, 1.2, 3.8, 0.4, "")
name.DataField = "CustomerName"

tl.Items.Add(logo)
tl.Items.Add(name)

'Data source: one label per row
Dim customers As New DataTable()
customers.Columns.Add("CustomerName")
For i As Integer = 1 To 100
    customers.Rows.Add("Customer " & i)
Next
tl.DataSource = customers

Using pj As New PrintJob()
    pj.ProgrammingLanguage = ProgrammingLanguage.ZPL
    pj.ThermalLabel = tl
    Dim commands As String = pj.GetNativePrinterCommands()
End Using

C#

var tl = new ThermalLabel(UnitType.Inch, 4, 3);

// A static company logo: a great candidate for caching
var logo = new ImageItem
{
    SourceFile = @"C:\images\logo.png",
    X = 0.1, Y = 0.1, Width = 1.5, Height = 0.8,
    UseCache = true,
    CacheItemId = "LOGO"   // optional, a random ID is used if omitted
};

// A dynamic item: it must NOT be cached
var name = new TextItem(0.1, 1.2, 3.8, 0.4, "") { DataField = "CustomerName" };

tl.Items.Add(logo);
tl.Items.Add(name);

// Data source: one label per row
var customers = new DataTable();
customers.Columns.Add("CustomerName");
for (int i = 1; i <= 100; i++)
    customers.Rows.Add("Customer " + i);
tl.DataSource = customers;

using (var pj = new PrintJob())
{
    pj.ProgrammingLanguage = ProgrammingLanguage.ZPL;
    pj.ThermalLabel = tl;
    string commands = pj.GetNativePrinterCommands();
}

How the cache lives in the printer

  • The cache is created per PrintJob print/generate call and is removed at the end of that call. It is not persistent across jobs, and a power cycle clears the printer RAM anyway.
  • If the job is canceled (PrintJobCanceledException), the SDK still appends the cleanup commands to the partial commands.
  • Items are downloaded before the first label, so the printer needs enough free RAM for all cached bitmaps. Cache only what is worth it.
  • Because the bitmap is monochrome and rendered at the job's DPI, set PrintJob.Dpi to your printer's real resolution so the cached image is not scaled.
  • Print orientation (PrintOrientation) is taken into account: the SDK keeps the cached item's width and height to relocate it when the label is rotated.

Common mistakes

  • Caching a data-bound item. UseCache is ignored when DataField is set. Cache only fixed content.
  • Duplicated CacheItemId. Two items with the same ID overwrite each other in the printer, so both labels would show the same bitmap. Use unique IDs, or leave it empty and let the SDK generate them.
  • Invalid IDs. More than 8 characters, or symbols/spaces. Stick to A-Z and 0-9.
  • Caching everything. A cached text or barcode becomes a bitmap. Cache images and complex static graphics, not every item.
  • Expecting changes to be reflected. Editing a cached item's content after the job started has no effect on already-downloaded bitmaps.

Don't confuse it with the render cache

When you export labels to image or PDF (not native printer commands) the SDK has an independent, internal render cache that reuses the already-rendered result of an item when it produces the same content again across data-bound records. It is controlled by PrintJob.RenderCacheEnabled (default True), is kept in memory only for that export call, and requires no configuration. UseCache and CacheItemId have no effect on it.