or run

tessl search

Version

Workspace: tessl
Visibility: Public
Created: about 8 hours ago
Last updated: about 8 hours ago

docs

examples

guides

reference

c-api.md encodings.md errors.md formats.md geometry.md gtin.md images.md reader-options.md reading.md results.md structured-append.md utilities.md writing.md

index.md

tile.json

tessl/github-zxing-cpp--zxing-cpp

tessl install tessl/github-zxing-cpp--zxing-cpp@2.3.0

Open-source, multi-format linear/matrix barcode image processing library implemented in C++

Barcode Writing

The ZXing-C++ writing API allows you to generate barcodes from text or binary data. This is an experimental API that requires the ZXING_EXPERIMENTAL_API compile flag.

Note: The writing API requires compiling with -DZXING_EXPERIMENTAL_API=ON.

Core Writing Functions

namespace ZXing {
    /**
     * Generate barcode from UTF-8 text
     *
     * @param contents  UTF-8 string to encode
     * @param options  CreatorOptions including format and parameters
     * @return Generated Barcode (check isValid() for success)
     */
    Barcode CreateBarcodeFromText(std::string_view contents, const CreatorOptions& options);

    /**
     * Generate barcode from raw binary data
     *
     * @param data  Pointer to byte array
     * @param size  Size of byte array
     * @param options  CreatorOptions including format and parameters
     * @return Generated Barcode (check isValid() for success)
     */
    Barcode CreateBarcodeFromBytes(const void* data, int size, const CreatorOptions& options);

    /**
     * Write barcode to SVG format
     *
     * @param barcode  Barcode to render
     * @param options  WriterOptions for rendering parameters
     * @return SVG string representation
     */
    std::string WriteBarcodeToSVG(const Barcode& barcode, const WriterOptions& options = {});

    /**
     * Write barcode to UTF-8 string using block characters
     *
     * @param barcode  Barcode to render
     * @param options  WriterOptions for rendering parameters
     * @return UTF-8 string with block graphics (e.g., '▀', '█')
     */
    std::string WriteBarcodeToUtf8(const Barcode& barcode, const WriterOptions& options = {});

    /**
     * Write barcode to bitmap image
     *
     * @param barcode  Barcode to render
     * @param options  WriterOptions for rendering parameters
     * @return Image object containing barcode bitmap
     */
    Image WriteBarcodeToImage(const Barcode& barcode, const WriterOptions& options = {});
}

CreatorOptions

class CreatorOptions {
public:
    /**
     * Constructor
     *
     * @param format  Barcode format to create
     */
    CreatorOptions(BarcodeFormat format);

    // Chainable property setters (return both lvalue and rvalue references)

    BarcodeFormat format() const noexcept;
    CreatorOptions& format(BarcodeFormat v) &;
    CreatorOptions&& format(BarcodeFormat v) &&;

    bool readerInit() const noexcept;
    CreatorOptions& readerInit(bool v) &;
    CreatorOptions&& readerInit(bool v) &&;

    bool forceSquareDataMatrix() const noexcept;
    CreatorOptions& forceSquareDataMatrix(bool v) &;
    CreatorOptions&& forceSquareDataMatrix(bool v) &&;

    std::string ecLevel() const noexcept;
    CreatorOptions& ecLevel(std::string v) &;
    CreatorOptions&& ecLevel(std::string v) &&;

    zint_symbol* zint() const;  // Access underlying zint symbol for advanced use
};

CreatorOptions Properties

format: Barcode format to generate (required)
readerInit: Set Reader Initialization flag (some formats)
forceSquareDataMatrix: Force square shape for Data Matrix (default: auto-select)
ecLevel: Error correction level (format-specific)
- QR Code: "L", "M", "Q", "H" (Low, Medium, Quality, High)
- Aztec: Percentage as string (e.g., "23")
- PDF417: 0-8 as string
- Micro QR: "L", "M", "Q"

WriterOptions

class WriterOptions {
public:
    WriterOptions();  // Default constructor

    // Chainable property setters (return both lvalue and rvalue references)

