docs: add encode api, updates [skip-ci]

added encode api docs
moved some things from decode.md to context.md and vice versa

docs/api.md

@@ -2,6 +2,7 @@
 
 * [Error handling](errors.md)
 * [Versioning](version.md)
-* [Context](context.md)
-* [Retrieving and setting chunks](chunk.md)
-* [Decode](decode.md)
+* [Common](context.md)
+* [Getting and setting chunk data](chunk.md)
+* [Decoder API](decode.md)
+* [Encoder API](encode.md)

docs/context.md

@@ -16,24 +16,108 @@ typedef struct spng_ctx spng_ctx;
 ```c
 enum spng_ctx_flags
 {
-    SPNG_CTX_IGNORE_ADLER32 = 1 /* ignore checksum in DEFLATE streams */
+    SPNG_CTX_IGNORE_ADLER32 = 1, /* Ignore checksum in DEFLATE streams */
+    SPNG_CTX_ENCODER = 2 /* Create an encoder context */
 };
 ```
 
-# spng_crc_action
+# spng_read_fn
+```c
+typedef int spng_read_fn(spng_ctx *ctx, void *user, void *dest, size_t length)
+```
+
+Type definition for callback passed to `spng_set_png_stream()` for decoders.
+
+A read callback function should copy `length` bytes to `dest` and return 0 or
+`SPNG_IO_EOF`/`SPNG_IO_ERROR` on error.
+
+
+# spng_write_fn
+```c
+typedef int spng_write_fn(spng_ctx *ctx, void *user, void *src, size_t length)
+```
+
+Type definition for callback passed to `spng_set_png_stream()` for encoders.
+
+The write callback should process `length` bytes and return 0 or `SPNG_IO_ERROR` on error.
+
+
+# spng_format
+```c
+enum spng_format
+{
+    SPNG_FMT_RGBA8 = 1,
+    SPNG_FMT_RGBA16 = 2,
+    SPNG_FMT_RGB8 = 4,
+
+    SPNG_FMT_GA8 = 16,
+    SPNG_FMT_GA16 = 32,
+    SPNG_FMT_G8 = 64,
+
+    /* No conversion or scaling */
+    SPNG_FMT_PNG = 256, /* host-endian */
+    SPNG_FMT_RAW = 512  /* big-endian */
+};
+```
+
+The channels are always in [byte-order](https://en.wikipedia.org/wiki/RGBA_color_model#RGBA8888) representation.
+
+# spng_filter
+```c
+enum spng_filter
+{
+    SPNG_FILTER_NONE = 0,
+    SPNG_FILTER_SUB = 1,
+    SPNG_FILTER_UP = 2,
+    SPNG_FILTER_AVERAGE = 3,
+    SPNG_FILTER_PAETH = 4
+};
+```
 
+# spng_row_info
 ```c
-enum spng_crc_action
+struct spng_row_info
 {
-    /* Default for critical chunks */
-    SPNG_CRC_ERROR = 0,
+    uint32_t scanline_idx;
+    uint32_t row_num;
+    int pass;
+    uint8_t filter;
+};
+```
+
+Contains row and scanline information, used for progressive decoding and encoding.
+
+# spng_option
+```c
+enum spng_option
+{
+    SPNG_KEEP_UNKNOWN_CHUNKS = 1,
 
-    /* Discard chunk, invalid for critical chunks,
-       since v0.6.2: default for ancillary chunks */
-    SPNG_CRC_DISCARD = 1,
+    SPNG_IMG_COMPRESSION_LEVEL,
+    SPNG_IMG_WINDOW_BITS,
+    SPNG_IMG_MEM_LEVEL,
+    SPNG_IMG_COMPRESSION_STRATEGY,
 
-    /* Ignore and don't calculate checksum */
-    SPNG_CRC_USE = 2
+    SPNG_TEXT_COMPRESSION_LEVEL,
+    SPNG_TEXT_WINDOW_BITS,
+    SPNG_TEXT_MEM_LEVEL,
+    SPNG_TEXT_COMPRESSION_STRATEGY,
+
+    SPNG_FILTER_CHOICE,
+};
+```
+
+# spng_filter_choice
+```c
+enum spng_filter_choice
+{
+    SPNG_DISABLE_FILTERING = 0,
+    SPNG_FILTER_CHOICE_NONE = 8,
+    SPNG_FILTER_CHOICE_SUB = 16,
+    SPNG_FILTER_CHOICE_UP = 32,
+    SPNG_FILTER_CHOICE_AVG = 64,
+    SPNG_FILTER_CHOICE_PAETH = 128,
+    SPNG_FILTER_CHOICE_ALL = (8|16|32|64|128)
 };
 ```
 
@@ -62,6 +146,27 @@ void spng_ctx_free(spng_ctx *ctx)
 
 Releases context resources.
 
+# spng_set_png_stream()
+```c
+int spng_set_png_stream(spng_ctx *ctx, spng_rw_fn *rw_func, void *user)
+```
+
+Set input PNG stream or output PNG stream, depending on context type.
+
+This can only be done once per context.
+
+!!! info
+    PNG's are read up to the file end marker, this is identical behavior to libpng.
+
+# spng_set_png_file()
+```c
+int spng_set_png_file(spng_ctx *ctx, FILE *file)
+```
+
+Set input PNG file or output PNG file, depending on context type.
+
+This can only be done once per context.
+
 # spng_set_image_limits()
 ```c
 int spng_set_image_limits(spng_ctx *ctx, uint32_t width, uint32_t height)
@@ -78,13 +183,6 @@ Get image width and height limits.
 
 `width` and `height` must be non-NULL.
 
-# spng_set_crc_action()
-```c
-int spng_set_crc_action(spng_ctx *ctx, int critical, int ancillary)
-```
-
-Set how chunk CRC errors should be handled for critical and ancillary chunks.
-
 # spng_set_chunk_limits()
 ```c
 int spng_set_chunk_limits(spng_ctx *ctx, size_t chunk_size, size_t cache_limit)
@@ -105,3 +203,24 @@ int spng_get_chunk_limits(spng_ctx *ctx, size_t *chunk_size, size_t *cache_limit
 ```
 
 Get chunk size and chunk cache limits.
+
+# spng_get_row_info()
+```c
+int spng_get_row_info(spng_ctx *ctx, struct spng_row_info *row_info)
+```
+
+Copies the current, to-be-decoded (or to-be-encoded) row's information to `row_info`.
+
+# spng_set_option()
+```c
+int spng_set_option(spng_ctx *ctx, enum spng_option option, int value)
+```
+
+Set `option` to the specified `value`.
+
+# spng_get_option()
+```c
+int spng_get_option(spng_ctx *ctx, enum spng_option option, int *value)
+```
+
+Get the value for the specified `option`.

docs/decode.md

@@ -1,37 +1,22 @@
 # Data types
 
+# spng_crc_action
 ```c
-typedef int spng_read_fn(spng_ctx *ctx, void *user, void *dest, size_t length)
-```
-
-Type definition for callback passed to `spng_set_png_stream()`.
-
-A read callback function should copy `length` bytes to `dest` and return 0 or
-`SPNG_IO_EOF`/`SPNG_IO_ERROR` on error.
-
-# spng_format
-
-```c
-enum spng_format
+enum spng_crc_action
 {
-    SPNG_FMT_RGBA8 = 1,
-    SPNG_FMT_RGBA16 = 2,
-    SPNG_FMT_RGB8 = 4,
+    /* Default for critical chunks */
+    SPNG_CRC_ERROR = 0,
 
-    SPNG_FMT_GA8 = 16,
-    SPNG_FMT_GA16 = 32,
-    SPNG_FMT_G8 = 64,
+    /* Discard chunk, invalid for critical chunks,
+       since v0.6.2: default for ancillary chunks */
+    SPNG_CRC_DISCARD = 1,
 
-    /* No conversion or scaling */
-    SPNG_FMT_PNG = 256, /* host-endian */
-    SPNG_FMT_RAW = 512  /* big-endian */
+    /* Ignore and don't calculate checksum */
+    SPNG_CRC_USE = 2
 };
 ```
 
-The channels are always in [byte-order](https://en.wikipedia.org/wiki/RGBA_color_model#RGBA8888) representation.
-
 # spng_decode_flags
-
 ```c
 enum spng_decode_flags
 {
@@ -166,29 +151,21 @@ This function combines the functionality of libpng's `png_set_chunk_cache_max()`
 
 # API
 
+See also: [spng_set_png_stream()](context.md#spng_set_png_stream), [spng_set_png_file()](context.md#spng_set_png_file).
+
 # spng_set_png_buffer()
 ```c
 int spng_set_png_buffer(spng_ctx *ctx, void *buf, size_t size)
 ```
 
 Set input PNG buffer, this can only be done once per context.
 
-# spng_set_png_stream()
+# spng_set_crc_action()
 ```c
-int spng_set_png_stream(spng_ctx *ctx, spng_read_fn *read_fn, void *user)
+int spng_set_crc_action(spng_ctx *ctx, int critical, int ancillary)
 ```
 
-Set input PNG stream, this can only be done once per context.
-
-!!! info
-    PNG's are read up to the file end marker, this is identical behavior to libpng.
-
-# spng_set_png_file()
-```c
-int spng_set_png_file(spng_ctx *ctx, FILE *file)
-```
-
-Set input PNG file, this can only be done once per context.
+Set how chunk CRC errors should be handled for critical and ancillary chunks.
 
 # spng_decoded_image_size()
 ```c
@@ -205,7 +182,7 @@ int spng_decode_image(spng_ctx *ctx, void *out, size_t len, int fmt, int flags)
 ```
 
 Decodes the PNG file and writes the image to `out`,
-the image is converted from any PNG format to the destination format `fmt`.
+the image is converted from the PNG format to the destination format `fmt`.
 
 Interlaced images are deinterlaced, 16-bit images are converted to host-endian.
 
@@ -249,14 +226,11 @@ This function requires the decoder to be initialized by calling
 
 The width of the row is the decoded image size divided by `ihdr.height`.
 
+For interlaced images rows are accessed multiple times and non-sequentially,
+use [spng_get_row_info()](context.md#spng_get_row_info) to get the current row number.
+
 For the last row and subsequent calls the return value is `SPNG_EOI`.
 
 If the image is not interlaced this function's behavior is identical to
 `spng_decode_scanline()`.
 
-# spng_get_row_info()
-```c
-int spng_get_row_info(spng_ctx *ctx, struct spng_row_info *row_info)
-```
-
-Copies the current, to-be-decoded row's information to `row_info`.