skia2/src/sksl
Brian Osman 4717fbbc38 Remove GL image support from SkSL
This was added to Ganesh briefly in 2016 for an experiment, then
reverted, and never used.

Change-Id: I65849aff53acc14f9adc7585398fd09363a4ed65
Reviewed-on: https://skia-review.googlesource.com/c/skia/+/374376
Reviewed-by: Brian Salomon <bsalomon@google.com>
Commit-Queue: Brian Osman <brianosman@google.com>
2021-02-24 00:51:53 +00:00
..
dsl SkSL DSL function objects are now callable 2021-02-23 20:06:18 +00:00
generated Remove GL image support from SkSL 2021-02-24 00:51:53 +00:00
ir Remove GL image support from SkSL 2021-02-24 00:51:53 +00:00
lex Remove "buffer" modifier from SkSL 2021-02-18 21:48:05 +00:00
GLSL.std.450.h
README Make all fragmentProcessors implicitly nullable in SkSL 2020-12-23 20:22:18 +00:00
sksl_fp_raw.sksl Code cleanup: update obsolete comment, remove macro. 2021-01-27 17:13:50 +00:00
sksl_frag.sksl Code cleanup: update obsolete comment, remove macro. 2021-01-27 17:13:50 +00:00
sksl_geom.sksl Declare sk_InvocationID programmatically 2020-10-13 16:41:41 +00:00
sksl_gpu.sksl Remove GL image support from SkSL 2021-02-24 00:51:53 +00:00
sksl_public.sksl Implement all public intrinsics directly in VM generator 2021-01-27 12:55:29 +00:00
sksl_runtime.sksl SkSL: In the front-end, rename PipelineStage to RuntimeEffect 2020-12-21 21:23:17 +00:00
sksl_vert.sksl Remove sk_ClipDistance. 2020-09-25 20:29:10 +00:00
SkSLAnalysis.cpp Optimize @switch statements in SwitchStatement::Make. 2021-02-23 21:36:04 +00:00
SkSLAnalysis.h Optimize @switch statements in SwitchStatement::Make. 2021-02-23 21:36:04 +00:00
SkSLASTFile.h Enable ClangTidy check llvm-namespace-comment. 2020-08-06 19:07:52 +00:00
SkSLASTNode.cpp Convert Operators namespace to first-class Operator object. 2021-02-16 16:54:20 +00:00
SkSLASTNode.h Convert Operators namespace to first-class Operator object. 2021-02-16 16:54:20 +00:00
SkSLBuiltinTypes.cpp Remove GL image support from SkSL 2021-02-24 00:51:53 +00:00
SkSLBuiltinTypes.h Remove GL image support from SkSL 2021-02-24 00:51:53 +00:00
SkSLCFGGenerator.cpp Added SkSL DSL SampleChild function 2021-02-16 19:13:04 +00:00
SkSLCFGGenerator.h Migrate DefinitionMap logic to its own class. 2021-02-09 02:27:26 +00:00
SkSLCodeGenerator.h Use a scoped helper class to push and pop CodeGenerator::fOut changes. 2020-12-07 18:21:55 +00:00
SkSLCompiler.cpp Remove GL image support from SkSL 2021-02-24 00:51:53 +00:00
SkSLCompiler.h Move ProgramKind and ProgramSettings types out of SkSL::Program. 2021-02-16 19:30:48 +00:00
SkSLConstantFolder.cpp Move Constructor generation and type-coercion out of IRGenerator. 2021-02-19 18:53:52 +00:00
SkSLConstantFolder.h Convert Operators namespace to first-class Operator object. 2021-02-16 16:54:20 +00:00
SkSLContext.cpp Migrate BuiltinTypes to a separate file from Context. 2021-01-15 17:23:16 +00:00
SkSLContext.h Make program configuration accessible from the SkSL context. 2021-02-17 18:49:34 +00:00
SkSLCPP.h
SkSLCPPCodeGenerator.cpp Make GrGLSLFragmentProcessors be created as std::unique_ptr. 2021-02-23 19:31:01 +00:00
SkSLCPPCodeGenerator.h Convert Operators namespace to first-class Operator object. 2021-02-16 16:54:20 +00:00
SkSLCPPUniformCTypes.cpp Add Type::isArray and Type::isStruct helper methods. 2020-12-03 22:58:52 +00:00
SkSLCPPUniformCTypes.h moved SkSL Variable data into IRNode 2020-10-07 21:29:12 +00:00
SkSLDefines.h Migrate SwizzleComponent to be shared between SkSL::Swizzle and the DSL. 2021-02-18 22:33:25 +00:00
SkSLDefinitionMap.cpp Convert Operators namespace to first-class Operator object. 2021-02-16 16:54:20 +00:00
SkSLDefinitionMap.h Only track compile-time expressions in definition maps. 2021-02-09 14:23:31 +00:00
SkSLDehydrator.cpp Remove GL image support from SkSL 2021-02-24 00:51:53 +00:00
SkSLDehydrator.h Add line breaks to make dehydrated files more merge-friendly. 2020-10-08 18:55:02 +00:00
SkSLErrorReporter.h Remove SkSL ABORT() macro. 2021-02-03 00:34:28 +00:00
SkSLExternalFunction.h SkSL: Remove ByteCode interpreter, generator, etc. 2021-01-22 14:38:41 +00:00
SkSLFileOutputStream.h Update skslc to compile multiple files during one invocation. 2020-11-12 15:05:27 +00:00
SkSLGLSLCodeGenerator.cpp Remove GL image support from SkSL 2021-02-24 00:51:53 +00:00
SkSLGLSLCodeGenerator.h Make program configuration accessible from the SkSL context. 2021-02-17 18:49:34 +00:00
SkSLHCodeGenerator.cpp Make GrGLSLFragmentProcessors be created as std::unique_ptr. 2021-02-23 19:31:01 +00:00
SkSLHCodeGenerator.h Replace SkSL-specific macros with Skia equivalents. 2021-02-02 22:46:53 +00:00
SkSLInliner.cpp Migrate convertSwitch to SwitchStatement::Make. 2021-02-23 19:16:40 +00:00
SkSLInliner.h Remove ProgramSettings from IRGenerator and the Inliner. 2021-02-17 22:17:22 +00:00
SkSLIRGenerator.cpp Require initializers on const variable declarations 2021-02-23 20:55:01 +00:00
SkSLIRGenerator.h Migrate convertSwitch to SwitchStatement::Make. 2021-02-23 19:16:40 +00:00
SkSLLexer.cpp Remove "buffer" modifier from SkSL 2021-02-18 21:48:05 +00:00
SkSLLexer.h Remove "buffer" modifier from SkSL 2021-02-18 21:48:05 +00:00
SkSLMain.cpp Demonstrate a bug with inlined static switches. 2021-02-22 15:05:58 +00:00
SkSLMangler.cpp Create SkSLOperators, centralize functionality 2021-02-06 16:24:12 +00:00
SkSLMangler.h Break SkSLInliner mangling out into a separate class 2021-01-11 19:55:04 +00:00
SkSLMemoryLayout.h Remove SkSL ABORT() macro. 2021-02-03 00:34:28 +00:00
SkSLMemoryPool.h Free unused scratch space from idle Pools. 2020-10-29 15:20:43 +00:00
SkSLMetalCodeGenerator.cpp Make program configuration accessible from the SkSL context. 2021-02-17 18:49:34 +00:00
SkSLMetalCodeGenerator.h Make program configuration accessible from the SkSL context. 2021-02-17 18:49:34 +00:00
SkSLModifiersPool.h Add SkSL DSLVar 2021-01-12 14:36:26 +00:00
SkSLOperators.cpp Convert Operators namespace to first-class Operator object. 2021-02-16 16:54:20 +00:00
SkSLOperators.h Convert Operators namespace to first-class Operator object. 2021-02-16 16:54:20 +00:00
SkSLOutputStream.cpp Add line breaks to make dehydrated files more merge-friendly. 2020-10-08 18:55:02 +00:00
SkSLOutputStream.h Replace SkSL-specific macros with Skia equivalents. 2021-02-02 22:46:53 +00:00
SkSLParser.cpp Remove GL image support from SkSL 2021-02-24 00:51:53 +00:00
SkSLParser.h Remove specific blend mode layout qualifiers 2021-02-23 15:45:55 +00:00
SkSLPipelineStageCodeGenerator.cpp Support global variables in pipeline stage generator 2021-02-18 00:54:49 +00:00
SkSLPipelineStageCodeGenerator.h Support global variables in pipeline stage generator 2021-02-18 00:54:49 +00:00
SkSLPool.cpp Created SKSL_USE_THREAD_LOCAL define 2020-12-01 19:13:43 +00:00
SkSLPool.h Move pooling implementation details out of IRNode class. 2021-02-02 16:06:05 +00:00
SkSLPosition.h Enable ClangTidy check llvm-namespace-comment. 2020-08-06 19:07:52 +00:00
SkSLProgramSettings.h Demonstrate a bug with inlined static switches. 2021-02-22 15:05:58 +00:00
SkSLRehydrator.cpp Remove GL image support from SkSL 2021-02-24 00:51:53 +00:00
SkSLRehydrator.h Remove nullable type support from SkSL 2020-12-26 03:15:47 +00:00
SkSLSampleUsage.cpp SkSL IR normalization: Convert while loops to for loops 2020-12-16 23:03:23 +00:00
SkSLSectionAndParameterHelper.cpp SkSL IR normalization: Convert while loops to for loops 2020-12-16 23:03:23 +00:00
SkSLSectionAndParameterHelper.h moved SkSL Variable data into IRNode 2020-10-07 21:29:12 +00:00
SkSLSPIRVCodeGenerator.cpp Remove GL image support from SkSL 2021-02-24 00:51:53 +00:00
SkSLSPIRVCodeGenerator.h Move ProgramKind and ProgramSettings types out of SkSL::Program. 2021-02-16 19:30:48 +00:00
SkSLSPIRVtoHLSL.cpp Add GrD3DPipelineStateBuilder class. 2020-04-23 15:01:58 +00:00
SkSLSPIRVtoHLSL.h Enable ClangTidy check llvm-namespace-comment. 2020-08-06 19:07:52 +00:00
SkSLString.cpp Enable printf warnings on SkSL::String. 2021-02-18 14:16:35 +00:00
SkSLString.h Enable printf warnings on SkSL::String. 2021-02-18 14:16:35 +00:00
SkSLStringStream.h Add line breaks to make dehydrated files more merge-friendly. 2020-10-08 18:55:02 +00:00
SkSLUtil.cpp Remove SkSL ABORT() macro. 2021-02-03 00:34:28 +00:00
SkSLUtil.h Remove specific blend mode layout qualifiers 2021-02-23 15:45:55 +00:00
SkSLVMGenerator.cpp Support initializers on global variables in SkSL to SkVM 2021-02-17 20:40:32 +00:00
SkSLVMGenerator.h Update particle system to use skvm, rather than ByteCode 2021-01-21 23:07:29 +00:00
spirv.h

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.canUseAnyFunctionInShader. 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.
* use sk_Clockwise instead of gl_FrontFacing. This is always relative to an
  upper left origin.
