disable the RGB API by default

Author: dloebl

README.md

@@ -40,11 +40,14 @@ int  cgif_addframe  (CGIF* pGIF, CGIF_FrameConfig* pConfig);  // adds a frame to
 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:
+// (EXPERIMENTAL: declared in the separate header "cgif_rgb.h")
 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);
 ```
 
+**Note:** The RGB API is **experimental** and subject to change. It is **disabled by default** and lives in its own header ```inc/cgif_rgb.h``` (include it via ```#include "cgif_rgb.h"```). To compile it into the library and install the header, configure the build with ```-Dexperimental_rgb=true```. The regular header ```inc/cgif.h``` no longer declares the RGB API.
+
 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)

examples/cgif_rgb_example.c

@@ -4,6 +4,7 @@
 #include <stdio.h>
 
 #include "cgif.h"
+#include "cgif_rgb.h"
 
 #define WIDTH  200
 #define HEIGHT 200

examples/cgif_rgb_example_video.c

@@ -4,6 +4,7 @@
 #include <stdio.h>
 
 #include "cgif.h"
+#include "cgif_rgb.h"
 
 #define WIDTH  200
 #define HEIGHT 200

fuzz/cgif_rgb_create_fuzz_seed.c

@@ -4,6 +4,7 @@
 */
 
 #include <cgif.h>
+#include <cgif_rgb.h>
 
 #include <stdio.h>
 #include <stdint.h>

fuzz/cgif_rgb_fuzzer.c

@@ -1,4 +1,5 @@
 #include <cgif.h>
+#include <cgif_rgb.h>
 
 #include <stddef.h>
 #include <stdint.h>

fuzz/meson.build

@@ -41,7 +41,9 @@ src_rgb = ['cgif_fuzzer_standalone.c', 'cgif_rgb_fuzzer.c']
 exe_rgb = executable(
   'cgif_rgb_fuzzer_standalone',
   sources : src_rgb,
-  dependencies : [libcgif_dep],
+  # use the RGB-enabled internal library so this keeps building regardless of
+  # the 'experimental_rgb' option
+  dependencies : [libcgif_rgb_dep],
   include_directories : ['../inc'],
 )
 # test indexed seed corpus with standalone fuzzer and standalone file fuzzer

inc/cgif.h

@@ -26,9 +26,6 @@ extern "C" {
 
 #define CGIF_INFINITE_LOOP               (0x0000uL)       // for animated GIF: 0 specifies infinite loop
 
-#define CGIF_RGB_FRAME_ATTR_INTERLACED   (1ul << 0)       // encode frame interlaced (default is not interlaced)
-#define CGIF_RGB_FRAME_ATTR_NO_DITHERING (1ul << 1)       // disable color dithering (default is with dithering)
-
 typedef enum {
   CGIF_ERROR = -1, // something unspecified failed
   CGIF_OK    =  0, // everything OK
@@ -41,17 +38,9 @@ typedef enum {
   CGIF_PENDING,
 } cgif_result;
 
-typedef enum {
-  CGIF_CHAN_FMT_RGB  = 3, // 3 byte per pixel (red, green, blue)
-  CGIF_CHAN_FMT_RGBA = 4, // 4 byte per pixel (red, green, blue, alpha)
-} cgif_chan_fmt;
-
 typedef struct st_gif                  CGIF;              // struct for the full GIF
 typedef struct st_gifconfig            CGIF_Config;       // global cofinguration parameters of the GIF
 typedef struct st_frameconfig          CGIF_FrameConfig;  // local configuration parameters for a frame
-typedef struct st_cgif_rgb_config      CGIFrgb_Config;
-typedef struct st_cgif_rgb             CGIFrgb;
-typedef struct st_cgif_rgb_frameconfig CGIFrgb_FrameConfig;
 
 typedef int cgif_write_fn(void* pContext, const uint8_t* pData, const size_t numBytes); // callback function for stream-based output
 
@@ -60,10 +49,6 @@ CGIF* cgif_newgif     (CGIF_Config* pConfig);                  // creates a new
 int   cgif_addframe   (CGIF* pGIF, CGIF_FrameConfig* pConfig); // adds the next frame to an existing GIF (returns 0 on success)
 int   cgif_close      (CGIF* pGIF);                          // close file and free allocated memory (returns 0 on success)
 
-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);
-
 // CGIF_Config type (parameters passed by user)
 // note: must stay AS IS for backward compatibility
 struct st_gifconfig {
@@ -91,25 +76,6 @@ struct st_frameconfig {
   uint8_t   transIndex;                                // introduced with V0.2.0
 };
 
-struct st_cgif_rgb_config {
-  cgif_write_fn* pWriteFn;
-  void*          pContext;
-  const char*    path;
-  uint32_t       attrFlags;
-  uint32_t       genFlags;
-  uint16_t       numLoops;
-  uint16_t       width;
-  uint16_t       height;
-};
-
-struct st_cgif_rgb_frameconfig {
-  uint8_t* pImageData;
-  cgif_chan_fmt fmtChan;
-  uint32_t attrFlags;   // TBD
-  uint32_t genFlags;    // TBD
-  uint16_t delay;
-};
-
 #ifdef __cplusplus
 }
 #endif

inc/cgif_rgb.h

@@ -0,0 +1,58 @@
+#ifndef CGIF_RGB_H
+#define CGIF_RGB_H
+
+// EXPERIMENTAL: the RGB API is experimental and subject to change.
+// It is not part of the stable cgif API and must be enabled explicitly
+// via the 'experimental_rgb' build option. The declarations below used to
+// live in cgif.h but have been moved out of the regular header.
+
+#include <stdint.h>
+
+#include "cgif.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// flags to set the RGB frame-attributes
+#define CGIF_RGB_FRAME_ATTR_INTERLACED   (1ul << 0)       // encode frame interlaced (default is not interlaced)
+#define CGIF_RGB_FRAME_ATTR_NO_DITHERING (1ul << 1)       // disable color dithering (default is with dithering)
+
+typedef enum {
+  CGIF_CHAN_FMT_RGB  = 3, // 3 byte per pixel (red, green, blue)
+  CGIF_CHAN_FMT_RGBA = 4, // 4 byte per pixel (red, green, blue, alpha)
+} cgif_chan_fmt;
+
+typedef struct st_cgif_rgb_config      CGIFrgb_Config;
+typedef struct st_cgif_rgb             CGIFrgb;
+typedef struct st_cgif_rgb_frameconfig CGIFrgb_FrameConfig;
+
+// prototypes
+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);
+
+struct st_cgif_rgb_config {
+  cgif_write_fn* pWriteFn;
+  void*          pContext;
+  const char*    path;
+  uint32_t       attrFlags;
+  uint32_t       genFlags;
+  uint16_t       numLoops;
+  uint16_t       width;
+  uint16_t       height;
+};
+
+struct st_cgif_rgb_frameconfig {
+  uint8_t* pImageData;
+  cgif_chan_fmt fmtChan;
+  uint32_t attrFlags;   // TBD
+  uint32_t genFlags;    // TBD
+  uint16_t delay;
+};
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // CGIF_RGB_H

