Refine drawing API semantics to pass drawing * instead of void *

This changes the drawing API so that implementations receive a
`drawing *` pointer with each call, instead of a `void *` pointer as
they did previously. The `void *` context pointer has been moved to be
a member of the `drawing` structure (which has been made public), from
which it can be retrieved via the new `GET_HANDLE_AS_TYPE()` macro. To
signal this breaking change to downstream front end authors, I've
added a version number to the `drawing_api` struct, which will
hopefully force them to notice.

The motivation for this change is the upcoming introduction of a
draw_polygon_fallback() function, which will use a series of calls to
draw_line() to perform software polygon rasterization on platforms
without a native polygon fill primitive. This function is fairly
large, so I desired that it not be included in the binary
distribution, except on platforms which require it (e.g. my Rockbox
port). One way to achieve this is via link-time optimization (LTO,
a.k.a. "interprocedural optimization"/IPO), so that the code is
unconditionally compiled (preventing bit-rot) but only included in the
linked executable if it is actually referenced from elsewhere.
Practically, this precludes the otherwise straightforward route of
including a run-time check of the `draw_polygon` pointer in the
drawing.c middleware. Instead, Simon recommended that a front end be
able to set its `draw_polygon` field to point to
draw_polygon_fallback(). However, the old drawing API's semantics of
passing a `void *` pointer prevented this from working in practice,
since draw_polygon_fallback(), implemented in middleware, would not be
able to perform any drawing operations without a `drawing *` pointer;
with the new API, this restriction is removed, clearing the way for
that function's introduction.

This is a breaking change for front ends, which must update their
implementations of the drawing API to conform. The migration process
is fairly straightforward: every drawing API function which previously
took a `void *` context pointer should be updated to take a `drawing *`
pointer in its place. Then, where each such function would have
previously casted the `void *` pointer to a meaningful type, they now
instead retrieve the context pointer from the `handle` field of the
`drawing` structure. To make this transition easier, the
`GET_HANDLE_AS_TYPE()` macro is introduced to wrap the context pointer
retrieval (see below for usage).

As an example, an old drawing API function implementation would have
looked like this:

void frontend_draw_func(void *handle, ...)
{
    frontend *fe = (frontend *)handle;
    /* do stuff with fe */
}

After this change, that function would be rewritten as:

void frontend_draw_func(drawing *dr, ...)
{
    frontend *fe = GET_HANDLE_AS_TYPE(dr, frontend);
    /* do stuff with fe */
}

I have already made these changes to all the in-tree front ends, but
out-of-tree front ends will need to follow the procedure outlined
above.

Simon pointed out that changing the drawing API function pointer
signatures to take `drawing *` instead of `void *` results only in a
compiler warning, not an outright error. Thus, I've introduced a
version field to the beginning of the `drawing_api` struct, which will
cause a compilation error and hopefully force front ends to notice
this. This field should be set to 1 for now. Going forward, it will
provide a clear means of communicating future breaking API changes.

emcc.c

@@ -456,22 +456,22 @@ static void ids_changed(void *ignored)
  * drawing functions. (Well, half of it; the other half is on the JS
  * side.)
  */
-static void js_start_draw(void *handle)
+static void js_start_draw(drawing *dr)
 {
     js_canvas_start_draw();
 }
 
-static void js_clip(void *handle, int x, int y, int w, int h)
+static void js_clip(drawing *dr, int x, int y, int w, int h)
 {
     js_canvas_clip_rect(x, y, w, h);
 }
 
-static void js_unclip(void *handle)
+static void js_unclip(drawing *dr)
 {
     js_canvas_unclip();
 }
 
