Expose all parameters of drawImage to Image()

[Jared-Sprague]

p5 image() maps directly to 2 of 3 valid usages of drawImage() this pull request adds the thrid and final valid usage as defined here: https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/drawImage

image(image, x, y);
image(image, x, y, width, weight)
image(image, sx, sy, sWidth, sHeight, x, y, width, height)

I've been using p5 to create some interactive games for the Kinect (https://github.com/mwcz/Kimotion), however one thing that p5 lacks that is essential for game creation is the ability to use sprite sheets for performance and efficiency. p5.play Sprites use image() to draw their image so the first step was adding the ability to use all the parameters of drawImage() in image(), and that's exactly what this Pull Request adds:
#941

See the live working examples here:
http://scripta.co/p5.js/examples/p5.Image/netherlandish_proverbs.html
http://scripta.co/p5.js/examples/p5.Image/animation.html
http://scripta.co/p5.js/examples/p5.Image/sprite-sheet.html

The new parameters are completely optional and follow the spec here: http://ow.ly/SDewA. Backward compatibility maintained and image() continues to work as it always has with default parameters, but you now also have the option to use the cropping parameters as well.

[brysonian]

I think this is great, however i'm a bit concerned about the switch in the meaning of arguments 2-5 between image(image, x, y, width, height) and image(image, sx, sy, sWidth, sHeight, dx, dy, dWidth, dHeight) I like that it matches exactly the canvas spec, but might it be confusing for new users that when used tot draw a crop those arguments specify the source not the destination? Would we gain some clarity with a separate sprite() function?

[Jared-Sprague]

Thank you for the feedback! I also thought hard about making this a separate function but in the end I decided not to for three reasons:

1. The usage of drawImage() is already very well documented, why change it in image()?
2. image() already maps directly to 2 of the 3 valid usages of drawImage(), we are just simply adding the third usage.
3. All of the current p5.js examples, references, and tutorials continue to work exactly as they always have, so new users won't be confused. But advanced users will have all the optional parameters available to them now for drawImage() if they want to use them.

I also like how image() is a generic function, as I think the ability to draw just part of an image has many creative uses other than just sprites.

Thank you!

[Jared-Sprague]

Here is a live example of an animation using a single image and just one call to image() in draw()
http://scripta.co/p5.js/examples/p5.Image/animation.html

[Jared-Sprague]

Finished another example usage. This feature isn't just for sprites!
http://scripta.co/p5.js/examples/p5.Image/netherlandish_proverbs.html

[indefinit]

no comments to add on implementation but just - wow, so cool! Awesome to see how powerful something like this is.

[Jared-Sprague]

@indefinit Thank you! Implementation is easy as image() is implemented using drawImage(). All I had to do was pass through the parameters of image() to drawImage() and add a little bit of logic to handle parameter defaults. Very little code. The majority of my pull request #941 is unit tests and additions to examples.

[lmccart]

closed with #941