submodule/skia/src/sksl/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 * 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.canUseAnyFunctionInShader. 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 * Swizzle components, in addition to the normal rgba / xyzw components, can also
  59   be LTRB (meaning "left/top/right/bottom", for when we store rectangles in
  60   vectors), and may also be the constants '0' or '1' to produce a constant 0 or
  61   1 in that channel instead of selecting anything from the source vector.
  62   foo.rgb1 is equivalent to float4(foo.rgb, 1).
  63 * All texture functions are named "sample", e.g. sample(sampler2D, float3) is
  64   equivalent to GLSL's textureProj(sampler2D, float3).
  65 * Functions support the 'inline' modifier, which causes the compiler to ignore
  66   its normal inlining heuristics and inline the function if at all possible
  67 * some built-in functions and one or two rarely-used language features are not
  68   yet supported (sorry!)