Merge pull request #86 from dloebl/dloebl/update-readme

Update README

Author: dloebl

README.md

@@ -3,6 +3,7 @@
 
 A fast and lightweight GIF encoder that can create GIF animations and images. Summary of the main features:
 - user-defined global or local color-palette with up to 256 colors (limit of the GIF format)
+- True Color to GIF conversion (RGB/RGBA input) with quantization and dithering
 - size-optimizations for GIF animations:
   - option to set a pixel to transparent if it has identical color in the previous frame (transparency optimization)
   - do encoding just for the rectangular area that differs from the previous frame (width/height optimization)
@@ -11,28 +12,40 @@ A fast and lightweight GIF encoder that can create GIF animations and images. Su
 - different options for GIF animations: static image, N repetitions, infinite repetitions
 - additional source-code for verifying the encoder after making changes
 - user-defined delay time from one frame to the next (can be set independently for each frame)
+- stream-based output (via callback)
 - source-code conforms to the C99 standard
 
 ## Examples
-To get started, we suggest that you have a look at our code examples. ```examples/cgif_example_video.c``` is an example that creates a GIF animation. ```examples/cgif_example.c``` is an example for a static GIF image.
+To get started, we suggest that you have a look at our code examples.
+- ```examples/cgif_example_video.c``` is an example that creates a GIF animation.
+- ```examples/cgif_example.c``` is an example for a static GIF image.
+- ```examples/cgif_rgb_example_video.c``` is an example that creates a GIF animation from RGB data.
+- ```examples/cgif_rgb_example.c``` is an example for a static GIF image from RGB data.
 
 ## Overview
