1Overview
2========
3
4SkSL ("Skia Shading Language") is a variant of GLSL which is used as Skia's
5internal shading language. SkSL is, at its heart, a single standardized version
6of GLSL which avoids all of the various version and dialect differences found
7in GLSL "in the wild", but it does bring a few of its own changes to the table.
8
9Skia uses the SkSL compiler to convert SkSL code to GLSL, GLSL ES, or SPIR-V
10before handing it over to the graphics driver.
11
12
13Differences from GLSL
14=====================
15
16* Precision modifiers are not used. 'float', 'int', and 'uint' are always high
17 precision. New types 'half', 'short', and 'ushort' are medium precision (we
18 do not use low precision).
19* Vector types are named <base type><columns>, so float2 instead of vec2 and
20 bool4 instead of bvec4
21* Matrix types are named <base type><columns>x<rows>, so float2x3 instead of
22 mat2x3 and double4x4 instead of dmat4
23* "@if" and "@switch" are static versions of if and switch. They behave exactly
24 the same as if and switch in all respects other than it being a compile-time
25 error to use a non-constant expression as a test.
26* GLSL caps can be referenced via the syntax 'sk_Caps.<name>', e.g.
27 sk_Caps.sampleVariablesSupport. The value will be a constant boolean or int,
28 as appropriate. As SkSL supports constant folding and branch elimination, this
29 means that an 'if' statement which statically queries a cap will collapse down
30 to the chosen branch, meaning that:
31
32 if (sk_Caps.externalTextureSupport)
33 do_something();
34 else
35 do_something_else();
36
37 will compile as if you had written either 'do_something();' or
38 'do_something_else();', depending on whether that cap is enabled or not.
39* no #version statement is required, and it will be ignored if present
40* the output color is sk_FragColor (do not declare it)
41* use sk_Position instead of gl_Position. sk_Position is in device coordinates
42 rather than normalized coordinates.
43* use sk_PointSize instead of gl_PointSize
44* use sk_VertexID instead of gl_VertexID
45* use sk_InstanceID instead of gl_InstanceID
46* the fragment coordinate is sk_FragCoord, and is always relative to the upper
47 left.
48* you do not need to include ".0" to make a number a float (meaning that
49 "float2x, y) * 4" is perfectly legal in SkSL, unlike GLSL where it would often
50 have to be expressed "float2x, y) * 4.0". There is no performance penalty for
51 this, as the number is converted to a float at compile time)
52* type suffixes on numbers (1.0f, 0xFFu) are both unnecessary and unsupported
53* creating a smaller vector from a larger vector (e.g. float2float31))) is
54 intentionally disallowed, as it is just a wordier way of performing a swizzle.
55 Use swizzles instead.
56* Use texture() instead of textureProj(), e.g. texture(sampler2D, float3 is
57 equivalent to GLSL's textureProj(sampler2D, float3
58* some built-in functions and one or two rarely-used language features are not
59 yet supported (sorry!)
60
61SkSL is still under development, and is expected to diverge further from GLSL
62over time.
63
64
65SkSL Fragment Processors
66========================
67
68An extension of SkSL allows for the creation of fragment processors in pure
69SkSL. The program defines its inputs similarly to a normal SkSL program (with
70'in' and 'uniform' variables), but the 'main()' function represents only this
71fragment processor's portion of the overall fragment shader.
72
73Within an '.fp' fragment processor file:
74
75* C++ code can be embedded in sections of the form:
76
77 @section_name { <arbitrary C++ code> }
78
79 Supported section are:
80 @header (in the .h file, outside the class declaration)
81 @headerEnd (at the end of the .h file)
82 @class (in the .h file, inside the class declaration)
83 @cpp (in the .cpp file)
84 @cppEnd (at the end of the .cpp file)
85 @constructorParams (extra parameters to the constructor, comma-separated)
86 @constructor (replaces the default constructor)
87 @initializers (constructor initializer list, comma-separated)
88 @emitCode (extra code for the emitCode function)
89 @fields (extra private fields, each terminated with a semicolon)
90 @make (replaces the default Make function)
91 @clone (replaces the default clone() function)
92 @setData(<pdman>) (extra code for the setData function, where <pdman> is
93 the name of the GrGLSLProgramDataManager)
94 @test(<testData>) (the body of the TestCreate function, where <testData> is
95 the name of the GrProcessorTestData* parameter)
96 @coordTransform(<sampler>)
97 (the matrix to attach to the named sampler2D's
98 GrCoordTransform)
99 @samplerParams(<sampler>)
100 (the sampler params to attach to the named sampler2D)
101* global 'in' variables represent data passed to the fragment processor at
102 construction time. These variables become constructor parameters and are
103 stored in fragment processor fields. float2 map to SkPoints, and float4 map to
104 SkRects (in x, y, width, height) order.
105* 'uniform' variables become, as one would expect, top-level uniforms. By
106 default they do not have any data provided to them; you will need to provide
107 them with data via the @setData section.
108* 'in uniform' variables are uniforms that are automatically wired up to
109 fragment processor constructor parameters
110* the 'sk_TransformedCoords2D' array provides access to 2D transformed
111 coordinates. sk_TransformedCoords2D[0] is equivalent to calling
112 fragBuilder->ensureCoords2D(args.fTransformedCoords[0]) (and the result is
113 cached, so you need not worry about using the value repeatedly).
114* Uniform variables support an additional 'when' layout key.
115 'layout(when=foo) uniform int x;' means that this uniform will only be
116 emitted when the 'foo' expression is true.
117* 'in' variables support an additional 'key' layout key.
118 'layout(key) uniform int x;' means that this uniform should be included in
119 the program's key. Matrix variables additionally support 'key=identity',
120 which causes the key to consider only whether or not the matrix is an
121 identity matrix.
122* 'float4' / 'half4' variables support an additional 'ctype' layout key,
123 providing the type they should be represented as from within the C++ code.
124 Currently the only two supported ctypes are 'SkRect' and 'SkPMColor'.
125