VGen File Format
Extension
ExtensionTop-Level Format
A VGen file may contain multiple VGen definitions. Each definition at top level is a yaml dictionary with required and optional keys.
| key name | type | required or optional | description |
name | string | required | The name of the VGen, must be unique. Used to identify this VGen in ScinthDef descriptions. |
rates | list | required | A list of strings identifying the rates the VGen supports, at least one of frame, shape, pixel. |
sampler | boolean | optional | If present, specifies if this VGen is a sampling VGen that will take an image input. If not present, the value is assumed to be false. |
tween | boolean | optional | If present, specifices if this VGen has a tween table to sample. |
inputs | list | optional | A list identifying input names in the shader program. The ordering of inputs here must match the ordering of inputs on the ScinthDef, as those inputs can be supplied unnamed. |
outputs | list | required | A list of strings identifying names of output parameters. At least one element must exist in this list. |
dimensions | list | required | A list of dictionaries of keys mapping dimension on inputs to dimension on outputs of the VGen (see below). |
shader | string | required | The GLSL shader program, with inputs, intrinsics, and intermediates, as well as exactly one instance of the keyword "@out" prefixed with @ symbols. |
Input and Output Dimensions List
The dimensions list enumerates the valid dimensions of input to, and output from, the VGen. As shader programs rely heavily on SIMD this means that many different configurations of output and input dimensions are typically supported by the built-in functions. The dimension key must be present in a valid VGen and contain a list with one or more dictionary elements with the following keys:
| key name | type | required or optional | description |
inputs | list or integer (see note) | required if VGen has inputs | Describes the dimensionality of each input signal. |
outputs | list or integer (see note) | required | Describes the dimensionality of each output signal. |
Shader Intrinsics
Some @names are reserved and will be automatically supplied to the VGen at compilation or runtime. They are described in short table form, with detailed descriptions below. Intrinsics have a rate, just like VGens, which describe their scope in terms of computation, meaning that it is not valid to use a shape-rate Intrinsic, for example, in a frame-rate VGen.
| name | dimenson | rate | brief description |
@fragCoord | 2 | pixel | The screen coordinates of the curent fragment in pixels. |
@normPos | 2 | shape | Position of vertex in normalized space. |
@pi | 1 | frame | A shortcut for the constant Pi. |
@position | 1-4 | shape only | Unormalized position of vertex. Undefined in pixel-rate VGens. Used internally by scinserver to indicate output of vertex shader. |
@sampler | n/a | frame | The curently configured and bound sampler and image. Only usable in sampling VGens. |
@time | 1 | frame | The runtime of the Scinth instance in seconds. |
@texPos | 2 | shape | Position of the fragment in texture coordinates space. |
@tweenSampler | n/a | frame | The currently configured and bound sampler of the tween. Only usable in tween VGens. |
@tweenDuration | 1 | frame | The total duration of the tween in seconds. Only usable in tween VGens. |
@fragCoord
Equates directly to gl_FragCoord.
@normPos
The normalized position of the vertex or fragment. This is computed to allow for image coordinates with a 1:1 aspect ratio even though the output window or framebuffer might be rectangular. The @normPos is always a 2 dimensional value and sets up coordinate systems such that the image in smaller of width or height will run from -1.0 to 1.0 in normPos space, with the larger size running under -1.0 and over 1.0. So, for instance, if the image is a tall rectangle with height twice that of width, the normPos will run from -1.0 to 1.0 in width, and -2.0 to 2.0 in height.
@pi
Always substituted for the value of pi.
@position
The unormalized position of the vector.
@sampler
In sampling VGens, represents the currently bound Vulkan sampler object and image within the shader.
@texPos
Texture coordinates are typically constrained within [0, 1] inclusive, with Samplers configured to do different things outside of the texture coordinate region. The synth will configure a shape to include texture coordinate information with the vertex and fragment shaders if this intrinsic is present. Texture coordinates are currently always assumed to be 2 dimensional.
@time
The VGen will receive a upated value every frame which contains the elapsed time in seconds from when the Scinth instance started. The time intrinsic is always 1 dimensional.
link::Scintillator/Reference/VGen-File-Format::