Re: [Tuxpaint-devel] Tux Paint 'Magic' tools turning into plugin architecture

[Bill K. <nb...@so...>]

On Tue, Jul 03, 2007 at 10:55:15PM -0700, Bill Kendrick wrote:
> 
> I'm putting together a basic (for now) plugin API in Tux Paint 0.9.18
> that will replace the hard-coded Magic tool code in tuxpaint.c.

BTW, here's the current API as I banged it out at a train station this
evening:

magic plugins must provide:
---------------------------
  int get_tool_count(void)
    return the number of Magic tools this plugin provides
    (below, 0 <= which < get_tool_count())

  char * get_name(int which)
    return the name of a/the magic tool (for button)

  SDL_Surface * get_icon(int which)
    return the icon of a/the magic tool (for button)

  char * get_description(int which)
    return the description of a/the magic tool (for Tux help text)

  int requires_colors(int which)
    return whether a/the magic tool accepts colors
    (activates color palette, or not)

  void set_color(Uint8 r, Uint8 g, Uint8 g)
    accept the color palette choice from Tux Paint
    (only called if requires_colors() for the current tool returned true)

  int init(void)
    initialization function; should load it the tool icon(s) and any
    other data;
    return 1 if success, 0 if failure (tool(s) will be disabled in Magic tool);
    happens once, at Tux Paint startup

  void shutdown(void)
    cleanup function; should free any alloc'd memory, icons, etc.;
    happens once, at Tux Paint shutdown

  void click(int which, SDL_Surface * snapshot, SDL_Surface * canvas,
             int x, int y)
    should affect 'canvas' at (x,y) location; may use 'snapshot' to fetch
    pixels from most recent undo buffer

  void drag(int which, SDL_Surface * snapshot, SDL_Surface * canvas,
            int ox, int oy, int x, int y)
    should affect 'canvas' between (ox,oy) and (x,y) locations;
    may use 'snapshot' to fetch pixels from most recent undo buffer


tp provides:
------------
  void line(SDL_Surface * snapshot, SDL_Surface * canvas,
            int x1, int y1, int x2, int y2, int step, FUNC callback)
    function that calls a callback between (x1,y1) and (x2,y2),
    stepping 'step' in between; sends an (x,y) and 'snapshot' and 'canvas'
    surfaces to the 'callback' function

  void playsound(Mix_Chunk * snd, int pan, int dist)
    function that plays a sound, panned left/right 'pan'
    and at distance 'dist'.  pan may be SNDPOS_LEFT, SNDPOS_CENTER or
    SNDPOS_RIGHT, and dist may be SNDDIST_NEAR.

  void putpixel(SDL_Surface * surf, int x, int y, Uint32 pixel)
    function that puts a pixel at an (x,y) position in a surface

  Uint32 getpixel(SDL_Surface * surf, int x, int y)
    function that returns a pixel value from an (x,y) position on a surface

  int in_circle(int x, int y, int radius)
    function that returns whether an x/y position (centered at (0,0)) is
    within a circle of 'radius'

  void show_progress_bar(void)
    draws the Tux Paint progress bar animation; use while you're busy

  void tuxpaint_version(int * major, int * minor, int * revision)
    returns the version of Tux Paint being used

  void special_notify(int flag)
    notifies tux paint of special events; SPECIAL_FLIP and SPECIAL_MIRROR
    flags may be sent

  float sRGB_to_linear_table[256]
    sRGB-to-linear look-up table

  unsigned char linear_to_sRGB(float linear)
    linear-to-sRGB look-up helper function



Note that the 'click/drag' stuff hasn't been implemented, nor has almost
_any_ of the TP side of things (except getpixel/putpixel/in_circle, to make
the 'Negative' tool happy).

And right now, inside src/tuxpaint.c, you'll find a lot of:

  #if 0 // MAGIC_ME
  ...
  #endif

wrapped around the old Magic tool code.


Hopefully I'll have more time to work on this on my ~8hrs of train
commutting on Thursday. :)

Enjoy!

-bill!

PS - Aside from making it easier for people like _us_ to add new Magic tools
to Tux Paint, my hope is that by providing an API, high school kids in
computer programming classes might get the chance to play with C and SDL
in a way that is fun and entertaining...  It would let Tux Paint, as a
project, span all they way from Preschool through to late High School,
if not early college.  Awesome, no!?