From 05cb4406dd50e633611e7b128543d3a1df84e1f8 Mon Sep 17 00:00:00 2001
From: DarthSim <darthsim@gmail.com>
Date: Sun, 19 Dec 2021 17:27:56 +0300
Subject: [PATCH] Update readme

---
 README.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 55 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 35c3781..b553472 100644
--- a/README.md
+++ b/README.md
@@ -19,7 +19,7 @@ cargo cinstall --release
 
 // Create new Quantizr options.
 // You're responsible for freeing it when the work is done (see below).
-quantizr_options *opts = quantizr_new_options();
+QuantizrOptions *opts = quantizr_new_options();
 // (optional) Set desired number of colors. The default number is 256.
 // This function returns QUANTIZR_VALUE_OUT_OF_RANGE if provided number is less than 2 or
 // greater than 255.
@@ -27,11 +27,11 @@ quantizr_set_max_colors(128);
 // Create new image object.
 // You're responsible for freeing it when the work is done (see below).
 // image_data is unsigned char array with raw RGBA pixels.
-quantizr_image *img = quantizr_create_image_rgba(image_data, image_width, image_height);
+QuantizrImage *img = quantizr_create_image_rgba(image_data, image_width, image_height);
 // Quantize image.
 // This function returns quantization result, which you're responsible to free when
 // the work is done (see below).
-quantizr_result *res = quantizr_quantize(img, opts);
+QuantizrResult *res = quantizr_quantize(img, opts);
 // Set dithering level for the future remapping. The default level is 1.0.
 // This function returns QUANTIZR_VALUE_OUT_OF_RANGE if provided level is less than 0.0 or
 // greater than 1.0.
@@ -42,7 +42,7 @@ quantizr_set_dithering_level(res, 0.8);
 // pal->entries is an array of colors.
 // pal->entries[i].r, pal->entries[i].g, pal->entries[i].b, and pal->entries[i].a are color channels
 // of palette colors.
-quantizr_palette *pal = quantizr_get_palette(res);
+QuantizrPalette *pal = quantizr_get_palette(res);
 // Write quantized image in the provided buffer.
 // The buffer should be prealocated and be large enough to fit entire image (width*height bytes).
 // This function returns QUANTIZR_BUFFER_TOO_SMALL if the buffer is not large enough.
@@ -53,6 +53,57 @@ quantizr_free_image(img);
 quantizr_free_options(opts);
 ```
 
+### Using histogram
+
+Sometimes it's necessary to generate a single palette for multiple images like animation frames. In this case, you can use histogram API:
+
+```c
+#include "quantizr.h"
+
+// Create new Quantizr options.
+// You're responsible for freeing it when the work is done (see below).
+QuantizrOptions *opts = quantizr_new_options();
+// (optional) Set desired number of colors. The default number is 256.
+// This function returns QUANTIZR_VALUE_OUT_OF_RANGE if provided number is less than 2 or
+// greater than 255.
+quantizr_set_max_colors(128);
+// Create new histogram.
+// You're responsible for freeing it when the work is done (see below).
+QuantizrHistogram *hist = quantizr_create_histogram();
+// Create new image object.
+// You're responsible for freeing it when the work is done (see below).
+// image_data is unsigned char array with raw RGBA pixels.
+QuantizrImage *img = quantizr_create_image_rgba(image_data, image_width, image_height);
+// Add the image to the histogram.
+// You can repeat these two steps multople times to add multiple images to the histogram.
+quantizr_histogram_add_image(hist, image);
+// Quantize histogram.
+// This function returns quantization result, which you're responsible to free when
+// the work is done (see below).
+QuantizrResult *res = quantizr_quantize_histogram(hist, opts);
+// Set dithering level for the future remapping. The default level is 1.0.
+// This function returns QUANTIZR_VALUE_OUT_OF_RANGE if provided level is less than 0.0 or
+// greater than 1.0.
+quantizr_set_dithering_level(res, 0.8);
+// Fetch palette from the quantization result.
+// Fetched pallette is read-only. You should not modify or free it.
+// pal->count is a number of colors in the palette.
+// pal->entries is an array of colors.
+// pal->entries[i].r, pal->entries[i].g, pal->entries[i].b, and pal->entries[i].a are color channels
+// of palette colors.
+QuantizrPalette *pal = quantizr_get_palette(res);
+// Write quantized image in the provided buffer.
+// The buffer should be prealocated and be large enough to fit entire image (width*height bytes).
+// This function returns QUANTIZR_BUFFER_TOO_SMALL if the buffer is not large enough.
+// You can repeat this step to remap multiple images.
+quantizr_remap(res, img, out_buffer, out_buffer_length);
+// Cleanup. Free quantization result, image, and options.
+quantizr_free_result(res);
+quantizr_free_histogram(hist);
+quantizr_free_image(img);
+quantizr_free_options(opts);
+```
+
 ## Using with [libvips](https://github.com/libvips/libvips)
 
 libvips currently doesn't have Quantizr support. That's why Quantizr partly implements libimagequant API enough to be used with libvips.