Shaders: reference for the shader pipeline as of score#2364

docs/reference-manual/devices/library/window-device.md

@@ -50,9 +50,24 @@ The following properties describe the single-window device:
 
 ## Mouse input
 
-* `/cursor/scaled`: mouse cursor position in the window scaled to `[0;1]` bounds.
+* `/cursor/scaled`: mouse cursor position in the window scaled to `[0;1]` bounds, y down.
+* `/cursor/gl`: the same with y up, as OpenGL texture coordinates.
+* `/cursor/clip`: mouse cursor position in clip space, x and y in `[-1;1]`, y up: the `mouse` of [vertexshaderart.com](https://www.vertexshaderart.com).
 * `/cursor/absolute`: mouse cursor position in the window in pixels.
 
+In **Multi-Window Mapping** mode, each window has these under its index prefix (`/0/cursor/clip`...).
+
+## Touch input
+
+In **Single Window** and **Background** modes:
+
+* `/touch/points`: the pointers, a list of 32 `[x, y, pressure]` in clip space, y up. Slot 0 is the mouse (pressure 1 while a button is pressed) or the first finger, then one slot per finger in the order they came down; a released slot keeps its position, with pressure 0. Writable: a value sent to it moves the pointers.
+* `/touch/history`: a texture, the last 240 frames of `/touch/points`: 32 × 240 RGBA float, one column per pointer, the newest frame in the row at `v = 0`, each texel `(x, y, pressure, time)`. This is the `touch` texture of vertexshaderart.com; route it to a texture inlet as any texture address.
+
+## Shader inputs
+
+Shader inputs named for the pointers are bound to these addresses of the first window device by default, in ISF, Vertex Shader Art and Render Pipeline shaders alike: a `point2D` named `iMouse` to `/cursor/absolute`, a `mouse` of a Vertex Shader Art shader to `/cursor/clip`, another `point2D` whose name contains `mouse` to `/cursor/gl`, and an image named `touch` to `/touch/history`. The address shows on the inlet, where it can be changed. See [ISF pointer inputs]({{ site.baseurl }}/reference/languages/isf.html#pointer-inputs) and [VSA mouse and touch]({{ site.baseurl }}/reference/languages/vertex-shader-art.html#mouse-and-touch).
+
 ## Tablet input
 
 * `/tablet/scaled`: tablet pen position in the window scaled to `[0;1]` bounds.

docs/reference-manual/languages/glsl.md

@@ -67,10 +67,10 @@ Important Vulkan differences:
 
 Texture coordinates, framebuffer origins and clip coordinates are separate concerns. Do not fix a flipped result by adding an unconditional Y flip everywhere.
 
-- **ISF fragments:** `isf_FragNormCoord` is the current normalized coordinate. `IMG_NORM_PIXEL` takes normalized coordinates; `IMG_PIXEL` takes pixel coordinates; `IMG_TEXEL` takes integer texel coordinates. `IMG_THIS_*` samples at the current fragment. These helpers account for runtime texture orientation. See the [full macro table]({{ site.baseurl }}/reference/languages/isf.html#texture-macros).
+- **ISF fragments:** `isf_FragNormCoord` is the current normalized coordinate. `IMG_NORM_PIXEL` takes normalized coordinates; `IMG_PIXEL` takes pixel coordinates of the sampled image; `IMG_TEXEL` takes integer texel coordinates. `IMG_THIS_*` samples at the current fragment. These helpers account for runtime texture orientation; a raw `texture()` on an ISF image input reads the backend's own row order. See the [full macro table]({{ site.baseurl }}/reference/languages/isf.html#texture-macros).
 - **Compute images:** derive integer coordinates from `gl_GlobalInvocationID`, bounds-check against the resource size, then use `IMG_LOAD`, `IMG_STORE` or `IMG_STORE_LAYER`. These implement score's image-origin convention; raw `imageLoad`/`imageStore` do not apply its fixups. The [image contract]({{ site.baseurl }}/reference/languages/csf.html#images) covers dimensionality and access.
 - **Raw-raster vertices:** start `main()` with `isf_vertShaderInit()` and end with `isf_vertShaderFinish()`. Compute clip position with `clipSpaceCorrMatrix * VIEWPROJECTION_MATRIX * MODEL_MATRIX * position` for directly cabled geometry. The matrix and finish helper have complementary backend duties; do not call the helper twice or add another backend Y flip. Flattened scenes instead use [per-draw transforms]({{ site.baseurl }}/reference/languages/raw-raster.html#scene-path).
-- **VSA:** write the original OpenGL-style clip-space position; score maps the depth convention. Do not add raw-raster init/finish calls or a second depth correction.
+- **VSA:** write the original OpenGL-style clip-space position; score maps the depth convention. Do not add raw-raster init/finish calls or a second depth correction. Raw `texture()`, `textureLod()` and `texelFetch()` reads of a VSA image input have `v = 0` at the bottom on every backend, as in WebGL.
 
 For texture lookup outside fragment shading, choose an explicit LOD where required, as in the cookbook's compute audio recipe. Implicit fragment derivatives are not available to a compute invocation. Sampler filtering, wrapping and mip generation are separate choices described in the resource header.