0
# Experimental Barcode Writing
1

2
ZXing-C++ provides advanced barcode generation capabilities through the experimental API (enabled with `ZXING_EXPERIMENTAL_API`). This modern API offers extended format support, multiple output formats, and more sophisticated configuration options compared to the legacy writer.
3

4
**Note**: This API requires compilation with `ZXING_EXPERIMENTAL_API` defined and may change in future versions.
5

6
## Core Classes
7

8
### CreatorOptions Class
9

10
The `CreatorOptions` class provides comprehensive barcode creation configuration:
11

12
```cpp { .api }
13
class CreatorOptions {
14
    CreatorOptions(BarcodeFormat format);
15
    ~CreatorOptions();
16
    CreatorOptions(CreatorOptions&&);
17
    CreatorOptions& operator=(CreatorOptions&&);
18
    
19
    // Configuration methods (fluent interface)
20
    BarcodeFormat format() const noexcept;
21
    CreatorOptions& format(BarcodeFormat f);
22
    
23
    bool readerInit() const noexcept;
24
    CreatorOptions& readerInit(bool v);
25
    
26
    bool forceSquareDataMatrix() const noexcept;
27
    CreatorOptions& forceSquareDataMatrix(bool v);
28
    
29
    std::string ecLevel() const noexcept;
30
    CreatorOptions& ecLevel(std::string level);
31
};
32
```
33

34
### WriterOptions Class
35

36
The `WriterOptions` class controls output rendering:
37

38
```cpp { .api }
39
class WriterOptions {
40
    WriterOptions();
41
    ~WriterOptions();
42
    WriterOptions(WriterOptions&&);
43
    WriterOptions& operator=(WriterOptions&&);
44
    
45
    // Rendering configuration
46
    int scale() const noexcept;
47
    WriterOptions& scale(int v);
48
    
49
    int sizeHint() const noexcept;
50
    WriterOptions& sizeHint(int v);
51
    
52
    int rotate() const noexcept;
53
    WriterOptions& rotate(int v);
54
    
55
    bool withHRT() const noexcept;
56
    WriterOptions& withHRT(bool v);
57
    
58
    bool withQuietZones() const noexcept;
59
    WriterOptions& withQuietZones(bool v);
60
};
61
```
62

63
## Creation Functions
64

65
### Text-Based Creation
66

67
```cpp { .api }
68
Barcode CreateBarcodeFromText(std::string_view contents, const CreatorOptions& options);
69

70
#if __cplusplus > 201703L
71
Barcode CreateBarcodeFromText(std::u8string_view contents, const CreatorOptions& options);
72
#endif
73
```
74

75
### Binary Data Creation
76

77
```cpp { .api }
78
Barcode CreateBarcodeFromBytes(const void* data, int size, const CreatorOptions& options);
79

80
// Template version for containers (C++17/20)
81
template<typename R>
82
Barcode CreateBarcodeFromBytes(const R& contents, const CreatorOptions& options);
83
```
84

85
## Output Functions
86

87
### SVG Output
88

89
```cpp { .api }
90
std::string WriteBarcodeToSVG(const Barcode& barcode, const WriterOptions& options = {});
91
```
92

93
### UTF-8 Text Output
94

95
```cpp { .api }
96
std::string WriteBarcodeToUtf8(const Barcode& barcode, const WriterOptions& options = {});
97
```
98

99
### Bitmap Image Output
100

101
```cpp { .api }
102
Image WriteBarcodeToImage(const Barcode& barcode, const WriterOptions& options = {});
103
```
104

105
## Basic Usage
106

107
### Simple Barcode Creation
108

109
```cpp
110
#ifdef ZXING_EXPERIMENTAL_API
111
#include "ZXing/WriteBarcode.h"
112

113
// Create QR Code
114
auto options = ZXing::CreatorOptions(ZXing::BarcodeFormat::QRCode)
115
    .ecLevel("M");
116

117
auto barcode = ZXing::CreateBarcodeFromText("Hello, World!", options);
118

119
if (barcode.isValid()) {
120
    std::cout << "Created barcode: " << barcode.text() << std::endl;
121
    
122
    // Generate SVG
123
    auto svg = ZXing::WriteBarcodeToSVG(barcode);
124
    std::cout << "SVG length: " << svg.length() << std::endl;
125
}
126
#endif
127
```
128