    int scale() const noexcept;
    WriterOptions& scale(int v) &;
    WriterOptions&& scale(int v) &&;

    int sizeHint() const noexcept;
    WriterOptions& sizeHint(int v) &;
    WriterOptions&& sizeHint(int v) &&;

    int rotate() const noexcept;
    WriterOptions& rotate(int v) &;
    WriterOptions&& rotate(int v) &&;

    bool withHRT() const noexcept;
    WriterOptions& withHRT(bool v) &;
    WriterOptions&& withHRT(bool v) &&;

    bool withQuietZones() const noexcept;
    WriterOptions& withQuietZones(bool v) &;
    WriterOptions&& withQuietZones(bool v) &&;
};

WriterOptions Properties

scale: Scale factor for rendering (default: 1)
sizeHint: Size hint for determining module size
rotate: Rotation angle in degrees (0, 90, 180, 270)
withHRT: Include Human Readable Text below barcode
withQuietZones: Include quiet zones (white space around barcode)

Usage Examples

Create QR Code

#include "ZXing/WriteBarcode.h"

// Create QR code with high error correction
ZXing::CreatorOptions options(ZXing::BarcodeFormat::QRCode);
options.ecLevel("H");  // High error correction (~30% damage recovery)

auto barcode = ZXing::CreateBarcodeFromText("https://example.com", options);

if (!barcode.isValid()) {
    std::cerr << "Failed to create barcode: " << barcode.error().msg() << "\n";
    return;
}

// Render to SVG
auto svg = ZXing::WriteBarcodeToSVG(barcode);
std::cout << svg << "\n";

Create Data Matrix

ZXing::CreatorOptions options(ZXing::BarcodeFormat::DataMatrix);

auto barcode = ZXing::CreateBarcodeFromText("12345", options);

// Render to image with scaling
ZXing::WriterOptions writerOpts;
writerOpts.scale(5).withQuietZones(true);

auto image = ZXing::WriteBarcodeToImage(barcode, writerOpts);

// Access image data
const uint8_t* data = image.data();
int width = image.width();
int height = image.height();

Create Barcode from Binary Data

std::vector<uint8_t> binaryData = {0x00, 0x01, 0x02, 0xFF};

ZXing::CreatorOptions options(ZXing::BarcodeFormat::DataMatrix);

auto barcode = ZXing::CreateBarcodeFromBytes(
    binaryData.data(),
    binaryData.size(),
    options
);

auto image = ZXing::WriteBarcodeToImage(barcode);

Create EAN-13

// EAN-13 requires 12 digits (13th is check digit, computed automatically)
ZXing::CreatorOptions options(ZXing::BarcodeFormat::EAN13);

auto barcode = ZXing::CreateBarcodeFromText("123456789012", options);

// Render with Human Readable Text
ZXing::WriterOptions writerOpts;
writerOpts.withHRT(true).scale(3);

auto svg = ZXing::WriteBarcodeToSVG(barcode, writerOpts);

Create Code 128

ZXing::CreatorOptions options(ZXing::BarcodeFormat::Code128);

auto barcode = ZXing::CreateBarcodeFromText("ABC123", options);

ZXing::WriterOptions writerOpts;
writerOpts.withHRT(true).withQuietZones(true).scale(2);

auto image = ZXing::WriteBarcodeToImage(barcode, writerOpts);

Create PDF417

ZXing::CreatorOptions options(ZXing::BarcodeFormat::PDF417);
options.ecLevel("5");  // Error correction level 0-8

auto barcode = ZXing::CreateBarcodeFromText("Large amount of data here...", options);

auto svg = ZXing::WriteBarcodeToSVG(barcode);

Create Aztec Code

ZXing::CreatorOptions options(ZXing::BarcodeFormat::Aztec);
options.ecLevel("23");  // 23% error correction

auto barcode = ZXing::CreateBarcodeFromText("Aztec data", options);

ZXing::WriterOptions writerOpts;
writerOpts.scale(4);

auto image = ZXing::WriteBarcodeToImage(barcode, writerOpts);

