Add p5.strands documentation and examples for color functions

[Yashisinghal285]

Closes #8915

Adds p5.strands-specific documentation and examples for color(), green(), blue(), alpha(), hue(), saturation(), brightness(), and lightness() in src/color/creating_reading.js. (red() and lerpColor() already had strand notes/examples from #8822.)

Each function's JSDoc now includes:

• A short note that in strands shader callbacks, the function operates on vec4 values with components normalized to the 0–1 range
• A note that colorMode() has no effect inside shader callbacks
• A minimal @example showing usage inside a baseMaterialShader().modify() callback, following the pattern established in feat(strands): add color() support for beginner-friendly color inputs #8822

Examples were kept minimal and focused per the style guide, as discussed in the issue thread.

cc @LalitNarayanYadav for review

[LalitNarayanYadav]

Thanks for the PR @Yashisinghal285! Good start - the strands descriptions for each function are accurate. A few things to fix before this is ready:

1. Examples are incomplete/incorrect

• The strands examples don't have createCanvas() or a working sketch structure.
• p5.getPixelInputs should be getPixelInputs (no p5. prefix inside modify()).
• The examples also need { myp5 } scope (or similar), following the existing strands examples in the test file.

2. color() strands example issue

The example returns c from inside getPixelInputs, but getPixelInputs expects the inputs object to be returned, not a color directly.

Instead, it should be:

inputs.color = c;
return inputs;

3. Missing blank line before strands paragraph

For brightness() and lightness(), the strands paragraph is placed immediately after the existing text without a blank line. This may break the JSDoc formatting.

4. lerpColor() example is incomplete

The strands example creates c1, c2, and mixed, but doesn't actually do anything with mixed—there's no hook or return value demonstrating its use.

5. Style guide

Per the p5.js documentation style guide, examples should be:

• Minimal
• Self-contained
• Include a describe() call

Happy to clarify any of these if needed!

[Yashisinghal285]

Thanks @LalitNarayanYadav for the detailed feedback! Fixed all 5 points:

1. Examples now include createCanvas(), setup()/draw(), and getPixelInputs (no p5. prefix)
2. color() now does inputs.color = c; return inputs;
3. Added the missing blank line before the strands paragraph in brightness() and lightness()
4. lerpColor() now actually applies mixed via inputs.color
5. All examples are minimal, self-contained, and include describe()

On the {myp5} scope note — checked test/unit/assets/testMaterial.js, which uses global-mode getPixelInputs() (no prefix), matching what I used and consistent with the rest of this file's examples. Let me know if you meant something different.

[LalitNarayanYadav]

Thanks for the updates @Yashisinghal285! Getting closer, but a few things still need fixing:

1. Examples still won't run

The strands examples are missing createCanvas(100, 100, WEBGL) and the shader setup. A minimal working example should look like:

function setup() {
  createCanvas(100, 100, WEBGL);

  let myShader = baseMaterialShader().modify(() => {
    getFinalColor((col) => {
      let c = color('#ff0000');
      col.rgb = c.rgb;
      return col;
    });
  });

  shader(myShader);
  noStroke();
  plane(100, 100);

  describe('A red plane');
}

2. getPixelInputs vs getFinalColor

The examples use getPixelInputs, but for color-related functions getFinalColor is more appropriate and consistent with the example sketch from the microgrant.

3. describe() is missing

Every example needs a describe() call per the p5.js documentation style guide.

4. Strands paragraph placement

The strands note should go just before the @method tag, not mixed in with the existing description text. Check how it was done in color() in PR #8822 as a reference.

5. Some functions still missing strands notes

brightness() and lightness() don't seem to have strands paragraphs added yet.

Suggest looking at the working example sketch at https://editor.p5js.org/LalitNarayanYadav/sketches/YMy8k8QSF as a reference for how these functions work together in practice.

[Yashisinghal285]

Thanks @LalitNarayanYadav —
Fixed — getFinalColor needs return vec4(...) explicitly, not col.rgb = .... Verified working in the editor: [your link]. Updated all strands examples (color, red, green, blue, alpha, hue, saturation, brightness, lightness, lerpColor) to match. Also double-checked — brightness()/lightness() already have their strand notes, and every example has describe()

[LalitNarayanYadav]

Thanks for addressing the feedback, @Yashisinghal285! The switch to getFinalColor with an explicit vec4(...) return looks correct, and it's great to hear you've verified it in the editor. If describe() has been added to all examples and the brightness()/lightness() documentation is now covered, everything looks good from my side.

@davepagurek @ksen0, this should be ready for maintainer review whenever you have a chance.

[p5-bot]

Continuous Release

CDN link

• https://raw.esm.sh/pr/p5@03a3a24/lib/p5.min.js

Published Packages

• https://pkg.pr.new/p5@03a3a24

Commit hash: 83e4039

Previous deployments

c5d3052

• https://raw.esm.sh/pr/p5@5aac96d/lib/p5.min.js
• https://pkg.pr.new/p5@5aac96d

---

This is an automated message.

[davepagurek]

Hi! If you take a look at the other examples on beta.p5js.org/reference, you'll notice they follow some different conventions.

• We don't use baseMaterialShader().modify(...); instead, we made buildMaterialShader(...) methods and use those in all the docs. The rationale is that the extra syntax provided more areas for users to get tripped up without giving much benefit, so we introduce people instead to the simpler single function (while still doing the more complex one under the hood internally.)
• We try not to use inline anonymous functions in shader callbacks. This works, but it's again a question of minimizing the new things readers have to understand in order to read the example. Since users will already by familiar with named top-level functions in order to create the function setup and function draw of p5, in examples, we prefer creating an additional top-level function like function myMaterial and then calling buildMaterialShader(myMaterial).
• Similar to the above, we have moved away from using the callback syntax to fill out the hooks in a shader. Nested functions provide an additional layer of syntactic complexity for users to understand, so rather than using getFinalColor(() => { ... }), our p5.strands examples universally use a finalColor.begin(); ...; finalColor.end() syntax instead. Where a callback would return a value, we use finalColor.set(...). Functions that just modify inputs (e.g. worldInputs) do not need to call .set at all.

For examples, we want to make sure that they actually run successfully and display the thing we want them to display. For that reason, rather than just writing it and trying to imagine what they do, we ask you to clone the p5.js-website repo, run it locally using your build of p5, and show us a screenshot of the results in a comment. See our contributor docs here for instructions on how to do that. This lets us also discuss whether anything could be visually improved, not just in the code.

Lastly, we also want to make sure that users aren't bogged down by all the possible ways one can use a function before seeing examples. For that reason, and because p5.strands is an advanced use case that most won't initially use, we should avoid adding text to the first big block of explanations above the simple examples, and instead put the explanation of p5.strands right before the relevant p5.strands example at the end of the reference page. To be able to have text in between examples, we will need to convert the examples for a reference entry from @examples to three-backtick-fenced examples. See the explanation here for details.

[davepagurek]

A p5.strands example should not be the first thing users see for red, let's put it at the end. We should maybe also move the explanation for how it works with p5.strands to the end too, right above it.

In order to do that, we need to switch from using these @example blocks to using three-backtick code fences. See this description in our contributor docs for what that looks like. This means we'll need to convert the existing examples for this reference into that format in order to be able to put text between the examples to add the explanation for p5.strands.