[WIP] Docs: Add reference entries for p5.strands hooks (feedback wanted)

src/webgl/p5.strands.js

@@ -0,0 +1,146 @@
+/**
+ * @function getWorldInputs
+ * @experimental
+ * @description
+ * Registers a callback to modify world-space vertex inputs for each vertex.
+ * The callback receives an object with the following properties:
+ *   - position: { x, y, z }
+ *   - normal: { x, y, z }
+ *   - texCoord: { x, y }
+ *   - color: { r, g, b, a }
+ * and should return a modified object with the same structure.
+ *
+ * This hook is available in:
+ * - {@link p5.baseMaterialShader}
+ * - {@link p5.baseNormalShader}
+ * - {@link p5.baseColorShader}
+ * - {@link p5.baseStrokeShader}
+ *
+ * @param {function(inputs: { position: {x: number, y: number, z: number}, normal: {x: number, y: number, z: number}, texCoord: {x: number, y: number}, color: {r: number, g: number, b: number, a: number} }): object} callback
+ *        A function that receives the current inputs and returns the modified inputs.
+ *
+ * @example
+ * <div modernizr='webgl'>
+ * <code>
+ * let myShader;
+ * function setup() {
+ *   createCanvas(200, 200, WEBGL);
+ *   myShader = baseMaterialShader().modify(() => {
+ *     getWorldInputs((inputs) => {
+ *       // Move the vertex up and down in a wave
+ *       inputs.position.y += 20 * Math.sin(millis() * 0.001 + inputs.position.x * 0.05);
+ *       return inputs;
+ *     });
+ *   });
+ * }
+ * function draw() {
+ *   background(255);
+ *   shader(myShader);
+ *   lights();
+ *   noStroke();
+ *   fill('red');
+ *   sphere(50);
+ * }
+ * </code>
+ * </div>
+ */
+
+/**
+ * @function combineColors
+ * @experimental
+ * @description
+ * Registers a callback to customize how color components are combined in the fragment shader.
+ * The callback receives an object with the following properties:
+ *   - baseColor: { r, g, b }
+ *   - opacity: number
+ *   - ambientColor: { r, g, b }
+ *   - specularColor: { r, g, b }
+ *   - diffuse: { r, g, b }
+ *   - ambient: { r, g, b }
+ *   - specular: { r, g, b }
+ *   - emissive: { r, g, b }
+ * and should return an object with a `color` property ({ r, g, b }) and an `opacity` property (number).
+ *
+ * This hook is available in:
+ * - {@link p5.baseMaterialShader}
+ * - {@link p5.baseNormalShader}
+ * - {@link p5.baseColorShader}
+ * - {@link p5.baseStrokeShader}
+ *
+ * @param {function(components: { baseColor: {r: number, g: number, b: number}, opacity: number, ambientColor: {r: number, g: number, b: number}, specularColor: {r: number, g: number, b: number}, diffuse: {r: number, g: number, b: number}, ambient: {r: number, g: number, b: number}, specular: {r: number, g: number, b: number}, emissive: {r: number, g: number, b: number} }): { color: {r: number, g: number, b: number}, opacity: number }} callback
+ *        A function that receives the current color components and returns the final color and opacity.
+ *
+ * @example
+ * <div modernizr='webgl'>
+ * <code>
+ * let myShader;
+ * function setup() {
+ *   createCanvas(200, 200, WEBGL);
+ *   myShader = baseMaterialShader().modify(() => {
+ *     combineColors((components) => {
+ *       // Custom color combination: add a red tint
+ *       let color = {
+ *         r: components.baseColor.r * components.diffuse.r +
+ *            components.ambientColor.r * components.ambient.r +
+ *            components.specularColor.r * components.specular.r +
+ *            components.emissive.r + 0.2,
+ *         g: components.baseColor.g * components.diffuse.g +
+ *            components.ambientColor.g * components.ambient.g +
+ *            components.specularColor.g * components.specular.g +
+ *            components.emissive.g,
+ *         b: components.baseColor.b * components.diffuse.b +
+ *            components.ambientColor.b * components.ambient.b +
+ *            components.specularColor.b * components.specular.b +
+ *            components.emissive.b
+ *       };
+ *       return { color, opacity: components.opacity };
+ *     });
+ *   });
+ * }
+ * function draw() {
+ *   background(255);
+ *   shader(myShader);
+ *   lights();
+ *   noStroke();
+ *   fill('red');
+ *   sphere(50);
+ * }
+ * </code>
+ * </div>
+ */
+
+/**
+ * @function getPointSize
+ * @experimental
+ * @description
+ * Registers a callback to modify the size of each point in the point shader.
+ * The callback receives the current point size (number) and should return the new size (number).
+ *
+ * This hook is available in:
+ * - {@link p5.pointShader}
+ *
+ * @param {function(size: number): number} callback
+ *        A function that receives the current point size and returns the modified size.
+ *
+ * @example
+ * <div modernizr='webgl'>
+ * <code>
+ * let myShader;
+ * function setup() {
+ *   createCanvas(200, 200, WEBGL);
+ *   myShader = pointShader().modify(() => {
+ *     getPointSize((size) => {
+ *       // Make points pulse
+ *       return size * (1 + 0.5 * Math.sin(millis() * 0.001));
+ *     });
+ *   });
+ * }
+ * function draw() {
+ *   background(255);
+ *   shader(myShader);
+ *   strokeWeight(10);
+ *   point(0, 0);
+ * }
+ * </code>
+ * </div>
+ */