[Tuxpaint-devel] Tux Paint Magic API change to `set_color()`

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

When using the Zoom and Perspective tools, the currently-chosen
color is used as a solid background color "behind" the altered
(e.g., shrunk via zoom) version of your drawing.

You can change the color at any time, however it is not reflected
in the picture until you adjust the zoom factor or perspective
angles.

I've rectified this, which involved making Magic tools'
"XYZ_set_color()" function accept more arguments.  (Before, it was
only getting a "magic_api *" and the three "Uint8" values
corresponding to the red, green, and blue values of the new color.)

Now, it also receives an "int" corresponding to which of the Magic
tool object's individual tools is being used (I usually give the
variable the name "which"), a snapshot of the canvas, and the
canvas itself (both "SDL_Surface *"s), and an "SDL_Rect *"
(I usually name it "update_rect") to send back the area of the
canvas that was updated, so Tux Paint can refresh it.

I've updated _all_ other magic tool source (.c) files, but two
things:

(1) These new, as-of-yet unused (and in most cases, never-to-be used)
    arguments are not flagged with "ATTRIBUTE_UNUSED", so building
    Tux Paint will result in a lot of "unused parameter" warnings.

    Also, I went on a copy/paste spree to add the new variables,
    so many places where the r/g/b value variables had that flag
    lost it, so now they are _also_ going to throw "unused parameter"
    warnings.

    I'll try to go back in and clean this up soon.  Bedtime now, though!

(2) While we look for whether or not all Magic API functions exist in
    the compiled object files _at all_, we do not currently check that
    they're actually accepting the arguments we feeding into them!

    So for example, if I had left any "set_color()" functions
    accepting only the API pointer and RGB values, they would not
    get fed a couple of "SDL_Surface *" pointers, and use their
    values as some of the color variables. :-[

    We're using SDL_LoadFunction(), which just returns a "void*",
    which we cast to an expected function declaration.
    I'm not sure how (or whether it's even feasible) to try and check
    that the function that we're loading from the Magic's object file
    actually accepts parameters we expect it to, and in the right
    order. [*]

    If anyone has clever ideas here, I'm all ears.


[*] For a while, I've pondered making Tux Paint's magic API more
    event-driven than function-based (like Qualcomm BREW was on
    mobile devices).

    In other words, each object would have an overarching function
    that accepted events, and responds to them (or ignores them) as
    needed.

    That way, if for example a Magic tool doesn't use colors at all,
    it could just ignore the incoming event (not even test for it
    in an "if" or "switch/case").  And there wouldn't be any need
    to waste a bunch of space declaring an empty function like:

      void XYZ_set_color(...<lots of arguments>...)
      {
      }

    This would require a MAJOR overhaul to _every_ Magic source file.
    And since the API changes rarely (I've now bumped it up to
    "version 7", and it took about 15 years to get there :-) ), I'm
    not sure it's worth the effort.  We don't really have people
    scrambling to write Magic tools.


Anyway, just an FYI /slash/ late night ramble...

-- 
-bill!
Sent from my computer