129
### Multiple Output Formats
130

131
```cpp
132
// Create barcode once, output in multiple formats
133
auto creatorOptions = ZXing::CreatorOptions(ZXing::BarcodeFormat::QRCode)
134
    .ecLevel("H")
135
    .readerInit(false);
136

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

139
if (barcode.isValid()) {
140
    // SVG for web use
141
    auto svg = ZXing::WriteBarcodeToSVG(barcode);
142
    
143
    // UTF-8 text for console output
144
    auto textOutput = ZXing::WriteBarcodeToUtf8(barcode);
145
    std::cout << textOutput << std::endl;
146
    
147
    // Bitmap for image processing
148
    auto writerOptions = ZXing::WriterOptions()
149
        .scale(4)
150
        .withQuietZones(true);
151
    auto image = ZXing::WriteBarcodeToImage(barcode, writerOptions);
152
}
153
```
154

155
## Advanced Creation Options
156

157
### QR Code Creation
158

159
```cpp
160
// QR Code with various error correction levels
161
auto qrLowEC = ZXing::CreatorOptions(ZXing::BarcodeFormat::QRCode)
162
    .ecLevel("L");  // ~7% error correction
163

164
auto qrMediumEC = ZXing::CreatorOptions(ZXing::BarcodeFormat::QRCode)
165
    .ecLevel("M");  // ~15% error correction (default)
166

167
auto qrQuartileEC = ZXing::CreatorOptions(ZXing::BarcodeFormat::QRCode)
168
    .ecLevel("Q");  // ~25% error correction
169

170
auto qrHighEC = ZXing::CreatorOptions(ZXing::BarcodeFormat::QRCode)
171
    .ecLevel("H");  // ~30% error correction
172

173
// Create high-reliability QR code
174
auto reliableQR = ZXing::CreateBarcodeFromText("Critical Data", qrHighEC);
175

176
// QR Code with reader initialization
177
auto readerInitQR = ZXing::CreatorOptions(ZXing::BarcodeFormat::QRCode)
178
    .ecLevel("M")
179
    .readerInit(true);  // Indicates reader programming symbol
180

181
auto programQR = ZXing::CreateBarcodeFromText("READER PROGRAM", readerInitQR);
182
```
183

184
### DataMatrix Creation
185

186
```cpp
187
// Standard DataMatrix
188
auto dmOptions = ZXing::CreatorOptions(ZXing::BarcodeFormat::DataMatrix);
189
auto dataMatrix = ZXing::CreateBarcodeFromText("DM12345", dmOptions);
190

191
// Force square DataMatrix (instead of rectangular)
192
auto squareDMOptions = ZXing::CreatorOptions(ZXing::BarcodeFormat::DataMatrix)
193
    .forceSquareDataMatrix(true);
194
auto squareDataMatrix = ZXing::CreateBarcodeFromText("SQUARE", squareDMOptions);
195
```
196

197
### Binary Data Encoding
198

199
```cpp
200
// Encode binary data
201
std::vector<uint8_t> binaryData = {0x01, 0x02, 0x03, 0xFF, 0xFE, 0xFD};
202
auto binaryOptions = ZXing::CreatorOptions(ZXing::BarcodeFormat::DataMatrix);
203

204
auto binaryBarcode = ZXing::CreateBarcodeFromBytes(binaryData.data(), binaryData.size(), binaryOptions);
205

206
// Using container template (C++17/20)
207
auto containerBarcode = ZXing::CreateBarcodeFromBytes(binaryData, binaryOptions);
208

209
// Encode string as binary
210
std::string data = "Binary Content";
211
auto stringBarcode = ZXing::CreateBarcodeFromBytes(data, binaryOptions);
212
```
213

214
### Extended Format Support
215

