o Add a C-API (experimental right now, don't use yet)

o Provide a shared library

include/led-matrix-c.h

@@ -0,0 +1,109 @@
+// -*- mode: c; c-basic-offset: 2; indent-tabs-mode: nil; -*-
+// Copyright (C) 2013 Henner Zeller <h.zeller@acm.org>
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation version 2.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <http://gnu.org/licenses/gpl-2.0.txt>
+
+// Controlling 16x32 or 32x32 RGB matrixes via GPIO. It allows daisy chaining
+// of a string of these, and also connecting a parallel string on newer
+// Raspberry Pis with more GPIO pins available.
+//
+// This is a C-binding (for the C++ library) to allow easy binding and
+// integration with other languages. The symbols are exported in librgbmatrix.a
+// and librgbmatrix.so.
+//
+// Usage: -------
+//   struct RGBLedMatrix *matrix = led_matrix_create(32, 3, 3);
+//
+//   // Get canvas and use it for drawing:
+//   struct LedCanvas *canvas = led_matrix_get_canvas(matrix);
+//   led_canvas_set_pixel(canvas, x, y, red, green, blue);
+//
+//   // Make sure to always call led_matrix_delete() in the end to reset the
+//   // display. Installing signal handlers for defined exit is a good idea.
+//   led_matrix_delete(matrix);
+// ---------------
+// For double-buffering, see example at led_matrix_swap_on_vsync() documentation.
+//
+#ifndef RPI_RGBMATRIX_C_H
+#define RPI_RGBMATRIX_C_H
+
+#include <stdint.h>
+
+#ifdef  __cplusplus
+extern "C" {
+#endif
+
+struct RGBLedMatrix;
+struct LedCanvas;
+
+// Create matrix and initialize hardware. Returns NULL if that was not
+// possible.
+// The "rows" are the number of rows supported by the display, so 32, 16 or 8.
+//
+// Number of "chained_display"s tells many of these are daisy-chained together
+// (output of one connected to input of next).
+//
+// The "parallel_display" number determines if there is one or two displays
+// connected in parallel to the GPIO port - this only works with newer
+// Raspberry Pi that have 40 interface pins.
+//
+// This creates a realtime thread and requires root access to access the GPIO
+// pins.
+// So if you run this in a daemon, this should be called after becoming a
+// daemon (as fork/exec stops threads) and before dropping privileges.
+struct RGBLedMatrix *led_matrix_create(int rows, int chained, int parallel);
+
+// Stop matrix and free.
+void led_matrix_delete(struct RGBLedMatrix *matrix);
+
+// Get active canvas from LED matrix for you to draw on.
+// Ownership of returned pointer stays with the matrix, don't free().
+struct LedCanvas *led_matrix_get_canvas(struct RGBLedMatrix *matrix);
+
+// Return size of canvas.
+void led_canvas_get_size(const struct LedCanvas *canvas,
+                         int *width, int *height);
+
+// Set pixel at (x, y) with color (r,g,b).
+void led_canvas_set_pixel(struct LedCanvas *canvas, int x, int y,
+			  uint8_t r, uint8_t g, uint8_t b);
+
+// Clear screen (black).
+void led_canvas_clear(struct LedCanvas *canvas);
+
+// Fill matrix with given color.
+void led_canvas_fill(struct LedCanvas *canvas, uint8_t r, uint8_t g, uint8_t b);
+
+// -- API to provide double-buffering.
+
+// Create a new canvas to be used with led_matrix_swap_on_vsync()
+// Ownership of returned pointer stays with the matrix, don't free().
+struct LedCanvas *led_matrix_create_offscreen_canvas(struct RGBLedMatrix *matrix);
+
+// Swap the given canvas (created with create_offscreen_canvas) with the
+// currently active canvas on vsync (blocks until vsync is reached).
+// Returns the previously active canvas. So with that, you can create double
+// buffering.
+//   struct LedCanvas *offscreen = led_matrix_create_offscreen_canvas(...);
+//   led_canvas_set_pixel(offscreen, ...);   // not shown until swap-on-vsync
+//   offscreen = led_matrix_swap_on_vsync(matrix, offscreen);
+//   // The returned buffer, assigned to offscreen, is now the inactive buffer
+//   // fill, then swap again.
+struct LedCanvas *led_matrix_swap_on_vsync(struct RGBLedMatrix *matrix,
+                                           struct LedCanvas *canvas);
+
+#ifdef  __cplusplus
+}  // extern C
+#endif
+
+#endif  // RPI_RGBMATRIX_C_H

lib/Makefile

@@ -3,8 +3,8 @@
 # So
 #   -lrgbmatrix
 ##
-OBJECTS=gpio.o led-matrix.o framebuffer.o thread.o bdf-font.o graphics.o transformer.o
-TARGET=librgbmatrix.a
+OBJECTS=gpio.o led-matrix.o framebuffer.o thread.o bdf-font.o graphics.o transformer.o led-matrix-c.o
+TARGET=librgbmatrix
 
 ###
 # After you change any of the following DEFINES, make sure to 'make clean'
@@ -81,9 +81,14 @@ DEFINES+=-DRGB_SLOWDOWN_GPIO=1
 INCDIR=../include
 CXXFLAGS=-Wall -O3 -g -fPIC $(DEFINES)
 
-$(TARGET) : $(OBJECTS)
+all : $(TARGET).a $(TARGET).so.1
+
+$(TARGET).a : $(OBJECTS)
 	ar rcs $@ $^
 
+$(TARGET).so.1 : $(OBJECTS)
+	gcc -shared -Wl,-soname,$@ -o $@ $^ -lpthread  -lrt -lm -lpthread
+
 led-matrix.o: led-matrix.cc $(INCDIR)/led-matrix.h
 thread.o : thread.cc $(INCDIR)/thread.h
 framebuffer.o: framebuffer.cc framebuffer-internal.h
@@ -93,7 +98,7 @@ graphics.o: graphics.cc utf8-internal.h
 	$(CXX) -I$(INCDIR) $(CXXFLAGS) -c -o $@ $<
 
 clean:
-	rm -f $(OBJECTS) $(TARGET)
+	rm -f $(OBJECTS) $(TARGET).a $(TARGET).so.1
 
 compiler-flags: FORCE
 	@echo '$(CXXFLAGS)' | cmp -s - $@ || echo '$(CXXFLAGS)' > $@

lib/led-matrix-c.cc

@@ -0,0 +1,86 @@
+// -*- mode: c++; c-basic-offset: 2; indent-tabs-mode: nil; -*-
+// Copyright (C) 2013 Henner Zeller <h.zeller@acm.org>
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation version 2.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <http://gnu.org/licenses/gpl-2.0.txt>
+//
+// C-bridge for led matrix.
+#include "led-matrix-c.h"
+
+#include "led-matrix.h"
+#include "gpio.h"
+
+// Our opaque dummy structs to communicate with the c-world
+struct RGBLedMatrix {};
+struct LedCanvas {};
+
+static rgb_matrix::RGBMatrix *to_matrix(struct RGBLedMatrix *matrix) {
+  return reinterpret_cast<rgb_matrix::RGBMatrix*>(matrix);
+}
+static struct RGBLedMatrix *from_matrix(rgb_matrix::RGBMatrix *matrix) {
+  return reinterpret_cast<struct RGBLedMatrix*>(matrix);
+}
+
+static rgb_matrix::FrameCanvas *to_canvas(struct LedCanvas *canvas) {
+  return reinterpret_cast<rgb_matrix::FrameCanvas*>(canvas);
+}
+static struct LedCanvas *from_canvas(rgb_matrix::FrameCanvas *canvas) {
+  return reinterpret_cast<struct LedCanvas*>(canvas);
+}
+
+struct RGBLedMatrix *led_matrix_create(int rows, int chained, int parallel) {
+  static rgb_matrix::GPIO gpio;
+  if (!gpio.Init()) {
+    return NULL;
+  }
+  rgb_matrix::RGBMatrix *matrix = new rgb_matrix::RGBMatrix(&gpio, rows, chained,
+                                                            parallel);
+  return from_matrix(matrix);
+}
+
+void led_matrix_delete(struct RGBLedMatrix *matrix) {
+  delete to_matrix(matrix);
+}
+
+struct LedCanvas *led_matrix_get_canvas(struct RGBLedMatrix *matrix) {
+  return from_canvas(to_matrix(matrix)->SwapOnVSync(NULL));
+}
+
+struct LedCanvas *led_matrix_create_offscreen_canvas(struct RGBLedMatrix *m) {
+  return from_canvas(to_matrix(m)->CreateFrameCanvas());
+}
+
+struct LedCanvas *led_matrix_swap_on_vsync(struct RGBLedMatrix *matrix,
+                                           struct LedCanvas *canvas) {
+  return from_canvas(to_matrix(matrix)->SwapOnVSync(to_canvas(canvas)));
+}
+
+void led_canvas_get_size(const struct LedCanvas *canvas,
+                         int *width, int *height) {
+  rgb_matrix::FrameCanvas *c = to_canvas((struct LedCanvas*)canvas);
+  if (c == NULL ) return;
+  if (width != NULL) *width = c->width();
+  if (height != NULL) *height = c->height();
+}
+
+void led_canvas_set_pixel(struct LedCanvas *canvas, int x, int y,
+			  uint8_t r, uint8_t g, uint8_t b) {
+  to_canvas(canvas)->SetPixel(x, y, r, g, b);
+}
+
+void led_canvas_clear(struct LedCanvas *canvas) {
+  to_canvas(canvas)->Clear();
+}
+
+void led_canvas_fill(struct LedCanvas *canvas, uint8_t r, uint8_t g, uint8_t b) {
+  to_canvas(canvas)->Fill(r, g, b);
+}

python/README.md

@@ -22,4 +22,4 @@ Using the library
       myMatrix = RGBMatrix(rows, chains, parallel)
       myMatrix.Fill(255, 0, 0)
       time.sleep(5)
-      myMatrix.Clear()
+      myMatrix.Clear()