Introduce KEEP_CONNECTIONS as a replacement for FLAT in computeNormals() #9270

Increasing access

Introducing KEEP_CONNECTIONS would make the behavior of computeNormals() clearer and more intuitive, especially for beginners working with custom 3D geometry.

Currently, FLAT can be misleading because it does not always produce true flat shading when faces share vertices. The new name would better communicate what the mode actually does, helping users understand and choose the appropriate normal calculation behavior.

Keeping FLAT as a deprecated alias would also ensure that existing sketches continue to work without requiring immediate changes.

Most appropriate sub-area of p5.js?

• Accessibility
• Color
• Core/Environment/Rendering
• Data
• DOM
• Events
• Image
• IO
• Math
• Typography
• Utilities
• WebGL
• Build process
• Unit testing
• Internationalization
• Friendly errors
• Other (specify if possible)

Feature enhancement details

Problem

Currently, computeNormals(FLAT) calculates vertex normals by accumulating face normals across connected vertices. Because vertices shared by multiple faces receive averaged normals, this does not always result in true flat shading.

The name FLAT can therefore be misleading, as discussed in #9205.

Proposed solution

Introduce a new shading constant, KEEP_CONNECTIONS, that represents the existing behavior of FLAT, while keeping FLAT as a deprecated alias for backward compatibility.

The proposed changes are:

• Introduce KEEP_CONNECTIONS as a supported shading mode for computeNormals().
• Preserve the current normal calculation behavior without modifying vertex connections or geometry attributes.
• Keep FLAT working as before throughout p5.js 2.x to avoid breaking existing sketches.
• Mark FLAT as deprecated in the documentation and recommend using KEEP_CONNECTIONS instead.
• Add or update tests to verify that both modes produce equivalent results.

As discussed with @davepagurek, FLAT could potentially be removed in the next major version (p5.js 3.0), rather than in a minor or patch release.

Related issues

• [p5.js 2.0+ Bug Report]: computeNormals(SMOOTH) destroys uv attribute #9205 — Original discussion about computeNormals() shading behavior.
• fix: preserve vertex attributes with smooth normals #9233 — Previous PR addressing UV attribute preservation in SMOOTH.

This issue focuses only on introducing KEEP_CONNECTIONS and deprecating FLAT. The proposed SEGMENTED mode for true flat shading will be tracked in a separate follow-up issue.