io7m
io7m-jparasol 0.11.3
Parasol Language 0.11.3 Specification
1
Notational Conventions
1.1
Unicode
1
The specification makes reference to the Unicode character set which, at the time of writing, is at version 6.2.0. The specification often references specific Unicode characters, and does so using the standard notation U+NNNN, where N represents a hexadecimal digit. For example, U+03BB corresponds to the lowercase lambda symbol λ.
1.2
EBNF
1
The specification gives grammar definitions in ISO/IEC 14977:1996 Extended Backus-Naur form.
1.3
Logic
1
The specification uses the following notation from propositional logic [0]. A summary of the notation used is as follows:
1.3.1. Set notations
NotationDescription
∀x. P xUniversal quantification; for all x the proposition P holds for x
∃x. P xExistential quantification; there exists some x such that the proposition P holds for x
P ⇒ QImplication; P implies Q
P ⋀ QConjunction; P and Q
1.4
Sets
1
Where the specification refers to sets, it is referring to sets as defined in ZFC[1].
1.4.1. Set notations
NotationDescription
e ∈ Ae is an element of the set A
e ∉ Ae is not an element of the set A
{ x₀, x₁, ... xₙ }A set consisting of values from x₀ to xₙ
{ e ∈ A | p(e) }A set consisting of the elements of A for which the proposition p holds
|A|The cardinality of the set A; a measure of the number of elements in A
∅The empty set
𝔹The booleans
ℕThe natural numbers
ℝThe real numbers
ℤThe integers
[a, b]A closed interval in a set (given separately or implicit from the types of a and b), from a to b, including a and b
(a, b]A closed interval in a set (given separately or implicit from the types of a and b), from a to b, excluding a but including b
[a, b)A closed interval in a set (given separately or implicit from the types of a and b), from a to b, including a but excluding b
(a, b)A closed interval in a set (given separately or implicit from the types of a and b), from a to b, excluding a and b
A ⊂ BA is a subset of, and is not equal to, B
A ⊆ BA is a subset of, or is equal to, B
1.5
Tuples
1
The notation tuples(S, N) denotes the set of n-tuples of length N of elements taken from the set S, where N is non-negative. For a given set S, the set of n-tuples may be defined inductively as follows:
1.5.1. Tuples
  • tuples(S, 0) is the set of 0-tuples, containing one element denoted ().
  • tuples(S, N) is an ordered pair (x, tuples(S, N - 1)) where x ∈ S.
2
Some example sets of n-tuples are as follows:
1.5.2. Example n-tuple sets
S = { 1, 2, 3 }

tuples(S, 0) = { () }

tuples(S, 1) = {
  (1, ()),
  (2, ()),
  (3, ())
}

tuples(S, 2) = {
  (1, (1, ())),
  (2, (1, ())),
  (3, (1, ())),
  (1, (2, ())),
  (2, (2, ())),
  (3, (2, ())),
  (1, (3, ())),
  (2, (3, ())),
  (3, (3, ()))
}
3
Specific n-tuples are denoted P = (x₀, x₁, ..., xₙ), which is essentially shorthand for P = (x₀, (x₁, (... (xₙ, ())))), with the 0th element of P being x₀ and the nth element being xₙ.
1.6
Types
1
The specification (and the parasol language itself) uses notation and concepts taken from type theory [2]. A summary of the notation used is as follows:
1.6.1. Type notation
NotationDescriptionExample
x : AThe term x is of type A23 : ℕ
A → BThe type of functions from values of type A to values of type Beven : ℕ → 𝔹
A × BThe type of products of A and B(23, true) : ℕ × 𝔹
2
Product types are typically used to encode the notion of n-ary functions, where (A × B × C) → D is the type of functions that take three arguments of types A, B, and C, respectively, and return values of type D.
1.7
Type rules
1
Declarative type rules describe the precise rules for assigning types to terms. If no type rule matches a term, then that term is considered ill-typed.
2
Type rules are given as zero or more premises, and a single conclusion, separated by a horizontal line. For a given rule, when all of the premises are true, then the conclusion is true. If a rule has no premises then the rule is taken as an axiom.
3
The gamma symbol Γ (U+0393) represents the current typing environment and can be thought of as a mapping from distinct variables to their types, with the set of variables in environment denoted by dom(Γ) (the domain of Γ). The notation Γ ⊢ P reads "Γ implies P" and is used in type rules to assign types to terms. The empty typing environment is represented by ∅ (U+2205). The diamond symbol ◇ (U+25C7) should be read as "is well-formed", so Γ ⊢ ◇ should be read as "the current typing environment is well-formed". The concept of well-formedness is often type-system-specific and is usually described when the rules are given. A summary of the notation is as follows:
1.7.1. Type rule notation
NotationDescriptionExample
ΓThe current typing environmentΓ
∅The empty typing environment∅
Γ, xThe typing environment Γ extended with the variable x [3] Γ, x where x ∉ dom(Γ)
dom(Γ)The set of distinct variables in Γdom((∅, x, y)) = { x, y }
Γ ⊢ PThe environment Γ implies PΓ ⊢ 23 : ℕ (in the current typing environment, 23 is of type ℕ)
Γ ⊢ ◇The environment Γ is well-formed∅ ⊢ ◇ (the empty typing environment is well-formed)
4
An example of typing rules for natural number addition:
1.7.2. Natural number addition typing
Natural number addition typing
5
The empty rule states that the empty typing environment is well-formed. Because there are no premises above the horizontal line, this is taken as an axiom. The extension rule states that adding a term to the typing environment that is not already in that environment, results in a well-formed environment. The natural_intro rule states that, given a well-formed typing environment, any expression that is syntactically a natural number (represented by ℕ) has type natural. The natural_plus rule states that, if variables m and n have type natural in the current typing environment, then m + n has type natural. When checking the type of the expression m + n, the rules are used to construct a derivation tree as follows:
1.7.3. Natural number addition derivation
Natural number addition derivation
6
Intuitively, a term only has a valid type if there is a sequence of rules from the empty environment that can assign a type to the term.
1.8
Operational Semantics
1
Operational semantics describe the precise rules for the evaluation of expressions in a given language. The rules make up the description of an abstract machine which passes through different states, one rule (or step) at a time, until the machine halts and produces a value.
2
Typically, operational semantics begin by first giving a set of values, indicating the final results of evaluation, and a set of identifiers syntactically identifying the set of evaluable expressions. The evaluation rules themselves are given in a style similar to type rules, where a rule applies if the premises above the horizontal line are true, and the conclusion indicates how the state of the abstract machine changes when the rule is applied.
3
As an example, assume a language of conditional expressions. An example expression in this language would be:
1.8.1. Conditionals example
if true then
  if false then
    true
  else
    if
      if true then
        false
      else
        true
      end
    then
      false
    else
      true
    end
  end
else
  true
end
4
The values of this language are true and false. The expressions in this language include the values, and the form if e₀ then e₁ else e₂ end, where e₀, e₁ and e₂ are expressions. There are clearly multiple ways to evaluate expressions in this language, but in order to produce an algorithm that will execute on a computer, the evaluation rules should be:
1.8.2. Evaluation characteristics
  • Deterministic. That is, given a non-value expression e, there must be at most one evaluation rule that applies in order to work towards producing a value from e. If multiple rules apply, then evaluation is nondeterministic.
  • Complete. That is, given a non-value expression e, there must be at least one evaluation rule that applies in order to work towards producing a value from e. If no rule applies, then evaluation is said to be stuck.
5
The operational semantics for the language could be written as follows:
1.8.3. Conditional semantics
Conditional semantics
6
Expressions are assigned the identifiers e₀ to eₙ, so terms of those forms are assumed to be evaluable expressions when they appear in rules.
7
The notation e → e' should be read "e evaluates to e' in a single step".
8
The if_true rule states that if the condition of an if expression is exactly true, then the expression evaluates to the expression given in the left branch, in one step.
9
The if_false rule states that if the condition of an if expression is exactly false, then the expression evaluates to the expression given in the right branch, in one step.
10
The if_condition rule states that if the condition of an if expression is not a value, then the condition is evaluated first.
11
The example expression given earlier can now be evaluated completely and deterministically by following the given rules:
1.8.4. Conditionals example evaluation
if true then
  if false then
    true
  else
    if
      if true then
        false
      else
        true
      end
    then
      false
    else
      true
    end
  end
else
  true
end

→ by if_true to:

if false then
  true
else
  if
    if true then
      false
    else
      true
    end
  then
    false
  else
    true
  end
end

→ by if_false to:

if
  if true then
    false
  else
    true
  end
then
  false
else
  true
end

→ by if_condition to:

if
  false
then
  false
else
  true
end

→ by if_false to:

true
12
The substitution notation e [x := y] denotes the expression e where all occurences (if any) of the variable x have been replaced with y. This is used, for example, to describe function evaluation:
1.8.5. Function semantics
Function semantics
13
The function_eval_0 and function_eval_1 rules state that expressions are evaluated from left-to-right when applying f to a pair of arguments.
14
The function_eval_2 rule states that when all of the expressions passed to f have been reduced to values, the expression as a whole evaluates to the body of f, called e, with occurrences of the arguments x and y in e substituted with their values.
1.9
OpenGL
1
As the parasol language is intended to be executed on programmable GPUs, familiarity with OpenGL and the OpenGL shading language is assumed.
2
Lexical Conventions
2.1
Units
1
The text of a parasol program is a combination of the texts of separate units, where a unit typically corresponds to a file in the operating system under which the compiler is running.
2
Units consist of a series of lexical tokens separated by whitespace. What constitutes a token is the subject of the following sections.
2.2
Character set
1
The character set used for parasol program source code is UTF-8. Inside of comments, any Unicode character is permitted. Outside of comments, the subset of UTF-8 permitted for use in programs is detailed in the following sections.
2.3
Whitespace
1
The following characters are considered to be whitespace:
2.3.1. Whitespace
CodepointName
U+0009Horizontal tab
U+000ALine feed
U+000CForm feed
U+000DCarriage return
U+0020Space
2
Lines of source are separated with line_separator, which may be any of the following:
2.3.2. Line separators
Codepoint(s)Name
U+000ALine feed
U+000DCarriage return
U+000D U+000ACarriage return immediately followed by line feed
2.4
Comments
1
A comment starts with -- (two adjacent U+002D characters) and extends to the end of the line. Comments may appear on any line in a unit. The contents of comments have no effect whatsoever on the semantics of parasol programs.
2.5
Tokens
2.5.1
Integer literals
1
An integer_literal is a sequence of one or more digits, optionally preceded by a minus sign (U+002D), representing a decimal integer. The precise syntax is given by the following EBNF:
2.5.1.1. Integer literals
digit_nonzero =
  "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;

digit =
  "0" | digit_nonzero ;

integer =
  "0" | ( ["-"] , digit_nonzero , { digit } ) ;
2.5.2
Real literals
1
A real_literal consists of an integral and fractional part, separated by a dot (U+002E) and optionally preceded by a minus sign (U+002D), and represents a real number. The precise syntax is given by the following EBNF:
2.5.2.1. Real literals
real =
  ["-"] , digit , { digit } , "." , digit , { digit } ;
2.5.3
Boolean literals
1
A boolean_literal is either true or false. The precise syntax is given by the following EBNF:
2.5.3.1. Boolean literals
boolean_literal =
  "true" | "false" ;
