Summary

Based on the discussion at https://discourse.matplotlib.org/t/method-to-add-transparency-to-a-saved-bufferregion/23121 (thanks @raphaelquast), I realized it may be possible to get rid of the internal BufferRegion type and restore_region, in favor of copy_from_bbox returning a tpl = (x, y, rgba_array) tuple and using canvas.get_renderer().draw_image(gc, x, y, rgba_array) to restore the region. draw_image could specifically add support for passing gc = None (i.e. create a throwaway gc just for this call), and then the restore call would be canvas.get_renderer().draw_image(None, *tpl) which seems just fine. Or we can just keep restore_region as a canvas method (on FigureCanvasBase, without need of being overridden by backends) which does the right draw_image call on the renderer, only getting rid of Renderer.restore_region.

Currently, restore_region just blindly copies the BufferRegion contents, without doing any alpha compositing; the new approach would instead alpha-composite against whatever was here before. However, most uses of copy_from_bbox/restore_region suppose opaque regions anyways, and callers can also modify the rgba_array's alpha channel as desired before calling draw_image. Hopefully the extra alpha compositing wouldn't be too much of a slowdown, or we could always extend draw_image to support rgb (not rgba) inputs and detect that in this case it can go through a fast path without alpha compositing.

The advantage of such a change would be to simplify the backend API (e.g. for third party backends), including removing the undocumented BufferRegion type. (Probably the correct transition path would be to first make the BufferRegion type fully opaque, by deprecating all its public methods.)

attn @tacaswell as I believe you have written quite a bit of docs about blitting.

Proposed fix

No response