Image Light Feature - GSOC 2023

src/webgl/light.js

@@ -494,6 +494,99 @@ p5.prototype.pointLight = function(v1, v2, v3, x, y, z) {
   return this;
 };
 
+/**
+ * Creates an image light with the given image.
+ *
+ * The image light simulates light from all the directions.
+ * This is done by using the image as a texture for an infinitely
+ * large sphere light. This sphere contains
+ * or encapsulates the whole scene/drawing.
+ * It will have different effect for varying shininess of the
+ * object in the drawing.
+ * Under the hood it is mainly doing 2 types of calculations,
+ * the first one is creating an irradiance map the
+ * environment map of the input image.
+ * The second one is managing reflections based on the shininess
+ * or roughness of the material used in the scene.
+ *
+ * Note: The image's diffuse light will be affected by fill()
+ * and the specular reflections will be affected by specularMaterial()
+ * and shininess().
+ *
+ * @method imageLight
+ * @param  {p5.image}    img  image for the background
+ * @example
+ * <div class="notest">
+ * <code>
+ * let img;
+ * function preload() {
+ *   img = loadImage('assets/outdoor_image.jpg');
+ * }
+ * function setup() {
+ *   createCanvas(100, 100, WEBGL);
+ * }
+ * function draw() {
+ *   background(220);
+ *   imageMode(CENTER);
+ *   push();
+ *   translate(0, 0, -200);
+ *   scale(2);
+ *   image(img, 0, 0, width, height);
+ *   pop();
+ *   ambientLight(50);
+ *   imageLight(img);
+ *   specularMaterial(20);
+ *   noStroke();
+ *   scale(2);
+ *   rotateX(frameCount * 0.005);
+ *   rotateY(frameCount * 0.005);
+ *   box(25);
+ * }
+ * </code>
+ * </div>
+ * @alt
+ * image light example
+ * @example
+ * <div class="notest">
+ * <code>
+ * let img;
+ * let slider;
+ * function preload() {
+ *   img = loadImage('assets/outdoor_spheremap.jpg');
+ * }
+ * function setup() {
+ *   createCanvas(100, 100, WEBGL);
+ *   slider = createSlider(0, 400, 100, 1);
+ *   slider.position(0, height);
+ * }
+ * function draw() {
+ *   background(220);
+ *   imageMode(CENTER);
+ *   push();
+ *   translate(0, 0, -200);
+ *   scale(2);
+ *   image(img, 0, 0, width, height);
+ *   pop();
+ *   ambientLight(50);
+ *   imageLight(img);
+ *   specularMaterial(20);
+ *   shininess(slider.value());
+ *   noStroke();
+ *   scale(2);
+ *   sphere(15);
+ * }
+ * </code>
+ * </div>
+ * @alt
+ * light with slider having a slider for varying roughness
+ */
+p5.prototype.imageLight = function(img){
+  // activeImageLight property is checked by _setFillUniforms
+  // for sending uniforms to the fillshader
+  this._renderer.activeImageLight = img;
+  this._renderer._enableLighting = true;
+};
+
 /**
  * Places an ambient and directional light in the scene.
  * The lights are set to ambientLight(128, 128, 128) and