ethannicholas | 5961bc9 | 2016-10-12 06:39:56 -0700 | [diff] [blame] | 1 | Overview |
| 2 | ======== |
| 3 | |
Ethan Nicholas | 0df1b04 | 2017-03-31 13:56:23 -0400 | [diff] [blame] | 4 | SkSL ("Skia Shading Language") is a variant of GLSL which is used as Skia's |
ethannicholas | 5961bc9 | 2016-10-12 06:39:56 -0700 | [diff] [blame] | 5 | internal shading language. SkSL is, at its heart, a single standardized version |
| 6 | of GLSL which avoids all of the various version and dialect differences found |
| 7 | in GLSL "in the wild", but it does bring a few of its own changes to the table. |
| 8 | |
| 9 | Skia uses the SkSL compiler to convert SkSL code to GLSL, GLSL ES, or SPIR-V |
| 10 | before handing it over to the graphics driver. |
| 11 | |
Ethan Nicholas | 762466e | 2017-06-29 10:03:38 -0400 | [diff] [blame] | 12 | |
ethannicholas | 5961bc9 | 2016-10-12 06:39:56 -0700 | [diff] [blame] | 13 | Differences from GLSL |
| 14 | ===================== |
| 15 | |
Ethan Nicholas | 8aa4569 | 2017-09-20 11:24:15 -0400 | [diff] [blame] | 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). |
Ethan Nicholas | 5af9ea3 | 2017-07-28 15:19:46 -0400 | [diff] [blame] | 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 |
Ethan Nicholas | 5ac13c2 | 2017-05-10 15:06:17 -0400 | [diff] [blame] | 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. |
Ethan Nicholas | 3605ace | 2016-11-21 15:59:48 -0500 | [diff] [blame] | 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. |
Ethan Nicholas | 5af9ea3 | 2017-07-28 15:19:46 -0400 | [diff] [blame] | 39 | * no #version statement is required, and it will be ignored if present |
ethannicholas | 5961bc9 | 2016-10-12 06:39:56 -0700 | [diff] [blame] | 40 | * the output color is sk_FragColor (do not declare it) |
Robert Phillips | fe8da17 | 2018-01-24 14:52:02 +0000 | [diff] [blame] | 41 | * use sk_Position instead of gl_Position. sk_Position is in device coordinates |
| 42 | rather than normalized coordinates. |
Ethan Nicholas | bed683a | 2017-09-26 14:23:59 -0400 | [diff] [blame] | 43 | * use sk_PointSize instead of gl_PointSize |
Ethan Nicholas | a51740c | 2017-02-07 14:53:32 -0500 | [diff] [blame] | 44 | * use sk_VertexID instead of gl_VertexID |
Chris Dalton | 8580d51 | 2017-10-14 22:12:33 -0600 | [diff] [blame] | 45 | * use sk_InstanceID instead of gl_InstanceID |
Ethan Nicholas | 3865711 | 2017-02-09 17:01:22 -0500 | [diff] [blame] | 46 | * the fragment coordinate is sk_FragCoord, and is always relative to the upper |
| 47 | left. |
Chris Dalton | 49d14e9 | 2018-07-27 12:38:35 -0600 | [diff] [blame] | 48 | * use sk_Clockwise instead of gl_FrontFacing. This is always relative to an |
| 49 | upper left origin. |
ethannicholas | 5961bc9 | 2016-10-12 06:39:56 -0700 | [diff] [blame] | 50 | * you do not need to include ".0" to make a number a float (meaning that |
Ethan Nicholas | 40d4420 | 2018-02-01 10:02:37 -0500 | [diff] [blame] | 51 | "float2(x, y) * 4" is perfectly legal in SkSL, unlike GLSL where it would |
| 52 | often have to be expressed "float2(x, y) * 4.0". There is no performance |
| 53 | penalty for this, as the number is converted to a float at compile time) |
ethannicholas | 5961bc9 | 2016-10-12 06:39:56 -0700 | [diff] [blame] | 54 | * type suffixes on numbers (1.0f, 0xFFu) are both unnecessary and unsupported |
Ethan Nicholas | 40d4420 | 2018-02-01 10:02:37 -0500 | [diff] [blame] | 55 | * creating a smaller vector from a larger vector (e.g. float2(float3(1))) is |
Ethan Nicholas | 84645e3 | 2017-02-09 13:57:14 -0500 | [diff] [blame] | 56 | intentionally disallowed, as it is just a wordier way of performing a swizzle. |
| 57 | Use swizzles instead. |
Ethan Nicholas | 40d4420 | 2018-02-01 10:02:37 -0500 | [diff] [blame] | 58 | * Use texture() instead of textureProj(), e.g. texture(sampler2D, float3) is |
| 59 | equivalent to GLSL's textureProj(sampler2D, float3) |
Ethan Nicholas | cd700e9 | 2018-08-24 16:43:57 -0400 | [diff] [blame] | 60 | * Render target width and height are available via sk_Width and sk_Height |
ethannicholas | 5961bc9 | 2016-10-12 06:39:56 -0700 | [diff] [blame] | 61 | * some built-in functions and one or two rarely-used language features are not |
| 62 | yet supported (sorry!) |
| 63 | |
| 64 | SkSL is still under development, and is expected to diverge further from GLSL |
| 65 | over time. |
Ethan Nicholas | 762466e | 2017-06-29 10:03:38 -0400 | [diff] [blame] | 66 | |
| 67 | |
| 68 | SkSL Fragment Processors |
| 69 | ======================== |
| 70 | |
Ethan Nicholas | 40d4420 | 2018-02-01 10:02:37 -0500 | [diff] [blame] | 71 | ******************************************************************************** |
| 72 | *** IMPORTANT: You must set gn arg "skia_compile_processors = true" to cause *** |
| 73 | *** .fp files to be recompiled! In order for compilation to succeed, you *** |
| 74 | *** must run bin/fetch-clang-format (once) to install our blessed version. *** |
| 75 | ******************************************************************************** |
| 76 | |
Ethan Nicholas | 762466e | 2017-06-29 10:03:38 -0400 | [diff] [blame] | 77 | An extension of SkSL allows for the creation of fragment processors in pure |
| 78 | SkSL. The program defines its inputs similarly to a normal SkSL program (with |
| 79 | 'in' and 'uniform' variables), but the 'main()' function represents only this |
| 80 | fragment processor's portion of the overall fragment shader. |
| 81 | |
| 82 | Within an '.fp' fragment processor file: |
| 83 | |
| 84 | * C++ code can be embedded in sections of the form: |
| 85 | |
| 86 | @section_name { <arbitrary C++ code> } |
| 87 | |
| 88 | Supported section are: |
| 89 | @header (in the .h file, outside the class declaration) |
Ethan Nicholas | 9fb036f | 2017-07-05 16:19:09 -0400 | [diff] [blame] | 90 | @headerEnd (at the end of the .h file) |
Ethan Nicholas | 762466e | 2017-06-29 10:03:38 -0400 | [diff] [blame] | 91 | @class (in the .h file, inside the class declaration) |
| 92 | @cpp (in the .cpp file) |
Ethan Nicholas | 9fb036f | 2017-07-05 16:19:09 -0400 | [diff] [blame] | 93 | @cppEnd (at the end of the .cpp file) |
Ethan Nicholas | 762466e | 2017-06-29 10:03:38 -0400 | [diff] [blame] | 94 | @constructorParams (extra parameters to the constructor, comma-separated) |
| 95 | @constructor (replaces the default constructor) |
| 96 | @initializers (constructor initializer list, comma-separated) |
| 97 | @emitCode (extra code for the emitCode function) |
| 98 | @fields (extra private fields, each terminated with a semicolon) |
| 99 | @make (replaces the default Make function) |
Ethan Nicholas | f57c0d6 | 2017-07-31 11:18:22 -0400 | [diff] [blame] | 100 | @clone (replaces the default clone() function) |
Ethan Nicholas | 762466e | 2017-06-29 10:03:38 -0400 | [diff] [blame] | 101 | @setData(<pdman>) (extra code for the setData function, where <pdman> is |
| 102 | the name of the GrGLSLProgramDataManager) |
| 103 | @test(<testData>) (the body of the TestCreate function, where <testData> is |
| 104 | the name of the GrProcessorTestData* parameter) |
Ethan Nicholas | 68990be | 2017-07-13 09:36:52 -0400 | [diff] [blame] | 105 | @coordTransform(<sampler>) |
| 106 | (the matrix to attach to the named sampler2D's |
| 107 | GrCoordTransform) |
| 108 | @samplerParams(<sampler>) |
| 109 | (the sampler params to attach to the named sampler2D) |
Ethan Nicholas | 762466e | 2017-06-29 10:03:38 -0400 | [diff] [blame] | 110 | * global 'in' variables represent data passed to the fragment processor at |
| 111 | construction time. These variables become constructor parameters and are |
Ethan Nicholas | 40d4420 | 2018-02-01 10:02:37 -0500 | [diff] [blame] | 112 | stored in fragment processor fields. By default float2/half2 maps to SkPoints, |
Michael Ludwig | a427559 | 2018-08-31 10:52:47 -0400 | [diff] [blame] | 113 | and float4/half4 maps to SkRects (in x, y, width, height) order. Similarly, |
| 114 | int2/short2 maps to SkIPoint and int4/half4 maps to SkIRect. Use ctype |
Ethan Nicholas | 40d4420 | 2018-02-01 10:02:37 -0500 | [diff] [blame] | 115 | (below) to override this default mapping. |
| 116 | * global variables support an additional 'ctype' layout key, providing the type |
| 117 | they should be represented as from within the C++ code. For instance, you can |
Brian Osman | 495993a | 2018-10-16 15:45:55 -0400 | [diff] [blame] | 118 | use 'layout(ctype=SkPMColor4f) in half4 color;' to create a variable that looks |
| 119 | like a half4 on the SkSL side of things, and a SkPMColor4f on the C++ side of |
Ethan Nicholas | 40d4420 | 2018-02-01 10:02:37 -0500 | [diff] [blame] | 120 | things. |
Ethan Nicholas | 762466e | 2017-06-29 10:03:38 -0400 | [diff] [blame] | 121 | * 'uniform' variables become, as one would expect, top-level uniforms. By |
| 122 | default they do not have any data provided to them; you will need to provide |
| 123 | them with data via the @setData section. |
| 124 | * 'in uniform' variables are uniforms that are automatically wired up to |
Ethan Nicholas | 40d4420 | 2018-02-01 10:02:37 -0500 | [diff] [blame] | 125 | fragment processor constructor parameters. The fragment processor will accept |
| 126 | a parameter representing the uniform's value, and automatically plumb it |
| 127 | through to the uniform's value in its generated setData() function. |
Michael Ludwig | a427559 | 2018-08-31 10:52:47 -0400 | [diff] [blame] | 128 | * 'in uniform' variables support a 'tracked' flag in the layout that will |
| 129 | have the generated code automatically implement state tracking on the uniform |
| 130 | value to minimize GPU calls. |
Ethan Nicholas | 762466e | 2017-06-29 10:03:38 -0400 | [diff] [blame] | 131 | * the 'sk_TransformedCoords2D' array provides access to 2D transformed |
| 132 | coordinates. sk_TransformedCoords2D[0] is equivalent to calling |
| 133 | fragBuilder->ensureCoords2D(args.fTransformedCoords[0]) (and the result is |
| 134 | cached, so you need not worry about using the value repeatedly). |
Ethan Nicholas | 762466e | 2017-06-29 10:03:38 -0400 | [diff] [blame] | 135 | * Uniform variables support an additional 'when' layout key. |
| 136 | 'layout(when=foo) uniform int x;' means that this uniform will only be |
| 137 | emitted when the 'foo' expression is true. |
| 138 | * 'in' variables support an additional 'key' layout key. |
| 139 | 'layout(key) uniform int x;' means that this uniform should be included in |
| 140 | the program's key. Matrix variables additionally support 'key=identity', |
| 141 | which causes the key to consider only whether or not the matrix is an |
| 142 | identity matrix. |
Michael Ludwig | 92e4c7f | 2018-08-30 16:08:18 -0400 | [diff] [blame] | 143 | * child processors can be declared with 'in fragmentProcessor <name>;', and can |
| 144 | be invoked by calling 'process(<name>)' or 'process(<name>, <inputColor>)'. |
| 145 | The first variant emits the child with a solid white input color. The second |
| 146 | variant emits the child with the result of the 2nd argument's expression, |
| 147 | which must evaluate to a half4. The process function returns a half4. |
Ethan Nicholas | 40d4420 | 2018-02-01 10:02:37 -0500 | [diff] [blame] | 148 | |
| 149 | |
| 150 | Creating a new .fp file |
| 151 | ======================= |
| 152 | |
| 153 | 1. Ensure that you have set gn arg "skia_compile_processors = true" |
| 154 | 2. Create your new .fp file, generally under src/gpu/effects. |
| 155 | 3. Add the .fp file to sksl.gni. |
| 156 | 4. Build Skia. This will cause the .fp file to be compiled, resulting in a new |
| 157 | .cpp and .h file for the fragment processor. |
| 158 | 5. Add the .cpp and .h files to gpu.gni. |
| 159 | 6. Add the new processor's ClassID (k<ProcessorName>_ClassID) to |
| 160 | GrProcessor::ClassID. |
| 161 | 7. At this point you can reference the new fragment processor from within Skia. |
| 162 | |
| 163 | Once you have done this initial setup, simply re-build Skia to pick up any |
Chris Dalton | 49d14e9 | 2018-07-27 12:38:35 -0600 | [diff] [blame] | 164 | changes to the .fp file. |