hayodea
fc1fcae0b0
We now specify intrins as separate DAPS lines. This syntax is much nicer and well-grouped than the previous negtrin-*/postrin-* param names. Alas, we're about to replace it in the next few commits already though.
5.9 KiB
Intrinsic Threshold Parameters
Overview
This document describes quale-iface-api-params that control threshold values for constructing stencils and delivering them to SMO via postrinInd/negtrinInd with different importance levels. These parameters allow the stimbuff API library to determine when to construct a stencil for postrin or negtrin data and present it to SMO with appropriate importance classifications.
Intrinsic parameters may appear only on dedicated intrinsic qualeIfaceApi
specs. The only supported forms are negtrin(...) and postrin(...).
You cannot attach intrinsic threshold params to a sensory or other
non-intrinsic qualeIfaceApi (for example pcloudIntensity, pcloudAmbience,
mesh, pcloud, and so on). Those lines are for sensory streams only.
A dedicated intrinsic line must name the sensory stimbuff it derives from via
from-stimbuff=<qualeIfaceApi> (non-empty). Policy validation rejects
intrinsic params and passband-style comparators on sensory lines, and rejects
dedicated lines that omit from-stimbuff.
Dedicated negtrin / postrin qualeIfaceApi names
On negtrin(...) or postrin(...), the intrinsic family (negative vs
positive) is fixed by the API name. The negtrin- and postrin-
prefixes on parameter names are optional: you may use short forms
interest-..., distraction-..., stupefaction- / stupefying-...,
and intolerable-... with the unit suffix rules below. Prefixed names such
as negtrin-interest-pc remain valid when you prefer explicit spelling.
Example (negtrin driven by ambience, short interest param, passband comparator):
+edev|avia0|negtrin(from-stimbuff=pcloudAmbience|interest-pc=85|passband-count-gt-val=120)|livoxGen1()|livoxProto1(SMO_IP)|3JEDK380010Z39
Unit Suffix Rules
All intrinsic threshold params must include an explicit unit suffix. These suffix families are not synonyms with each other; they select different units:
-percentage/-pc-threshold/-thresh/-thr
Parameters with the -percentage or -pc suffix take a percentage in
the range 0-100.
Parameters with the -threshold, -thresh, or -thr suffix take an
absolute number. The interpretation of that number, and the underlying
unit, is defined by the API library itself.
Users must specify only one unit-suffixed parameter per targeted intrinsic classification. If multiple unit-suffixed variants targeting the same classification are supplied anyway, the lattermost supplied parameter takes precedence.
Shorthand params without a unit suffix are not permitted. The following forms are invalid because they omit units:
[<pos|neg>trin-]<interest|distraction|stupef<action|ying>|intolerable>
On dedicated postrin(...) / negtrin(...) lines, the short forms
interest-..., distraction-..., etc. still require those unit
suffixes.
Interest Threshold Parameters
Parameter forms (only inside negtrin(...) or postrin(...)):
- Prefixed:
postrin-interest-<percentage|pc|threshold|thresh|thr>,negtrin-interest-<percentage|pc|threshold|thresh|thr> - Short (prefix optional because the line is already negtrin or postrin):
interest-<percentage|pc|threshold|thresh|thr>
Description: These parameters denote the value at which the stimbuff API library should construct a stencil for the postrin or negtrin that it delivers for this intrinsic spec, and present it to SMO via postrinInd/negtrinInd with the "importance" argument set to "INTERESTING".
Example (dedicated negtrin line):
+edev|avia0|negtrin(from-stimbuff=pcloudAmbience|interest-pc=85|passband-count-gt-val=120)|livoxGen1()|livoxProto1(SMO_IP)|3JEDK380010Z39
Distraction Threshold Parameters
Parameter forms (only inside negtrin(...) or postrin(...)):
- Prefixed:
postrin-distraction-<percentage|pc|threshold|thresh|thr>,negtrin-distraction-<percentage|pc|threshold|thresh|thr> - Short:
distraction-<percentage|pc|threshold|thresh|thr>(family is fixed by thenegtrin/postrinAPI name)
Description: These parameters denote the value at which the stimbuff API library ought to construct a stencil and deliver it to SMO via negtrinInd/postrinInd with the importance argument set to "DISTRACTION".
Stupefying Threshold Parameters (Postrin)
Parameter forms (only inside postrin(...)):
- Prefixed:
[postrin-]stupefaction-<percentage|pc|threshold|thresh|thr>,[postrin-]stupefying-<percentage|pc|threshold|thresh|thr> - Short:
stupefaction-...,stupefying-...with unit suffix
Description: These parameters denote the value at which the stimbuff API library ought to construct a stencil and deliver it to SMO via postrinInd with the importance argument set to "STUPEFYING".
Intolerable Threshold Parameters (Negtrin)
Parameter forms (only inside negtrin(...)):
- Prefixed:
[negtrin-]intolerable-<percentage|pc|threshold|thresh|thr> - Short:
intolerable-<percentage|pc|threshold|thresh|thr>
Description: These parameters denote the value at which the stimbuff API library ought to construct a stencil and deliver it to SMO via negtrinInd with the importance argument set to "INTOLERABLE".
Notes
The way that SMO handles these importance levels is not yet fully worked out. For postrins, the distinction between "interesting" vs "stupefying" is somewhat reasonably intuitively clear, but how that meaning is given in code has not been worked out yet. Similarly, for negtrins, the distinctions between "interesting" vs "distracting" vs "intolerable" are not entirely clear in terms of how their handling will impose meaningful differences that will give meaning to their distinctions.
These parameters provide the mechanism for the stimbuff API library to classify and deliver intrinsic stimuli with appropriate importance levels, but the downstream processing and behavioral implications of these classifications within SMO remain to be fully defined.