Breaking API changes for 1.0.0

[randy408]

This issue is for listing potentially breaking API changes for 1.0.0.

The API is guaranteed to be stable starting from 0.4.0 through 0.8.x and is tracked on ABI laboratory, note that it detects changes to the opaque type spng_ctx as breaks and needs manual verification.

So far no major mistakes have been made to warrant an incompatible API for 1.0.0

[randy408]

3d94f11 deprecates SPNG_DECODE_USE_* flags.

[randy408]

struct spng_bkgd.plte_index is an uint16_t, it should be uint8_t.

[randy408]

Consider combining spng_ctx_new() and spng_ctx_new2() and changing the return value to int.

[randy408]

Consider renaming spng_set_png_buffer/stream() to something like spng_set_src_buffer/stream() to allow for more consistent function names once encode support is added, functions for setting the output buffer/stream for the encoder would be named spng_set_dst_buffer/stream().

[randy408]

New types could be introduced as typedefs to spng_ctx:

• spng_dec - decoder
• spng_enc - encoder

To simplify the API and make things clearer:

• spng_set_*() functions would be changed to take spng_enc*
• Functions for context creation and setting of source/destination PNG can be merged:
• int spng_new_buffer_decoder(spng_dec**, spng_alloc*, int flags, void *buf, size_t len);
• int spng_new_stream_decoder(spng_dec**, spng_alloc*, int flags, spng_read_fn*, void *user);
• int spng_new_stream_encoder(spng_enc**, spng_alloc*, int flags, spng_write_fn*, void *user);

These functions could also be added without introducing the typedefs, spng_new_buffer_decoder() is more descriptive than spng_ctx_new() + spng_set_src_buffer().

[randy408]

spng_get_text() and spng_get_splt() should use regular int pointers for array counts and check for INT32_MAX instead of checking for unsigned overflow when adding a new entry to its internal list, the list should also be assigned to a pointer instead of making the user allocate a struct array:

spng_get_text(spng_ctx*, struct spng_text **text, int *n_text);

struct spng_text should also change to reflect the internal version.

[randy408]

Progressive encode/decode functions should probably not return SPNG_EOI on the last row (#205).

[randy408]

struct spng_chunk should have been removed from the header before the API was stabilized, this led to struct spng_unknown_chunk as a workaround.

Consider renaming the latter to the former and shortening spng_set/get_unknown_chunks() too.

[randy408]

struct spng_ihdr.color_type is currently uint8_t, enum spng_color_type would be better.

[randy408]

Consider widening struct spng_offs.unit_specifier and struct spng_phys.unit_specifier to enums.

edit: struct spng_row_info.filter and struct spng_ihdr.interlace_method too