Support for 3D coordinate on Image

src/image/loading_displaying.js

@@ -1070,6 +1070,108 @@ function _sAssign(sVal, iVal) {
  * }
  * </code>
  * </div>
+ * <div>
+ * <code>
+ * let img;
+ *
+ * function preload() {
+ *   img = loadImage('assets/moonwalk.jpg');
+ * }
+ *
+ * function setup() {
+ *   // Create a 3D canvas
+ *   background(200);
+ *   createCanvas(400, 400, WEBGL);
+ * }
+ * function draw() {
+ *   image(img, 0, 0, -100);
+ *   describe('An image at the center 100 units away from the camera');
+ * }
+ * </code>
+ * </div>
+ *
+ * <div>
+ * <code>
+ * let img;
+ * function preload() {
+ *   img = loadImage('assets/moonwalk.jpg');
+ * }
+ *
+ * function setup() {
+ *   // Create a 3D canvas
+ *   createCanvas(400, 400, WEBGL);
+ * }
+ *
+ * function draw() {
+ *   background(200);
+ *   image(img, 0, 0, 400 , 300 , 300);
+ *   describe('Scale image 300 by 300 and zoomin 400 units');
+ * }
+ * </code>
+ * </div>
+ *
+ * <div>
+ * <code>
+ * let img;
+ * function preload() {
+ *   img = loadImage('assets/moonwalk.jpg');
+ * }
+ *
+ * function setup() {
+ *   // Create a 3D canvas
+ *   createCanvas(400, 400, WEBGL);
+ * }
+ *
+ * function draw() {
+ *   background(200);
+ *   image(img, 0, 0, -400 , 300 , 300);
+ *   describe('Scale image 300 by 300 and zoomout 400 units');
+ * }
+ * </code>
+ * </div>
+ *
+ * <div>
+ * <code>
+ * let img;
+ * function preload() {
+ *   img = loadImage('assets/moonwalk.jpg');
+ * }
+ *
+ * function setup() {
+ *   // Create a 3D canvas
+ *   createCanvas(400, 400, WEBGL);
+ * }
+ *
+ * function draw() {
+ *   background(200);
+ *   image(img, 0, 0, 0, 400, 400,500, 100, 200, 200);
+ *   describe('Draw a subsection of the image from 500 by 100 units position at the center with size 400x400');
+ * }
+ * </code>
+ * </div>
+ *
+ * <div>
+ * <code>
+ * let img;
+ * function preload() {
+ *   img = loadImage('assets/moonwalk.jpg');
+ * }
+ *
+ * function setup() {
+ *   // Create a 3D canvas
+ *   createCanvas(400, 400, WEBGL);
+ * }
+ *
+ * function draw() {
+ *   background(200);
+ *   image(img, 0, 0, -200, 400, 400,500, 100, 200, 200);
+ *   describe('Draw a subsection of the image from 500 by 100 units position at the center with size 400x400 and zoomedout by 200 units');
+ * }
+ *
+ * </code>
+ * </div>
+ *
+ *
  */
 /**
  * @method image
@@ -1078,6 +1180,8 @@ function _sAssign(sVal, iVal) {
  *                           rectangle in which to draw the source image
  * @param  {Number}   dy     the y-coordinate of the destination
  *                           rectangle in which to draw the source image
+ * @param  {Number}   dz     the z-coordinate (depth) of the destination
+ *                           rectangle in which to draw the source image (WEBGL only)
  * @param  {Number}   dWidth  the width of the destination rectangle
  * @param  {Number}   dHeight the height of the destination rectangle
  * @param  {Number}   sx     the x-coordinate of the subsection of the source
@@ -1097,6 +1201,7 @@ p5.prototype.image = function(
   img,
   dx,
   dy,
+  dz,
   dWidth,
   dHeight,
   sx,
@@ -1110,6 +1215,23 @@ p5.prototype.image = function(
   // set defaults per spec: https://goo.gl/3ykfOq
 
   p5._validateParameters('image', arguments);
+  // check for P5 Graphics instance
+  let isP5G = img instanceof p5.Graphics ? true : false;
+  // check for P5 Framebuffer instance
+  let isP5Fbo = img instanceof p5.Framebuffer ? true : false;
+
+  if(this._renderer instanceof p5.RendererGL === false){
+    // From the 3rd arguement shift the assingment one position to the right
+    yAlign = xAlign;
+    xAlign = fit;
+    fit = sHeight;
+    sHeight = sWidth;
+    sWidth = sy;
+    sy = sx;
+    sx = dHeight;
+    dHeight = dWidth;
+    dWidth = dz;
+  }
 
   let defW = img.width;
   let defH = img.height;
@@ -1175,18 +1297,37 @@ p5.prototype.image = function(
     _sh
   );
 
-  // tint the image if there is a tint
-  this._renderer.image(
-    img,
-    vals.sx,
-    vals.sy,
-    vals.sw,
-    vals.sh,
-    vals.dx,
-    vals.dy,
-    vals.dw,
-    vals.dh
-  );
+  //if it is not graphics nor framebuffer but WEGL instance
+  //default to use 3D rendering
+  if (this._renderer instanceof p5.RendererGL && !isP5G && !isP5Fbo) {
+    if (dz === undefined){dz = 0;}
+    this._renderer.image3D(
+      img,
+      vals.sx,
+      vals.sy,
+      dz,
+      vals.sw,
+      vals.sh,
+      vals.dx,
+      vals.dy,
+      vals.dw,
+      vals.dh
+    );
+  }else {
+    // tint the image if there is a tint
+    // Default 2D rendering
+    this._renderer.image(
+      img,
+      vals.sx,
+      vals.sy,
+      vals.sw,
+      vals.sh,
+      vals.dx,
+      vals.dy,
+      vals.dw,
+      vals.dh
+    );
+  }
 };
 
 /**

src/webgl/p5.RendererGL.js

@@ -2391,6 +2391,44 @@ p5.RendererGL = class RendererGL extends p5.Renderer {
 
     return triangleVerts;
   }
+
+  image3D(img,sx,sy,sz,sWidth,sHeight,dx,dy,dWidth,dHeight) {
+    const viewport = this.GL.getParameter(this.GL.VIEWPORT);
+    const width = viewport[2];
+    const height = viewport[3];
+    dx = (-width / 2) + dx;
+    dy = (-height / 2) + dy;
+    this._pInst.push();
+    this._pInst.noLights();
+    this._pInst.noStroke();
+    this._pInst.texture(img);
+    this._pInst.textureMode(constants.NORMAL);
+
+    // Calculate texture coordinates for subsection
+    let u0 = sx / img.width;
+    let u1 = (sx + sWidth) / img.width;
+    let v0 = sy / img.height;
+    let v1 = (sy + sHeight) / img.height;
+
+    // Draw a textured rectangle (plane) with the texture coordinates
+    this.beginShape();
+    // Top-left corner
+    this.vertex(dx, dy, sz, u0, v0);
+    // Top-right corner
+    this.vertex(dx + dWidth, dy, sz, u1, v0);
+    // Bottom-right corner
+    this.vertex(dx + dWidth, dy + dHeight, sz, u1, u1);
+    // Bottom-left corner
+    this.vertex(dx, dy + dHeight, sz, u0, v1);
+    this.endShape(constants.CLOSE);
+
+    this._pInst.pop();
+
+    if (this._isErasing) {
+      this.blendMode(constants.REMOVE);
+    }
+  }
+
 };
 /**
  * ensures that p5 is using a 3d renderer. throws an error if not.

test/unit/image/loading.js

@@ -537,7 +537,7 @@ suite('displaying images that use fit mode', function() {
   test('CONTAIN when source image is larger than destination', function() {
     let src = myp5.createImage(400, 1000);
     sinon.spy(myp5._renderer, 'image');
-    myp5.image(src, 0, 0, 300, 400, 0, 0, 400, 1000, myp5.CONTAIN);
+    myp5.image(src, 0, 0, 0, 300, 400, 0, 0, 400, 1000, myp5.CONTAIN);
     assert(myp5._renderer.image.calledOnce);
     assert.equal(myp5._renderer.image.getCall(0).args[7], 400 / (1000 / 400)); //  dw
     assert.equal(myp5._renderer.image.getCall(0).args[8], 1000 / (1000 / 400)); // dh
@@ -546,7 +546,7 @@ suite('displaying images that use fit mode', function() {
   test('CONTAIN when source image is smaller than destination', function() {
     let src = myp5.createImage(40, 90);
     sinon.spy(myp5._renderer, 'image');
-    myp5.image(src, 0, 0, 300, 500, 0, 0, 400, 1000, myp5.CONTAIN);
+    myp5.image(src, 0, 0, 0, 300, 500, 0, 0, 400, 1000, myp5.CONTAIN);
     assert(myp5._renderer.image.calledOnce);
     assert.equal(myp5._renderer.image.getCall(0).args[7], 40 / (90 / 500)); //  dw
     assert.equal(myp5._renderer.image.getCall(0).args[8], 90 / (90 / 500)); // dh