3rdparty/libspng/spng.h

   1 /* SPDX-License-Identifier: (BSD-2-Clause AND libpng-2.0) */
   2 #ifndef SPNG_H
   3 #define SPNG_H
   4
   5 #ifdef __cplusplus
   6 extern "C" {
   7 #endif
   8
   9 #if (defined(_WIN32) || defined(__CYGWIN__)) && !defined(SPNG_STATIC)
  10     #if defined(SPNG__BUILD)
  11         #define SPNG_API __declspec(dllexport)
  12     #else
  13         #define SPNG_API __declspec(dllimport)
  14     #endif
  15 #else
  16     #define SPNG_API
  17 #endif
  18
  19 #if defined(_MSC_VER)
  20     #define SPNG_CDECL __cdecl
  21 #else
  22     #define SPNG_CDECL
  23 #endif
  24
  25 #include <stdlib.h>
  26 #include <stdint.h>
  27 #include <stdio.h>
  28
  29 #define SPNG_VERSION_MAJOR 0
  30 #define SPNG_VERSION_MINOR 7
  31 #define SPNG_VERSION_PATCH 3
  32
  33 enum spng_errno
  34 {
  35     SPNG_IO_ERROR = -2,
  36     SPNG_IO_EOF = -1,
  37     SPNG_OK = 0,
  38     SPNG_EINVAL,
  39     SPNG_EMEM,
  40     SPNG_EOVERFLOW,
  41     SPNG_ESIGNATURE,
  42     SPNG_EWIDTH,
  43     SPNG_EHEIGHT,
  44     SPNG_EUSER_WIDTH,
  45     SPNG_EUSER_HEIGHT,
  46     SPNG_EBIT_DEPTH,
  47     SPNG_ECOLOR_TYPE,
  48     SPNG_ECOMPRESSION_METHOD,
  49     SPNG_EFILTER_METHOD,
  50     SPNG_EINTERLACE_METHOD,
  51     SPNG_EIHDR_SIZE,
  52     SPNG_ENOIHDR,
  53     SPNG_ECHUNK_POS,
  54     SPNG_ECHUNK_SIZE,
  55     SPNG_ECHUNK_CRC,
  56     SPNG_ECHUNK_TYPE,
  57     SPNG_ECHUNK_UNKNOWN_CRITICAL,
  58     SPNG_EDUP_PLTE,
  59     SPNG_EDUP_CHRM,
  60     SPNG_EDUP_GAMA,
  61     SPNG_EDUP_ICCP,
  62     SPNG_EDUP_SBIT,
  63     SPNG_EDUP_SRGB,
  64     SPNG_EDUP_BKGD,
  65     SPNG_EDUP_HIST,
  66     SPNG_EDUP_TRNS,
  67     SPNG_EDUP_PHYS,
  68     SPNG_EDUP_TIME,
  69     SPNG_EDUP_OFFS,
  70     SPNG_EDUP_EXIF,
  71     SPNG_ECHRM,
  72     SPNG_EPLTE_IDX,
  73     SPNG_ETRNS_COLOR_TYPE,
  74     SPNG_ETRNS_NO_PLTE,
  75     SPNG_EGAMA,
  76     SPNG_EICCP_NAME,
  77     SPNG_EICCP_COMPRESSION_METHOD,
  78     SPNG_ESBIT,
  79     SPNG_ESRGB,
  80     SPNG_ETEXT,
  81     SPNG_ETEXT_KEYWORD,
  82     SPNG_EZTXT,
  83     SPNG_EZTXT_COMPRESSION_METHOD,
  84     SPNG_EITXT,
  85     SPNG_EITXT_COMPRESSION_FLAG,
  86     SPNG_EITXT_COMPRESSION_METHOD,
  87     SPNG_EITXT_LANG_TAG,
  88     SPNG_EITXT_TRANSLATED_KEY,
  89     SPNG_EBKGD_NO_PLTE,
  90     SPNG_EBKGD_PLTE_IDX,
  91     SPNG_EHIST_NO_PLTE,
  92     SPNG_EPHYS,
  93     SPNG_ESPLT_NAME,
  94     SPNG_ESPLT_DUP_NAME,
  95     SPNG_ESPLT_DEPTH,
  96     SPNG_ETIME,
  97     SPNG_EOFFS,
  98     SPNG_EEXIF,
  99     SPNG_EIDAT_TOO_SHORT,
 100     SPNG_EIDAT_STREAM,
 101     SPNG_EZLIB,
 102     SPNG_EFILTER,
 103     SPNG_EBUFSIZ,
 104     SPNG_EIO,
 105     SPNG_EOF,
 106     SPNG_EBUF_SET,
 107     SPNG_EBADSTATE,
 108     SPNG_EFMT,
 109     SPNG_EFLAGS,
 110     SPNG_ECHUNKAVAIL,
 111     SPNG_ENCODE_ONLY,
 112     SPNG_EOI,
 113     SPNG_ENOPLTE,
 114     SPNG_ECHUNK_LIMITS,
 115     SPNG_EZLIB_INIT,
 116     SPNG_ECHUNK_STDLEN,
 117     SPNG_EINTERNAL,
 118     SPNG_ECTXTYPE,
 119     SPNG_ENOSRC,
 120     SPNG_ENODST,
 121     SPNG_EOPSTATE,
 122     SPNG_ENOTFINAL,
 123 };
 124
 125 enum spng_text_type
 126 {
 127     SPNG_TEXT = 1,
 128     SPNG_ZTXT = 2,
 129     SPNG_ITXT = 3
 130 };
 131
 132 enum spng_color_type
 133 {
 134     SPNG_COLOR_TYPE_GRAYSCALE = 0,
 135     SPNG_COLOR_TYPE_TRUECOLOR = 2,
 136     SPNG_COLOR_TYPE_INDEXED = 3,
 137     SPNG_COLOR_TYPE_GRAYSCALE_ALPHA = 4,
 138     SPNG_COLOR_TYPE_TRUECOLOR_ALPHA = 6
 139 };
 140
 141 enum spng_filter
 142 {
 143     SPNG_FILTER_NONE = 0,
 144     SPNG_FILTER_SUB = 1,
 145     SPNG_FILTER_UP = 2,
 146     SPNG_FILTER_AVERAGE = 3,
 147     SPNG_FILTER_PAETH = 4
 148 };
 149
 150 enum spng_filter_choice
 151 {
 152     SPNG_DISABLE_FILTERING = 0,
 153     SPNG_FILTER_CHOICE_NONE = 8,
 154     SPNG_FILTER_CHOICE_SUB = 16,
 155     SPNG_FILTER_CHOICE_UP = 32,
 156     SPNG_FILTER_CHOICE_AVG = 64,
 157     SPNG_FILTER_CHOICE_PAETH = 128,
 158     SPNG_FILTER_CHOICE_ALL = (8|16|32|64|128)
 159 };
 160
 161 enum spng_interlace_method
 162 {
 163     SPNG_INTERLACE_NONE = 0,
 164     SPNG_INTERLACE_ADAM7 = 1
 165 };
 166
 167 /* Channels are always in byte-order */
 168 enum spng_format
 169 {
 170     SPNG_FMT_RGBA8 = 1,
 171     SPNG_FMT_RGBA16 = 2,
 172     SPNG_FMT_RGB8 = 4,
 173
 174     /* Partially implemented, see documentation */
 175     SPNG_FMT_GA8 = 16,
 176     SPNG_FMT_GA16 = 32,
 177     SPNG_FMT_G8 = 64,
 178
 179     /* No conversion or scaling */
 180     SPNG_FMT_PNG = 256,
 181     SPNG_FMT_RAW = 512  /* big-endian (everything else is host-endian) */
 182 };
 183
 184 enum spng_ctx_flags
 185 {
 186     SPNG_CTX_IGNORE_ADLER32 = 1, /* Ignore checksum in DEFLATE streams */
 187     SPNG_CTX_ENCODER = 2 /* Create an encoder context */
 188 };
 189
 190 enum spng_decode_flags
 191 {
 192     SPNG_DECODE_USE_TRNS = 1, /* Deprecated */
 193     SPNG_DECODE_USE_GAMA = 2, /* Deprecated */
 194     SPNG_DECODE_USE_SBIT = 8, /* Undocumented */
 195
 196     SPNG_DECODE_TRNS = 1, /* Apply transparency */
 197     SPNG_DECODE_GAMMA = 2, /* Apply gamma correction */
 198     SPNG_DECODE_PROGRESSIVE = 256 /* Initialize for progressive reads */
 199 };
 200
 201 enum spng_crc_action
 202 {
 203     /* Default for critical chunks */
 204     SPNG_CRC_ERROR = 0,
 205
 206     /* Discard chunk, invalid for critical chunks.
 207        Since v0.6.2: default for ancillary chunks */
 208     SPNG_CRC_DISCARD = 1,
 209
 210     /* Ignore and don't calculate checksum.
 211        Since v0.6.2: also ignores checksums in DEFLATE streams */
 212     SPNG_CRC_USE = 2
 213 };
 214
 215 enum spng_encode_flags
 216 {
 217     SPNG_ENCODE_PROGRESSIVE = 1, /* Initialize for progressive writes */
 218     SPNG_ENCODE_FINALIZE = 2, /* Finalize PNG after encoding image */
 219 };
 220
 221 struct spng_ihdr
 222 {
 223     uint32_t width;
 224     uint32_t height;
 225     uint8_t bit_depth;
 226     uint8_t color_type;
 227     uint8_t compression_method;
 228     uint8_t filter_method;
 229     uint8_t interlace_method;
 230 };
 231
 232 struct spng_plte_entry
 233 {
 234     uint8_t red;
 235     uint8_t green;
 236     uint8_t blue;
 237
 238     uint8_t alpha; /* Reserved for internal use */
 239 };
 240
 241 struct spng_plte
 242 {
 243     uint32_t n_entries;
 244     struct spng_plte_entry entries[256];
 245 };
 246
 247 struct spng_trns
 248 {
 249     uint16_t gray;
 250
 251     uint16_t red;
 252     uint16_t green;
 253     uint16_t blue;
 254
 255     uint32_t n_type3_entries;
 256     uint8_t type3_alpha[256];
 257 };
 258
 259 struct spng_chrm_int
 260 {
 261     uint32_t white_point_x;
 262     uint32_t white_point_y;
 263     uint32_t red_x;
 264     uint32_t red_y;
 265     uint32_t green_x;
 266     uint32_t green_y;
 267     uint32_t blue_x;
 268     uint32_t blue_y;
 269 };
 270
 271 struct spng_chrm
 272 {
 273     double white_point_x;
 274     double white_point_y;
 275     double red_x;
 276     double red_y;
 277     double green_x;
 278     double green_y;
 279     double blue_x;
 280     double blue_y;
 281 };
 282
 283 struct spng_iccp
 284 {
 285     char profile_name[80];
 286     size_t profile_len;
 287     char *profile;
 288 };
 289
 290 struct spng_sbit
 291 {
 292     uint8_t grayscale_bits;
 293     uint8_t red_bits;
 294     uint8_t green_bits;
 295     uint8_t blue_bits;
 296     uint8_t alpha_bits;
 297 };
 298
 299 struct spng_text
 300 {
 301     char keyword[80];
 302     int type;
 303
 304     size_t length;
 305     char *text;
 306
 307     uint8_t compression_flag; /* iTXt only */
 308     uint8_t compression_method; /* iTXt, ztXt only */
 309     char *language_tag; /* iTXt only */
 310     char *translated_keyword; /* iTXt only */
 311 };
 312
 313 struct spng_bkgd
 314 {
 315     uint16_t gray; /* Only for gray/gray alpha */
 316     uint16_t red;
 317     uint16_t green;
 318     uint16_t blue;
 319     uint16_t plte_index; /* Only for indexed color */
 320 };
 321
 322 struct spng_hist
 323 {
 324     uint16_t frequency[256];
 325 };
 326
 327 struct spng_phys
 328 {
 329     uint32_t ppu_x, ppu_y;
 330     uint8_t unit_specifier;
 331 };
 332
 333 struct spng_splt_entry
 334 {
 335     uint16_t red;
 336     uint16_t green;
 337     uint16_t blue;
 338     uint16_t alpha;
 339     uint16_t frequency;
 340 };
 341
 342 struct spng_splt
 343 {
 344     char name[80];
 345     uint8_t sample_depth;
 346     uint32_t n_entries;
 347     struct spng_splt_entry *entries;
 348 };
 349
 350 struct spng_time
 351 {
 352     uint16_t year;
 353     uint8_t month;
 354     uint8_t day;
 355     uint8_t hour;
 356     uint8_t minute;
 357     uint8_t second;
 358 };
 359
 360 struct spng_offs
 361 {
 362     int32_t x, y;
 363     uint8_t unit_specifier;
 364 };
 365
 366 struct spng_exif
 367 {
 368     size_t length;
 369     char *data;
 370 };
 371
 372 struct spng_chunk
 373 {
 374     size_t offset;
 375     uint32_t length;
 376     uint8_t type[4];
 377     uint32_t crc;
 378 };
 379
 380 enum spng_location
 381 {
 382     SPNG_AFTER_IHDR = 1,
 383     SPNG_AFTER_PLTE = 2,
 384     SPNG_AFTER_IDAT = 8,
 385 };
 386
 387 struct spng_unknown_chunk
 388 {
 389     uint8_t type[4];
 390     size_t length;
 391     void *data;
 392     enum spng_location location;
 393 };
 394
 395 enum spng_option
 396 {
 397     SPNG_KEEP_UNKNOWN_CHUNKS = 1,
 398
 399     SPNG_IMG_COMPRESSION_LEVEL,
 400     SPNG_IMG_WINDOW_BITS,
 401     SPNG_IMG_MEM_LEVEL,
 402     SPNG_IMG_COMPRESSION_STRATEGY,
 403
 404     SPNG_TEXT_COMPRESSION_LEVEL,
 405     SPNG_TEXT_WINDOW_BITS,
 406     SPNG_TEXT_MEM_LEVEL,
 407     SPNG_TEXT_COMPRESSION_STRATEGY,
 408
 409     SPNG_FILTER_CHOICE,
 410     SPNG_CHUNK_COUNT_LIMIT,
 411     SPNG_ENCODE_TO_BUFFER,
 412 };
 413
 414 typedef void* SPNG_CDECL spng_malloc_fn(size_t size);
 415 typedef void* SPNG_CDECL spng_realloc_fn(void* ptr, size_t size);
 416 typedef void* SPNG_CDECL spng_calloc_fn(size_t count, size_t size);
 417 typedef void SPNG_CDECL spng_free_fn(void* ptr);
 418
 419 struct spng_alloc
 420 {
 421     spng_malloc_fn *malloc_fn;
 422     spng_realloc_fn *realloc_fn;
 423     spng_calloc_fn *calloc_fn;
 424     spng_free_fn *free_fn;
 425 };
 426
 427 struct spng_row_info
 428 {
 429     uint32_t scanline_idx;
 430     uint32_t row_num; /* deinterlaced row index */
 431     int pass;
 432     uint8_t filter;
 433 };
 434
 435 typedef struct spng_ctx spng_ctx;
 436
 437 typedef int spng_read_fn(spng_ctx *ctx, void *user, void *dest, size_t length);
 438 typedef int spng_write_fn(spng_ctx *ctx, void *user, void *src, size_t length);
 439
 440 typedef int spng_rw_fn(spng_ctx *ctx, void *user, void *dst_src, size_t length);
 441
 442 SPNG_API spng_ctx *spng_ctx_new(int flags);
 443 SPNG_API spng_ctx *spng_ctx_new2(struct spng_alloc *alloc, int flags);
 444 SPNG_API void spng_ctx_free(spng_ctx *ctx);
 445
 446 SPNG_API int spng_set_png_buffer(spng_ctx *ctx, const void *buf, size_t size);
 447 SPNG_API int spng_set_png_stream(spng_ctx *ctx, spng_rw_fn *rw_func, void *user);
 448 SPNG_API int spng_set_png_file(spng_ctx *ctx, FILE *file);
 449
 450 SPNG_API void *spng_get_png_buffer(spng_ctx *ctx, size_t *len, int *error);
 451
 452 SPNG_API int spng_set_image_limits(spng_ctx *ctx, uint32_t width, uint32_t height);
 453 SPNG_API int spng_get_image_limits(spng_ctx *ctx, uint32_t *width, uint32_t *height);
 454
 455 SPNG_API int spng_set_chunk_limits(spng_ctx *ctx, size_t chunk_size, size_t cache_size);
 456 SPNG_API int spng_get_chunk_limits(spng_ctx *ctx, size_t *chunk_size, size_t *cache_size);
 457
 458 SPNG_API int spng_set_crc_action(spng_ctx *ctx, int critical, int ancillary);
 459
 460 SPNG_API int spng_set_option(spng_ctx *ctx, enum spng_option option, int value);
 461 SPNG_API int spng_get_option(spng_ctx *ctx, enum spng_option option, int *value);
 462
 463 SPNG_API int spng_decoded_image_size(spng_ctx *ctx, int fmt, size_t *len);
 464
 465 /* Decode */
 466 SPNG_API int spng_decode_image(spng_ctx *ctx, void *out, size_t len, int fmt, int flags);
 467
 468 /* Progressive decode */
 469 SPNG_API int spng_decode_scanline(spng_ctx *ctx, void *out, size_t len);
 470 SPNG_API int spng_decode_row(spng_ctx *ctx, void *out, size_t len);
 471 SPNG_API int spng_decode_chunks(spng_ctx *ctx);
 472
 473 /* Encode/decode */
 474 SPNG_API int spng_get_row_info(spng_ctx *ctx, struct spng_row_info *row_info);
 475
 476 /* Encode */
 477 SPNG_API int spng_encode_image(spng_ctx *ctx, const void *img, size_t len, int fmt, int flags);
 478
 479 /* Progressive encode */
 480 SPNG_API int spng_encode_scanline(spng_ctx *ctx, const void *scanline, size_t len);
 481 SPNG_API int spng_encode_row(spng_ctx *ctx, const void *row, size_t len);
 482 SPNG_API int spng_encode_chunks(spng_ctx *ctx);
 483
 484 SPNG_API int spng_get_ihdr(spng_ctx *ctx, struct spng_ihdr *ihdr);
 485 SPNG_API int spng_get_plte(spng_ctx *ctx, struct spng_plte *plte);
 486 SPNG_API int spng_get_trns(spng_ctx *ctx, struct spng_trns *trns);
 487 SPNG_API int spng_get_chrm(spng_ctx *ctx, struct spng_chrm *chrm);
 488 SPNG_API int spng_get_chrm_int(spng_ctx *ctx, struct spng_chrm_int *chrm_int);
 489 SPNG_API int spng_get_gama(spng_ctx *ctx, double *gamma);
 490 SPNG_API int spng_get_gama_int(spng_ctx *ctx, uint32_t *gama_int);
 491 SPNG_API int spng_get_iccp(spng_ctx *ctx, struct spng_iccp *iccp);
 492 SPNG_API int spng_get_sbit(spng_ctx *ctx, struct spng_sbit *sbit);
 493 SPNG_API int spng_get_srgb(spng_ctx *ctx, uint8_t *rendering_intent);
 494 SPNG_API int spng_get_text(spng_ctx *ctx, struct spng_text *text, uint32_t *n_text);
 495 SPNG_API int spng_get_bkgd(spng_ctx *ctx, struct spng_bkgd *bkgd);
 496 SPNG_API int spng_get_hist(spng_ctx *ctx, struct spng_hist *hist);
 497 SPNG_API int spng_get_phys(spng_ctx *ctx, struct spng_phys *phys);
 498 SPNG_API int spng_get_splt(spng_ctx *ctx, struct spng_splt *splt, uint32_t *n_splt);
 499 SPNG_API int spng_get_time(spng_ctx *ctx, struct spng_time *time);
 500 SPNG_API int spng_get_unknown_chunks(spng_ctx *ctx, struct spng_unknown_chunk *chunks, uint32_t *n_chunks);
 501
 502 /* Official extensions */
 503 SPNG_API int spng_get_offs(spng_ctx *ctx, struct spng_offs *offs);
 504 SPNG_API int spng_get_exif(spng_ctx *ctx, struct spng_exif *exif);
 505
 506
 507 SPNG_API int spng_set_ihdr(spng_ctx *ctx, struct spng_ihdr *ihdr);
 508 SPNG_API int spng_set_plte(spng_ctx *ctx, struct spng_plte *plte);
 509 SPNG_API int spng_set_trns(spng_ctx *ctx, struct spng_trns *trns);
 510 SPNG_API int spng_set_chrm(spng_ctx *ctx, struct spng_chrm *chrm);
 511 SPNG_API int spng_set_chrm_int(spng_ctx *ctx, struct spng_chrm_int *chrm_int);
 512 SPNG_API int spng_set_gama(spng_ctx *ctx, double gamma);
 513 SPNG_API int spng_set_gama_int(spng_ctx *ctx, uint32_t gamma);
 514 SPNG_API int spng_set_iccp(spng_ctx *ctx, struct spng_iccp *iccp);
 515 SPNG_API int spng_set_sbit(spng_ctx *ctx, struct spng_sbit *sbit);
 516 SPNG_API int spng_set_srgb(spng_ctx *ctx, uint8_t rendering_intent);
 517 SPNG_API int spng_set_text(spng_ctx *ctx, struct spng_text *text, uint32_t n_text);
 518 SPNG_API int spng_set_bkgd(spng_ctx *ctx, struct spng_bkgd *bkgd);
 519 SPNG_API int spng_set_hist(spng_ctx *ctx, struct spng_hist *hist);
 520 SPNG_API int spng_set_phys(spng_ctx *ctx, struct spng_phys *phys);
 521 SPNG_API int spng_set_splt(spng_ctx *ctx, struct spng_splt *splt, uint32_t n_splt);
 522 SPNG_API int spng_set_time(spng_ctx *ctx, struct spng_time *time);
 523 SPNG_API int spng_set_unknown_chunks(spng_ctx *ctx, struct spng_unknown_chunk *chunks, uint32_t n_chunks);
 524
 525 /* Official extensions */
 526 SPNG_API int spng_set_offs(spng_ctx *ctx, struct spng_offs *offs);
 527 SPNG_API int spng_set_exif(spng_ctx *ctx, struct spng_exif *exif);
 528
 529
 530 SPNG_API const char *spng_strerror(int err);
 531 SPNG_API const char *spng_version_string(void);
 532
 533 #ifdef __cplusplus
 534 }
 535 #endif
 536
 537 #endif /* SPNG_H */