From de6f83bc641477352de6ff6be08012df024dcfe0 Mon Sep 17 00:00:00 2001
From: Randy <randy408@protonmail.com>
Date: Fri, 23 Apr 2021 16:10:39 +0200
Subject: [PATCH] docs: add section on memory usage [skip-ci]

also moved notes on memory usage from usage.md
---
 docs/decode.md | 24 ++++++++++++++++++++++++
 docs/usage.md  |  8 +-------
 2 files changed, 25 insertions(+), 7 deletions(-)

diff --git a/docs/decode.md b/docs/decode.md
index 6bb43f13..f7efc6b4 100644
--- a/docs/decode.md
+++ b/docs/decode.md
@@ -140,6 +140,30 @@ it implements a subset of its features:
 The `SPNG_CTX_IGNORE_ADLER32` context flag has the same effect as `PNG_IGNORE_ADLER32`
 used with `png_set_option()`.
 
+## Memory usage
+
+The library will always allocate a context buffer,
+if the input PNG is a stream or file it will also create a read buffer.
+
+Decoding an image requires at least 2 rows to be kept in memory,
+3 if the image is interlaced.
+
+Gamma correction requires an additional 128KB for a lookup table if
+the output format has 16 bits per channel (e.g. `SPNG_FMT_RGBA16`).
+
+To limit memory usage for image decoding use `spng_set_image_limits()`
+to set an image width/height limit.
+This is the equivalent of `png_set_user_limits()`.
+
+Moreover the size calculated by `spng_decoded_image_size()` can be checked
+against a hard limit before allocating memory for the output image.
+
+Chunks of arbitrary length (e.g. text, color profiles) take up additional memory,
+`spng_set_chunk_limits()` is used to set hard limits on chunk length- and cache limits,
+note that reaching either limit is handled as a fatal error.
+
+This function combines the functionality of libpng's `png_set_chunk_cache_max()` and `png_set_chunk_malloc_max()`.
+
 # API
 
 # spng_set_png_buffer()
diff --git a/docs/usage.md b/docs/usage.md
index e4b8e2ac..2971b49b 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -26,7 +26,7 @@ spng_ctx_free(ctx);
 
 ```
 
-For a complete example see [example.c](https://github.com/randy408/libspng/blob/v0.6.3/examples/example.c)
+For a complete example see [example.c](https://github.com/randy408/libspng/blob/v0.6.3/examples/example.c).
 
 
 ## Decoding untrusted files
@@ -42,9 +42,3 @@ To decode untrusted files safely it is required to at least:
   to avoid running out of memory. Note that exceeding either limit is
   handled as an out-of-memory error since v0.6.0.
 
-### Notes on memory use
-
-The library allocates 2 to 3 times the width of the PNG image for decoding.
-
-Gamma correction requires an additional 128KB for a lookup table if
-the output format has 16-bits per channel (e.g. `SPNG_FMT_RGBA16`).