-To get an overview of the API, we recommend having a look at our wiki (https://github.com/dloebl/cgif/wiki/General-API) where types and functions are described. The corresponding implementations can be found in ```src/cgif.c``` and ```src/cgif_raw.c```. Here the most important types and functions:
+To get an overview of the API, we recommend having a look at our wiki (https://github.com/dloebl/cgif/wiki/General-API) where types and functions are described. The corresponding implementations can be found in ```src/cgif.c```, ```src/cgif_raw.c```, and ```src/cgif_rgb.c```. Here the most important types and functions:
 
 ```C
-// These are the four struct types that contain all GIF data and parameters:
-typedef CGIF_Config               // global cofinguration parameters of the GIF
+// These are the struct types that contain all GIF data and parameters:
+typedef CGIF_Config               // global configuration parameters of the GIF
 typedef CGIF_FrameConfig          // local configuration parameters for a frame
-typedef CGIF                     // struct for the full GIF
-typedef CGIF_Frame               // struct for a single frame
+typedef CGIF                      // struct for the full GIF
+typedef CGIFrgb_Config            // global cofinguration parameters of the RGB GIF
+typedef CGIFrgb_FrameConfig       // local configuration parameters for an RGB frame
+typedef CGIFrgb                   // struct for the full RGB GIF
 
-// The user needs only these three functions to create a GIF image:
+// The user needs only these functions to create a GIF image:
 CGIF* cgif_newgif   (CGIF_Config* pConfig);                   // creates a new GIF
 int  cgif_addframe  (CGIF* pGIF, CGIF_FrameConfig* pConfig);  // adds a frame to an existing GIF
-int  cgif_close     (CGIF* pGIF);                           // close the created file and free memory
+int  cgif_close     (CGIF* pGIF);                             // close the created file and free memory
+
+// The user needs only these functions to create a GIF image from RGB data:
+CGIFrgb*    cgif_rgb_newgif    (const CGIFrgb_Config* pConfig);
+cgif_result cgif_rgb_addframe  (CGIFrgb* pGIF, const CGIFrgb_FrameConfig* pConfig);
+cgif_result cgif_rgb_close     (CGIFrgb* pGIF);
 ```
 
-With our encoder you can create animated or static GIFs, you can or cannot use certain optimizations, and so on. You can switch between all these different options easily using the two attributes ```attrFlags``` and ```genFlags``` in the configurations ```CGIF_Config``` and ```CGIF_FrameConfig```. These attributes are of type ```uint32_t``` and bundle yes/no-options with a bit-wise logic. So far only a few of the 32 bits are used leaving space to include further functionalities ensuring backward compatibility. We provide the following flag settings which can be combined by bit-wise or-operations:
+With our encoder you can create animated or static GIFs, you can or cannot use certain optimizations, and so on. You can switch between all these different options easily using the two attributes ```attrFlags``` and ```genFlags``` in the configurations ```CGIF_Config``` and ```CGIF_FrameConfig``` (or their RGB counterparts). These attributes are of type ```uint32_t``` and bundle yes/no-options with a bit-wise logic. So far only a few of the 32 bits are used leaving space to include further functionalities ensuring backward compatibility. We provide the following flag settings which can be combined by bit-wise or-operations:
 ```C
 CGIF_ATTR_IS_ANIMATED              // make an animated GIF (default is non-animated GIF)
 CGIF_ATTR_NO_GLOBAL_TABLE          // disable global color table (global color table is default)
@@ -45,19 +58,34 @@ CGIF_FRAME_ATTR_HAS_SET_TRANS      // transparency setting provided by user (tra
 CGIF_FRAME_ATTR_INTERLACED         // encode frame interlaced
 CGIF_FRAME_GEN_USE_TRANSPARENCY    // use transparency optimization (size optimization)
 CGIF_FRAME_GEN_USE_DIFF_WINDOW     // do encoding just for the sub-window that changed (size optimization)
+
+// Flags specific to the RGB API:
+CGIF_RGB_FRAME_ATTR_INTERLACED     // encode frame interlaced
+CGIF_RGB_FRAME_ATTR_NO_DITHERING   // disable dithering
 ```
-If you didn't understand the point of ```attrFlags``` and ```genFlags``` and the flags, please don't worry. The example files ```examples/cgif_example.c``` and ```examples/cgif_example_video.c``` are all you need to get started and the used default settings for ```attrFlags``` and ```genFlags``` cover most cases quite well.
+If you didn't understand the point of ```attrFlags``` and ```genFlags``` and the flags, please don't worry. The example files are all you need to get started and the used default settings cover most cases quite well.
 
 ## Compiling the example
 An example can be compiled and tested simply by:
 ```
-$ c99 -o cgif_example -Iinc examples/cgif_example_video.c src/cgif.c src/cgif_raw.c
+$ c99 -o cgif_example -Iinc examples/cgif_example_video.c src/cgif.c src/cgif_raw.c src/cgif_rgb.c
 $ ./cgif_example
-
+```
+Alternatively, you can use the Meson build system:
+```
+$ meson build
+$ cd build
+$ ninja
+$ ./examples/cgif_example
 ```
 
 ## Validating the encoder
-In the folder ```tests```, we provide several testing routines that you can run via the script ```tests/performtests.sh```. To perform the tests you need to install the programs [ImageMagick](https://github.com/ImageMagick/ImageMagick), [gifsicle](https://github.com/kohler/gifsicle) and [tcc (tiny c compiler)](https://bellard.org/tcc/). 
+In the folder ```tests```, we provide several testing routines that you can run via Meson.
+```
+$ meson build
+$ cd build
+$ meson test
+```
 With the provided tests you can validate that the encoder still generates correct GIF files after making changes on the encoder itself.
 
 ## Further explanations
@@ -70,7 +98,7 @@ The following additional guarantees are provided:
 * Public API of versions 0.x.x are stable.
 
 ## Debugging
-There is a Visual Studio Code debug configuration with launch targets for the two examples. You need to install the C/C++ extension and a LLDB extension (debugger) to debug cgif.
+There is a Visual Studio Code debug configuration with launch targets for the examples. You need to install the C/C++ extension and a LLDB extension (debugger) to debug cgif.
 
 ## License
 Licensed under the MIT license (permissive).