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* use sk_Clockwise instead of gl_FrontFacing. This is always relative to an 49 upper left origin. 50* you do not need to include ".0" to make a number a float (meaning that 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) 54* type suffixes on numbers (1.0f, 0xFFu) are both unnecessary and unsupported 55* creating a smaller vector from a larger vector (e.g. float2(float3(1))) is 56 intentionally disallowed, as it is just a wordier way of performing a swizzle. 57 Use swizzles instead. 58* The last swizzle component, in addition to the normal rgba / xyzw components, 59 can also be the constants '0' or '1'. foo.rgb1 is equivalent to 60 float4(foo.rgb, 1). 61* All texture functions are named "sample", e.g. sample(sampler2D, float3) is 62 equivalent to GLSL's textureProj(sampler2D, float3). 63* Render target width and height are available via sk_Width and sk_Height 64* some built-in functions and one or two rarely-used language features are not 65 yet supported (sorry!) 66 67SkSL is still under development, and is expected to diverge further from GLSL 68over time. 69 70 71SkSL Fragment Processors 72======================== 73 74******************************************************************************** 75*** IMPORTANT: You must set gn arg "skia_compile_processors = true" to cause *** 76*** .fp files to be recompiled! In order for compilation to succeed, you *** 77*** must run bin/fetch-clang-format (once) to install our blessed version. *** 78******************************************************************************** 79 80An extension of SkSL allows for the creation of fragment processors in pure 81SkSL. The program defines its inputs similarly to a normal SkSL program (with 82'in' and 'uniform' variables), but the 'main()' function represents only this 83fragment processor's portion of the overall fragment shader. 84 85Within an '.fp' fragment processor file: 86 87* C++ code can be embedded in sections of the form: 88 89 @section_name { <arbitrary C++ code> } 90 91 Supported section are: 92 @header (in the .h file, outside the class declaration) 93 @headerEnd (at the end of the .h file) 94 @class (in the .h file, inside the class declaration) 95 @cpp (in the .cpp file) 96 @cppEnd (at the end of the .cpp file) 97 @constructorParams (extra parameters to the constructor, comma-separated) 98 @constructor (replaces the default constructor) 99 @initializers (constructor initializer list, comma-separated) 100 @emitCode (extra code for the emitCode function) 101 @fields (extra private fields, each terminated with a semicolon) 102 @make (replaces the default Make function) 103 @clone (replaces the default clone() function) 104 @setData(<pdman>) (extra code for the setData function, where <pdman> is 105 the name of the GrGLSLProgramDataManager) 106 @test(<testData>) (the body of the TestCreate function, where <testData> is 107 the name of the GrProcessorTestData* parameter) 108 @coordTransform(<sampler>) 109 (the matrix to attach to the named sampler2D's 110 GrCoordTransform) 111 @samplerParams(<sampler>) 112 (the sampler params to attach to the named sampler2D) 113* global 'in' variables represent data passed to the fragment processor at 114 construction time. These variables become constructor parameters and are 115 stored in fragment processor fields. By default float2/half2 maps to SkPoints, 116 and float4/half4 maps to SkRects (in x, y, width, height) order. Similarly, 117 int2/short2 maps to SkIPoint and int4/half4 maps to SkIRect. Use ctype 118 (below) to override this default mapping. 119* global variables support an additional 'ctype' layout key, providing the type 120 they should be represented as from within the C++ code. For instance, you can 121 use 'layout(ctype=SkPMColor4f) in half4 color;' to create a variable that looks 122 like a half4 on the SkSL side of things, and a SkPMColor4f on the C++ side of 123 things. 124* 'uniform' variables become, as one would expect, top-level uniforms. By 125 default they do not have any data provided to them; you will need to provide 126 them with data via the @setData section. 127* 'in uniform' variables are uniforms that are automatically wired up to 128 fragment processor constructor parameters. The fragment processor will accept 129 a parameter representing the uniform's value, and automatically plumb it 130 through to the uniform's value in its generated setData() function. 131* 'in uniform' variables support a 'tracked' flag in the layout that will 132 have the generated code automatically implement state tracking on the uniform 133 value to minimize GPU calls. 134* the 'sk_TransformedCoords2D' array provides access to 2D transformed 135 coordinates. sk_TransformedCoords2D[0] is equivalent to calling 136 fragBuilder->ensureCoords2D(args.fTransformedCoords[0]) (and the result is 137 cached, so you need not worry about using the value repeatedly). 138* Uniform variables support an additional 'when' layout key. 139 'layout(when=foo) uniform int x;' means that this uniform will only be 140 emitted when the 'foo' expression is true. 141* 'in' variables support an additional 'key' layout key. 142 'layout(key) uniform int x;' means that this uniform should be included in 143 the program's key. Matrix variables additionally support 'key=identity', 144 which causes the key to consider only whether or not the matrix is an 145 identity matrix. 146* child processors can be declared with 'in fragmentProcessor <name>;', and can 147 be invoked by calling 'sample(<name>)' or 'sample(<name>, <inputColor>)'. 148 The first variant emits the child with a solid white input color. The second 149 variant emits the child with the result of the 2nd argument's expression, 150 which must evaluate to a half4. The process function returns a half4. 151* By default, fragment processors must be non-null. The type for a nullable 152 fragment processor is 'fragmentProcessor?', as in 153 'in fragmentProcessor? <name>'. You can check for the presence of such a 154 fragment processor by comparing it to 'null'. 155 156 157Creating a new .fp file 158======================= 159 1601. Ensure that you have set gn arg "skia_compile_processors = true" 1612. Create your new .fp file, generally under src/gpu/effects. 1623. Add the .fp file to sksl.gni. 1634. Build Skia. This will cause the .fp file to be compiled, resulting in a new 164 .cpp and .h file for the fragment processor. 1655. Add the .cpp and .h files to gpu.gni. 1666. Add the new processor's ClassID (k<ProcessorName>_ClassID) to 167 GrProcessor::ClassID. 1687. At this point you can reference the new fragment processor from within Skia. 169 170Once you have done this initial setup, simply re-build Skia to pick up any 171changes to the .fp file. 172