New Writer/Generator/Creator API

[axxel]

Given that the "discussion" in #332 is lengthy and mostly outdated and also not in form of a github discussion, I summarize my current state of mind here:

• the c++ implementations of the barcode writers in this repo will (in the long run) be completely removed and replaced by libzint.
• the Barcode class will be the central point of both reading and generating barcodes and can also be written/rendered into an image/svg.
• there will be consistent C++ API for both reading and generating barcodes that (almost) completely hides the fact that the zint c-library is used behind the scenes.
• there will be a C-API that closely maps to the C++-API for both applications, completely independent of the existing zint API.
• there will be wrappers, partly based on that C-API, that model the C++-API more or less, depending on what feels 'native' in the respective language. Every wrapper should feel as if the library was written in that language natively.
• the C++ "wrapper" around zint will not strive to expose all bells and whistles / features of the zint library, e.g. only the symbologies currently known to zxing-cpp will be exposed; the segmented ECI block feature will likely not be (maybe later if there is demand); writing directly to png-files will not be, the option to pass non-utf8 text might not be supported, etc.
• there might be a build option to choose either the old backend or libzint depending on the tradeoffs of the two solutions.

Now is the time to communicate your needs, use cases and wishes with regards to this API. Especially, if it is something that is in conflict with my intentions stated above. The specific "mechanics" of a potential 'fluent interface' API are discussed here.

[axxel]

I added 2 changesets:

• 3a79c38: add a new experimental 'create' and 'write' (next to 'read') API along the lines of what is discussed above
• 0ee68df: add libzint based backend for new API, needs ZXING_USE_ZINT=ON cmake option

The shortest possible use case in c++ with the current function based API (the 'fluent interface' is still on the table / in the making) looks like this:

auto svg = WriteBarcodeToSVG(CreateBarcodeFromText("hello", BarcodeFormat::QRCode));

A more realistic scenario with an image instead of an SVG string would be:

auto cOpts = CreatorOptions(BarcodeFormat::QRCode).ecLevel("M");
auto bcode = CreateBarcodeFromText("hello", cOpts);
auto wOpts = WriterOptions().sizeHint(400).withQuietZones(true).withHRT(true);
auto image = WriteBarcodeToImage(barcode, wOpts);
// write_to_file(image.data(), image.width(), image.height(), image.format());

Looking for feedback...

[axxel]

9a17b97: adds a writer API to the Rust wrapper

[Sec-ant]

There're both ecLevel and eccLevel these 2 names in the codebase, should them be unified?

[axxel]

That is exactly what I did, see here.

[axxel]

66accce: adds writer API to .NET wrapper

[farfromrefug]

@axxel i am trying your code with WriterOptions but i get an error Incomplete type 'ZXing::WriterOptions'

Any idea what might be going on? I am using c++ 20

EDIT: actually seems to be an IDE thing as it is building correctly

[Sec-ant]

Hi @axxel I don't have suggestions or objections whatsoever, just reply to let you know I'm following this :)

Though I'd like to kindly request a draft of the API structure in your mind, like what are the fields and values of the r/w Options and Barcode object, what are the names we plan to use, etc. Right now this kind of information is spreaded across several issues and discussions, which takes some time to look forth and behind. It will make it easier for wrapper developers to make an early move and decide how to properly deprecate some properties and refactor their codebases.

Please ignore my request if this adds unnecessary burden to you. I appreciate all your work put on this.

[axxel]

@vkrause you mentioned a while back that there might be some interest from your side to use the writer/creator capabilities of zxing-cpp instead of using separate libraries for individual symbologies. Is that still something of interest? Can you have look at the current API proposal (e.g. see above or here) and tell me if that would fit your bill?

Is there something you specifically need or missed with the old writer support?

Do you have a use for the WriteBarcodeToSVG() function including the withHRT (human readable text) option that the libzint backend brings to the table?

[vkrause]

That's still of interest, although I haven't pursued this further yet as the future of the writer support sounded a bit uncertain back then. The exact API style doesn't really matter, as this will be an implementation detail behind our own API anyway (as we need to integrate this with Qt rendering). So as long as we can input text and raw binary data (for symbologies supporting that), specify the error correction level (and maybe the PDF417 aspect ratio), and get some form of bit matrix out we are fine. Everything I have seen proposed would work for us.

For the output we don't need anything but the barcode bit matrix itself, ie. no SVG, no image writing, no human readable text, no scaling, no expanding 1D barcodes to a certain height, not even quiet zones.

[farfromrefug]

@axxel using the new API (generating SVG string), if the text passed to CreateBarcodeFromText is not a "valid" text for the format it seems to go in an endless loop.
Is there a way to test if a string is valid for a format?
Could it be that you dont use ZBarcode_Encode_and_Print as explained here?
EDIT: i managed to catch the std exception. Still wondering if i could "check" a string against a format without the need to catch the exception

[axxel]

What do you mean with "endless loop"? You mean the CreateBarcodeFromText function never returns? In that case, please open an issue and provide a sample text input that shows the problem.

There is no other way to "check" the validity of a string other than calling the function and catching and evaluating any potentially thrown exception. Exceptions are the means of transporting error information in this API.

[farfromrefug]

@axxel i thought it was an endless loop because my cpu was going crazy at that time. But now seeing i managed to simply catch the exception, i think it must have been something else. Sorry.
Ok for the check i ll keep on doing it with the exception handling

[farfromrefug]

@axxel i forgot to mention that the new API works great. I tested image generation and svg. I am using svg right now and it is great!
One side note on that. My app have 2 flavors, one with qrcode and one without. Comparing the 2 i can see that zxing adds 2 Mb to my so lib (on android) in release mode. Is that coming from zint? (did not have the time to test older zxing versions not using zint).
Seems quite big but not sure if we can do anything about it