Skip to content

Commit e73b524

Browse files
Abhayaj247Abhayaj247
committed
Add documentation for remaining public shader hooks in ShaderGenerator.js
1 parent 1d01ca8 commit e73b524

File tree

1 file changed

+333
-6
lines changed

1 file changed

+333
-6
lines changed

‎src/webgl/ShaderGenerator.js

Lines changed: 333 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1644,9 +1644,8 @@ if (typeof p5 !== 'undefined') {
16441644
/* ------------------------------------------------------------- */
16451645
/**
16461646
* @function getWorldInputs
1647-
* @experimental
16481647
* @description
1649-
* Registers a callback to modify the world-space properties of each vertex in a shader. This hook can be used inside <a href="#/p5/baseMaterialShader">baseMaterialShader()</a>.modify() and similar shader modify calls to customize vertex positions, normals, texture coordinates, and colors before rendering. "World space" refers to the coordinate system of the 3D scene, before any camera or projection transformations are applied.
1648+
* Registers a callback to modify the world-space properties of each vertex in a shader. This hook can be used inside <a href="#/p5/baseColorShader">baseColorShader()</a>.modify() and similar shader modify calls to customize vertex positions, normals, texture coordinates, and colors before rendering. "World space" refers to the coordinate system of the 3D scene, before any camera or projection transformations are applied.
16501649
*
16511650
* This hook is available in:
16521651
* - <a href="#/p5/baseMaterialShader">baseMaterialShader()</a>
@@ -1687,7 +1686,6 @@ if (typeof p5 !== 'undefined') {
16871686

16881687
/**
16891688
* @function combineColors
1690-
* @experimental
16911689
* @description
16921690
* Registers a callback to customize how color components are combined in the fragment shader. This hook can be used inside <a href="#/p5/baseMaterialShader">baseMaterialShader()</a>.modify() and similar shader modify calls to control the final color output of a material. The callback receives an object with the following properties:
16931691
*
@@ -1704,9 +1702,6 @@ if (typeof p5 !== 'undefined') {
17041702
*
17051703
* This hook is available in:
17061704
* - <a href="#/p5/baseMaterialShader">baseMaterialShader()</a>
1707-
* - <a href="#/p5/baseNormalShader">baseNormalShader()</a>
1708-
* - <a href="#/p5/baseColorShader">baseColorShader()</a>
1709-
* - <a href="#/p5/baseStrokeShader">baseStrokeShader()</a>
17101705
*
17111706
* @param {function} callback
17121707
* A callback function which receives the object described above and returns a vector with four components for the final color.
@@ -1746,4 +1741,336 @@ if (typeof p5 !== 'undefined') {
17461741
* }
17471742
* </code>
17481743
* </div>
1744+
*/
1745+
1746+
/**
1747+
* @function beforeVertex
1748+
* @description
1749+
* Registers a callback to run custom code at the very start of the vertex shader. This hook can be used inside <a href="#/p5/baseColorShader">baseColorShader()</a>.modify() and similar shader modify calls to set up variables or perform calculations that affect every vertex before processing begins. The callback receives no arguments.
1750+
*
1751+
* This hook is available in:
1752+
* - <a href="#/p5/baseColorShader">baseColorShader()</a>
1753+
* - <a href="#/p5/baseMaterialShader">baseMaterialShader()</a>
1754+
* - <a href="#/p5/baseNormalShader">baseNormalShader()</a>
1755+
* - <a href="#/p5/baseStrokeShader">baseStrokeShader()</a>
1756+
*
1757+
* @param {function} callback
1758+
* A callback function which is called before each vertex is processed.
1759+
*
1760+
* @example
1761+
* <div modernizr='webgl'>
1762+
* <code>
1763+
* let myShader;
1764+
* function setup() {
1765+
* createCanvas(200, 200, WEBGL);
1766+
* myShader = baseColorShader().modify(() => {
1767+
* beforeVertex(() => {
1768+
* // Set up a variable for later use
1769+
* let wave = sin(millis() * 0.001);
1770+
* });
1771+
* });
1772+
* }
1773+
* </code>
1774+
* </div>
1775+
*/
1776+
1777+
/**
1778+
* @function getObjectInputs
1779+
* @description
1780+
* Registers a callback to modify the properties of each vertex before any transformations are applied in the vertex shader. This hook can be used inside <a href="#/p5/baseColorShader">baseColorShader()</a>.modify() and similar shader modify calls to move, color, or otherwise modify the raw model data. The callback receives an object with the following properties:
1781+
* - `position`: `[x, y, z]` — the original position of the vertex
1782+
* - `normal`: `[x, y, z]` — the direction the surface is facing
1783+
* - `texCoord`: `[u, v]` — the texture coordinates
1784+
* - `color`: `[r, g, b, a]` — the color of the vertex
1785+
*
1786+
* Return the modified object to update the vertex.
1787+
*
1788+
* This hook is available in:
1789+
* - <a href="#/p5/baseColorShader">baseColorShader()</a>
1790+
* - <a href="#/p5/baseMaterialShader">baseMaterialShader()</a>
1791+
* - <a href="#/p5/baseNormalShader">baseNormalShader()</a>
1792+
* - <a href="#/p5/baseStrokeShader">baseStrokeShader()</a>
1793+
*
1794+
* @param {function} callback
1795+
* A callback function which receives the vertex object and should return it after making any changes.
1796+
*
1797+
* @example
1798+
* <div modernizr='webgl'>
1799+
* <code>
1800+
* let myShader;
1801+
* function setup() {
1802+
* createCanvas(200, 200, WEBGL);
1803+
* myShader = baseColorShader().modify(() => {
1804+
* getObjectInputs(inputs => {
1805+
* // Raise all vertices by 10 units
1806+
* inputs.position[1] += 10;
1807+
* return inputs;
1808+
* });
1809+
* });
1810+
* }
1811+
* </code>
1812+
* </div>
1813+
*/
1814+
1815+
/**
1816+
* @function getCameraInputs
1817+
* @description
1818+
* Registers a callback to adjust vertex properties after the model has been transformed by the camera, but before projection, in the vertex shader. This hook can be used inside <a href="#/p5/baseColorShader">baseColorShader()</a>.modify() and similar shader modify calls to create effects that depend on the camera's view. The callback receives an object with the following properties:
1819+
* - `position`: `[x, y, z]` — the position after camera transformation
1820+
* - `normal`: `[x, y, z]` — the normal after camera transformation
1821+
* - `texCoord`: `[u, v]` — the texture coordinates
1822+
* - `color`: `[r, g, b, a]` — the color of the vertex
1823+
*
1824+
* Return the modified object to update the vertex.
1825+
*
1826+
* This hook is available in:
1827+
* - <a href="#/p5/baseColorShader">baseColorShader()</a>
1828+
* - <a href="#/p5/baseMaterialShader">baseMaterialShader()</a>
1829+
* - <a href="#/p5/baseNormalShader">baseNormalShader()</a>
1830+
* - <a href="#/p5/baseStrokeShader">baseStrokeShader()</a>
1831+
*
1832+
* @param {function} callback
1833+
* A callback function which receives the vertex object and should return it after making any changes.
1834+
*
1835+
* @example
1836+
* <div modernizr='webgl'>
1837+
* <code>
1838+
* let myShader;
1839+
* function setup() {
1840+
* createCanvas(200, 200, WEBGL);
1841+
* myShader = baseColorShader().modify(() => {
1842+
* getCameraInputs(inputs => {
1843+
* // Tint all vertices blue
1844+
* inputs.color[2] = 1.0;
1845+
* return inputs;
1846+
* });
1847+
* });
1848+
* }
1849+
* </code>
1850+
* </div>
1851+
*/
1852+
1853+
/**
1854+
* @function afterVertex
1855+
* @description
1856+
* Registers a callback to run custom code at the very end of the vertex shader. This hook can be used inside <a href="#/p5/baseColorShader">baseColorShader()</a>.modify() and similar shader modify calls to perform cleanup or final calculations after all vertex processing is done. The callback receives no arguments.
1857+
*
1858+
* This hook is available in:
1859+
* - <a href="#/p5/baseColorShader">baseColorShader()</a>
1860+
* - <a href="#/p5/baseMaterialShader">baseMaterialShader()</a>
1861+
* - <a href="#/p5/baseNormalShader">baseNormalShader()</a>
1862+
* - <a href="#/p5/baseStrokeShader">baseStrokeShader()</a>
1863+
*
1864+
* @param {function} callback
1865+
* A callback function which is called after each vertex is processed.
1866+
*
1867+
* @example
1868+
* <div modernizr='webgl'>
1869+
* <code>
1870+
* let myShader;
1871+
* function setup() {
1872+
* createCanvas(200, 200, WEBGL);
1873+
* myShader = baseColorShader().modify(() => {
1874+
* afterVertex(() => {
1875+
* // Example: store the y position for use in the fragment shader
1876+
* myVarying = position.y;
1877+
* });
1878+
* });
1879+
* }
1880+
* </code>
1881+
* </div>
1882+
*/
1883+
1884+
/**
1885+
* @function beforeFragment
1886+
* @description
1887+
* Registers a callback to run custom code at the very start of the fragment shader. This hook can be used inside <a href="#/p5/baseColorShader">baseColorShader()</a>.modify() and similar shader modify calls to set up variables or perform calculations that affect every pixel before color calculations begin. The callback receives no arguments.
1888+
*
1889+
* This hook is available in:
1890+
* - <a href="#/p5/baseColorShader">baseColorShader()</a>
1891+
* - <a href="#/p5/baseMaterialShader">baseMaterialShader()</a>
1892+
* - <a href="#/p5/baseNormalShader">baseNormalShader()</a>
1893+
* - <a href="#/p5/baseStrokeShader">baseStrokeShader()</a>
1894+
*
1895+
* @param {function} callback
1896+
* A callback function which is called before each fragment is processed.
1897+
*
1898+
* @example
1899+
* <div modernizr='webgl'>
1900+
* <code>
1901+
* let myShader;
1902+
* function setup() {
1903+
* createCanvas(200, 200, WEBGL);
1904+
* myShader = baseColorShader().modify(() => {
1905+
* beforeFragment(() => {
1906+
* // Set up a variable for later use
1907+
* let brightness = 0.5;
1908+
* });
1909+
* });
1910+
* }
1911+
* </code>
1912+
* </div>
1913+
*/
1914+
1915+
/**
1916+
* @function getPixelInputs
1917+
* @description
1918+
* Registers a callback to modify the properties of each fragment (pixel) before the final color is calculated in the fragment shader. This hook can be used inside <a href="#/p5/baseMaterialShader">baseMaterialShader()</a>.modify() and similar shader modify calls to change opacity or other per-pixel properties. The callback receives an object with the following properties:
1919+
* - `opacity`: a number between 0 and 1 for the pixel's transparency
1920+
* (Other properties may be available depending on the shader.)
1921+
*
1922+
* Return the modified object to update the fragment.
1923+
*
1924+
* This hook is available in:
1925+
* - <a href="#/p5/baseMaterialShader">baseMaterialShader()</a>
1926+
* - <a href="#/p5/baseStrokeShader">baseStrokeShader()</a>
1927+
*
1928+
* @param {function} callback
1929+
* A callback function which receives the fragment inputs object and should return it after making any changes.
1930+
*
1931+
* @example
1932+
* <div modernizr='webgl'>
1933+
* <code>
1934+
* let myShader;
1935+
* function setup() {
1936+
* createCanvas(200, 200, WEBGL);
1937+
* myShader = baseMaterialShader().modify(() => {
1938+
* getPixelInputs(inputs => {
1939+
* // Make the fragment half as opaque
1940+
* inputs.opacity *= 0.5;
1941+
* return inputs;
1942+
* });
1943+
* });
1944+
* }
1945+
* </code>
1946+
* </div>
1947+
*/
1948+
1949+
/**
1950+
* @function shouldDiscard
1951+
* @description
1952+
* Registers a callback to decide whether to discard (skip drawing) a fragment (pixel) in the fragment shader. This hook can be used inside <a href="#/p5/baseStrokeShader">baseStrokeShader()</a>.modify() and similar shader modify calls to create effects like round points or custom masking. The callback receives a boolean:
1953+
* - `willDiscard`: true if the fragment would be discarded by default
1954+
*
1955+
* Return true to discard the fragment, or false to keep it.
1956+
*
1957+
* This hook is available in:
1958+
* - <a href="#/p5/baseStrokeShader">baseStrokeShader()</a>
1959+
*
1960+
* @param {function} callback
1961+
* A callback function which receives a boolean and should return a boolean.
1962+
*
1963+
* @example
1964+
* <div modernizr='webgl'>
1965+
* <code>
1966+
* let myShader;
1967+
* function setup() {
1968+
* createCanvas(200, 200, WEBGL);
1969+
* myShader = baseStrokeShader().modify(() => {
1970+
* shouldDiscard(willDiscard => {
1971+
* // Never discard any fragments
1972+
* return false;
1973+
* });
1974+
* });
1975+
* }
1976+
* </code>
1977+
* </div>
1978+
*/
1979+
1980+
/**
1981+
* @function getFinalColor
1982+
* @description
1983+
* Registers a callback to change the final color of each pixel after all lighting and mixing is done in the fragment shader. This hook can be used inside <a href="#/p5/baseColorShader">baseColorShader()</a>.modify() and similar shader modify calls to adjust the color before it appears on the screen. The callback receives a color array:
1984+
* - `[r, g, b, a]`: the current color (red, green, blue, alpha)
1985+
*
1986+
* Return a new color array to change the output color.
1987+
*
1988+
* This hook is available in:
1989+
* - <a href="#/p5/baseColorShader">baseColorShader()</a>
1990+
* - <a href="#/p5/baseMaterialShader">baseMaterialShader()</a>
1991+
* - <a href="#/p5/baseNormalShader">baseNormalShader()</a>
1992+
* - <a href="#/p5/baseStrokeShader">baseStrokeShader()</a>
1993+
*
1994+
* @param {function} callback
1995+
* A callback function which receives the color array and should return a color array.
1996+
*
1997+
* @example
1998+
* <div modernizr='webgl'>
1999+
* <code>
2000+
* let myShader;
2001+
* function setup() {
2002+
* createCanvas(200, 200, WEBGL);
2003+
* myShader = baseColorShader().modify(() => {
2004+
* getFinalColor(color => {
2005+
* // Make the output color fully opaque
2006+
* color[3] = 1.0;
2007+
* return color;
2008+
* });
2009+
* });
2010+
* }
2011+
* </code>
2012+
* </div>
2013+
*/
2014+
2015+
/**
2016+
* @function afterFragment
2017+
* @description
2018+
* Registers a callback to run custom code at the very end of the fragment shader. This hook can be used inside <a href="#/p5/baseColorShader">baseColorShader()</a>.modify() and similar shader modify calls to perform cleanup or final per-pixel effects after all color calculations are done. The callback receives no arguments.
2019+
*
2020+
* This hook is available in:
2021+
* - <a href="#/p5/baseColorShader">baseColorShader()</a>
2022+
* - <a href="#/p5/baseMaterialShader">baseMaterialShader()</a>
2023+
* - <a href="#/p5/baseNormalShader">baseNormalShader()</a>
2024+
* - <a href="#/p5/baseStrokeShader">baseStrokeShader()</a>
2025+
*
2026+
* @param {function} callback
2027+
* A callback function which is called after each fragment is processed.
2028+
*
2029+
* @example
2030+
* <div modernizr='webgl'>
2031+
* <code>
2032+
* let myShader;
2033+
* function setup() {
2034+
* createCanvas(200, 200, WEBGL);
2035+
* myShader = baseColorShader().modify(() => {
2036+
* afterFragment(() => {
2037+
* // Example: darken the final color of each pixel
2038+
* finalColor.rgb *= 0.8;
2039+
* });
2040+
* });
2041+
* }
2042+
* </code>
2043+
* </div>
2044+
*/
2045+
2046+
/**
2047+
* @function getColor
2048+
* @description
2049+
* Registers a callback to set the final color for each pixel in a filter shader. This hook can be used inside <a href="#/p5/baseFilterShader">baseFilterShader()</a>.modify() and similar shader modify calls to control the output color for each pixel. The callback receives the following arguments:
2050+
* - `inputs`: an object with properties like `texCoord`, `canvasSize`, `texelSize`, etc.
2051+
* - `canvasContent`: a sampler2D texture with the sketch's contents before the filter is applied
2052+
*
2053+
* Return a color array `[r, g, b, a]` for the pixel.
2054+
*
2055+
* This hook is available in:
2056+
* - <a href="#/p5/baseFilterShader">baseFilterShader()</a>
2057+
*
2058+
* @param {function} callback
2059+
* A callback function which receives the inputs object and canvasContent, and should return a color array.
2060+
*
2061+
* @example
2062+
* <div modernizr='webgl'>
2063+
* <code>
2064+
* let myShader;
2065+
* function setup() {
2066+
* createCanvas(200, 200, WEBGL);
2067+
* myShader = baseFilterShader().modify(() => {
2068+
* getColor((inputs, canvasContent) => {
2069+
* // Return the original color
2070+
* return getTexture(canvasContent, inputs.texCoord);
2071+
* });
2072+
* });
2073+
* }
2074+
* </code>
2075+
* </div>
17492076
*/

0 commit comments

Comments
 (0)