2.5.4
Identifiers
1
Identifiers are sequences of uppercase letters ([U+0041, U+005A]), lowercase letters ([U+0061, U+007A]), and underscores (U+005F). An identifier is uppercase iff its first character is an uppercase letter, or lowercase iff its first character is a lowercase letter. Identifiers cannot begin with underscores or digits. The precise syntax is given by the following EBNF:
2.5.4.1. Identifiers
letter_lower =
  "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" |
  "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" |
  "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" |
  "y" | "z" ;

letter_upper =
  "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" |
  "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" |
  "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" |
  "Y" | "Z" ;

letter =
  letter_lower | letter_upper ;

name_lower =
  letter_lower , { letter | digit | "-" | "_" } ;

name_upper =
  letter_upper , { letter | digit | "-" | "_" } ;
2.5.5
Keywords
1
All of the following character sequences are reserved as keywords and cannot be used otherwise:
2.5.5.1. Keywords
  • : (U+003A)
  • , (U+002C)
  • { (U+007B)
  • } (U+007D)
  • . (U+002E)
  • = (U+003D)
  • ( (U+0028)
  • ) (U+0029)
  • ; (U+003B)
  • [ (U+005B)
  • ] (U+005D)
  • as
  • column
  • depth
  • discard
  • else
  • end
  • false
  • fragment
  • function
  • if
  • import
  • in
  • is
  • let
  • module
  • new
  • out
  • package
  • parameter
  • program
  • record
  • shader
  • then
  • true
  • type
  • value
  • vertex
  • with
3
Declarations
3.1
Overview
1
The parasol language consists of terms, types, and shaders, which are organized into modules (which are further organized into packages).
3.2
Terms
3.2.1
Description
1
Terms are the computational elements of the parasol language. They consist of values, which effectively give names to expressions, and functions, which are named computational rules in the mathematical sense.
3.2.2
Declarations
1
A term_declaration may either be a value_declaration or a function_declaration.
3.2.3
Names
1
The names selected for terms must be unique with respect to other terms within the module in which they are defined. That is, there cannot be two terms with the same name in the same module. Terms do not share a name space with types or shaders.
2
The following restrictions apply when naming terms:
3.2.3.1. Name restrictions
  • Term names must begin with a lowercase letter. This is directly implied by the grammar.
  • Names cannot contain two adjacent underscores (U+005F).
  • Names cannot end with underscores (U+005F).
  • Names cannot start with the character sequence "gl_" (U+0067, U+006C, U+005F).
  • Names cannot match any of the keywords or reserved words defined in any version of the OpenGL shading language. See the GLSL identifiers section for the complete list.
3.2.4
Recursion
1
No term_declaration can be recursive with respect to itself or any other term_declaration in the module in which it appears.
2
A term d₀ is said to refer statically to a term d₁ if the free variables of d₀ contain the name of d₁.
3
A term_declaration d is (mutually) recursive iff:
3.2.4.1. Recursion conditions
  • d refers statically to itself.
  • There is a sequence of terms t₀, t₁, ..., tₙ such that d refers statically to t₀, and for all m where 0 <= m < n, tₘ refers statically t₍ₘ₊₁₎, and tₙ refers statically to d.
3.2.5
Order of declarations
1
For the purposes of sorting term declarations based on their dependencies, terms can be partially ordered based on the terms to which they refer statically. That is, if a term t₀ refers statically to term t₁, then t₁ < t₀.
2
Terms do not have to be declared in any given order. That is, if a term t₀ refers statically to term t₁ in the same module, there is no requirement that t₁ be declared before t₀.
3
Terms are sorted topologically prior to any evaluation based on the given partial order relation, and the restrictions on recursion ensure that it is always possible to sort terms in the order of their dependencies.
3.2.6
Values
1
A value_declaration binds an expression to a name.
2
The type of the value_declaration will be inferred from the given expression, but the declaration can be optionally ascribed with the name of a type, in which case the type of the expression will be checked against the ascription and an error raised in the case of a mismatch.
3.2.7
Functions
1
A function_declaration binds an expression e to a name along with a given return type t and a set of formal parameters, where e contains zero or more variables bound by the formal parameters and which, when evaluated, will result in a value of type t.
3.2.8
Type rules
1
A value_declaration of type t introduces a term of type t into the environment:
3.2.8.1. Value declaration type rule (value_declaration)
Value declaration type rule (value_declaration)
3.2.8.2. Value declaration (ascribed) type rule (value_declaration_ascribed)
Value declaration (ascribed) type rule (value_declaration_ascribed)
2
A function_declaration with parameters of type (s₀ ✕ s₁ ✕ ... sₙ) that returns type u introduces a term of type (s₀ ✕ s₁ ✕ ... sₙ) → u into the environment:
3.2.8.3. Function declaration type rule (function_declaration)
Function declaration type rule (function_declaration)
3.2.9
Operational semantics
1
With terms sorted according to their partial order, evaluation of value_declarations in the current module proceeds from top-to-bottom, with the value of each evaluated value_declaration being substituted into the terms that follow it:
3.2.9.1. Top level evaluation (top_level)
Top level evaluation (top_level)
3.2.10
Syntax
1
The precise syntax of term_declarations is given by the following EBNF:
3.2.10.1. Term declaration syntax
type_path =
    name_lower
  | name_upper , "." , name_lower ;

value_declaration =
  "value" , name_lower , [ ":" , type_path ] , "=" , expression ;

function_formal_parameter =
  name_lower , ":" , type_path ;

function_formal_parameters =
  "(" , function_formal_parameter, { "," , function_formal_parameter } , ")" ;

function_declaration =
  "function" , name_lower , function_formal_parameters , ":" , type_path , "=" , expression ;

term_declaration =
  value_declaration | function_declaration ;
3.2.11
Examples
3.2.11.1. Examples
value x = 23;

value y = I.plus x 24;

function identity (
  x : integer
) : integer = x;
3.3
Types
3.3.1
Declarations
1
A type_declaration declares a new record type. This section documents the declarations themselves, while the types section documents the actual type system itself.
3.3.2
Names
1
The names selected for types must be unique with respect to other types within the module in which they are defined. That is, there cannot be two types with the same name in the same module. Types do not share a name space with terms or shaders.
2
The following restrictions apply when naming types:
3.3.2.1. Name restrictions
  • Type names must begin with a lowercase letter. This is directly implied by the grammar.
  • Names cannot contain two adjacent underscores (U+005F).
  • Names cannot end with underscores (U+005F).
  • Names cannot start with the character sequence "gl_" (U+0067, U+006C, U+005F).
  • Names cannot match any of the keywords or reserved words defined in any version of the OpenGL shading language. See the GLSL identifiers section for the complete list.
3.3.3
Recursion
1
No type_declaration can be recursive with respect to itself or any other type_declaration in the module in which it appears.
2
A type d₀ is said to refer statically to a type d₁ if d₀ appears anywhere in the definition of d₁.
3
A type_declaration d is (mutually) recursive iff:
3.3.3.1. Recursion conditions
  • d refers statically to itself.
  • There is a sequence of types t₀, t₁, ..., tₙ such that d refers statically to t₀, and for all m where 0 <= m < n, tₘ refers statically t₍ₘ₊₁₎, and tₙ refers statically to d.
3.3.4
Records
1
A type_declaration binds a record_type_expression to a name. A record_type_expression declares a set of named fields and types.
2
A record_type_expression cannot contain two fields with the same name, but two distinct record_type_expressions can have fields with the same names. To clarify, these are valid type_declarations:
3.3.4.1. Valid type declarations
type t is record
  x : integer,
  y : integer
end;

type u is record
  x : integer,
  y : integer
end;
3
However, this is not:
3.3.4.2. Invalid type declarations (duplicate field)
type t is record
  x : integer,
  x : integer
end;
4
As described in the types section, types have by-name equivalence and therefore two identical record_type_expressions bound to different names are not type-compatible.
3.3.5
Type rules
1
A type_declaration introduces a new record type into the typing environment. See the rules for record types for the effects that this has on typing rules.
3.3.6
Syntax
1
The precise syntax of type declarations is given by the following EBNF:
3.3.6.1. Type declaration syntax
record_type_field =
  name_lower , ":" , type_path ;

record_type_expression =
  "record" , record_type_field , { "," , record_type_field } , "end" ;

type_declaration =
  "type" , name_lower , "is" , type_expression ;

type_expression =
  record_type_expression
  ;
3.3.7
Examples
3.3.7.1. Examples
type t is record
  x : integer,
  y : integer,
  z : integer
end;

type u is record
  v0 : t,
  v1 : t,
  v2 : t
end;
3.4
Shaders
3.4.1
Description
1
Shaders represent programs that will execute on the targeted graphics hardware. They are divided into vertex shaders, fragment shaders, and programs, (which essentially aggregate other shaders into usable programs).
3.4.2
Declarations
1
A shader_declaration may either be a shader_vertex_declaration, a shader_fragment_declaration, or a shader_program_declaration.
3.4.3
Names
1
The names selected for shaders must be unique with respect to other shaders within the module in which they are defined. That is, there cannot be two shaders with the same name in the same module. Shaders do not share a name space with terms or types.
2
The following restrictions apply when naming shaders:
3.4.3.1. Name restrictions
  • Shader names must begin with a lowercase letter. This is directly implied by the grammar.
  • Names cannot contain two adjacent underscores (U+005F).
  • Names cannot end with underscores (U+005F).
  • Names cannot start with the character sequence "gl_" (U+0067, U+006C, U+005F).
  • Names cannot match any of the keywords or reserved words defined in any version of the OpenGL shading language. See the GLSL identifiers section for the complete list.
3.4.4
Inputs/Outputs/Parameters
1
Shaders consume data from inputs and parameters, and produce data on outputs.
2
Inputs are data sources that produce values that may change every time the shader is executed (once per vertex for vertex shaders and once per fragment for fragment shaders).
3
Parameters are data sources that produce values that may be constant over the entire lifetime of the program.
4
Outputs are data sinks that, when assigned values, pass those values to the next stage of the rendering pipeline. Typically, vertex shaders linearly interpolate values written to outputs and pass them on to the fragment shader, and fragment shaders send values written to outputs to the framebuffer for display.
5
The following restrictions apply when naming inputs, outputs, and parameters:
3.4.4.1. Name restrictions
  • Names must begin with a lowercase letter. This is directly implied by the grammar.
  • Names cannot contain two adjacent underscores (U+005F).
  • Names cannot end with underscores (U+005F).
  • Names cannot start with the character sequence "gl_" (U+0067, U+006C, U+005F).
  • Names cannot match any of the keywords or reserved words defined in any version of the OpenGL shading language. See the GLSL identifiers section for the complete list.
3.4.5
Type rules
1
Only a subset of the available types are permitted for inputs, and outputs:
3.4.5.1. Input/Output types
2
Parameters may be of any type [4].
3.4.6
Syntax
1
The precise syntax of shader declarations is given by the following EBNF:
3.4.6.1. Shader declaration syntax
shader_parameter_declaration =
  "parameter" , name_lower , ":" , type_path ;

shader_vertex_input_declaration =
  "in" , name_lower , ":" , type_path ;

shader_vertex_output_declaration =
  "out" , name_lower , ":" , type_path ;

shader_vertex_output_declaration =
  "out" , "vertex" , name_lower , ":" , type_path ;