216
```cpp
217
// Formats available in experimental API that may not be in legacy
218
auto aztecOptions = ZXing::CreatorOptions(ZXing::BarcodeFormat::Aztec)
219
    .ecLevel("23");  // Error correction percentage
220

221
auto aztecCode = ZXing::CreateBarcodeFromText("Aztec Data", aztecOptions);
222

223
auto pdf417Options = ZXing::CreatorOptions(ZXing::BarcodeFormat::PDF417)
224
    .ecLevel("2");   // Error correction level
225

226
auto pdf417Code = ZXing::CreateBarcodeFromText("PDF417 Content", pdf417Options);
227
```
228

229
## Output Customization
230

231
### SVG Generation
232

233
```cpp
234
auto barcode = ZXing::CreateBarcodeFromText("SVG Test", 
235
    ZXing::CreatorOptions(ZXing::BarcodeFormat::QRCode));
236

237
// Basic SVG
238
auto basicSVG = ZXing::WriteBarcodeToSVG(barcode);
239

240
// Customized SVG output
241
auto writerOptions = ZXing::WriterOptions()
242
    .scale(6)           // Larger scale
243
    .withQuietZones(true)  // Include quiet zones
244
    .rotate(0);         // No rotation
245

246
auto customSVG = ZXing::WriteBarcodeToSVG(barcode, writerOptions);
247

248
// Save SVG to file
249
std::ofstream svgFile("barcode.svg");
250
svgFile << customSVG;
251
svgFile.close();
252
```
253

254
### UTF-8 Text Output
255

256
```cpp
257
auto barcode = ZXing::CreateBarcodeFromText("Text Output", 
258
    ZXing::CreatorOptions(ZXing::BarcodeFormat::QRCode));
259

260
// Console-friendly text representation
261
auto textOptions = ZXing::WriterOptions()
262
    .scale(1)           // Minimal scale for console
263
    .withQuietZones(false); // No extra spacing
264

265
auto textBarcode = ZXing::WriteBarcodeToUtf8(barcode, textOptions);
266
std::cout << textBarcode << std::endl;
267

268
// Larger text representation
269
auto largeTextOptions = ZXing::WriterOptions()
270
    .scale(2)
271
    .withQuietZones(true);
272

273
auto largeTextBarcode = ZXing::WriteBarcodeToUtf8(barcode, largeTextOptions);
274
std::cout << largeTextBarcode << std::endl;
275
```
276

277
### Bitmap Image Generation
278

279
```cpp
280
auto barcode = ZXing::CreateBarcodeFromText("Image Output", 
281
    ZXing::CreatorOptions(ZXing::BarcodeFormat::DataMatrix));
282

283
// Generate bitmap with options
284
auto imageOptions = ZXing::WriterOptions()
285
    .scale(8)           // 8x scale for high resolution
286
    .withHRT(false)     // No human-readable text
287
    .withQuietZones(true)
288
    .rotate(0);
289

290
auto image = ZXing::WriteBarcodeToImage(barcode, imageOptions);
291

292
// Access image properties
293
std::cout << "Image size: " << image.width() << "x" << image.height() << std::endl;
294
std::cout << "Format: " << static_cast<int>(image.format()) << std::endl;
295

296
// Access raw pixel data
297
const uint8_t* pixelData = image.data();
298
// Process pixel data as needed...
299
```
300

301
### Rotated Output
302

303
```cpp
304
auto barcode = ZXing::CreateBarcodeFromText("Rotated", 
305
    ZXing::CreatorOptions(ZXing::BarcodeFormat::Code128));
306

307
// Generate rotated versions
308
std::vector<int> rotations = {0, 90, 180, 270};
309

310
for (int rotation : rotations) {
311
    auto rotatedOptions = ZXing::WriterOptions()
312
        .rotate(rotation)
313
        .scale(4);
314
    
315
    auto rotatedSVG = ZXing::WriteBarcodeToSVG(barcode, rotatedOptions);
316
    
317
    std::string filename = "barcode_" + std::to_string(rotation) + ".svg";
318
    std::ofstream file(filename);
319
    file << rotatedSVG;
320
}
321
```
322

