Merge pull request #5706 from aceslowman/main

added describe() to all 3d reference examples

Author: kjhollen

src/webgl/3d_primitives.js

@@ -27,6 +27,7 @@ import * as constants from '../core/constants';
  * // with width 50 and height 50
  * function setup() {
  *   createCanvas(100, 100, WEBGL);
+ *   describe('a white plane with black wireframe lines');
  * }
  *
  * function draw() {
@@ -112,6 +113,7 @@ p5.prototype.plane = function(width, height, detailX, detailY) {
  * // with width, height and depth of 50
  * function setup() {
  *   createCanvas(100, 100, WEBGL);
+ *   describe('a white box rotating in 3D space');
  * }
  *
  * function draw() {
@@ -231,6 +233,7 @@ p5.prototype.box = function(width, height, depth, detailX, detailY) {
  * // draw a sphere with radius 40
  * function setup() {
  *   createCanvas(100, 100, WEBGL);
+ *   describe('a white sphere with black wireframe lines');
  * }
  *
  * function draw() {
@@ -250,6 +253,9 @@ p5.prototype.box = function(width, height, depth, detailX, detailY) {
  *   detailX = createSlider(3, 24, 3);
  *   detailX.position(10, height + 5);
  *   detailX.style('width', '80px');
+ *   describe(
+ *     'a white sphere with low detail on the x-axis, including a slider to adjust detailX'
+ *   );
  * }
  *
  * function draw() {
@@ -270,6 +276,9 @@ p5.prototype.box = function(width, height, depth, detailX, detailY) {
  *   detailY = createSlider(3, 16, 3);
  *   detailY.position(10, height + 5);
  *   detailY.style('width', '80px');
+ *   describe(
+ *     'a white sphere with low detail on the y-axis, including a slider to adjust detailY'
+ *   );
  * }
  *
  * function draw() {
@@ -441,6 +450,7 @@ const _truncatedCone = function(
  * // with radius 20 and height 50
  * function setup() {
  *   createCanvas(100, 100, WEBGL);
+ *   describe('a rotating white cylinder');
  * }
  *
  * function draw() {
@@ -462,6 +472,9 @@ const _truncatedCone = function(
  *   detailX = createSlider(3, 24, 3);
  *   detailX.position(10, height + 5);
  *   detailX.style('width', '80px');
+ *   describe(
+ *     'a rotating white cylinder with limited X detail, with a slider that adjusts detailX'
+ *   );
  * }
  *
  * function draw() {
@@ -482,6 +495,9 @@ const _truncatedCone = function(
  *   detailY = createSlider(1, 16, 1);
  *   detailY.position(10, height + 5);
  *   detailY.style('width', '80px');
+ *   describe(
+ *     'a rotating white cylinder with limited Y detail, with a slider that adjusts detailY'
+ *   );
  * }
  *
  * function draw() {
@@ -576,6 +592,7 @@ p5.prototype.cylinder = function(
  * // with radius 40 and height 70
  * function setup() {
  *   createCanvas(100, 100, WEBGL);
+ *   describe('a rotating white cone');
  * }
  *
  * function draw() {
@@ -597,6 +614,9 @@ p5.prototype.cylinder = function(
  *   detailX = createSlider(3, 16, 3);
  *   detailX.position(10, height + 5);
  *   detailX.style('width', '80px');
+ *   describe(
+ *     'a rotating white cone with limited X detail, with a slider that adjusts detailX'
+ *   );
  * }
  *
  * function draw() {
@@ -617,6 +637,9 @@ p5.prototype.cylinder = function(
  *   detailY = createSlider(3, 16, 3);
  *   detailY.position(10, height + 5);
  *   detailY.style('width', '80px');
+ *   describe(
+ *     'a rotating white cone with limited Y detail, with a slider that adjusts detailY'
+ *   );
  * }
  *
  * function draw() {
@@ -692,6 +715,7 @@ p5.prototype.cone = function(radius, height, detailX, detailY, cap) {
  * // with radius 30, 40 and 40.
  * function setup() {
  *   createCanvas(100, 100, WEBGL);
+ *   describe('a white 3d ellipsoid');
  * }
  *
  * function draw() {
@@ -711,6 +735,9 @@ p5.prototype.cone = function(radius, height, detailX, detailY, cap) {
  *   detailX = createSlider(2, 24, 12);
  *   detailX.position(10, height + 5);
  *   detailX.style('width', '80px');
+ *   describe(
+ *     'a rotating white ellipsoid with limited X detail, with a slider that adjusts detailX'
+ *   );
  * }
  *
  * function draw() {
@@ -731,6 +758,9 @@ p5.prototype.cone = function(radius, height, detailX, detailY, cap) {
  *   detailY = createSlider(2, 24, 6);
  *   detailY.position(10, height + 5);
  *   detailY.style('width', '80px');
+ *   describe(
+ *     'a rotating white ellipsoid with limited Y detail, with a slider that adjusts detailY'
+ *   );
  * }
  *
  * function draw() {
@@ -826,6 +856,7 @@ p5.prototype.ellipsoid = function(radiusX, radiusY, radiusZ, detailX, detailY) {
  * // with ring radius 30 and tube radius 15
  * function setup() {
  *   createCanvas(100, 100, WEBGL);
+ *   describe('a rotating white torus');
  * }
  *
  * function draw() {
@@ -847,6 +878,9 @@ p5.prototype.ellipsoid = function(radiusX, radiusY, radiusZ, detailX, detailY) {
  *   detailX = createSlider(3, 24, 3);
  *   detailX.position(10, height + 5);
  *   detailX.style('width', '80px');
+ *   describe(
+ *     'a rotating white torus with limited X detail, with a slider that adjusts detailX'
+ *   );
  * }
  *
  * function draw() {
@@ -867,6 +901,9 @@ p5.prototype.ellipsoid = function(radiusX, radiusY, radiusZ, detailX, detailY) {
  *   detailY = createSlider(3, 16, 3);
  *   detailY.position(10, height + 5);
  *   detailY.style('width', '80px');
+ *   describe(
+ *     'a rotating white torus with limited Y detail, with a slider that adjusts detailY'
+ *   );
  * }
  *
  * function draw() {

src/webgl/interaction.js

@@ -30,6 +30,9 @@ import * as constants from '../core/constants';
  * function setup() {
  *   createCanvas(100, 100, WEBGL);
  *   normalMaterial();
+ *   describe(
+ *     'Camera orbits around a box when mouse is hold-clicked & then moved.'
+ *   );
  * }
  * function draw() {
  *   background(200);
@@ -167,6 +170,9 @@ p5.prototype.orbitControl = function(sensitivityX, sensitivityY, sensitivityZ) {
  *   camera(0, -30, 100, 0, 0, 0, 0, 1, 0);
  *   normalMaterial();
  *   debugMode();
+ *   describe(
+ *     'a 3D box is centered on a grid in a 3D sketch. an icon indicates the direction of each axis: a red line points +X, a green line +Y, and a blue line +Z. the grid and icon disappear when the spacebar is pressed.'
+ *   );
  * }
  *
  * function draw() {
@@ -194,6 +200,7 @@ p5.prototype.orbitControl = function(sensitivityX, sensitivityY, sensitivityZ) {
  *   camera(0, -30, 100, 0, 0, 0, 0, 1, 0);
  *   normalMaterial();
  *   debugMode(GRID);
+ *   describe('a 3D box is centered on a grid in a 3D sketch.');
  * }
  *
  * function draw() {
@@ -214,6 +221,9 @@ p5.prototype.orbitControl = function(sensitivityX, sensitivityY, sensitivityZ) {
  *   camera(0, -30, 100, 0, 0, 0, 0, 1, 0);
  *   normalMaterial();
  *   debugMode(AXES);
+ *   describe(
+ *     'a 3D box is centered in a 3D sketch. an icon indicates the direction of each axis: a red line points +X, a green line +Y, and a blue line +Z.'
+ *   );
  * }
  *
  * function draw() {
@@ -236,6 +246,7 @@ p5.prototype.orbitControl = function(sensitivityX, sensitivityY, sensitivityZ) {
  *   camera(0, -30, 100, 0, 0, 0, 0, 1, 0);
  *   normalMaterial();
  *   debugMode(GRID, 100, 10, 0, 0, 0);
+ *   describe('a 3D box is centered on a grid in a 3D sketch');
  * }
  *
  * function draw() {
@@ -256,6 +267,9 @@ p5.prototype.orbitControl = function(sensitivityX, sensitivityY, sensitivityZ) {
  *   camera(0, -30, 100, 0, 0, 0, 0, 1, 0);
  *   normalMaterial();
  *   debugMode(100, 10, 0, 0, 0, 20, 0, -40, 0);
+ *   describe(
+ *     'a 3D box is centered on a grid in a 3D sketch. an icon indicates the direction of each axis: a red line points +X, a green line +Y, and a blue line +Z.'
+ *   );
  * }
  *
  * function draw() {
@@ -361,6 +375,9 @@ p5.prototype.debugMode = function(...args) {
  *   camera(0, -30, 100, 0, 0, 0, 0, 1, 0);
  *   normalMaterial();
  *   debugMode();
+ *   describe(
+ *     'a 3D box is centered on a grid in a 3D sketch. an icon indicates the direction of each axis: a red line points +X, a green line +Y, and a blue line +Z. the grid and icon disappear when the spacebar is pressed.'
+ *   );
  * }
  *
  * function draw() {

src/webgl/light.js

@@ -37,6 +37,7 @@ import * as constants from '../core/constants';
  * function setup() {
  *   createCanvas(100, 100, WEBGL);
  *   noStroke();
+ *   describe('sphere with coral color under black light');
  * }
  * function draw() {
  *   background(100);
@@ -55,6 +56,7 @@ import * as constants from '../core/constants';
  * function setup() {
  *   createCanvas(100, 100, WEBGL);
  *   noStroke();
+ *   describe('sphere with coral color under white light');
  * }
  * function draw() {
  *   background(100);
@@ -144,6 +146,9 @@ p5.prototype.ambientLight = function(v1, v2, v3, a) {
  * function setup() {
  *   createCanvas(100, 100, WEBGL);
  *   noStroke();
+ *   describe(
+ *     'Sphere with specular highlight. Clicking the mouse toggles the specular highlight color between red and the default white.'
+ *   );
  * }
  *
  * function draw() {
@@ -256,6 +261,9 @@ p5.prototype.specularColor = function(v1, v2, v3) {
  * <code>
  * function setup() {
  *   createCanvas(100, 100, WEBGL);
+ *   describe(
+ *     'scene with sphere and directional light. The direction of the light is controlled with the mouse position.'
+ *   );
  * }
  * function draw() {
  *   background(0);
@@ -374,6 +382,9 @@ p5.prototype.directionalLight = function(v1, v2, v3, x, y, z) {
  * <code>
  * function setup() {
  *   createCanvas(100, 100, WEBGL);
+ *   describe(
+ *     'scene with sphere and point light. The position of the light is controlled with the mouse position.'
+ *   );
  * }
  * function draw() {
  *   background(0);
@@ -481,6 +492,7 @@ p5.prototype.pointLight = function(v1, v2, v3, x, y, z) {
  * <code>
  * function setup() {
  *   createCanvas(100, 100, WEBGL);
+ *   describe('the light is partially ambient and partially directional');
  * }
  * function draw() {
  *   background(0);
@@ -534,6 +546,9 @@ p5.prototype.lights = function() {
  * function setup() {
  *   createCanvas(100, 100, WEBGL);
  *   noStroke();
+ *   describe(
+ *     'Two spheres with different falloff values show different intensity of light'
+ *   );
  * }
  * function draw() {
  *   ortho();
@@ -654,6 +669,9 @@ p5.prototype.lightFalloff = function(
  * <code>
  * function setup() {
  *   createCanvas(100, 100, WEBGL);
+ *   describe(
+ *     'scene with sphere and spot light. The position of the light is controlled with the mouse position.'
+ *   );
  * }
  * function draw() {
  *   background(0);
@@ -985,6 +1003,9 @@ p5.prototype.spotLight = function(
  * <code>
  * function setup() {
  *   createCanvas(100, 100, WEBGL);
+ *   describe(
+ *     'Three white spheres. Each appears as a different color due to lighting.'
+ *   );
  * }
  * function draw() {
  *   background(200);

src/webgl/loading.js

@@ -50,6 +50,7 @@ import './p5.Geometry';
  *
  * function setup() {
  *   createCanvas(100, 100, WEBGL);
+ *   describe('Vertically rotating 3-d octahedron.');
  * }
  *
  * function draw() {
@@ -77,6 +78,7 @@ import './p5.Geometry';
  *
  * function setup() {
  *   createCanvas(100, 100, WEBGL);
+ *   describe('Vertically rotating 3-d teapot with red, green and blue gradient.');
  * }
  *
  * function draw() {
@@ -602,6 +604,7 @@ function parseASCIISTL(model, lines) {
  *
  * function setup() {
  *   createCanvas(100, 100, WEBGL);
+ *   describe('Vertically rotating 3-d octahedron.');
  * }
  *
  * function draw() {