=encoding UTF-8

=head1 NAME

Image::PNG::QRCode - make a PNG image containing a QR code from text

=head1 SYNOPSIS

    use Image::PNG::QRCode 'qrpng';
    qrpng (text => 'boom shake shake shake the room', out => 'shake.png');

=head1 DESCRIPTION

This module converts input text to a PNG image of a QR code containing
the text. The PNG image can either be stored to a file or it can be a
scalar.

Image::PNG::Libpng requires "libpng" to be installed. "libpng" should
already be installed on most Linux and Windows systems.

=head1 FUNCTIONS

=head2 qrpng

    my $png = qrpng (text => 'this is my text');

This makes a scalar PNG data in C<$png> containing the QR code PNG.    
    
    qrpng (in => 'file.txt', out => 'file.png');

This makes a PNG file F<file.png> from the contents of F<file.txt>.

=head3 qrpng options

=over

=item text

Text to convert to a QR code.

=item in

C<in> specifies an input file of text to convert to a QR code.

=item out

C<out> specifies an output file or a scalar to put the PNG data into.

     qrpng (out => 'file.png');

writes to F<file.png>, but

     qrpng (out => \$s);

writes the PNG data into a scalar C<$s>.

=item version

Specify the "version" of the QR code. The "version" is like the size
of the code. Maximum value is 40. If no version is specified, the
program chooses one using the length of the text. If you choose a
version which is too small for the input data, a fatal error occurs.

=item level

Specify the amount of error checking code (ECC) to use. The default is
level one, which corresponds to 7% error tolerance. The level can go
up to 4, which corresponds to 30% error tolerance. Values less than
one or greater than four cause a fatal error.

=item quiet

Specify the size of the "quiet zone". The default is 4.

=item scale

Specify how many pixels one "module" (one block of the QR code)
occupies. The default is 3. You can't use fractional values.

=back

=head1 DIAGNOSTICS

=over

=item %!$#"@*

This message is produced in the case of errors.

=back

=head1 SCRIPT AND EXAMPLES

There is a script "qrpng" installed with the module:

    qrpng "earphone pad" 

makes F<qrcode.png>. Try

    qrpng --help

for more options.

There is an example script F<qrpng.cgi> in F<examples>.

=begin html

<p>It makes a QR code for HTML:</p>

<img src='http://www.lemoda.net/png/qrcode/qrpng.cgi?w=Image::PNG::QRCode%20is%20probably%20the%20best%20QR%20code%20module%20in%20the%20world'>

=end html

=head1 SEE ALSO

=head2 About QR codes

L<QRCode.com from Denso Wave|http://www.qrcode.com/en/index.html>, the
inventors of the QR code, contains much information.

=head2 Other QR code generators

=head3 On CPAN

=over

=item Imager::QRCode

L<Imager::QRCode> is based on the L<Imager> module and libqrencode.

=item Text::QRCode

L<Text::QRCode> makes a text QR code. It's based on libqrencode.

=item HTML::QRCode

L<HTML::QRCode> is based on Text::QRCode.

=item Term::QRCode

L<Term::QRCode> makes QR codes on terminal windows.

=item  PostScript::Barcode::qrcode

This is part of L<PostScript::Barcode>. It's actually PostScript
rather than Perl.

=back

=head3 Non-CPAN

=over

=item qrduino

L<qrduino|https://github.com/tz1/qrduino> is a QR code generator
developed for a platform called the Arduino. Image::PNG::QRCode is a
fork of this project.

=item libqrencode

L<libqrencode|http://fukuchi.org/works/qrencode/index.html.en> is the
library underlying L<Text::QRCode> and its dependents.

=item Google Charts QR code generator

L<Google Charts offers a QR code
generator|https://developers.google.com/chart/infographics/docs/qr_codes>.
The QR codes generated by Image::PNG::QRCode are about 1/3 the size of
the default Google charts ones, for example the "Hello world" example
in the above documentation is 728 bytes, but Image::PNG::QRCode makes
an equivalent QR code using only 243 bytes. The reason for the reduced
size is that Google Charts uses RGB colour space, whereas
Image::PNG::QRCode uses one-bit monochrome colour space.

=item ZXing

L<ZXing|https://github.com/zxing/zxing/> is a Java project which can
generate QR codes. These are one-bit monochrome ones.

=item 

L<QrCode.net|http://qrcodenet.codeplex.com/> is a .Net version.

=item JavaScript qrcode generators

These might be a useful alternative to using a server-side solution:

L<http://d-project.googlecode.com/svn/trunk/misc/qrcode/js/>

L<http://code.google.com/p/jsqrencode/downloads/list>

However, sending these JavaScript files over the internet results in
much more bandwidth than sending the QR codes themselves.

=back

=head1 BUGS

The QR code PNG files are very small and various tricks are used to
make the memory use and the PNG file very small. Although the original
plan was to interoperate with L<Image::PNG::Libpng>, this ended up
looking like a big burden to get only a small return, so this module
actually just copies the parts of the code of
L<Image::PNG::Libpng>. If you want to manipulate the output PNG file
you'll need to read it in again and operate on it.

The module isn't optimized for repeated uses, it builds up and tears
down everyting.

The QR encoding is not checked for correctness. The QR code library
comes from the "qrduino" project, but the contents have been worked on
so it's not clear whether it's still correct. Also there was a bug in
the original thing leading to reading uninitialized memory.

This encoder doesn't support the "shift-JIS" format. UTF-8 seems to
pass through it OK. It doesn't use a BOM for the UTF-8.

=head1 COPYRIGHT AND LICENCE

The QR code creation part (the contents of F<qrencode.c> in the
distribution) is copyright 2010, tz@execpc.com. The rest of the module
is copyright by Ben Bullock 2014.

This Perl module is licensed under the Gnu General Public Licence
version 3.

=cut