323
## Human Readable Text (HRT)
324

325
```cpp
326
// Enable human-readable text below barcode (where supported)
327
auto barcode = ZXing::CreateBarcodeFromText("123456789", 
328
    ZXing::CreatorOptions(ZXing::BarcodeFormat::Code128));
329

330
auto hrtOptions = ZXing::WriterOptions()
331
    .withHRT(true)      // Include human-readable text
332
    .scale(4)
333
    .withQuietZones(true);
334

335
// Generate with HRT
336
auto svgWithHRT = ZXing::WriteBarcodeToSVG(barcode, hrtOptions);
337
auto imageWithHRT = ZXing::WriteBarcodeToImage(barcode, hrtOptions);
338
```
339

340
## Error Handling
341

342
### Creation Errors
343

344
```cpp
345
try {
346
    // This might fail for invalid content
347
    auto options = ZXing::CreatorOptions(ZXing::BarcodeFormat::EAN13);
348
    auto barcode = ZXing::CreateBarcodeFromText("invalid", options);
349
    
350
    if (!barcode.isValid()) {
351
        std::cout << "Creation failed: " << barcode.error().msg() << std::endl;
352
    }
353
} catch (const std::exception& e) {
354
    std::cout << "Exception during creation: " << e.what() << std::endl;
355
}
356
```
357

358
### Output Errors
359

360
```cpp
361
auto barcode = ZXing::CreateBarcodeFromText("Test", 
362
    ZXing::CreatorOptions(ZXing::BarcodeFormat::QRCode));
363

364
if (barcode.isValid()) {
365
    try {
366
        // This should succeed for valid barcodes
367
        auto svg = ZXing::WriteBarcodeToSVG(barcode);
368
        auto image = ZXing::WriteBarcodeToImage(barcode);
369
    } catch (const std::exception& e) {
370
        std::cout << "Output generation failed: " << e.what() << std::endl;
371
    }
372
}
373
```
374

375
## Integration Examples
376

377
### Web Service Integration
378

379
```cpp
380
#include <httplib.h>  // Example HTTP library
381

382
class BarcodeService {
383
public:
384
    std::string generateQRCodeSVG(const std::string& content, 
385
                                 const std::string& errorLevel = "M") {
386
        auto options = ZXing::CreatorOptions(ZXing::BarcodeFormat::QRCode)
387
            .ecLevel(errorLevel);
388
        
389
        auto barcode = ZXing::CreateBarcodeFromText(content, options);
390
        
391
        if (!barcode.isValid()) {
392
            throw std::runtime_error("Failed to create barcode: " + barcode.error().msg());
393
        }
394
        
395
        auto writerOptions = ZXing::WriterOptions()
396
            .scale(4)
397
            .withQuietZones(true);
398
        
399
        return ZXing::WriteBarcodeToSVG(barcode, writerOptions);
400
    }
401
};
402

403
// HTTP server endpoint
404
httplib::Server server;
405
BarcodeService service;
406

407
server.Get("/qr", [&](const httplib::Request& req, httplib::Response& res) {
408
    std::string content = req.get_param_value("content");
409
    std::string ecLevel = req.get_param_value("ec", "M");
410
    
411
    try {
412
        std::string svg = service.generateQRCodeSVG(content, ecLevel);
413
        res.set_content(svg, "image/svg+xml");
414
    } catch (const std::exception& e) {
415
        res.status = 400;
416
        res.set_content("Error: " + std::string(e.what()), "text/plain");
417
    }
418
});
419
```
420

421
### File Processing Pipeline
422

