Usability tweaks for the canvas.

[Kevinpgalligan]

This adds a function called (draw-canvas ...) so that people don't need to include boilerplate code every time they want to draw a canvas. Also exports canvas-width, canvas-height, image-width and image-height, which I think are useful to have. Finally, it updates the canvas documentation. I left the "stars" example untouched in case it's helpful to see how to draw a canvas using lower-level functions.

Example:

(defsketch test
      ((title "Canvas test")
       (size-scale 1))
    (let ((cv (make-canvas 2 2)))
      (canvas-paint cv +blue+ 0 0)
      (canvas-paint cv +red+ 0 1)
      (canvas-paint cv +green+ 1 0)
      (canvas-paint cv +white+ 1 1)
      (canvas-lock cv)
      (let ((draw-size (* size-scale 2)))
        (draw-canvas cv :width draw-size :height draw-size
                     :min-filter :linear :mag-filter :linear)))
    (setf size-scale (mod (1+ size-scale) 50)))

(I'm not sure how the min & mag filters are supposed to work, but even when I pass :nearest, it still looks like a linear interpolation between the colours).

[Kevinpgalligan]

Woops, I accidentally included my documentation update in this. I'll fix that tomorrow.

[Gleefre]

I'm not sure how the min & mag filters are supposed to work

Those should be passed to canvas-lock, as they are not updated when image is locked.

[Kevinpgalligan]

Okay, I've removed the accidental commit. Also confirmed that passing :min-filter and :mag-filter to (canvas-lock ...) gets it to behave in the expected way, and updated the documentation of (draw-canvas ...) to make that usage more clear.

[vydd]

@Kevinpgalligan sorry for not asking earlier; it looks that we'll now have three ways of drawing things:

DRAW method that sketch classes are using (normally not overriden) IMAGE for drawing images DRAW-CANVAS coming from this PR

--- do you think all of these could use DRAW? (we could make it work for images in a separate PR and still support the old API for compat)

[Kevinpgalligan]

Hmm, I think I can de-duplicate the code that is shared between IMAGE and DRAW-CANVAS. I'm not sure that I see how DRAW is related, though? From my understanding, it's a method that each sketch implements that is called once per drawing loop. Within the DRAW method, i.e. the sketch body, we use functions like IMAGE, DRAW-CANVAS, RECT, LINE, etc. to draw actual shapes or objects. I'm not sure how they can be unified with DRAW or if it would make sense to do so, unless you're referring to a different DRAW interface.

Edit: I think I see what you mean. We would be able to call (draw sketch), (draw canvas) and (draw image). But I think the image and canvas drawing functions require extra information that makes them incompatible with (draw sketch), i.e. the position, the width, the height. Unless we add &allow-extra-keys to the generic interface, then add those extra arguments as keyword args to the implementing methods. That could indeed be a nicer interface, less words to remember. Let me think it over.

[vydd]

@Kevinpgalligan DRAW is already defined with &allow-extra-keys. It's already used with figures, but figures need a big revamp before they are useful.

[Kevinpgalligan]

I like your suggestion, soDRAW is now used to draw the canvas. Updated the corresponding part of the docs. Also added a TODO so that we don't forget to refactor when adding a DRAW method for images. I'm happy to do that myself once this pull request has been merged.

[vydd]

Thanks!