Render to Terminal (UTF-8 Block Characters)

ZXing::CreatorOptions options(ZXing::BarcodeFormat::QRCode);
auto barcode = ZXing::CreateBarcodeFromText("Hello", options);

// Render using UTF-8 block characters
auto utf8 = ZXing::WriteBarcodeToUtf8(barcode);
std::cout << utf8 << "\n";

// Output will use characters like: ▀ ▄ █ to draw barcode in terminal

Method Chaining

// Options support method chaining
auto barcode = ZXing::CreateBarcodeFromText(
    "Data",
    ZXing::CreatorOptions(ZXing::BarcodeFormat::QRCode)
        .ecLevel("H")
        .readerInit(false)
);

auto svg = ZXing::WriteBarcodeToSVG(
    barcode,
    ZXing::WriterOptions()
        .scale(5)
        .withQuietZones(true)
        .rotate(90)
);

Rotated Output

ZXing::CreatorOptions options(ZXing::BarcodeFormat::QRCode);
auto barcode = ZXing::CreateBarcodeFromText("Rotated", options);

// Render rotated 90 degrees
ZXing::WriterOptions writerOpts;
writerOpts.rotate(90).scale(3);

auto image = ZXing::WriteBarcodeToImage(barcode, writerOpts);

Square vs. Rectangular Data Matrix

// Default: auto-select shape
ZXing::CreatorOptions auto_options(ZXing::BarcodeFormat::DataMatrix);
auto auto_barcode = ZXing::CreateBarcodeFromText("Auto", auto_options);

// Force square
ZXing::CreatorOptions square_options(ZXing::BarcodeFormat::DataMatrix);
square_options.forceSquareDataMatrix(true);
auto square_barcode = ZXing::CreateBarcodeFromText("Square", square_options);

C++20 Overloads

C++20 provides additional convenience overloads:

// UTF-8 string_view overload
std::u8string_view u8text = u8"Unicode text";
auto barcode = ZXing::CreateBarcodeFromText(u8text, options);

// Range-based CreateBarcodeFromBytes
std::vector<uint8_t> data = {0, 1, 2, 3};
auto barcode = ZXing::CreateBarcodeFromBytes(data, options);  // Deduces size

std::array<uint8_t, 4> arr = {4, 5, 6, 7};
auto barcode2 = ZXing::CreateBarcodeFromBytes(arr, options);

Supported Formats for Writing

Not all formats support writing. Here are the writing capabilities:

Fully Supported for Writing

QR Code (all versions)
Data Matrix
Aztec
PDF417
Code 39
Code 93
Code 128
Codabar
ITF
EAN-8, EAN-13
UPC-A, UPC-E

Limited or No Support

Micro QR Code - Experimental
rMQR Code - Experimental (with ZXING_WRITERS=NEW)
MaxiCode - Experimental (with ZXING_WRITERS=NEW)
DataBar variants - Experimental (with ZXING_WRITERS=NEW)
DX Film Edge - Not supported

Check support at runtime:

auto supported = ZXing::SupportedBarcodeFormats(ZXing::Operation::Create);
bool canWrite = supported.testFlag(ZXing::BarcodeFormat::QRCode);

Error Correction Levels

QR Code Error Correction

L (Low): ~7% recovery
M (Medium): ~15% recovery
Q (Quality): ~25% recovery
H (High): ~30% recovery

ZXing::CreatorOptions options(ZXing::BarcodeFormat::QRCode);
options.ecLevel("H");  // Maximum error correction

Aztec Error Correction

Specify as percentage (5-95):

ZXing::CreatorOptions options(ZXing::BarcodeFormat::Aztec);
options.ecLevel("23");  // 23% error correction

PDF417 Error Correction

Levels 0-8, where higher is more redundancy:

ZXing::CreatorOptions options(ZXing::BarcodeFormat::PDF417);
options.ecLevel("5");  // Medium error correction

Image Output Format

WriteBarcodeToImage() returns an Image object:

auto image = ZXing::WriteBarcodeToImage(barcode);

