Merge pull request #141 from saxbophone/develop

v0.22.0

CMakeLists.txt

@@ -23,7 +23,7 @@
 # begin basic metadata
 cmake_minimum_required(VERSION 3.0)
 
-project(libsaxbospiral VERSION 0.21.2 LANGUAGES C)
+project(libsaxbospiral VERSION 0.22.0 LANGUAGES C)
 
 # set default C standard to use (C99) if not already set
 if(NOT DEFINED SAXBOSPIRAL_C_STANDARD)
@@ -89,12 +89,43 @@ if(CMAKE_BUILD_TYPE STREQUAL "Debug" OR CMAKE_BUILD_TYPE STREQUAL "")
     enable_c_compiler_flag_if_supported("-Werror")
 endif()
 
-# dependencies
+# begin dependencies
 # add custom dependencies directory
 set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${CMAKE_SOURCE_DIR}/cmake/Modules/")
 # libpng
-find_package(PNG 1 EXACT REQUIRED)
-include_directories(${PNG_INCLUDE_DIR})
+# work out whether we have or have not requested PNG support, or don't care (default)
+if(NOT DEFINED SAXBOSPIRAL_PNG_SUPPORT)
+    # try and find libpng v1.x, but don't fail if we can't
+    message(STATUS "PNG output support will be enabled if possible")
+    find_package(PNG 1 EXACT)
+    # set SAXBOSPIRAL_PNG_SUPPORT based on value of PNG_FOUND
+    if(PNG_FOUND)
+        set(SAXBOSPIRAL_PNG_SUPPORT ON)
+    else()
+        set(SAXBOSPIRAL_PNG_SUPPORT OFF)
+    endif()
+elseif(SAXBOSPIRAL_PNG_SUPPORT)
+    # find libpng v1.x and fail the build if we can't
+    message(STATUS "PNG output support explicitly enabled")
+    find_package(PNG 1 EXACT REQUIRED)
+else()
+    # we've explicitly disabled PNG support, so don't include libpng
+    # issue a message saying so
+    message(STATUS "PNG output support explicitly disabled")
+endif()
+
+# include libpng directories and add feature test macro if support is enabled
+if(SAXBOSPIRAL_PNG_SUPPORT)
+    include_directories(${PNG_INCLUDE_DIR})
+    # feature test macro
+    add_definitions(-DSAXBOSPIRAL_PNG_SUPPORT)
+    # issue message
+    message(STATUS "PNG output support enabled")
+else()
+    # issue message
+    message(STATUS "PNG output support disabled")
+endif()
+# end dependencies
 
 # C source files
 file(
@@ -114,12 +145,16 @@ set_target_properties(
     saxbospiral PROPERTIES VERSION ${SAXBOSPIRAL_VERSION_STRING}
     SOVERSION ${PROJECT_VERSION_MAJOR}
 )
-# Link libsaxbospiral with libpng so we get libpng symbols
-target_link_libraries(saxbospiral ${PNG_LIBRARY})
+# link libsaxbospiral with C math library
+target_link_libraries(saxbospiral m)
+# Link libsaxbospiral with libpng so we get libpng symbols (if support enabled)
+if(SAXBOSPIRAL_PNG_SUPPORT)
+    target_link_libraries(saxbospiral ${PNG_LIBRARY})
+endif()
 
 add_executable(sxp_test tests.c)
 
-target_link_libraries(sxp_test saxbospiral ${PNG_LIBRARY})
+target_link_libraries(sxp_test saxbospiral)
 
 install(
     TARGETS saxbospiral

README.md

@@ -44,6 +44,8 @@ You will need:
 
 - A compiler that can compile ISO C99 or C11 code
 - [Cmake](https://cmake.org/) - v3.0 or newer
+
+*If you also want to be able to produce images in PNG format with the library, you will need:*
 - [libpng](http://www.libpng.org/pub/png/libpng.html) - (this often comes preinstalled with many modern unix-like systems)
 
 > ### Note:
@@ -75,6 +77,20 @@ cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=ON -DSAXBOSPIRAL_C_STANDARD
 LIBSAXBOSPIRAL_C_STANDARD=11 cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=ON .
 ```
 
+Also, by default the CMake build script will look for libpng. If it cannot find it then it will disable support for PNG output.
+
+You may choose to explicitly disable or enable PNG support with the `SAXBOSPIRAL_PNG_SUPPORT` CMake variable, which can be passed on the command-line like so:
+
+```sh
+# PNG support is required, build will fail if libpng can't be found
+cmake -DSAXBOSPIRAL_PNG_SUPPORT=ON .
+```
+
+```sh
+# PNG support is not included, even if libpng can be found
+cmake -DSAXBOSPIRAL_PNG_SUPPORT=OFF .
+```
+
 > ### Note:
 
 > Building as a shared library is recommended as then binaries compiled from [sxbp](https://github.com/saxbophone/sxbp) or your own programs that are linked against the shared version can immediately use any installed upgraded versions of libsaxbospiral with compatible ABIs without needing re-compiling.

saxbospiral/render_backends/backend_png.c

@@ -5,6 +5,11 @@
  * This compilation unit provides functionality to render a bitmap struct to a
  * PNG image (stored in a buffer).
  *
+ * NOTE: PNG output support may have not been enabled in the compiled version
+ * of libsaxbospiral that you have. If support is not enabled, the library
+ * boolean constant SXBP_PNG_SUPPORT will be set to false and the one public
+ * function defined in this library will return SXBP_NOT_IMPLEMENTED.
+ *
  *
  *
  * Copyright (C) 2016, Joshua Saxby joshua.a.saxby+TNOPLuc8vM==@gmail.com
@@ -22,10 +27,16 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 #include <assert.h>
+// only include these extra dependencies if support for PNG output was enabled
+#ifdef SAXBOSPIRAL_PNG_SUPPORT
 #include <stdlib.h>
 #include <string.h>
+#endif
 
+// only include libpng if support for it was enabled
+#ifdef SAXBOSPIRAL_PNG_SUPPORT
 #include <png.h>
+#endif
 
 #include "../saxbospiral.h"
 #include "../render.h"
@@ -36,6 +47,8 @@
 extern "C"{
 #endif
 
+// only define the following private functions if libpng support was enabled
+#ifdef SAXBOSPIRAL_PNG_SUPPORT
 // private custom libPNG buffer write function
 static void buffer_write_data(
     png_structp png_ptr, png_bytep data, png_size_t length
@@ -80,11 +93,13 @@ static void cleanup_png_lib(
         free(row);
     }
 }
+#endif // SAXBOSPIRAL_PNG_SUPPORT
 
 /*
  * given a bitmap_t struct and a pointer to a blank buffer_t, write the bitmap
  * data as a PNG image to the buffer, using libpng.
- * returns a status struct containing error information, if any
+ * returns a status struct containing error information
+ * returns SXBP_NOT_IMPLEMENTED if PNG support was not enabled
  *
  * Asserts:
  * - That bitmap.pixels is not NULL
@@ -96,6 +111,11 @@ sxbp_status_t sxbp_render_backend_png(
     // preconditional assertsions
     assert(bitmap.pixels != NULL);
     assert(buffer->bytes == NULL);
+    // only do PNG operations if support is enabled
+    #ifndef SAXBOSPIRAL_PNG_SUPPORT
+    // return SXBP_NOT_IMPLEMENTED
+    return SXBP_NOT_IMPLEMENTED;
+    #else
     // result status
     sxbp_status_t result;
     // init buffer
@@ -186,6 +206,7 @@ sxbp_status_t sxbp_render_backend_png(
     // status ok
     result = SXBP_OPERATION_OK;
     return result;
+    #endif // SAXBOSPIRAL_PNG_SUPPORT
 }
 
 #ifdef __cplusplus

saxbospiral/render_backends/backend_png.h

@@ -5,6 +5,11 @@
  * This compilation unit provides functionality to render a bitmap struct to a
  * PNG image (stored in a buffer).
  *
+ * NOTE: PNG output support may have not been enabled in the compiled version
+ * of libsaxbospiral that you have. If support is not enabled, the library
+ * boolean constant SXBP_PNG_SUPPORT will be set to false and the one public
+ * function defined in this library will return SXBP_NOT_IMPLEMENTED.
+ *
  *
  *
  * Copyright (C) 2016, Joshua Saxby joshua.a.saxby+TNOPLuc8vM==@gmail.com
@@ -35,7 +40,8 @@ extern "C"{
 /*
  * given a bitmap_t struct and a pointer to a blank buffer_t, write the bitmap
  * data as a PNG image to the buffer, using libpng.
- * returns a status struct containing error information, if any
+ * returns a status struct containing error information
+ * returns SXBP_NOT_IMPLEMENTED if PNG support was not enabled
  *
  * Asserts:
  * - That bitmap.pixels is not NULL

saxbospiral/saxbospiral.c

@@ -21,6 +21,8 @@
  * You should have received a copy of the GNU Affero General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+#include <stdbool.h>
+
 #include "saxbospiral.h"
 
 
@@ -35,6 +37,12 @@ const sxbp_version_t LIB_SXBP_VERSION = {
     .patch = SAXBOSPIRAL_VERSION_PATCH,
     .string = SAXBOSPIRAL_VERSION_STRING,
 };
+// flag for whether PNG output support has been compiled in based, on macro
+#ifdef SAXBOSPIRAL_PNG_SUPPORT
+const bool SXBP_PNG_SUPPORT = true;
+#else
+const bool SXBP_PNG_SUPPORT = false;
+#endif
 
 /*
  * computes a version_hash_t for a given version_t,

saxbospiral/saxbospiral.h

@@ -41,6 +41,8 @@ typedef struct sxbp_version_t {
 } sxbp_version_t;
 
 extern const sxbp_version_t LIB_SXBP_VERSION;
+// flag for whether PNG output support has been compiled in based, on macro
+extern const bool SXBP_PNG_SUPPORT;
 
 // used for indexing and comparing different versions in order
 typedef uint32_t sxbp_version_hash_t;
@@ -54,10 +56,11 @@ sxbp_version_hash_t sxbp_version_hash(sxbp_version_t version);
 // enum for function error information
 typedef enum sxbp_status_t {
     SXBP_STATE_UNKNOWN = 0, // unknown, the default state
+    SXBP_OPERATION_OK, // no problem
     SXBP_OPERATION_FAIL, // generic failure state
     SXBP_MALLOC_REFUSED, // memory allocation or re-allocation was refused
     SXBP_IMPOSSIBLE_CONDITION, // condition thought to be impossible detected
-    SXBP_OPERATION_OK, // no problem
+    SXBP_NOT_IMPLEMENTED, // function is not implemented / enabled
 } sxbp_status_t;
 
 // type for representing a cartesian direction