* 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.
* Swizzle components, in addition to the normal rgba / xyzw components, can also
  be LTRB (meaning "left/top/right/bottom", for when we store rectangles in
  vectors), and may also be the constants '0' or '1' to produce a constant 0 or
  1 in that channel instead of selecting anything from the source vector.
  foo.rgb1 is equivalent to float4(foo.rgb, 1).
* All texture functions are named "sample", e.g. sample(sampler2D, float3) is
  equivalent to GLSL's textureProj(sampler2D, float3).
* Render target width and height are available via sk_Width and sk_Height
* Functions support the 'inline' modifier, which causes the compiler to ignore
  its normal inlining heuristics and inline the function if at all possible
* 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. The 'main' function
can optionally have a 'float2' parameter that holds the sample coordinates the
processor is evaluated at.

Processors do not need to declare this parameter if they do not rely on local
coordinates or only invoke child processors using the no-arg and matrix-based
sample() functions.

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)
    @dumpInfo          (replaces the default dumpInfo() 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)
    @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. Similarly,
  int2/short2 maps to SkIPoint and int4/half4 maps to SkIRect. 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=SkPMColor4f) in half4 color;' to create a variable that looks
  like a half4 on the SkSL side of things, and a SkPMColor4f 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.
* 'in uniform' variables support a 'tracked' flag in the layout that will
  have the generated code automatically implement state tracking on the uniform
  value to minimize GPU calls.
* 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) in 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.
* child processors can be declared with 'in fragmentProcessor <name>;', and can
  be invoked by calling 'sample(<name>)' or 'sample(<name>, <inputColor>)'.
  The first variant emits the child with a solid white input color. The second
  variant emits the child with the result of the 2nd argument's expression,
  which must evaluate to a half4. The process function returns a half4.
  Invoking 'sample()' on a null fragment processor will return the inputColor
  unchanged (this defaults to solid white if not explicitly specified).


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.