// Image properties
int width = image.width();
int height = image.height();
auto format = image.format();  // ImageFormat::Lum (grayscale)

// Access pixel data
const uint8_t* data = image.data();

// data[y * width + x] is pixel at (x, y)
// 0 = black, 255 = white

SVG Output Format

WriteBarcodeToSVG() returns a complete SVG document as a string:

auto svg = ZXing::WriteBarcodeToSVG(barcode, writerOpts);

// svg contains complete SVG markup:
// <?xml version="1.0" encoding="UTF-8"?>
// <svg xmlns="http://www.w3.org/2000/svg" width="..." height="...">
//   <rect x="..." y="..." width="..." height="..." fill="black"/>
//   ...
// </svg>

// Save to file
std::ofstream file("barcode.svg");
file << svg;

UTF-8 Block Character Output

WriteBarcodeToUtf8() renders the barcode using Unicode block drawing characters:

auto utf8 = ZXing::WriteBarcodeToUtf8(barcode);

// Example output:
// ████████████      ██  ████████████
// ██      ████  ██  ████      ██
// ██  ██████      ████  ██████  ██
// ...

std::cout << utf8;  // Display in terminal

This is useful for:

Terminal/console display
Quick visualization
Text-based interfaces

Performance Considerations

Barcode generation is generally fast (< 1ms for QR codes)
Complex formats (PDF417, large QR codes) may take longer
SVG rendering is faster than bitmap rendering
Scaling affects bitmap rendering time but not generation time

Thread Safety

All writing functions are thread-safe. You can generate barcodes from multiple threads simultaneously.

// Safe to use from multiple threads
#pragma omp parallel for
for (int i = 0; i < numBarcodes; ++i) {
    auto barcode = ZXing::CreateBarcodeFromText(texts[i], options);
    images[i] = ZXing::WriteBarcodeToImage(barcode);
}

Advanced: Direct Zint Access

For advanced control, access the underlying zint symbol:

ZXing::CreatorOptions options(ZXing::BarcodeFormat::QRCode);
zint_symbol* sym = options.zint();

// Modify zint properties directly if needed
// (requires knowledge of libzint API)

Barcode Results - Barcode object details
Barcode Formats - Supported formats
Image Handling - Image and ImageView types
Error Handling - Error reporting

Version

tessl/github-zxing-cpp--zxing-cpp

writing.mddocs/reference/

Barcode Writing

Core Writing Functions

CreatorOptions

CreatorOptions Properties

WriterOptions

WriterOptions Properties

Usage Examples

Create QR Code

Create Data Matrix

Create Barcode from Binary Data

Create EAN-13

Create Code 128

Create PDF417

Create Aztec Code

Render to Terminal (UTF-8 Block Characters)

Method Chaining

Rotated Output

Square vs. Rectangular Data Matrix

C++20 Overloads

Supported Formats for Writing

Fully Supported for Writing

Limited or No Support

Error Correction Levels

QR Code Error Correction

Aztec Error Correction

PDF417 Error Correction

Image Output Format

SVG Output Format

UTF-8 Block Character Output

Performance Considerations

Thread Safety

Advanced: Direct Zint Access

Related

Version

tessl/github-zxing-cpp--zxing-cpp

writing.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/reference/

Barcode Writing

Core Writing Functions

CreatorOptions

CreatorOptions Properties

WriterOptions

WriterOptions Properties

Usage Examples

Create QR Code

Create Data Matrix

Create Barcode from Binary Data

Create EAN-13

Create Code 128

Create PDF417

Create Aztec Code

Render to Terminal (UTF-8 Block Characters)

Method Chaining

Rotated Output

Square vs. Rectangular Data Matrix

C++20 Overloads

Supported Formats for Writing

Fully Supported for Writing

Limited or No Support

Error Correction Levels

QR Code Error Correction

Aztec Error Correction

PDF417 Error Correction

Image Output Format

SVG Output Format

UTF-8 Block Character Output

Performance Considerations

Thread Safety

Advanced: Direct Zint Access

Related

writing.mddocs/reference/