acid-drop

- Hacking the planet from a LilyGo T-Deck using custom firmware
git clone git://git.acid.vegas/acid-drop.git
Log | Files | Refs | Archive | README | LICENSE

qrcodegen.h (14451B)

      1 /*
      2  * QR Code generator library (C)
      3  *
      4  * Copyright (c) Project Nayuki. (MIT License)
      5  * https://www.nayuki.io/page/qr-code-generator-library
      6  *
      7  * Permission is hereby granted, free of charge, to any person obtaining a copy of
      8  * this software and associated documentation files (the "Software"), to deal in
      9  * the Software without restriction, including without limitation the rights to
     10  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
     11  * the Software, and to permit persons to whom the Software is furnished to do so,
     12  * subject to the following conditions:
     13  * - The above copyright notice and this permission notice shall be included in
     14  *   all copies or substantial portions of the Software.
     15  * - The Software is provided "as is", without warranty of any kind, express or
     16  *   implied, including but not limited to the warranties of merchantability,
     17  *   fitness for a particular purpose and noninfringement. In no event shall the
     18  *   authors or copyright holders be liable for any claim, damages or other
     19  *   liability, whether in an action of contract, tort or otherwise, arising from,
     20  *   out of or in connection with the Software or the use or other dealings in the
     21  *   Software.
     22  */
     23 
     24 #pragma once
     25 
     26 #include <stdbool.h>
     27 #include <stddef.h>
     28 #include <stdint.h>
     29 
     30 
     31 #ifdef __cplusplus
     32 extern "C" {
     33 #endif
     34 
     35 
     36 /*
     37  * This library creates QR Code symbols, which is a type of two-dimension barcode.
     38  * Invented by Denso Wave and described in the ISO/IEC 18004 standard.
     39  * A QR Code structure is an immutable square grid of black and white cells.
     40  * The library provides functions to create a QR Code from text or binary data.
     41  * The library covers the QR Code Model 2 specification, supporting all versions (sizes)
     42  * from 1 to 40, all 4 error correction levels, and 4 character encoding modes.
     43  *
     44  * Ways to create a QR Code object:
     45  * - High level: Take the payload data and call qrcodegen_encodeText() or qrcodegen_encodeBinary().
     46  * - Low level: Custom-make the list of segments and call
     47  *   qrcodegen_encodeSegments() or qrcodegen_encodeSegmentsAdvanced().
     48  * (Note that all ways require supplying the desired error correction level and various byte buffers.)
     49  */
     50 
     51 
     52 /*---- Enum and struct types----*/
     53 
     54 /*
     55  * The error correction level in a QR Code symbol.
     56  */
     57 enum qrcodegen_Ecc {
     58 	// Must be declared in ascending order of error protection
     59 	// so that an internal qrcodegen function works properly
     60 	qrcodegen_Ecc_LOW = 0 ,  // The QR Code can tolerate about  7% erroneous codewords
     61 	qrcodegen_Ecc_MEDIUM  ,  // The QR Code can tolerate about 15% erroneous codewords
     62 	qrcodegen_Ecc_QUARTILE,  // The QR Code can tolerate about 25% erroneous codewords
     63 	qrcodegen_Ecc_HIGH    ,  // The QR Code can tolerate about 30% erroneous codewords
     64 };
     65 
     66 
     67 /*
     68  * The mask pattern used in a QR Code symbol.
     69  */
     70 enum qrcodegen_Mask {
     71 	// A special value to tell the QR Code encoder to
     72 	// automatically select an appropriate mask pattern
     73 	qrcodegen_Mask_AUTO = -1,
     74 	// The eight actual mask patterns
     75 	qrcodegen_Mask_0 = 0,
     76 	qrcodegen_Mask_1,
     77 	qrcodegen_Mask_2,
     78 	qrcodegen_Mask_3,
     79 	qrcodegen_Mask_4,
     80 	qrcodegen_Mask_5,
     81 	qrcodegen_Mask_6,
     82 	qrcodegen_Mask_7,
     83 };
     84 
     85 
     86 /*
     87  * Describes how a segment's data bits are interpreted.
     88  */
     89 enum qrcodegen_Mode {
     90 	qrcodegen_Mode_NUMERIC      = 0x1,
     91 	qrcodegen_Mode_ALPHANUMERIC = 0x2,
     92 	qrcodegen_Mode_BYTE         = 0x4,
     93 	qrcodegen_Mode_KANJI        = 0x8,
     94 	qrcodegen_Mode_ECI          = 0x7,
     95 };
     96 
     97 
     98 /*
     99  * A segment of character/binary/control data in a QR Code symbol.
    100  * The mid-level way to create a segment is to take the payload data
    101  * and call a factory function such as qrcodegen_makeNumeric().
    102  * The low-level way to create a segment is to custom-make the bit buffer
    103  * and initialize a qrcodegen_Segment struct with appropriate values.
    104  * Even in the most favorable conditions, a QR Code can only hold 7089 characters of data.
    105  * Any segment longer than this is meaningless for the purpose of generating QR Codes.
    106  * Moreover, the maximum allowed bit length is 32767 because
    107  * the largest QR Code (version 40) has 31329 modules.
    108  */
    109 struct qrcodegen_Segment {
    110 	// The mode indicator of this segment.
    111 	enum qrcodegen_Mode mode;
    112 	
    113 	// The length of this segment's unencoded data. Measured in characters for
    114 	// numeric/alphanumeric/kanji mode, bytes for byte mode, and 0 for ECI mode.
    115 	// Always zero or positive. Not the same as the data's bit length.
    116 	int numChars;
    117 	
    118 	// The data bits of this segment, packed in bitwise big endian.
    119 	// Can be null if the bit length is zero.
    120 	uint8_t *data;
    121 	
    122 	// The number of valid data bits used in the buffer. Requires
    123 	// 0 <= bitLength <= 32767, and bitLength <= (capacity of data array) * 8.
    124 	// The character count (numChars) must agree with the mode and the bit buffer length.
    125 	int bitLength;
    126 };
    127 
    128 
    129 
    130 /*---- Macro constants and functions ----*/
    131 
    132 #define qrcodegen_VERSION_MIN   1  // The minimum version number supported in the QR Code Model 2 standard
    133 #define qrcodegen_VERSION_MAX  40  // The maximum version number supported in the QR Code Model 2 standard
    134 
    135 // Calculates the number of bytes needed to store any QR Code up to and including the given version number,
    136 // as a compile-time constant. For example, 'uint8_t buffer[qrcodegen_BUFFER_LEN_FOR_VERSION(25)];'
    137 // can store any single QR Code from version 1 to 25 (inclusive). The result fits in an int (or int16).
    138 // Requires qrcodegen_VERSION_MIN <= n <= qrcodegen_VERSION_MAX.
    139 #define qrcodegen_BUFFER_LEN_FOR_VERSION(n)  ((((n) * 4 + 17) * ((n) * 4 + 17) + 7) / 8 + 1)
    140 
    141 // The worst-case number of bytes needed to store one QR Code, up to and including
    142 // version 40. This value equals 3918, which is just under 4 kilobytes.
    143 // Use this more convenient value to avoid calculating tighter memory bounds for buffers.
    144 #define qrcodegen_BUFFER_LEN_MAX  qrcodegen_BUFFER_LEN_FOR_VERSION(qrcodegen_VERSION_MAX)
    145 
    146 
    147 
    148 /*---- Functions (high level) to generate QR Codes ----*/
    149 
    150 /*
    151  * Encodes the given text string to a QR Code, returning true if encoding succeeded.
    152  * If the data is too long to fit in any version in the given range
    153  * at the given ECC level, then false is returned.
    154  * - The input text must be encoded in UTF-8 and contain no NULs.
    155  * - The variables ecl and mask must correspond to enum constant values.
    156  * - Requires 1 <= minVersion <= maxVersion <= 40.
    157  * - The arrays tempBuffer and qrcode must each have a length
    158  *   of at least qrcodegen_BUFFER_LEN_FOR_VERSION(maxVersion).
    159  * - After the function returns, tempBuffer contains no useful data.
    160  * - If successful, the resulting QR Code may use numeric,
    161  *   alphanumeric, or byte mode to encode the text.
    162  * - In the most optimistic case, a QR Code at version 40 with low ECC
    163  *   can hold any UTF-8 string up to 2953 bytes, or any alphanumeric string
    164  *   up to 4296 characters, or any digit string up to 7089 characters.
    165  *   These numbers represent the hard upper limit of the QR Code standard.
    166  * - Please consult the QR Code specification for information on
    167  *   data capacities per version, ECC level, and text encoding mode.
    168  */
    169 bool qrcodegen_encodeText(const char *text, uint8_t tempBuffer[], uint8_t qrcode[],
    170 	enum qrcodegen_Ecc ecl, int minVersion, int maxVersion, enum qrcodegen_Mask mask, bool boostEcl);
    171 
    172 
    173 /*
    174  * Encodes the given binary data to a QR Code, returning true if encoding succeeded.
    175  * If the data is too long to fit in any version in the given range
    176  * at the given ECC level, then false is returned.
    177  * - The input array range dataAndTemp[0 : dataLen] should normally be
    178  *   valid UTF-8 text, but is not required by the QR Code standard.
    179  * - The variables ecl and mask must correspond to enum constant values.
    180  * - Requires 1 <= minVersion <= maxVersion <= 40.
    181  * - The arrays dataAndTemp and qrcode must each have a length
    182  *   of at least qrcodegen_BUFFER_LEN_FOR_VERSION(maxVersion).
    183  * - After the function returns, the contents of dataAndTemp may have changed,
    184  *   and does not represent useful data anymore.
    185  * - If successful, the resulting QR Code will use byte mode to encode the data.
    186  * - In the most optimistic case, a QR Code at version 40 with low ECC can hold any byte
    187  *   sequence up to length 2953. This is the hard upper limit of the QR Code standard.
    188  * - Please consult the QR Code specification for information on
    189  *   data capacities per version, ECC level, and text encoding mode.
    190  */
    191 bool qrcodegen_encodeBinary(uint8_t dataAndTemp[], size_t dataLen, uint8_t qrcode[],
    192 	enum qrcodegen_Ecc ecl, int minVersion, int maxVersion, enum qrcodegen_Mask mask, bool boostEcl);
    193 
    194 
    195 /*---- Functions (low level) to generate QR Codes ----*/
    196 
    197 /*
    198  * Renders a QR Code representing the given segments at the given error correction level.
    199  * The smallest possible QR Code version is automatically chosen for the output. Returns true if
    200  * QR Code creation succeeded, or false if the data is too long to fit in any version. The ECC level
    201  * of the result may be higher than the ecl argument if it can be done without increasing the version.
    202  * This function allows the user to create a custom sequence of segments that switches
    203  * between modes (such as alphanumeric and byte) to encode text in less space.
    204  * This is a low-level API; the high-level API is qrcodegen_encodeText() and qrcodegen_encodeBinary().
    205  * To save memory, the segments' data buffers can alias/overlap tempBuffer, and will
    206  * result in them being clobbered, but the QR Code output will still be correct.
    207  * But the qrcode array must not overlap tempBuffer or any segment's data buffer.
    208  */
    209 bool qrcodegen_encodeSegments(const struct qrcodegen_Segment segs[], size_t len,
    210 	enum qrcodegen_Ecc ecl, uint8_t tempBuffer[], uint8_t qrcode[]);
    211 
    212 
    213 /*
    214  * Renders a QR Code representing the given segments with the given encoding parameters.
    215  * Returns true if QR Code creation succeeded, or false if the data is too long to fit in the range of versions.
    216  * The smallest possible QR Code version within the given range is automatically
    217  * chosen for the output. Iff boostEcl is true, then the ECC level of the result
    218  * may be higher than the ecl argument if it can be done without increasing the
    219  * version. The mask number is either between 0 to 7 (inclusive) to force that
    220  * mask, or -1 to automatically choose an appropriate mask (which may be slow).
    221  * This function allows the user to create a custom sequence of segments that switches
    222  * between modes (such as alphanumeric and byte) to encode text in less space.
    223  * This is a low-level API; the high-level API is qrcodegen_encodeText() and qrcodegen_encodeBinary().
    224  * To save memory, the segments' data buffers can alias/overlap tempBuffer, and will
    225  * result in them being clobbered, but the QR Code output will still be correct.
    226  * But the qrcode array must not overlap tempBuffer or any segment's data buffer.
    227  */
    228 bool qrcodegen_encodeSegmentsAdvanced(const struct qrcodegen_Segment segs[], size_t len, enum qrcodegen_Ecc ecl,
    229 	int minVersion, int maxVersion, int mask, bool boostEcl, uint8_t tempBuffer[], uint8_t qrcode[]);
    230 
    231 
    232 /*
    233  * Tests whether the given string can be encoded as a segment in alphanumeric mode.
    234  * A string is encodable iff each character is in the following set: 0 to 9, A to Z
    235  * (uppercase only), space, dollar, percent, asterisk, plus, hyphen, period, slash, colon.
    236  */
    237 bool qrcodegen_isAlphanumeric(const char *text);
    238 
    239 
    240 /*
    241  * Tests whether the given string can be encoded as a segment in numeric mode.
    242  * A string is encodable iff each character is in the range 0 to 9.
    243  */
    244 bool qrcodegen_isNumeric(const char *text);
    245 
    246 
    247 /*
    248  * Returns the number of bytes (uint8_t) needed for the data buffer of a segment
    249  * containing the given number of characters using the given mode. Notes:
    250  * - Returns SIZE_MAX on failure, i.e. numChars > INT16_MAX or
    251  *   the number of needed bits exceeds INT16_MAX (i.e. 32767).
    252  * - Otherwise, all valid results are in the range [0, ceil(INT16_MAX / 8)], i.e. at most 4096.
    253  * - It is okay for the user to allocate more bytes for the buffer than needed.
    254  * - For byte mode, numChars measures the number of bytes, not Unicode code points.
    255  * - For ECI mode, numChars must be 0, and the worst-case number of bytes is returned.
    256  *   An actual ECI segment can have shorter data. For non-ECI modes, the result is exact.
    257  */
    258 size_t qrcodegen_calcSegmentBufferSize(enum qrcodegen_Mode mode, size_t numChars);
    259 
    260 
    261 /*
    262  * Returns a segment representing the given binary data encoded in
    263  * byte mode. All input byte arrays are acceptable. Any text string
    264  * can be converted to UTF-8 bytes and encoded as a byte mode segment.
    265  */
    266 struct qrcodegen_Segment qrcodegen_makeBytes(const uint8_t data[], size_t len, uint8_t buf[]);
    267 
    268 
    269 /*
    270  * Returns a segment representing the given string of decimal digits encoded in numeric mode.
    271  */
    272 struct qrcodegen_Segment qrcodegen_makeNumeric(const char *digits, uint8_t buf[]);
    273 
    274 
    275 /*
    276  * Returns a segment representing the given text string encoded in alphanumeric mode.
    277  * The characters allowed are: 0 to 9, A to Z (uppercase only), space,
    278  * dollar, percent, asterisk, plus, hyphen, period, slash, colon.
    279  */
    280 struct qrcodegen_Segment qrcodegen_makeAlphanumeric(const char *text, uint8_t buf[]);
    281 
    282 
    283 /*
    284  * Returns a segment representing an Extended Channel Interpretation
    285  * (ECI) designator with the given assignment value.
    286  */
    287 struct qrcodegen_Segment qrcodegen_makeEci(long assignVal, uint8_t buf[]);
    288 
    289 
    290 /*---- Functions to extract raw data from QR Codes ----*/
    291 
    292 /*
    293  * Returns the side length of the given QR Code, assuming that encoding succeeded.
    294  * The result is in the range [21, 177]. Note that the length of the array buffer
    295  * is related to the side length - every 'uint8_t qrcode[]' must have length at least
    296  * qrcodegen_BUFFER_LEN_FOR_VERSION(version), which equals ceil(size^2 / 8 + 1).
    297  */
    298 int qrcodegen_getSize(const uint8_t qrcode[]);
    299 
    300 
    301 /*
    302  * Returns the color of the module (pixel) at the given coordinates, which is false
    303  * for white or true for black. The top left corner has the coordinates (x=0, y=0).
    304  * If the given coordinates are out of bounds, then false (white) is returned.
    305  */
    306 bool qrcodegen_getModule(const uint8_t qrcode[], int x, int y);
    307 
    308 /*
    309  * Returns the qrcode size of the specified version. Returns -1 on failure
    310  */
    311 int qrcodegen_version2size(int version);
    312 /*
    313  * Returns the min version of the data that can be stored. Returns -1 on failure
    314  */
    315 int qrcodegen_getMinFitVersion(enum qrcodegen_Ecc ecl, size_t dataLen);
    316 
    317 #ifdef __cplusplus
    318 }
    319 #endif