423
```cpp
424
class BarcodeProcessor {
425
public:
426
    struct ProcessingOptions {
427
        ZXing::BarcodeFormat format = ZXing::BarcodeFormat::QRCode;
428
        std::string ecLevel = "M";
429
        int scale = 4;
430
        bool includeHRT = false;
431
        int rotation = 0;
432
    };
433
    
434
    void processBatch(const std::vector<std::string>& contents,
435
                     const std::string& outputDir,
436
                     const ProcessingOptions& opts = {}) {
437
        
438
        auto creatorOptions = ZXing::CreatorOptions(opts.format)
439
            .ecLevel(opts.ecLevel);
440
        
441
        auto writerOptions = ZXing::WriterOptions()
442
            .scale(opts.scale)
443
            .withHRT(opts.includeHRT)
444
            .rotate(opts.rotation)
445
            .withQuietZones(true);
446
        
447
        for (size_t i = 0; i < contents.size(); ++i) {
448
            auto barcode = ZXing::CreateBarcodeFromText(contents[i], creatorOptions);
449
            
450
            if (barcode.isValid()) {
451
                // Generate multiple formats
452
                auto svg = ZXing::WriteBarcodeToSVG(barcode, writerOptions);
453
                auto image = ZXing::WriteBarcodeToImage(barcode, writerOptions);
454
                
455
                // Save files
456
                std::string baseName = outputDir + "/barcode_" + std::to_string(i);
457
                
458
                std::ofstream svgFile(baseName + ".svg");
459
                svgFile << svg;
460
                
461
                // Save bitmap (assuming you have image saving capability)
462
                saveBitmapAsPNG(image, baseName + ".png");
463
            }
464
        }
465
    }
466
};
467
```
468

469
### Advanced Content Processing
470

471
```cpp
472
// Handle different content types
473
class ContentProcessor {
474
public:
475
    ZXing::Barcode createFromURL(const std::string& url) {
476
        auto options = ZXing::CreatorOptions(ZXing::BarcodeFormat::QRCode)
477
            .ecLevel("M");
478
        return ZXing::CreateBarcodeFromText(url, options);
479
    }
480
    
481
    ZXing::Barcode createFromVCard(const std::map<std::string, std::string>& contact) {
482
        std::string vcard = "BEGIN:VCARD\nVERSION:3.0\n";
483
        
484
        for (const auto& field : contact) {
485
            vcard += field.first + ":" + field.second + "\n";
486
        }
487
        vcard += "END:VCARD";
488
        
489
        auto options = ZXing::CreatorOptions(ZXing::BarcodeFormat::QRCode)
490
            .ecLevel("M");
491
        return ZXing::CreateBarcodeFromText(vcard, options);
492
    }
493
    
494
    ZXing::Barcode createFromJSON(const std::string& json) {
495
        auto options = ZXing::CreatorOptions(ZXing::BarcodeFormat::DataMatrix);
496
        return ZXing::CreateBarcodeFromText(json, options);
497
    }
498
};
499
```
500

501
## Performance Considerations
502

503
### Batch Processing Optimization
504

505
```cpp
506
// Reuse CreatorOptions for better performance
507
class OptimizedBarcodeGenerator {
508
private:
509
    std::map<ZXing::BarcodeFormat, ZXing::CreatorOptions> creatorCache_;
510
    std::map<std::string, ZXing::WriterOptions> writerCache_;
511
    
512
public:
513
    OptimizedBarcodeGenerator() {
514
        // Pre-configure common options
515
        creatorCache_[ZXing::BarcodeFormat::QRCode] = 
516
            ZXing::CreatorOptions(ZXing::BarcodeFormat::QRCode).ecLevel("M");
517
        creatorCache_[ZXing::BarcodeFormat::DataMatrix] = 
518
            ZXing::CreatorOptions(ZXing::BarcodeFormat::DataMatrix);
519
        
520
        writerCache_["web"] = ZXing::WriterOptions().scale(4).withQuietZones(true);
521
        writerCache_["print"] = ZXing::WriterOptions().scale(8).withHRT(true);
522
    }
523
    
524
    std::string generateSVG(const std::string& content, 
525
                           ZXing::BarcodeFormat format,
526
                           const std::string& profile = "web") {
527
        auto barcode = ZXing::CreateBarcodeFromText(content, creatorCache_[format]);
528
        return ZXing::WriteBarcodeToSVG(barcode, writerCache_[profile]);
529
    }
530
};
531
```