led-matrix-c.h

/* -*- 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. You still need to call the final link with
 *
 * See examples-api-use/c-example.c for a usage example.
 *
 */
#ifndef RPI_RGBMATRIX_C_H
#define RPI_RGBMATRIX_C_H

#include <stdint.h>
#include <stdio.h>

#ifdef  __cplusplus
extern "C" {
#endif

struct RGBLedMatrix;
struct LedCanvas;

/**
 * Parameters to create a new matrix.
 *
 * To get the defaults, non-set values have to be initialized to zero, so you
 * should zero out this struct before setting anything.
 */
struct RGBLedMatrixOptions {
  /*
   * Name of the hardware mapping used. If passed NULL here, the default
   * is used.
   */
  const char *hardware_mapping;

  /* The "rows" are the number of rows supported by the display, so 32 or 16.
   * Default: 32.
   * Corresponding flag: --led-rows
   */
  int rows;

  /* The chain_length is the number of displays daisy-chained together
   * (output of one connected to input of next). Default: 1
   * Corresponding flag: --led-chain
   */
  int chain_length;

  /* The number of parallel chains connected to the Pi; in old Pis with 26
   * GPIO pins, that is 1, in newer Pis with 40 interfaces pins, that can
   * also be 2 or 3. The effective number of pixels in vertical direction is
   * then thus rows * parallel. Default: 1
   * Corresponding flag: --led-parallel
   */
  int parallel;

  /* Set PWM bits used for output. Default is 11, but if you only deal with
   * limited comic-colors, 1 might be sufficient. Lower require less CPU and
   * increases refresh-rate.
   * Corresponding flag: --led-pwm-bits
   */
  int pwm_bits;

  /* Change the base time-unit for the on-time in the lowest
   * significant bit in nanoseconds.
   * Higher numbers provide better quality (more accurate color, less
   * ghosting), but have a negative impact on the frame rate.
   * Corresponding flag: --led-pwm-lsb-nanoseconds
   */
  int pwm_lsb_nanoseconds;

  /* The initial brightness of the panel in percent. Valid range is 1..100
   * Corresponding flag: --led-brightness
   */
  int brightness;

  /* Scan mode: 0=progressive, 1=interlaced
   * Corresponding flag: --led-scan-mode
   */
  int scan_mode;

  /* In case the internal sequence of mapping is not "RGB", this contains the
   * real mapping. Some panels mix up these colors.
   */
  const char *led_rgb_sequence;     /* Corresponding flag: --led-rgb-sequence */

  /** The following are boolean flags, all off by default **/

  /* Allow to use the hardware subsystem to create pulses. This won't do
   * anything if output enable is not connected to GPIO 18.
   * Corresponding flag: --led-hardware-pulse
   */
  unsigned disable_hardware_pulsing:1;
  unsigned show_refresh_rate:1;  /* Corresponding flag: --led-show-refresh    */
  // unsigned swap_green_blue:1; /* deprecated, use led_sequence instead */
  unsigned inverse_colors:1;     /* Corresponding flag: --led-inverse         */
};

/**
 * Universal way to create and initialize a matrix.
 * The "options" struct (if not NULL) contains all default configuration values
 * chosen by the programmer to create the matrix.
 *
 * If "argc" and "argv" are provided, this function also reads command line
 * flags provided, that then can override any of the defaults given.
 * The arguments that have been used from the command line are removed from
 * the argv list (and argc is adjusted) - that way these don't mess with your
 * own command line handling.
 *
 * The actual options used are filled back into the "options" struct if not
 * NULL.
 *
 * Usage:
 * ----------------
 * int main(int argc, char **argv) {
 *   struct RGBLedMatrixOptions options;
 *   memset(&options, 0, sizeof(options));
 *   options.rows = 32;            // You can set defaults if you want.
 *   options.chain_length = 1;
 *   struct RGBLedMatrix *matrix = led_matrix_create_from_options(&options,
 *                                                                &argc, &argv);
 *   if (matrix == NULL) {
 *      led_matrix_print_flags(stderr);
 *      return 1;
 *   }
 *   // do additional commandline handling; then use matrix...
 * }
 * ----------------
 */
struct RGBLedMatrix *led_matrix_create_from_options(
             struct RGBLedMatrixOptions *options, int *argc, char ***argv);


/**
 * Print available LED matrix options.
 */
void led_matrix_print_flags(FILE *out);

/**
 * Simple form of led_matrix_create_from_options() with just the few
 * main options. 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 memory.
 * Always call before the end of the program to properly reset the hardware
 */
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