You send a logo to a TSC printer with BITMAP and get
a solid black rectangle, or a black block with your logo as a white
silhouette. The command is fine. The bits are upside down.
The cause: in TSPL a 0 bit is black
The TSC TSPL/TSPL2 programming manual's own BITMAP example
prints an arrow, and the rows that are all 00 bytes are the
arrow's solid black bar. So in TSPL a 0 bit prints a dot and a 1 bit
leaves the paper white. ZPL's ^GF and most image
libraries use the opposite convention: 1 is black. Data converted with a
ZPL habit, or taken straight from a 1-bit image library, therefore prints
as its own negative. A mostly white logo becomes a mostly black box.
Four ways to get it wrong
Inverted bits. The case above. Invert every byte
(b ^ 0xFF) before sending.
Width in dots instead of bytes. The third parameter
is the width in bytes: 8 dots per byte, rounded up. A 100-dot wide
image is 13 bytes, not 100. A wrong width shears the image into diagonal
stripes.
Padding bits set to 0. With 13 bytes for 100 dots, the
last 4 bits of every row are padding. In TSPL they must be 1, or a black
stripe appears along the right edge.
Hex text or line-ending conversion. The data after
the sixth parameter is raw binary, exactly width × height
bytes. Sending it as hex text, or through a channel that rewrites
0D/0A bytes (a text-mode file copy, some serial
drivers), shifts every following byte.
What the command looks like
SIZE 50 mm, 25 mm
GAP 3 mm, 0 mm
CLS
BITMAP 20,20,13,60,0,<780 raw bytes>
PRINT 1
Parameters: x, y, width in bytes, height in dots, mode, data. Mode
0 overwrites the area, 1 ORs the image onto what
is already drawn, 2 XORs it.
Check it before you print
The TSPL viewer draws BITMAP
with the manual's bit meaning, so an inverted image shows up as a black box
on screen too. For binary data, send the job file as raw bytes to the
render API (POST /v1/tspl/render); a text box cannot carry
arbitrary bytes. To skip the conversion entirely, upload the image to
image to ZPL, choose TSPL (BITMAP)
as the output language, and you get a ready binary job with the bits,
padding and byte width already right.
Our rendering follows the TSC manual; it has not been checked against
every TSC firmware. Print one label before a large batch.
Frequently asked questions
Why does my TSPL BITMAP print as a black square?
In TSPL a 0 bit prints a dot and a 1 bit stays white, the opposite of ZPL ^GF and most image libraries. Data prepared the ZPL way prints as its negative, so a mostly white logo becomes a mostly black box. Invert every byte before sending.
Is the BITMAP width in dots or bytes?
In bytes: 8 dots per byte, rounded up. A 100-dot wide image is 13 bytes wide, and the unused padding bits at the end of each row must be 1 (white) in TSPL.
