README
1 Overview 2 ======== 3 4 SkSL ("Skia Shading Language") is a variant of GLSL which is used as Skia's 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 12 13 Differences from GLSL 14 ===================== 15 16 SkSL is based on GLSL 4.5. For the most part, write SkSL exactly as you would 17 desktop GLSL, and the SkSL compiler will take care of version and dialect 18 differences (for instance, you always use "in" and "out", and skslc will handle 19 translating them to "varying" and "attribute" as appropriate). Be aware of the 20 following differences between SkSL and GLSL: 21 22 * "@if" and "@switch" are static versions of if and switch. They behave exactly 23 the same as if and switch in all respects other than it being a compile-time 24 error to use a non-constant expression as a test. 25 * GLSL caps can be referenced via the syntax 'sk_Caps.<name>', e.g. 26 sk_Caps.sampleVariablesSupport. The value will be a constant boolean or int, 27 as appropriate. As SkSL supports constant folding and branch elimination, this 28 means that an 'if' statement which statically queries a cap will collapse down 29 to the chosen branch, meaning that: 30 31 if (sk_Caps.externalTextureSupport) 32 do_something(); 33 else 34 do_something_else(); 35 36 will compile as if you had written either 'do_something();' or 37 'do_something_else();', depending on whether that cap is enabled or not. 38 * no #version statement is required, and will be ignored if present 39 * the output color is sk_FragColor (do not declare it) 40 * use sk_VertexID instead of gl_VertexID 41 * the fragment coordinate is sk_FragCoord, and is always relative to the upper 42 left. 43 * lowp, mediump, and highp are always permitted (but will only be respected if 44 you run on a device which supports them) 45 * you do not need to include ".0" to make a number a float (meaning that 46 "vec2(x, y) * 4" is perfectly legal in SkSL, unlike GLSL where it would often 47 have to be expressed "vec2(x, y) * 4.0". There is no performance penalty for 48 this, as the number is converted to a float at compile time) 49 * type suffixes on numbers (1.0f, 0xFFu) are both unnecessary and unsupported 50 * creating a smaller vector from a larger vector (e.g. vec2(vec3(1))) is 51 intentionally disallowed, as it is just a wordier way of performing a swizzle. 52 Use swizzles instead. 53 * Use texture() instead of textureProj(), e.g. texture(sampler2D, vec3) is 54 equivalent to GLSL's textureProj(sampler2D, vec3) 55 * some built-in functions and one or two rarely-used language features are not 56 yet supported (sorry!) 57 58 SkSL is still under development, and is expected to diverge further from GLSL 59 over time. 60 61 62 SkSL Fragment Processors 63 ======================== 64 65 An extension of SkSL allows for the creation of fragment processors in pure 66 SkSL. The program defines its inputs similarly to a normal SkSL program (with 67 'in' and 'uniform' variables), but the 'main()' function represents only this 68 fragment processor's portion of the overall fragment shader. 69 70 Within an '.fp' fragment processor file: 71 72 * C++ code can be embedded in sections of the form: 73 74 @section_name { <arbitrary C++ code> } 75 76 Supported section are: 77 @header (in the .h file, outside the class declaration) 78 @headerEnd (at the end of the .h file) 79 @class (in the .h file, inside the class declaration) 80 @cpp (in the .cpp file) 81 @cppEnd (at the end of the .cpp file) 82 @constructorParams (extra parameters to the constructor, comma-separated) 83 @constructor (replaces the default constructor) 84 @initializers (constructor initializer list, comma-separated) 85 @emitCode (extra code for the emitCode function) 86 @fields (extra private fields, each terminated with a semicolon) 87 @make (replaces the default Make function) 88 @setData(<pdman>) (extra code for the setData function, where <pdman> is 89 the name of the GrGLSLProgramDataManager) 90 @test(<testData>) (the body of the TestCreate function, where <testData> is 91 the name of the GrProcessorTestData* parameter) 92 @coordTransform(<sampler>) 93 (the matrix to attach to the named sampler2D's 94 GrCoordTransform) 95 @samplerParams(<sampler>) 96 (the sampler params to attach to the named sampler2D) 97 * global 'in' variables represent data passed to the fragment processor at 98 construction time. These variables become constructor parameters and are 99 stored in fragment processor fields. vec2s map to SkPoints, and vec4s map to 100 SkRects (in x, y, width, height) order. 101 * 'uniform' variables become, as one would expect, top-level uniforms. By 102 default they do not have any data provided to them; you will need to provide 103 them with data via the @setData section. 104 * 'in uniform' variables are uniforms that are automatically wired up to 105 fragment processor constructor parameters 106 * the 'sk_TransformedCoords2D' array provides access to 2D transformed 107 coordinates. sk_TransformedCoords2D[0] is equivalent to calling 108 fragBuilder->ensureCoords2D(args.fTransformedCoords[0]) (and the result is 109 cached, so you need not worry about using the value repeatedly). 110 * 'colorSpaceXform' is a supported type. It is reflected within SkSL as a mat4, 111 and on the C++ side as sk_sp<GrColorSpaceXform>. 112 * the texture() function can be passed a colorSpaceXform as an additional 113 parameter 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