meson.build

@@ -10,7 +10,16 @@ project(
 cc = meson.get_compiler('c')
 m_dep = cc.find_library('m', required : false)
 
-cgif_sources = ['src/cgif.c', 'src/cgif_raw.c', 'src/cgif_rgb.c']
+cgif_sources = ['src/cgif.c', 'src/cgif_raw.c']
+cgif_headers = ['inc/cgif.h']
+
+# EXPERIMENTAL: the RGB API is opt-in and disabled by default.
+# When enabled it is compiled into the public library and its header installed.
+if get_option('experimental_rgb')
+  cgif_sources += 'src/cgif_rgb.c'
+  cgif_headers += 'inc/cgif_rgb.h'
+endif
+
 lib = library(
   'cgif',
   cgif_sources,
@@ -21,7 +30,7 @@ lib = library(
   install : true,
 )
 
-install_headers('inc/cgif.h')
+install_headers(cgif_headers)
 
 import('pkgconfig').generate(
   lib,
@@ -32,6 +41,19 @@ import('pkgconfig').generate(
 libcgif_dep = declare_dependency(link_with : lib)
 
 if get_option('tests') and not meson.is_cross_build()
+  # Internal (non-installed) library that always includes the experimental RGB
+  # API so the RGB tests keep building even when 'experimental_rgb' is off.
+  cgif_rgb_test_lib = static_library(
+    'cgif_rgb_test',
+    ['src/cgif.c', 'src/cgif_raw.c', 'src/cgif_rgb.c'],
+    dependencies : m_dep,
+    include_directories : ['inc/'],
+    install : false,
+  )
+  libcgif_rgb_dep = declare_dependency(
+    link_with : cgif_rgb_test_lib,
+    include_directories : ['inc/'],
+  )
   subdir('tests')
   if get_option('fuzzer')
     subdir('fuzz')

meson_options.txt

@@ -19,6 +19,16 @@ option(
   description : 'build tests',
 )
 
+# EXPERIMENTAL: the RGB API is experimental and disabled by default.
+# When disabled, the public library does not export the RGB API and the
+# cgif_rgb.h header is not installed. The tests always build the RGB API.
+option(
+  'experimental_rgb',
+  type : 'boolean',
+  value : false,
+  description : 'build the experimental RGB API into the library (EXPERIMENTAL, API subject to change)',
+)
+
 # for debugging purposes
 option(
   'install_examples',