shader_vertex_parameter =
    shader_parameter_declaration
  | shader_vertex_input_declaration
  | shader_vertex_output_declaration
  | shader_vertex_output_main_declaration ;

shader_vertex_parameters =
  { shader_vertex_parameter , ";" } ;

shader_vertex_output_assignment =
  "out" , name_lower , "=" , term_path ;

shader_vertex_output_assignments =
  shader_vertex_output_assignment , ";" , { shader_vertex_output_assignments } ;

shader_vertex_declaration =
  "vertex" , name_lower , "is" ,
  shader_vertex_parameters ,
  [ "with" , local_declarations ] ,
  "as" ,
  shader_vertex_output_assignments ,
  "end" ;

shader_fragment_input_declaration =
  "in" , name_lower , ":" , type_path ;

shader_fragment_output_declaration =
  "out" , name_lower , ":" , type_path , "as" , integer_literal ;

shader_fragment_parameter =
    shader_parameter_declaration
  | shader_fragment_input_declaration
  | shader_fragment_output_declaration ;

shader_fragment_parameters =
  { shader_fragment_parameter , ";" } ;

shader_fragment_discard_declaration =
  "discard" , "(" , expression , ")" ;

shader_fragment_local_declaration =
    local_declaration
  | shader_fragment_discard_declaration ;

shader_fragment_local_declarations =
  shader_fragment_local_declaration , ";" , { shader_fragment_local_declarations } ;

shader_fragment_output_assignment =
  "out" , name_lower , "=" , term_path ;

shader_fragment_output_assignments =
  shader_fragment_output_assignment , ";" , { shader_fragment_output_assignments } ;

shader_fragment_declaration =
  "fragment" , name_lower , "is" ,
  shader_fragment_parameters ,
  [ "with" , shader_fragment_local_declarations ] ,
  "as" ,
  shader_fragment_output_assignments ,
  "end" ;

shader_program_declaration =
  "program" , name_lower , "is" ,
  "vertex" , shader_path , ";" ,
  "fragment" , shader_path , ";" ,
  "end" ;

shader_declaration =
  "shader" , ( shader_vertex_declaration | shader_fragment_declaration | shader_program_declaration ) ;

shader_declarations =
  { shader_declaration , ";" } ;
3.5
Vertex shaders
3.5.1
Description
1
Vertex shaders are programs that process data on a per-vertex basis in OpenGL.
3.5.2
Declarations
1
A shader_vertex_declaration declares a set of inputs, outputs, and parameters, as well as a sequence of zero or more local_value_declarations, similar in semantics and typing to that found in a let expression, and a sequence of assignments of values to the declared outputs. A vertex shader must also define exactly one output of type vector_4f, indicated with the vertex keyword, to which must be assigned a value representing the current homogeneous vertex position.
2
It is required that there be exactly one shader_vertex_output_assignment for each shader_vertex_output_declaration.
3.5.3
Type rules
1
Each shader_parameter_declaration and shader_vertex_input_declaration introduces a new term of the given type into the environment, accessible only within the scope of the shader definition, as shown by the shader_vertex_inputs_parameters rule:
3.5.3.1. Vertex shader inputs/parameters (shader_vertex_inputs_parameters)
Vertex shader inputs/parameters (shader_vertex_inputs_parameters)
2
Each local_value_declaration introduces a new term of the given type into the environment, accessible in each successive local_value_declaration and in the shader_vertex_output_assignments, as shown by the shader_vertex_values rule:
3.5.3.2. Vertex shader values (shader_vertex_values)
Vertex shader values (shader_vertex_values)
3
Finally, each output assigned in a shader_vertex_output_assignment must be of the correct type, as shown by the shader_vertex_output_assignment rule:
3.5.3.3. Vertex shader output assignments (shader_vertex_output)
Vertex shader output assignments (shader_vertex_output)
3.5.4
Operational Semantics
1
The local_value_declarations are evaluated from top-to-bottom, in an identical manner to let expressions, as shown by the shader_vertex_values rule:
3.5.4.1. Vertex shader local declarations (shader_vertex_values)
Vertex shader local declarations (shader_vertex_values)
3.5.5
Examples
3.5.5.1. Examples
shader vertex v is
  parameter mm_modelview  : matrix_4x4f;
  parameter mm_projection : matrix_4x4f;
  parameter mm_normal     : matrix_3x3f;
  in position             : vector_4f;
  in normal               : vector_3f;
  out vertex r_position   : vector_4f;
  out r_normal            : vector_3f;
with
  value p_result = M4.multiply_vector (M4.multiply (mm_projection, mm_modelview), position);
  value n_result = M3.multiply_vector (mm_normal, normal);
as
  out r_position = p_result;
  out r_normal   = n_result;