-static void js_draw_text(void *handle, int x, int y, int fonttype,
+static void js_draw_text(drawing *dr, int x, int y, int fonttype,
                          int fontsize, int align, int colour,
                          const char *text)
 {
@@ -491,31 +491,31 @@ static void js_draw_text(void *handle, int x, int y, int fonttype,
                         fontsize, fonttype == FONT_FIXED, text);
 }
 
-static void js_draw_rect(void *handle, int x, int y, int w, int h, int colour)
+static void js_draw_rect(drawing *dr, int x, int y, int w, int h, int colour)
 {
     js_canvas_draw_rect(x, y, w, h, colour);
 }
 
-static void js_draw_line(void *handle, int x1, int y1, int x2, int y2,
+static void js_draw_line(drawing *dr, int x1, int y1, int x2, int y2,
                          int colour)
 {
     js_canvas_draw_line(x1, y1, x2, y2, 1, colour);
 }
 
-static void js_draw_thick_line(void *handle, float thickness,
+static void js_draw_thick_line(drawing *dr, float thickness,
                                float x1, float y1, float x2, float y2,
                                int colour)
 {
     js_canvas_draw_line(x1, y1, x2, y2, thickness, colour);
 }
 
-static void js_draw_poly(void *handle, const int *coords, int npoints,
+static void js_draw_poly(drawing *dr, const int *coords, int npoints,
                          int fillcolour, int outlinecolour)
 {
     js_canvas_draw_poly(coords, npoints, fillcolour, outlinecolour);
 }
 
-static void js_draw_circle(void *handle, int cx, int cy, int radius,
+static void js_draw_circle(drawing *dr, int cx, int cy, int radius,
                            int fillcolour, int outlinecolour)
 {
     js_canvas_draw_circle(cx, cy, radius, fillcolour, outlinecolour);
@@ -526,7 +526,7 @@ struct blitter {
     int w, h;                          /* easier to retain here */
 };
 
-static blitter *js_blitter_new(void *handle, int w, int h)
+static blitter *js_blitter_new(drawing *dr, int w, int h)
 {
     blitter *bl = snew(blitter);
     bl->w = w;
@@ -535,7 +535,7 @@ static blitter *js_blitter_new(void *handle, int w, int h)
     return bl;
 }
 
-static void js_blitter_free(void *handle, blitter *bl)
+static void js_blitter_free(drawing *dr, blitter *bl)
 {
     js_canvas_free_blitter(bl->id);
     sfree(bl);
@@ -569,7 +569,7 @@ static void trim_rect(int *x, int *y, int *w, int *h)
     *h = y1 - y0;
 }
 
-static void js_blitter_save(void *handle, blitter *bl, int x, int y)
+static void js_blitter_save(drawing *dr, blitter *bl, int x, int y)
 {
     int w = bl->w, h = bl->h;
     trim_rect(&x, &y, &w, &h);
@@ -577,7 +577,7 @@ static void js_blitter_save(void *handle, blitter *bl, int x, int y)
         js_canvas_copy_to_blitter(bl->id, x, y, w, h);
 }
 
-static void js_blitter_load(void *handle, blitter *bl, int x, int y)
+static void js_blitter_load(drawing *dr, blitter *bl, int x, int y)
 {
     int w = bl->w, h = bl->h;
     trim_rect(&x, &y, &w, &h);
@@ -585,30 +585,31 @@ static void js_blitter_load(void *handle, blitter *bl, int x, int y)
         js_canvas_copy_from_blitter(bl->id, x, y, w, h);
 }
 
-static void js_draw_update(void *handle, int x, int y, int w, int h)
+static void js_draw_update(drawing *dr, int x, int y, int w, int h)
 {
     trim_rect(&x, &y, &w, &h);
     if (w > 0 && h > 0)
         js_canvas_draw_update(x, y, w, h);
 }
 
-static void js_end_draw(void *handle)
+static void js_end_draw(drawing *dr)
 {
     js_canvas_end_draw();
 }
 
-static void js_status_bar(void *handle, const char *text)
+static void js_status_bar(drawing *dr, const char *text)
 {
     js_canvas_set_statusbar(text);
 }
 
-static char *js_text_fallback(void *handle, const char *const *strings,
+static char *js_text_fallback(drawing *dr, const char *const *strings,
                               int nstrings)
 {
     return dupstr(strings[0]); /* Emscripten has no trouble with UTF-8 */
 }
 
 static const struct drawing_api js_drawing = {
+    1,
     js_draw_text,
     js_draw_rect,
     js_draw_line,