diff --git a/docs/openapi.yaml b/docs/openapi.yaml index 6fc0aac..ad371c2 100644 --- a/docs/openapi.yaml +++ b/docs/openapi.yaml @@ -1079,6 +1079,9 @@ components: font: type: string description: Font asset id used by text parameters, when declared. + fontParameter: + type: string + description: Enum parameter id used to select a text parameter font at runtime. value: description: Current parameter value. oneOf: diff --git a/shaders/SHADER_CONTRACT.md b/shaders/SHADER_CONTRACT.md index c48728e..e7dca34 100644 --- a/shaders/SHADER_CONTRACT.md +++ b/shaders/SHADER_CONTRACT.md @@ -592,6 +592,40 @@ float4 premultipliedText = drawTitleText(textUv, float4(1.0, 1.0, 1.0, 1.0)); Text is currently limited to printable ASCII. `maxLength` defaults to `64` and is clamped to `1..256`. The optional `font` field references a packaged font declared in `fonts`; if no font is specified, the runtime uses its fallback sans-serif renderer. +Text parameters can also choose their font from an enum parameter by setting `fontParameter` to that enum parameter's `id`: + +```json +{ + "fonts": [ + { "id": "inter", "path": "fonts/Inter-Regular.ttf" }, + { "id": "mono", "path": "fonts/Mono-Regular.ttf" } + ], + "parameters": [ + { + "id": "font", + "label": "Font", + "type": "enum", + "default": "inter", + "options": [ + { "value": "inter", "label": "Inter" }, + { "value": "mono", "label": "Mono" } + ] + }, + { + "id": "titleText", + "label": "Title", + "type": "text", + "default": "LIVE", + "font": "inter", + "fontParameter": "font", + "maxLength": 64 + } + ] +} +``` + +Every option `value` in the font selector enum must match a declared font asset `id`. The `font` field remains useful as the default/fallback font for the text parameter, while `fontParameter` lets operators switch atlases at runtime without adding shader-specific code. + Trigger example: ```json @@ -619,6 +653,7 @@ Parameter validation: - `color` must have exactly 4 numbers. - Enum defaults must match one of the declared option values. - Text defaults must be strings. Non-printable characters are dropped and values are clamped to `maxLength`. +- Text `fontParameter` values must reference an enum parameter whose option values are declared font asset IDs. - Trigger values are incremented by the host when triggered. The shader sees the trigger count and last trigger time. - Non-finite numeric values are rejected. @@ -800,6 +835,7 @@ For multipass shaders, these files reflect the most recently compiled pass. If a - Remember enum globals are integer indexes, not strings. - Declare every texture in `shader.json`; undeclared texture samplers will not be bound. - Declare packaged fonts in `shader.json` when text parameters should use a specific font. +- For selectable fonts, use a text parameter `fontParameter` that points at an enum whose option values are font IDs. - Keep temporal history requests modest. They consume texture units and memory and are capped by runtime config. - If a parameter appears in the UI but not in Slang, the shader may still compile, but the control has no effect. - If a Slang name collides with a generated global, rename your parameter or local symbol. @@ -815,5 +851,6 @@ Before committing a new shader package: - Texture files referenced by `textures` exist. - Font files referenced by `fonts` exist. - Enum defaults are present in their `options`. +- Text `fontParameter` selectors reference valid font assets through their enum options. - Temporal shaders handle short or empty history gracefully. - The app can reload and compile the shader without errors.