end;
3.6
Fragment shaders
3.6.1
Description
1
Fragment shaders are programs that process data on a per-fragment basis in OpenGL.
3.6.2
Declarations
1
A shader_fragment_declaration declares a set of inputs, outputs, and parameters, as well as a sequence of zero or more shader_fragment_local_declaration, and a sequence of assignments of values to the declared outputs.
2
A fragment shader may optionally define at most one output of type float, indicated with the depth keyword, to which must be assigned a value representing the current desired fragment depth (overriding the depth value typically calculated by the graphics system's rasterizer).
3
A shader_fragment_local_declaration is either a local_value_declaration, similar in semantics and typing to that found in a let expression, or a shader_fragment_discard_declaration.
3.6.3
Discard
1
A shader_fragment_discard_declaration statement halts evaluation of the current fragment shader iff the given expression evaluates to true.
3.6.4
Type rules
1
Each shader_parameter_declaration and shader_fragment_input_declaration introduces a new term of the given type into the environment, accessible only within the scope of the shader definition, as shown by the shader_fragment_inputs_parameters rule:
3.6.4.1. Fragment shader inputs/parameters (shader_fragment_inputs_parameters)
Vertex shader inputs/parameters (shader_fragment_inputs_parameters)
2
Each local_value_declaration introduces a new term of the given type into the environment, accessible in each successive local_value_declaration and in the shader_fragment_output_assignments, as shown by the shader_fragment_values rule:
3.6.4.2. Fragment shader values (shader_fragment_values)
Vertex shader values (shader_fragment_values)
3
Each output assigned in a shader_fragment_output_assignment must be of the correct type, as shown by the shader_fragment_output_assignment rule:
3.6.4.3. Fragment shader output assignments (shader_fragment_output)
Vertex shader output assignments (shader_fragment_output)
4
Finally, the expression passed to a shader_fragment_discard_declaration must be of a boolean type as shown by the shader_fragment_discard rule [5]:
3.6.4.4. Fragment shader discard (shader_fragment_discard)
Fragment shader discard (shader_fragment_discard)
3.6.5
Operational Semantics
1
The shader_fragment_local_declaration are evaluated from top-to-bottom, in an identical manner to let expressions, as shown by the shader_fragment_values rule:
3.6.5.1. Fragment shader local declarations (shader_fragment_values)
Fragment shader local declarations (shader_fragment_values)
2
Evaluation halts immediately upon evaluating any shader_fragment_discard_declaration where the condition evaluates to true.
3.6.6
Examples
3.6.6.1. Examples
shader fragment f is
  parameter texture_0 : sampler_2d;
  in uv               : vector_2f;
  out out0            : vector_4f as 0;
with
  value rgba = T.texture (texture_0, uv);
as
  out out0 = rgba;
end;
3.7
Programs
3.7.1
Description
1
Programs aggregate vertex and fragment shaders into single entities that are executed on the targeted graphics hardware.
3.7.2
Declarations
1
A shader_program_declaration declares a dependency on a vertex shader and a fragment shader.
3.7.3
Compatibility
1
In order for a given vertex shader and fragment shader to be used in a program, the set of inputs I of the fragment shader must be compatible with the set of outputs O of the vertex shader. Specifically, for each 0 <= s <= |I| - 1, there must be some 0 <= t <= |O| - 1 such that the name and type of Iₛ matches that of Oₜ:
3.7.3.1. Input/output compatibility
∀s. 0 <= s <= |I| - 1 ⇒
  ∃t. (0 <= t <= |O| - 1 ⋀ ((name(Iₛ) = name(Oₜ) ⋀  type(Iₛ) = type(Oₜ)))
2
The set of parameters P of the given given vertex shader, and the set of parameters Q of the given fragment shader must be type-compatible if they share any of the same names. That is, for each 0 <= s <= |P| - 1, if there is some 0 <= t <= |Q| - 1 such that the name of Pₛ equals that of Qₜ, then the type of Pₛ must equal that of Qₜ.
3.7.3.2. Input/output compatibility
∀s. 0 <= s <= |P| - 1 ⇒
  ∃t. (0 <= t <= |Q| - 1 ⋀ name(Iₛ) = name(Oₜ)) ⇒
    type(Iₛ) = type(Oₜ)
3.7.4
Examples
3.7.4.1. Examples
shader program p is
  vertex p;
  fragment f;
end;
3.8
Modules
3.8.1
Description
1
A module is a organizational unit containing terms, types, and shaders. Modules exist solely to partition the namespace into separate sections to allow for ease of code re-use across projects.
3.8.2
Declarations
1
A module_declaration declares a new module.
3.8.3
Names
1
The names selected for modules must be unique with respect to other modules within the package in which they are defined. That is, there cannot be two modules with the same name in the same package.
2
The following restrictions apply when naming modules:
3.8.3.1. Name restrictions
  • Module names must begin with an uppercase letter. This is directly implied by the grammar.
  • Names cannot contain two adjacent underscores (U+005F).
  • Names cannot end with underscores (U+005F).
  • Names cannot start with the character sequence "GL_" (U+0047, U+004C, U+005F).
  • Names cannot match any of the keywords or reserved words defined in any version of the OpenGL shading language. See the GLSL identifiers section for the complete list.
3.8.4
Imports
1
A module may import any number of modules via import_declarations. An import_declaration, given in module X, specifies a name of a module Y prefixed with the name of the package in which the module Y was defined. The terms, types, and shaders of Y are then accessible in X by qualifying their names with Y. As an example:
3.8.4.1. Module import example
package com.example;

module Y is
  value k = 23;
end;

module X is
  import com.example.Y;
  value z = Y.k;
end;
2
The value of X.z is 23.
3
Because two modules defined in different packages can have the same names, it is possible for imports to collide: If a X imports both modules com.example_0.Y and com.example_1.Y, then the name Y will be introduced twice. An import_declaration may therefore provide an optional name to disambiguate imported modules:
3.8.4.2. Module import renaming
package com.example;

module X is
  import com.example_0.Y;
  import com.example_1.Y as Z;

  value z = Y.k;
  value q = Z.p;
end;
4
If a module X imports a module Y as Z, the terms, types, and shaders of Y are then accessible in X by qualifying their names with Z.
5
The imported names of modules are not visible outside of the module in which they are imported. For example, if a module X imports a module Y, and Y imports a module Z, the module Z is not visible as Y.Z.
3.8.5
Recursion
1
No module_declaration can be recursive with respect to itself or any other module_declaration.
2
A module_declaration d is (mutually) recursive iff:
3.8.5.1. Recursion conditions
  • d imports itself.
  • There is a sequence of modules d₀, d₁, ..., dₙ such that d imports d₀, and for all m where 0 <= m < n, dₘ imports d₍ₘ₊₁₎, and dₙ imports d.
3.8.6
Syntax
1
The precise syntax of module declarations is given by the following EBNF:
3.8.6.1. Module declaration syntax
package_path =
  name_lower , { "." , name_lower } ;

import_path =
  package_path , "." , name_upper ;

import_declaration =
  "import" , import_path , [ "as" , name_upper ] ;

import_declarations =
  { import_declaration , ";" } ;

module_level_declarations =
  { value_declarations | function_declarations | type_declarations | shader_declarations } ;

module_declaration =
  "module" , name_upper , "is" ,
  import_declarations ,
  module_level_declarations ,
  "end" ;

module_declarations =
  module_declaration , ";" , { module_declaration , ";" } ;
3.9
Packages
3.9.1
Description
1
Packages are to modules as modules are to terms, types, and shaders. Packages provide a non-hierarchical partitioned namespace that separates modules for ease of code re-use across projects.
3.9.2
Declarations
1
A package_declaration declares that the current unit will contain declarations that will be placed in the named package.
2
Multiple units can contain the same package_declaration, however a single unit must contain exactly one package_declaration.
3.9.3
Syntax
1
The precise syntax of package declarations is given by the following EBNF:
3.9.3.1. Package declaration syntax
package_path =
  name_lower , { "." , name_lower } ;

package_declaration =
  "package" , package_path ;
4
Expressions
4.1
Description
4.1.1
Overview
1
An expression is a computation that evaluates to a value of a single type according to the rules given in the operational semantics for each expression form. Expressions may be one of the following forms:
4.1.1.1. Expression forms
4.1.2
Operational Semantics
1
The operational semantics for each expression form appears in the respective sections for each. The following syntactic forms are considered to be values:
4.1.2.1. Values (values)
Values (values)
4.2
Syntax
1
The precise syntax of expressions is given by the following EBNF:
4.2.1. Expression syntax
term_path =
    name_lower
  | name_upper , "." , name_lower ;

type_path =
    name_lower
  | name_upper , "." , name_lower ;

variable_or_application_expression =
  term_path [ "(" , expression , { "," , expression } , ")" ]
  ;

new_parameters =
  "(" , expression , { "," , expression } , ")" ;

new_expression =
  "new" , type_path , new_parameters ;

record_expression_fields =
  "{" , name_lower , "=" , expression , { "," name_lower , "=" , expression } , "}" ;

record_expression =
  "record" , type_path , record_expression_fields ;

local_declaration =
  "value" , name_lower , [ ":" , type_path ] , "=" , expression ;

local_declarations =
  local_declaration , ";" , { local_declarations } ;

let_expression =
  "let" , local_declarations , "in" , expression , "end" ;

conditional_expression =
  "if" , expression , "then" , expression , "else" , expression , "end" ;

matrix_column_access_expression =
  "column" , expression , integer_literal ;

expression_pre =
    integer_literal
  | real_literal
  | boolean_literal
  | variable_or_application_expression
  | conditional_expression
  | matrix_column_access_expression
  | let_expression
  | new_expression
  | record_expression
  ;

expression_projection =
  "." , name_lower ;

expression_swizzle_names =
  "[" , name_lower , { "," , name_lower } , "]" ;

expression =
  expression_pre , { expression_swizzle | expression_projection } ;
4.3
Integer literal
4.3.1
Description
1
An integer_literal is a simple integer value.
4.3.2
Type rules
1
integer_literal expressions are of type integer, where ℤ represents the literal:
4.3.2.1. Integer literal type rule (integer_constant)
Integer literal type rule (integer_constant)
4.3.3
Operational semantics
1
integer_literal expressions are values by definition, and are equal to the value of the literal.
4.4
Real literal
4.4.1
Description
1
A real_literal is a simple real-number value.
4.4.2
Type rules
1
Real literal expressions are of type float, where ℝ represents the literal:
4.4.2.1. Real literal type rule (float_constant)
Real literal type rule (float_constant)
4.4.3
Operational semantics
1
real_literal expressions are values by definition, and are equal to the value of the literal.
4.5
Boolean literal
4.5.1
Description
1
A boolean_literal is a simple true or false value.
4.5.2
Type rules
1
boolean_literal expressions are of type boolean:
4.5.2.1. Boolean true literal type rule (true_constant)
Boolean true literal type rule (true_constant)
4.5.2.2. Boolean false literal type rule (false_constant)
Boolean false literal type rule (false_constant)
4.5.3
Operational semantics
1
Boolean literal expressions are values by definition, and are equal to the value of the literal.
4.6
Variable
4.6.1
Description
1
A variable expression is a simple reference to a variable in the current environment.
4.6.2
Type rules
1
For variable expressions, if a variable x is of type t in the current environment, then the result of evaluating the variable has type t:
4.6.2.1. Variable type rule (variable)
Variable type rule (variable)
4.6.3
Operational semantics
1
Variables are replaced with their values during the evaluation of functions, let expressions, and top-level value declarations.
4.7
Function application
4.7.1
Description
1
A function_application expression applies a given function f to an n-tuple of argument expressions.
4.7.2
Type rules
1
For function_application expressions, if a function f takes an n-tuple of values of types (t₀ ✕ ... ✕ tₙ) and returns a value of type u, then applying f to an n-tuple of expressions of the corresponding types, results in a value of type u:
4.7.2.1. Function application type rule (function_application)
Function application type rule (function_application)
4.7.3
Operational semantics
1
For a function_application expression e, expressions passed to the function are evaluated from left-to-right by rules function_application_left_0 and function_application_left_1, and when all of the arguments have evaluated to values, the variables in the body of the function are substituted with the values of the arguments and the expression as a whole is evaluated, by rule function_application_body.
4.7.3.1. Function application semantics (function_application)
Function application semantics (function_application)
4.8
Conditional
4.8.1
Description
1
A conditional expression evaluates to the expression in either of its defined branches based on a given condition.
4.8.2
Type rules
1
For conditional expressions, if the condition is of type boolean, and both branches are of type t, then evaluating the expression results in a value of type t:
4.8.2.1. Conditional type rule (conditional)
Conditional type rule (conditional)
4.8.3
Operational semantics
1
For a conditional expression e, the condition of the expression is evaluated, if it is not already a value, by rule if_condition. If the condition is true, e evaluates to the expression in the left branch, by rule if_true. If the condition is false, e evaluates to the expression in the right branch, by rule if_false.
4.8.3.1. Conditional semantics (condition)
Conditional semantics (condition)
4.9
Let
4.9.1
Description
1
A let_expression consists of a sequence of local_value_declarations and a body consisting of a single expression. The local_value_declarations differ from top-level value_declarations in that the order of declaration is significant, and it is legal for multiple local_value_declarations to have the same name, with each new declaration hiding any previous declarations (including top level declarations) with the same name.
2
The same rules apply for local_value_declarations with regards to recursion as any other term declaration.
4.9.2
Type rules
1
For let_expressions, if each successive local_value_declaration is well-typed (with respect to the environment and the preceding local_value_declarations), and the body of the expression (denoted y) is of type t, then evaluating the expression results in a value of type t:
4.9.2.1. Let type rule (let)
Let type rule (let)
4.9.3
Operational semantics
1
For a let expression e, the local_value_declarations are evaluated from top-to-bottom with each of the previously evaluated declarations being substituted into the current declaration before evaluation, by rule let_locals. When all of the declarations have been evaluated, the values of the declarations are subsituted into the body of the let and e evaluates to the resulting expression, by rule let_body.
4.9.3.1. Let semantics (let)
Let semantics (let)
4.10
Record Projection
4.10.1
Description
1
A record_projection expression returns the value of a field from an expression r, which is expected to be of a record type.
4.10.2
Type rules
1
For record_projection expressions, if an expression r is of type t, and t is a record type with fields 𝔽ₘ to 𝔽ₙ, of types tₘ to tₙ, then accessing field 𝔽ₖ of r, where k ∈ [m, n], results in a value of type tₖ:
4.10.2.1. Record projection type rule (record_projection)
Record projection type rule (record_projection)
4.10.3
Operational semantics
1
For a record_projection expression e, the left hand side of the expression is evaluated, by rule record_projection_pre, and then e evaluates to the value associated with the label k by rule record_projection_value.
4.10.3.1. Record projection semantics (record_projection)
Record projection semantics (record_projection)
4.11
Record
4.11.1
Description
1
A record_expression constructs a new value of a record type.
4.11.2
Type rules
1
If a record type t exists in the current environment, then a record expression creates a new value of type t. Note that the type rule implies that all fields of the corresponding record type must be specified exactly once.
4.11.2.1. Record expression type rule (record_expression)
Record expression type rule (record_expression)
4.11.3
Operational semantics
1
A record_expression is a set of distinct record field labels with associated expressions. The expressions associated with each field are evaluated in the order that they appear in the source code, by rules record_expression_0 and record_expression_1, resulting in a new value of type t.
4.11.3.1. Record expression semantics (record_expression)
Record expression semantics (record_expression)
4.12
Swizzle
4.12.1
Description
1
A swizzle_expression selects one or more named components of an expression of a vector type, returning either a scalar value, or another vector.
4.12.2
Type rules
1
For swizzle_expressions, special type rules apply as described in the Vectors section of the Types section.
4.12.3
Operational semantics
1
For a swizzle_expression e, the left hand side of the expression is evaluated, by rule swizzle_pre, and the resulting expression is a new vector or scalar value.
4.12.3.1. Swizzle semantics (swizzle)
Swizzle semantics (swizzle)
4.13
Matrix Column Access
4.13.1
Description
1
A matrix_column_access_expression retrieves exactly one column of a matrix type, returning a value of an appropriate vector type representing the column.
4.13.2
Type rules
1
For matrix_column_access_expressions, special type rules apply as described in the Matrices section of the Types section.
4.13.3
Operational semantics
1
For a matrix_column_access_expression e, the first subexpression is evaluated, by rule matrix_column_access_pre, and the resulting expression is a new vector value.
4.13.3.1. Matrix Column Access semantics (matrix_column_access)
Matrix Column Access semantics (matrix_column_access)
2
Note that the integer constant given as the index of the column to return is required by the type rules to be greater than zero and less than the number of columns in the type, and therefore evaluation cannot fail due to an out-of-range index.
4.14
New
4.14.1
Description
1
A new_expression creates a new value of a given type, initialized with the values of the given expressions.
4.14.2
Type rules
1
For new_expression, that construct values of types with the new keyword, special type rules apply as described in the Constructors section of the Types section.
4.14.3
Operational semantics
1
A new_expression is of the form new t x, where the x is an n-tuple of expressions given as constructor arguments. The expressions given are evaluated from left-to-right by rules new_left_0 and new_left_1, resulting in a new value of type t.
4.14.3.1. New semantics (new)
New semantics (new)
5
Types
5.1
Overview
1
A type classifies a set of values. Types in the parasol language have by-name equivalence (that is, two types are equal iff they have the same name) and the types of all terms are checked statically. All well-typed terms in the language have exactly one type.
2
The language defines a set of basic types, and allows the declaration of new types. The set of basic types is:
5.1.1. Basic types
3
Values of the basic types may be introduced via certain literal expressions, or via the use of the new keyword, which invokes an appropriate constructor function for the given type. The constructor function chosen is based upon the n-tuple of arguments presented to the new keyword, and if no appropriate function exists, the expression is rejected as ill-typed.
5.2
Constructors
1
Each of the basic types have zero or more associated anonymous constructor functions (often abbreviated to constructors) which are responsible for introducing values of the types into the environment. An expression of the form new s (x₀ : t₀, ..., xₙ : tₙ) has type s iff there is a constructor for s of type (t₀ ✕ ... tₙ) → s.
2
The descriptions for each of the basic types describe the available constructors for each.
5.3
Integer
5.3.1
Description
1
The integer type represents a signed, 32 bit, two's-complement integer. Values outside of the range [-(2³¹), (2³¹) - 1] are silently wrapped to produce the low-order 32 bits of the result.
5.3.2
Constructors
1
The type has the following constructors:
5.3.2.1. Constructors
  • integer → integer
  • boolean → integer
  • float → integer
2
The constructor taking a value v of type boolean results in an integer value 0 iff v = false and an integer value 1 iff v = true.
3
The constructor taking a value v of type float results in an integer value consisting of the integral part of v with the fractional part truncated.
4
The integer type is a scalar type. As with the other scalar types, the type rule for the construction of values of type integer is:
5.3.2.2. Scalar new type rule (new_scalar)
Scalar new type rule (new_scalar)
5.4
Float
5.4.1
Description
1
The float type represents a single-precision IEEE754 floating point number.
5.4.2
Constructors
1
The type has the following constructors:
5.4.2.1. Constructors
  • integer → float
  • boolean → float
  • float → float
2
The constructor taking a value v of type boolean results in a value 0.0 iff v = false and a value 1.0 v = true.
3
The constructor taking a value v of type integer results in an value with an integral part as close as possible to the value of v dependent on the internal precision of the float type.
4
The float type is a scalar type. As with the other scalar types, the type rule for the construction of values of type float is:
5.4.2.2. Scalar new type rule (new_scalar)
Scalar new type rule (new_scalar)
5.5
Boolean
5.5.1
Description
1
The boolean type represents a true or false value.
5.5.2
Constructors
1
The type has the following constructors:
5.5.2.1. Constructors
  • boolean → boolean
  • float → boolean
  • integer → boolean
2
The constructor taking a value v of type float results in a value false iff v = 0.0 and a value true otherwise.
3
The constructor taking a value v of type integer results in a value false iff v = 0 and a value true otherwise.
4
The boolean type is a scalar type. As with the other scalar types, the type rule for the construction of values of type boolean is:
5.5.2.2. Scalar new type rule (new_scalar)
Scalar new type rule (new_scalar)
5.6
Vectors
5.6.1
Description
1
The vector_NT types represent fixed-length vectors, where N ∈ [2, 4] and represents the number of components in the vector, and T ∈ {f, i} where f indicates that the components of the vector are of type float and i indicates that the components of the vector are of type integer.
2
The components of the vector_NT types are labelled, in order, from the n-tuple of labels K = (x, y, z, w). At most N labels are used for each type, so the first, second, third, and fourth elements of the vector_4T types are labelled x, y, z, and w, respectively. The vector_3T types lack a w component, and the vector_2T types lack both z and w components.
3
The values of the components of the vector_NT types are extracted via swizzle expressions. A swizzle expression consists of an n-tuple Sₚ of labels taken from the set S = tuples(L, M) of n-tuples, where M <= N, L is the first M - 1 elements of K, and 0 <= P <= |S|, and evaluates to a value of type vector_MT or, in the case that M = 1, a scalar value of type T, consisting of the values of the components named in Sₚ:
5.6.1.1. Swizzle vector type rule (vector_swizzle)
Swizzle vector type rule (vector_swizzle)
5.6.1.2. Swizzle scalar type rule (vector_swizzle_single)
Swizzle scalar type rule (vector_swizzle_single)
4
Algebraically, swizzling is analogous to multiplication of a vector v of size N by an NxN matrix p, where each row of p consists of N - 1 zeroes and exactly one 1:
5.6.1.3. Swizzle matrix example
Swizzle matrix example
5.6.2
Constructors
1
The constructors of the vector_NT types can be conceptually divided into primary and auxiliary constructors. Each vector_NT type has exactly one primary constructor which initializes the components of the resulting vector_NT value to the values of the expressions in the exact order given. There is no practical or visible difference between a primary and auxiliary constructor; the distinction is simply made for the purposes of describing the typing rules.
2
The types of the primary constructors for each type are:
5.6.2.1. Vector primary constructors
TypeConstructor type
vector_2i(integer, integer) → vector_2i
vector_3i(integer, integer, integer) → vector_3i
vector_4i(integer, integer, integer, integer) → vector_4i
vector_2f(float, float) → vector_2f
vector_3f(float, float, float) → vector_3f
vector_4f(float, float, float, float) → vector_4f
3
Given the presence of primary constructors, the type rule for the construction of a vector using the new keyword is:
5.6.2.2. Vector new type rule (vector_new)
Vector new type rule (vector_new)
4
The auxiliary constructors for the vector_NT types are:
5.6.2.3. Vector auxiliary constructors
TypeConstructor type
vector_2ivector_2i → vector_2i
vector_3i(integer, vector_2i) → vector_3i
vector_3i(vector_2i, integer) → vector_3i
vector_3ivector_3i → vector_3i
vector_4i(vector_2i, integer, integer) → vector_4i
vector_4i(integer, vector_2i, integer) → vector_4i
vector_4i(vector_2i, vector_2i) → vector_4i
vector_4i(integer, integer, vector_2i) → vector_4i
vector_4i(vector_3i, integer) → vector_4i
vector_4i(integer, vector_3i) → vector_4i
vector_4ivector_4i → vector_4i
vector_2fvector_2f → vector_2f
vector_3f(float, vector_2f) → vector_3f
vector_3f(vector_2f, float) → vector_3f
vector_3fvector_3f → vector_3f
vector_4f(vector_2f, float, float) → vector_4f
vector_4f(float, vector_2f, float) → vector_4f
vector_4f(vector_2f, vector_2f) → vector_4f
vector_4f(float, float, vector_2f) → vector_4f
vector_4f(vector_3f, float) → vector_4f
vector_4f(float, vector_3f) → vector_4f
vector_4fvector_4f → vector_4f
5
For each auxiliary constructor for a given vector_NT type, the values of the scalars (if any), and the values of the components of the given vectors (if any), are concatenated together in the order given to produce an n-tuple of length N which is then passed directly to the primary constructor for the given type.
5.7
Matrices
5.7.1
Description
1
The matrix_NxNf types represent square matrices, where N ∈ [3, 4] and represents the number of rows/columns in the matrix. Only matrices with elements of type float are provided.
2
The columns of values of matrix_NxNf types are extracted via matrix_column_access expressions. A matrix_column_access expression consists of an expression e of a matrix_NxNf type, and an integer constant K where 0 <= K < N, and evaluates to a value of type vector_Nf representing the Kth column of e.
5.7.1.1. Matrix Column Access type rule (matrix_column_access)
Matrix Column Access type rule (matrix_column_access)
5.7.2
Constructors
1
Values of the matrix_NxNf types are constructed by providing exactly N column vectors of size N. This is reflected in the available constructors for the matrix_NxNf types:
5.7.2.1. Matrix constructors
TypeConstructor type
matrix_3x3f(vector_3f, vector_3f, vector_3f) → matrix_3x3f
matrix_4x4f(vector_4f, vector_4f, vector_4f, vector_4f) → matrix_4x4f
2
The type rule for the construction of matrices with the new keyword is:
5.7.2.2. Matrix new type rule (matrix_new)
Matrix new type rule (matrix_new)
5.8
Samplers
5.8.1
Description
1
The sampler_2d and sampler_cube types represent abstract handles to two-dimensional and cube textures, respectively.
5.8.2
Constructors
1
The types have no constructors and there is no way to create new values of the types in the language. They are intended for use as parameters to shaders.
5.9
Records
5.9.1
Description
1
Record types are composite types consisting of labelled fields. Values of record types are constructed with the new keyword, and values of fields are accessed with record_projection expressions.
2
Only a subset of the available types can be used as fields in records:
5.9.1.1. Record field types
5.9.2
Constructors
1
Record types do not have constructors and values of record types can only be introduced with record expressions.
6
Compilation and Execution
6.1
Overview
1
This section attempts to informally document the typical life cycle of a parasol program, from its initial state as a set of source code, to its final state executing on a GPU, from a somewhat abstract and idealized viewpoint. The intention is to allow the reader to better understand how the given operational semantics fit together and how the language as structured results in a working program.
6.2
Lifecycle
1
First, the intended program is compiled:
6.2.1. Compilation
  1. The user submits a series of units, in no particular order, to the parasol implementation compiler, along with the fully-qualified name of a program.
  2. The compiler combines the units, checks for module name collisions, checks the sanity of the submitted modules, resolves all names, and checks the types of all terms.
  3. The compiler then erases all module_declarations from the environment, renaming all terms to result in a set of terms with unique names.
  4. The compiler then determines all terms upon which the program depends, removing all unused terms and sorting the resulting terms topologically.
2
At this point, the environment contains a vertex shader V with an associated ordered set of terms T, and fragment shader F with an associated ordered set of terms U.
3
Execution then proceeds as follows:
6.2.2. Execution
  1. Execution of V begins.
  2. The terms in T are evaluated in the order given.
  3. The operational semantics imply that the values of the terms in T have been substituted into the local declarations of V. The local declarations defined in V are evaluated.
  4. The values resulting from evaluation are written to the outputs of V.
  5. Execution of F begins.
  6. The terms in U are evaluated in the order given.
  7. The operational semantics imply that the values of the terms in U have been substituted into the local declarations of F. The local declarations defined in F are evaluated.
  8. If F contains a discard declaration, and the condition evaluates to true, execution of F halts and no output is produced.
  9. The values resulting from evaluation are written to the outputs of F.
7
Standard Library Reference
7.1
Module com.io7m.parasol.Boolean
7.1.1
or
7.1.1.1. or Definition
function or (x : boolean, y : boolean) : boolean
1
Return the true iff x == true or y == true.
7.2
Module com.io7m.parasol.Float
7.2.1
absolute
7.2.1.1. absolute Definition
function absolute (x : float) : float
1
Return the absolute value of x.
7.2.2
add
7.2.2.1. add Definition
function add (x : float, y : float) : float
1
Return x + y.
7.2.3
arc_cosine
7.2.3.1. arc_cosine Definition
function arc_cosine (x : float) : float
1
Return the arc cosine acos(x).
7.2.4
arc_sine
7.2.4.1. arc_sine Definition
function arc_sine (x : float) : float
1
Return the arc sine asin(x).
7.2.5
arc_tangent
7.2.5.1. arc_tangent Definition
function arc_tangent (x : float) : float
1
Return the arc tangent atan(x).
7.2.6
ceiling
7.2.6.1. ceiling Definition
function ceiling (x : float) : float
1
Return a value equal to the nearest integer that is greater than or equal to x.
7.2.7
clamp
7.2.7.1. clamp Definition
function clamp (x : float, min : float, max : float) : float
1
Return x constrainted to the range [min, max].
7.2.8
cosine
7.2.8.1. cosine Definition
function cosine (x : float) : float
1
Return the cosine cos(x).
7.2.9
divide
7.2.9.1. divide Definition
function divide (x : float, y : float) : float
1
Return the division x / y. The result is only defined if y > 0.
7.2.10
equals
7.2.10.1. equals Definition
function equals (x : float, y : float) : boolean
1
Return true iff x == y.
7.2.11
floor
7.2.11.1. floor Definition
function floor (x : float) : float
1
Return a value equal to the nearest integer that is less than or equal to x.
7.2.12
greater
7.2.12.1. greater Definition
function greater (x : float, y : float) : boolean
1
Return true iff x > y.
7.2.13
greater_or_equal
7.2.13.1. greater_or_equal Definition
function greater_or_equal (x : float, y : float) : boolean
1
Return true iff x >= y.
7.2.14
interpolate
7.2.14.1. interpolate Definition
function interpolate (x : float, y : float, a : float) : float
1
Return a linearly interpolated value in the range [x, y] given by (x ✕ (1 - a)) + (y ✕ a).
7.2.15
is_infinite
7.2.15.1. is_infinite Definition
function is_infinite (x : float) : boolean
1
Return true iff x == infinity.
7.2.16
is_nan
7.2.16.1. is_nan Definition
function is_nan (x : float) : boolean
1
Return true iff x is not a number.
7.2.17
lesser
7.2.17.1. lesser Definition
function lesser (x : float, y : float) : boolean
1
Return true iff x < y.
7.2.18
lesser_or_equal
7.2.18.1. lesser_or_equal Definition
function lesser_or_equal (x : float, y : float) : boolean
1
Return true iff x <= y.
7.2.19
log2
7.2.19.1. log2 Definition
function log2 (x : float) : float
1
Return the base 2 logarithm of x.
7.2.20
maximum
7.2.20.1. maximum Definition
function maximum (x : float, y : float) : float
1
Return the maximum value of x and y.
7.2.21
minimum
7.2.21.1. minimum Definition
function minimum (x : float, y : float) : float
1
Return the minimum value of x and y.
7.2.22
modulo
7.2.22.1. modulo Definition
function modulo (x : float, y : float) : float
1
Return the value of x mod y.
7.2.23
multiply
7.2.23.1. multiply Definition
function multiply (x : float, y : float) : float
1
Return the value of x ✕ y.
7.2.24
negate
7.2.24.1. negate Definition
function negate (x : float) : float
1
Return the negation -x.
7.2.25
power
7.2.25.1. power Definition
function power (x : float, n : float) : float
1
Return the value of xⁿ.
7.2.26
round
7.2.26.1. round Definition
function round (x : float) : float
1
Return the value of the nearest integer to x.
7.2.27
sign
7.2.27.1. sign Definition
function sign (x : float) : float
1
Return 0.0 iff x == 0.0, 1.0 iff x > 0.0, and -1.0 otherwise.
7.2.28
sine
7.2.28.1. sine Definition
function sine (x : float) : float
1
Return the sine sin(x).
7.2.29
square_root
7.2.29.1. square_root Definition
function square_root (x : float) : float
1
Return the square root of x.
7.2.30
subtract
7.2.30.1. subtract Definition
function subtract (x : float, y : float) : float
1
Return the value of of x - y.
7.2.31
tangent
7.2.31.1. tangent Definition
function tangent (x : float) : float
1
Return the tangent tan(x).
7.2.32
truncate
7.2.32.1. truncate Definition
function truncate (x : float) : float
1
Return the nearest integer to x whose absolute value is not greater than the absolute value of x.
7.3
Module com.io7m.parasol.Integer
7.3.1
add
7.3.1.1. add Definition
function add (x : integer, y : integer) : integer
1
Return x + y.
7.3.2
divide
7.3.2.1. divide Definition
function divide (x : integer, y : integer) : integer
1
Return the division x / y. The result is only defined if y > 0.
7.3.3
multiply
7.3.3.1. multiply Definition
function multiply (x : integer, y : integer) : integer
1
Return x ✕ y.
7.3.4
subtract
7.3.4.1. subtract Definition
function subtract (x : integer, y : integer) : integer
1
Return x - y.
7.4
Module com.io7m.parasol.Matrix3x3f
7.4.1
multiply
7.4.1.1. multiply Definition
function multiply (m0 : matrix_3x3f, m1 : matrix_3x3f) : matrix_3x3f
1
Return m0 ✕ m1.
7.4.2
multiply_vector
7.4.2.1. multiply_vector Definition
function multiply_vector (m : matrix_3x3f, v : vector_3f) : vector_3f
1
Return m ✕ v.
7.5
Module com.io7m.parasol.Matrix4x4f
7.5.1
multiply
7.5.1.1. multiply Definition
function multiply (m0 : matrix_4x4f, m1 : matrix_4x4f) : matrix_4x4f
1
Return m0 ✕ m1.
7.5.2
multiply_vector
7.5.2.1. multiply_vector Definition
function multiply_vector (m : matrix_4x4f, v : vector_4f) : vector_4f
1
Return m ✕ v.
7.6
Module com.io7m.parasol.Sampler2D
7.6.1
texture
7.6.1.1. texture Definition
function texture (t : sampler_2d, uv : vector_2f) : vector_4f
1
Retrieve a texel from the texture t from the texture coordinate uv.
7.6.2
texture_with_offset
7.6.2.1. texture_with_offset Definition
function texture_with_offset (t : sampler_2d, uv : vector_2f, o : vector_2i) : vector_4f
1
Retrieve a texel from the texture t from the texture coordinate uv using texel offsets o.
2
This function is not available on GLSL versions <= 120, and GLSL ES version 100, and no software emulation is possible.
7.6.3
texture_with_lod
7.6.3.1. texture_with_lod Definition
function texture_with_lod (t : sampler_2d, uv : vector_2f, lod : float) : vector_4f
1
Retrieve a texel from the texture t from the texture coordinate uv using an explicit level-of-detail lod.
2
This function is not available on GLSL versions <= 120, and GLSL ES version 100, and no software emulation is possible.
7.7
Module com.io7m.parasol.Vector2f
7.7.1
add
7.7.1.1. add Definition
function add (v0 : vector_2f, v1 : vector_2f) : vector_2f
1
Return the component-wise addition v0 + v1.
7.7.2
add_scalar
7.7.2.1. add_scalar Definition
function add_scalar (v : vector_2f, x : float) : vector_2f
1
Return the addition (v[x] + s, v[y] + s).
7.7.3
divide
7.7.3.1. divide Definition
function divide (v0 : vector_2f, v1 : vector_2f) : vector_2f
1
Return the component-wise division v0 / v1.
7.7.4
divide_scalar
7.7.4.1. divide_scalar Definition
function divide_scalar (v : vector_2f, x : float) : vector_2f
1
Return the division (v[x] / s, v[y] / s).
7.7.5
dot
7.7.5.1. dot Definition
function dot (v0 : vector_2f, v1 : vector_2f) : float
1
Return the dot product v0 ⋅ v1.
7.7.6
interpolate
7.7.6.1. interpolate Definition
function interpolate (v0 : vector_2f, v1 : vector_2f, t : float) : vector_2f
1
Return the linear interpolation (v1 ✕ t) + (v0 ✕ (1 - t)).
7.7.7
magnitude
7.7.7.1. magnitude Definition
function magnitude (v : vector_2f) : float
1
Return the magnitude of v.
7.7.8
multiply
7.7.8.1. multiply Definition
function multiply (v0 : vector_2f, v1 : vector_2f) : vector_2f
1
Return the component-wise multiplication v0 ✕ v1.
7.7.9
multiply_scalar
7.7.9.1. multiply_scalar Definition
function multiply_scalar (v0 : vector_2i, x : float) : vector_3f
1
Return the multiplication (v[x] ✕ s, v[y] ✕ s).
7.7.10
negate
7.7.10.1. negate Definition
function negate (v : vector_2f) : vector_2f
1
Return the component-wise negation -v.
7.7.11
normalize
7.7.11.1. normalize Definition
function normalize (v : vector_2f) : vector_2f
1
Return a vector pointing in the same direction as v but with a magnitude of 1.
7.7.12
reflect
7.7.12.1. reflect Definition
function reflect (i : vector_2f, n : vector_2f) : vector_2f
1
Return the reflection of the incident vector i with respect to the vector n, as given by i - 2.0 ✕ dot(n, i) ✕ n.
7.7.13
refract
7.7.13.1. refract Definition
function refract (i : vector_2f, n : vector_2f, e : float) : vector_2f
1
Return the refraction vector of the incident vector i with respect to the vector n, with the given ratio of indices of refraction e.
7.7.14
subtract
7.7.14.1. subtract Definition
function subtract (v0 : vector_2f, v1 : vector_2f) : vector_2f
1
Return the component-wise subtraction v0 - v1.
7.8
Module com.io7m.parasol.Vector2i
7.8.1
add
7.8.1.1. add Definition
function add (v0 : vector_2i, v1 : vector_2i) : vector_2i
1
Return the component-wise addition v0 + v1.
7.8.2
add_scalar
7.8.2.1. add_scalar Definition
function add_scalar (v : vector_2i, x : integer) : vector_2i
1
Return the addition (v[x] + s, v[y] + s).
7.8.3
divide
7.8.3.1. divide Definition
function divide (v0 : vector_2i, v1 : vector_2i) : vector_2i
1
Return the component-wise division v0 / v1.
7.8.4
divide_scalar
7.8.4.1. divide_scalar Definition
function divide_scalar (v : vector_2i, x : integer) : vector_2i
1
Return the division (v[x] / s, v[y] / s).
7.8.5
dot
7.8.5.1. dot Definition
function dot (v0 : vector_2i, v1 : vector_2i) : integer
1
Return the dot product v0 ⋅ v1.
7.8.6
interpolate
7.8.6.1. interpolate Definition
function interpolate (v0 : vector_2i, v1 : vector_2i, t : float) : vector_2i
1
Return the linear interpolation (v1 ✕ t) + (v0 ✕ (1 - t)).
7.8.7
magnitude
7.8.7.1. magnitude Definition
function magnitude (v : vector_2i) : float
1
Return the magnitude of v.
7.8.8
multiply
7.8.8.1. multiply Definition
function multiply (v0 : vector_2i, v1 : vector_2i) : vector_2i
1
Return the component-wise multiplication v0 ✕ v1.
7.8.9
multiply_scalar
7.8.9.1. multiply_scalar Definition
function multiply_scalar (v0 : vector_2i, x : integer) : vector_3f
1
Return the multiplication (v[x] ✕ s, v[y] ✕ s).
7.8.10
negate
7.8.10.1. negate Definition
function negate (v : vector_2i) : vector_2i
1
Return the component-wise negation -v.
7.8.11
normalize
7.8.11.1. normalize Definition
function normalize (v : vector_2i) : vector_2i
1
Return a vector pointing in the same direction as v but with a magnitude of 1.
7.8.12
reflect
7.8.12.1. reflect Definition
function reflect (i : vector_2i, n : vector_2i) : vector_2i
1
Return the reflection of the incident vector i with respect to the vector n, as given by i - 2.0 ✕ dot(n, i) ✕ n.
7.8.13
refract
7.8.13.1. refract Definition
function refract (i : vector_2i, n : vector_2i, e : float) : vector_2i
1
Return the refraction vector of the incident vector i with respect to the vector n, with the given ratio of indices of refraction e.
7.8.14
subtract
7.8.14.1. subtract Definition
function subtract (v0 : vector_2i, v1 : vector_2i) : vector_2i
1
Return the component-wise subtraction v0 - v1.
7.9
Module com.io7m.parasol.Vector3f
7.9.1
add
7.9.1.1. add Definition
function add (v0 : vector_3f, v1 : vector_3f) : vector_3f
1
Return the component-wise addition v0 + v1.
7.9.2
add_scalar
7.9.2.1. add_scalar Definition
function add_scalar (v : vector_3f, x : integer) : vector_3f
1
Return the addition (v[x] + s, v[y] + s, v[z] + s).
7.9.3
divide
7.9.3.1. divide Definition
function divide (v0 : vector_3f, v1 : vector_3f) : vector_3f
1
Return the component-wise division v0 / v1.
7.9.4
divide_scalar
7.9.4.1. divide_scalar Definition
function divide_scalar (v : vector_3f, x : integer) : vector_3f
1
Return the division (v[x] / s, v[y] / s, v[z] / s).
7.9.5
cross
7.9.5.1. cross Definition
function cross (v0 : vector_3f, v1 : vector_3f) : vector_3f
1
Return the cross product v0 ✕ v1.
7.9.6
dot
7.9.6.1. dot Definition
function dot (v0 : vector_3f, v1 : vector_3f) : integer
1
Return the dot product v0 ⋅ v1.
7.9.7
interpolate
7.9.7.1. interpolate Definition
function interpolate (v0 : vector_3f, v1 : vector_3f, t : float) : vector_3f
1
Return the linear interpolation (v1 ✕ t) + (v0 ✕ (1 - t)).
7.9.8
magnitude
7.9.8.1. magnitude Definition
function magnitude (v : vector_3f) : float
1
Return the magnitude of v.
7.9.9
multiply
7.9.9.1. multiply Definition
function multiply (v0 : vector_3f, v1 : vector_3f) : vector_3f
1
Return the component-wise multiplication v0 ✕ v1.
7.9.10
multiply_scalar
7.9.10.1. multiply_scalar Definition
function multiply_scalar (v0 : vector_3f, x : float) : vector_3f
1
Return the multiplication (v[x] ✕ s, v[y] ✕ s, v[z] ✕ s).
7.9.11
negate
7.9.11.1. negate Definition
function negate (v : vector_3f) : vector_3f
1
Return the component-wise negation -v.
7.9.12
normalize
7.9.12.1. normalize Definition
function normalize (v : vector_3f) : vector_3f
1
Return a vector pointing in the same direction as v but with a magnitude of 1.
7.9.13
reflect
7.9.13.1. reflect Definition
function reflect (i : vector_3f, n : vector_3f) : vector_3f
1
Return the reflection of the incident vector i with respect to the vector n, as given by i - 2.0 ✕ dot(n, i) ✕ n.
7.9.14
refract
7.9.14.1. refract Definition
function refract (i : vector_3f, n : vector_3f, e : float) : vector_3f
1
Return the refraction vector of the incident vector i with respect to the vector n, with the given ratio of indices of refraction e.
7.9.15
subtract
7.9.15.1. subtract Definition
function subtract (v0 : vector_3f, v1 : vector_3f) : vector_3f
1
Return the component-wise subtraction v0 - v1.
7.10
Module com.io7m.parasol.Vector3i
7.10.1
add
7.10.1.1. add Definition
function add (v0 : vector_3i, v1 : vector_3i) : vector_3i
1
Return the component-wise addition v0 + v1.
7.10.2
add_scalar
7.10.2.1. add_scalar Definition
function add_scalar (v : vector_3i, x : integer) : vector_3i
1
Return the addition (v[x] + s, v[y] + s, v[z] + s).
7.10.3
divide
7.10.3.1. divide Definition
function divide (v0 : vector_3i, v1 : vector_3i) : vector_3i
1
Return the component-wise division v0 / v1.
7.10.4
divide_scalar
7.10.4.1. divide_scalar Definition
function divide_scalar (v : vector_3i, x : integer) : vector_3i
1
Return the division (v[x] / s, v[y] / s, v[z] / s).
7.10.5
dot
7.10.5.1. dot Definition
function dot (v0 : vector_3i, v1 : vector_3i) : integer
1
Return the dot product v0 ⋅ v1.
7.10.6
interpolate
7.10.6.1. interpolate Definition
function interpolate (v0 : vector_3i, v1 : vector_3i, t : float) : vector_3i
1
Return the linear interpolation (v1 ✕ t) + (v0 ✕ (1 - t)).
7.10.7
magnitude
7.10.7.1. magnitude Definition
function magnitude (v : vector_3i) : float
1
Return the magnitude of v.
7.10.8
multiply
7.10.8.1. multiply Definition
function multiply (v0 : vector_3i, v1 : vector_3i) : vector_3i
1
Return the component-wise multiplication v0 ✕ v1.
7.10.9
multiply_scalar
7.10.9.1. multiply_scalar Definition
function multiply_scalar (v0 : vector_3i, x : float) : vector_3i
1
Return the multiplication (v[x] ✕ s, v[y] ✕ s, v[z] ✕ s).
7.10.10
negate
7.10.10.1. negate Definition
function negate (v : vector_3i) : vector_3i
1
Return the component-wise negation -v.
7.10.11
normalize
7.10.11.1. normalize Definition
function normalize (v : vector_3i) : vector_3i
1
Return a vector pointing in the same direction as v but with a magnitude of 1.
7.10.12
reflect
7.10.12.1. reflect Definition
function reflect (i : vector_3i, n : vector_3i) : vector_3i
1
Return the reflection of the incident vector i with respect to the vector n, as given by i - 2.0 ✕ dot(n, i) ✕ n.
7.10.13
refract
7.10.13.1. refract Definition
function refract (i : vector_3i, n : vector_3i, e : float) : vector_3i
1
Return the refraction vector of the incident vector i with respect to the vector n, with the given ratio of indices of refraction e.
7.10.14
subtract
7.10.14.1. subtract Definition
function subtract (v0 : vector_3i, v1 : vector_3i) : vector_3i
1
Return the component-wise subtraction v0 - v1.
7.11
Module com.io7m.parasol.Vector4f
7.11.1
add
7.11.1.1. add Definition
function add (v0 : vector_4f, v1 : vector_4f) : vector_4f
1
Return the component-wise addition v0 + v1.
7.11.2
add_scalar
7.11.2.1. add_scalar Definition
function add_scalar (v : vector_4f, x : integer) : vector_4f
1
Return the addition (v[x] + s, v[y] + s, v[z] + s, v[w] + s).
7.11.3
divide
7.11.3.1. divide Definition
function divide (v0 : vector_4f, v1 : vector_4f) : vector_4f
1
Return the component-wise division v0 / v1.
7.11.4
divide_scalar
7.11.4.1. divide_scalar Definition
function divide_scalar (v : vector_4f, x : integer) : vector_4f
1
Return the division (v[x] / s, v[y] / s, v[z] / s, v[w] / s).
7.11.5
dot
7.11.5.1. dot Definition
function dot (v0 : vector_4f, v1 : vector_4f) : integer
1
Return the dot product v0 ⋅ v1.
7.11.6
interpolate
7.11.6.1. interpolate Definition
function interpolate (v0 : vector_4f, v1 : vector_4f, t : float) : vector_4f
1
Return the linear interpolation (v1 ✕ t) + (v0 ✕ (1 - t)).
7.11.7
magnitude
7.11.7.1. magnitude Definition
function magnitude (v : vector_4f) : float
1
Return the magnitude of v.
7.11.8
multiply
7.11.8.1. multiply Definition
function multiply (v0 : vector_4f, v1 : vector_4f) : vector_4f
1
Return the component-wise multiplication v0 ✕ v1.
7.11.9
multiply_scalar
7.11.9.1. multiply_scalar Definition
function multiply_scalar (v0 : vector_4f, x : float) : vector_4f
1
Return the multiplication (v[x] ✕ s, v[y] ✕ s, v[z] ✕ s, v[w] ✕ s).
7.11.10
negate
7.11.10.1. negate Definition
function negate (v : vector_4f) : vector_4f
1
Return the component-wise negation -v.
7.11.11
normalize
7.11.11.1. normalize Definition
function normalize (v : vector_4f) : vector_4f
1
Return a vector pointing in the same direction as v but with a magnitude of 1.
7.11.12
reflect
7.11.12.1. reflect Definition
function reflect (i : vector_4f, n : vector_4f) : vector_4f
1
Return the reflection of the incident vector i with respect to the vector n, as given by i - 2.0 ✕ dot(n, i) ✕ n.
7.11.13
refract
7.11.13.1. refract Definition
function refract (i : vector_4f, n : vector_4f, e : float) : vector_4f
1
Return the refraction vector of the incident vector i with respect to the vector n, with the given ratio of indices of refraction e.
7.11.14
subtract
7.11.14.1. subtract Definition
function subtract (v0 : vector_4f, v1 : vector_4f) : vector_4f
1
Return the component-wise subtraction v0 - v1.
7.12
Module com.io7m.parasol.Vector4i
7.12.1
add
7.12.1.1. add Definition
function add (v0 : vector_4i, v1 : vector_4i) : vector_4i
1
Return the component-wise addition v0 + v1.
7.12.2
add_scalar
7.12.2.1. add_scalar Definition
function add_scalar (v : vector_4i, x : integer) : vector_4i
1
Return the addition (v[x] + s, v[y] + s, v[z] + s, v[w] + s).
7.12.3
divide
7.12.3.1. divide Definition
function divide (v0 : vector_4i, v1 : vector_4i) : vector_4i
1
Return the component-wise division v0 / v1.
7.12.4
divide_scalar
7.12.4.1. divide_scalar Definition
function divide_scalar (v : vector_4i, x : integer) : vector_4i
1
Return the division (v[x] / s, v[y] / s, v[z] / s, v[w] / s).
7.12.5
dot
7.12.5.1. dot Definition
function dot (v0 : vector_4i, v1 : vector_4i) : integer
1
Return the dot product v0 ⋅ v1.
7.12.6
interpolate
7.12.6.1. interpolate Definition
function interpolate (v0 : vector_4i, v1 : vector_4i, t : float) : vector_4i
1
Return the linear interpolation (v1 ✕ t) + (v0 ✕ (1 - t)).
7.12.7
magnitude
7.12.7.1. magnitude Definition
function magnitude (v : vector_4i) : float
1
Return the magnitude of v.
7.12.8
multiply
7.12.8.1. multiply Definition
function multiply (v0 : vector_4i, v1 : vector_4i) : vector_4i
1
Return the component-wise multiplication v0 ✕ v1.
7.12.9
multiply_scalar
7.12.9.1. multiply_scalar Definition
function multiply_scalar (v0 : vector_4i, x : float) : vector_4i
1
Return the multiplication (v[x] ✕ s, v[y] ✕ s, v[z] ✕ s, v[w] ✕ s).
7.12.10
negate
7.12.10.1. negate Definition
function negate (v : vector_4i) : vector_4i
1
Return the component-wise negation -v.
7.12.11
normalize
7.12.11.1. normalize Definition
function normalize (v : vector_4i) : vector_4i
1
Return a vector pointing in the same direction as v but with a magnitude of 1.
7.12.12
reflect
7.12.12.1. reflect Definition
function reflect (i : vector_4i, n : vector_4i) : vector_4i
1
Return the reflection of the incident vector i with respect to the vector n, as given by i - 2.0 ✕ dot(n, i) ✕ n.
7.12.13
refract
7.12.13.1. refract Definition
function refract (i : vector_4i, n : vector_4i, e : float) : vector_4i
1
Return the refraction vector of the incident vector i with respect to the vector n, with the given ratio of indices of refraction e.
7.12.14
subtract
7.12.14.1. subtract Definition
function subtract (v0 : vector_4i, v1 : vector_4i) : vector_4i
1
Return the component-wise subtraction v0 - v1.
8
Appendices
8.1
EBNF Grammar
1
The full EBNF grammar of the language is as follows:
8.1.1. EBNF Grammar
(* Terminals *)

digit_nonzero =
  "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;

digit =
  "0" | digit_nonzero ;

letter_lower =
  "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" |
  "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" |
  "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" |
  "y" | "z" ;

letter_upper =
  "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" |
  "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" |
  "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" |
  "Y" | "Z" ;

letter =
  letter_lower | letter_upper ;

name_lower =
  letter_lower , { letter | digit | "-" | "_" } ;

name_upper =
  letter_upper , { letter | digit | "-" | "_" } ;

integer_literal =
  "0" | ( ["-"] , digit_nonzero , { digit } ) ;

real_literal =
  ["-"] , digit , { digit } , "." , digit , { digit } ;

boolean_literal =
  "true" | "false" ;

(* Non-terminals *)

package_path =
  name_lower , { "." , name_lower } ;

package_declaration =
  "package" , package_path ;

import_path =
  package_path , "." , name_upper ;

import_declaration =
  "import" , import_path , [ "as" , name_upper ] ;

import_declarations =
  { import_declaration , ";" } ;

type_path =
    name_lower
  | name_upper , "." , name_lower ;

term_path =
    name_lower
  | name_upper , "." , name_lower ;

shader_path =
    name_lower
  | name_upper , "." , name_lower ;

value_declaration =
  "value" , name_lower , [ ":" , type_path ] , "=" , expression ;

value_declarations =
  { value_declaration , ";" } ;

function_formal_parameter =
  name_lower , ":" , type_path ;

function_formal_parameters =
  "(" , function_formal_parameter, { "," , function_formal_parameter } , ")" ;

function_declaration =
  "function" , name_lower , function_formal_parameters , ":" , type_path , "=" , expression ;

term_declaration =
  value_declaration | function_declaration ;

record_type_field =
  name_lower , ":" , type_path ;

record_type_expression =
  "record" , record_type_field , { "," , record_type_field } , "end" ;

type_declaration =
  "type" , name_lower , "is" , type_expression ;

type_declarations =
  { type_declaration , ";" } ;

type_expression =
  record_type_expression
  ;

variable_or_application_expression =
  term_path [ "(" , expression , { "," , expression } , ")" ]
  ;

new_parameters =
  "(" , expression , { "," , expression } , ")" ;

new_expression =
  "new" , type_path , new_parameters ;

record_expression_fields =
  "{" , name_lower , "=" , expression , { "," name_lower , "=" , expression } , "}" ;

record_expression =
  "record" , type_path , record_expression_fields ;

local_declaration =
  "value" , name_lower , [ ":" , type_path ] , "=" , expression ;

local_declarations =
  local_declaration , ";" , { local_declarations } ;

let_expression =
  "let" , local_declarations , "in" , expression , "end" ;

conditional_expression =
  "if" , expression , "then" , expression , "else" , expression , "end" ;

matrix_column_access_expression =
  "column" , expression , integer_literal ;

expression_pre =
    integer_literal
  | real_literal
  | boolean_literal
  | variable_or_application_expression
  | conditional_expression
  | matrix_column_access_expression
  | let_expression
  | new_expression
  | record_expression
  ;

expression_projection =
  "." , name_lower ;

expression_swizzle_names =
  "[" , name_lower , { "," , name_lower } , "]" ;

expression =
  expression_pre , { expression_swizzle | expression_projection } ;

shader_parameter_declaration =
  "parameter" , name_lower , ":" , type_path ;

shader_vertex_input_declaration =
  "in" , name_lower , ":" , type_path ;

shader_vertex_output_declaration =
  "out" , name_lower , ":" , type_path ;

shader_vertex_output_main_declaration =
  "out" , "vertex" , name_lower , ":" , type_path ;

shader_vertex_parameter =
    shader_parameter_declaration
  | shader_vertex_input_declaration
  | shader_vertex_output_declaration
  | shader_vertex_output_main_declaration ;

shader_vertex_parameters =
  { shader_vertex_parameter , ";" } ;

shader_vertex_output_assignment =
  "out" , name_lower , "=" , term_path ;

shader_vertex_output_assignments =
  shader_vertex_output_assignment , ";" , { shader_vertex_output_assignments } ;

shader_vertex_declaration =
  "vertex" , name_lower , "is" ,
  shader_vertex_parameters ,
  [ "with" , local_declarations ] ,
  "as" ,
  shader_vertex_output_assignments ,
  "end" ;

shader_fragment_input_declaration =
  "in" , name_lower , ":" , type_path ;

shader_fragment_output_declaration =
  "out" , name_lower , ":" , type_path , "as" , integer_literal ;

shader_fragment_output_depth_declaration =
  "out" , "depth", name_lower , ":" , type_path ;

shader_fragment_parameter =
    shader_parameter_declaration
  | shader_fragment_input_declaration
  | shader_fragment_output_declaration
  | shader_fragment_output_depth_declaration ;

shader_fragment_parameters =
  { shader_fragment_parameter , ";" } ;

shader_fragment_discard_declaration =
  "discard" , "(" , expression , ")" ;

shader_fragment_local_declaration =
    local_declaration
  | shader_fragment_discard_declaration ;

shader_fragment_local_declarations =
  shader_fragment_local_declaration , ";" , { shader_fragment_local_declarations } ;

shader_fragment_output_assignment =
  "out" , name_lower , "=" , term_path ;

shader_fragment_output_assignments =
  shader_fragment_output_assignment , ";" , { shader_fragment_output_assignments } ;

shader_fragment_declaration =
  "fragment" , name_lower , "is" ,
  shader_fragment_parameters ,
  [ "with" , shader_fragment_local_declarations ] ,
  "as" ,
  shader_fragment_output_assignments ,
  "end" ;

shader_program_declaration =
  "program" , name_lower , "is" ,
  "vertex" , shader_path , ";" ,
  "fragment" , shader_path , ";" ,
  "end" ;

shader_declaration =
  "shader" , ( shader_vertex_declaration | shader_fragment_declaration | shader_program_declaration ) ;

shader_declarations =
  { shader_declaration , ";" } ;

module_level_declarations =
  { value_declarations | function_declarations | type_declarations | shader_declarations } ;

module_declaration =
  "module" , name_upper , "is" ,
  import_declarations ,
  module_level_declarations ,
  "end" ;

module_declarations =
  module_declaration , ";" , { module_declaration , ";" } ;

unit =
  package_declaration , ";" ,
  module_declarations ;
8.2
Type rules
1
The full type rules for the language are as follows:
8.2.1. Type rules
Type rules
8.3
Operational semantics
1
The full operational semantics for the language are as follows:
8.3.1. Operational semantics
Operational semantics
8.4
GLSL identifiers
1
The complete list of reserved words in the OpenGL shading language as of version 4.3 are:
8.4.1. GLSL identifiers
  • active
  • asm
  • atomic_uint
  • attribute
  • bool
  • break
  • buffer
  • bvec2
  • bvec3
  • bvec4
  • case
  • cast
  • centroid
  • class
  • coherent
  • common
  • const
  • continue
  • default
  • discard
  • dmat2
  • dmat2x2
  • dmat2x3
  • dmat2x4
  • dmat3
  • dmat3x2
  • dmat3x3
  • dmat3x4
  • dmat4
  • dmat4x2
  • dmat4x3
  • dmat4x4
  • do
  • double
  • dvec2
  • dvec3
  • dvec4
  • else
  • enum
  • extern
  • external
  • false
  • filter
  • fixed
  • flat
  • float
  • for
  • fvec2
  • fvec3
  • fvec4
  • goto
  • half
  • highp
  • hvec2
  • hvec3
  • hvec4
  • if
  • iimage1D
  • iimage1DArray
  • iimage2D
  • iimage2DArray
  • iimage2DMS
  • iimage2DMSArray
  • iimage2DRect
  • iimage3D
  • iimageBuffer
  • iimageCube
  • iimageCubeArray
  • image1D
  • image1DArray
  • image2D
  • image2DArray
  • image2DMS
  • image2DMSArray
  • image2DRect
  • image3D
  • imageBuffer
  • imageCube
  • imageCubeArray
  • in
  • inline
  • inout
  • input
  • int
  • interface
  • invariant
  • isampler1D
  • isampler1DArray
  • isampler2D
  • isampler2DArray
  • isampler2DMS
  • isampler2DMSArray
  • isampler2DRect
  • isampler3D
  • isamplerBuffer
  • isamplerCube
  • isamplerCubeArray
  • ivec2
  • ivec3
  • ivec4
  • layout
  • long
  • lowp
  • mat2
  • mat2x2
  • mat2x3
  • mat2x4
  • mat3
  • mat3x2
  • mat3x3
  • mat3x4
  • mat4
  • mat4x2
  • mat4x3
  • mat4x4
  • mediump
  • namespace
  • noinline
  • noperspective
  • out
  • output
  • packed
  • partition
  • patch
  • precision
  • public
  • readonly
  • resource
  • restrict
  • return
  • row_major
  • sample
  • sampler1D
  • sampler1DArray
  • sampler1DArrayShadow
  • sampler1DShadow
  • sampler2D
  • sampler2DArray
  • sampler2DArrayShadow
  • sampler2DMS
  • sampler2DMSArray
  • sampler2DRect
  • sampler2DRectShadow
  • sampler2DShadow
  • sampler3D
  • sampler3DRect
  • samplerBuffer
  • samplerCube
  • samplerCubeArray
  • samplerCubeArrayShadow
  • samplerCubeShadow
  • shared
  • short
  • sizeof
  • smooth
  • static
  • struct
  • subroutine
  • superp
  • switch
  • template
  • this
  • true
  • typedef
  • uimage1D
  • uimage1DArray
  • uimage2D
  • uimage2DArray
  • uimage2DMS
  • uimage2DMSArray
  • uimage2DRect
  • uimage3D
  • uimageBuffer
  • uimageCube
  • uimageCubeArray
  • uint
  • uniform
  • union
  • unsigned
  • usampler1D
  • usampler1DArray
  • usampler2D
  • usampler2DArray
  • usampler2DMS
  • usampler2DMSArray
  • usampler2DRect
  • usampler3D
  • usamplerBuffer
  • usamplerCube
  • usamplerCubeArray
  • using
  • uvec2
  • uvec3
  • uvec4
  • varying
  • vec2
  • vec3
  • vec4
  • void
  • volatile
  • while
  • writeonly
8.5
Lists
8.5.1. List of specifications
8.5.2. List of examples
[0]
http://en.wikipedia.org/wiki/Propositional_logic
[1]
http://en.wikipedia.org/wiki/Zermelo-Fraenkel_set_theory
[2]
https://en.wikipedia.org/wiki/Type_theory
[3]
Usually accompanied with a side condition that x does not appear in dom(Γ))
[4]
Notably, parameters are the only means by which values of the sampler types can be introduced into a program.
[5]
The shader_fragment_discard_declaration is described as having type boolean, but the result of the expression is effectively consumed by the parasol language runtime and so this is not observable in practice.