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