docs: Added basic shader tutorial (#3799)

Added Basic Shader Tutirial to Flame documentation.
Added one note to CONTRIBUTING.md, which explains how to resolve non
UTF-8 characters in path.

---------

Co-authored-by: Lukas Klingsbo <lukas.klingsbo@gmail.com>
Co-authored-by: Lukas Klingsbo <me@lukas.fyi>

Author: kornellapu

.github/.cspell/gamedev_dictionary.txt

@@ -27,6 +27,7 @@ jank # stutter or inconsistent gap or timing
 lerp # short for linear interpolation
 LTRBR # left top right bottom radius
 LTWH # left top width height
+mediump # medium GLSL float precision
 metalness # a measure of how much a surface reflects light for the purposes of physically based rendering
 Minkowski # Minkowski sum, a sum of two sets of vectors, A and B, where the result is the sum of each vector pair
 multitap # support from a device to recognize many taps at the same time
@@ -49,6 +50,7 @@ subfolders # plural of subfolders
 sublists # plural of sublist
 subrange # a range entirely contained on a given range
 SVGs # plural of SVG
+texel # texture pixel (unit of texture map)
 texels # plural of texel
 tileset # image with a collection of tiles. in games, tiles are small square sprites laid out in a grid to form the game map
 tilesets # plural of tileset

.github/.cspell/people_usernames.txt

@@ -7,8 +7,12 @@ erickzanardo # github.com/erickzanardo
 feroult # github.com/feroult 
 fröber # github.com/Brixto
 gnarhard # github.com/gnarhard
+Hoodead # github.com/kornellapu
 kenney # kenney.nl
 Klingsbo # github.com/spydon
+Kornél # github.com/kornellapu
+lapu # Artist of reference art (basic shader tutorial)
+Lapu # github.com/kornellapu
 luan # github.com/luanpotter
 luanpotter # github.com/luanpotter
 Lukas # github.com/spydon

doc/images/tutorials/basic_shader/final_result.png

@@ -0,0 +1,29 @@
+# Basic shader tutorial
+
+This tutorial will give you a brief understanding of how to create and use basic shaders on
+`SpriteComponent`s with `PostProcess` and `PostProcessComponent` using Dart/Flutter and the Flame
+engine.
+
+This tutorial assumes that you have a working Flame project set up. If you don't, please follow
+the [](bare_flame_game.md) tutorial first.
+
+The tutorial consists of 4 steps. We will create a simple outline shader for sprites which have a
+transparent background layer.
+
+```{note}
+This tutorial is intended to work on images with transparent
+background, like `.png` files.
+```
+
+*Created by Kornél (Hoodead) Lapu.*
+
+
+```{toctree}
+:hidden:
+
+1. Sprite Component         <step1.md>
+2. Outline Post Process     <step2.md>
+3. Shader                   <step3.md>
+4. User Input               <step4.md>
+5. Takeaways                <takeaways.md>
+```

doc/images/tutorials/basic_shader/hover_demo.webp

@@ -0,0 +1,96 @@
+# 1. Sprite Component
+
+
+## Architecture and Responsibilities
+
+Let's create the component where we render our sprite and apply the shader. We will split this
+into two classes:
+
+- a `SpriteComponent` subclass that loads the image and handles input events
+- a `PostProcessComponent` subclass that wraps the sprite and applies the shader
+
+This separation means that shader changes only require editing the wrapper class, while sprite
+changes like adding input event mixins or additional children only require editing the sprite
+class.
+
+
+## Image resource
+
+For this tutorial we need an image with a transparent background to apply the outline shader to.
+Create an `assets/images/` directory in your project and add your `.png` image there.
+
+Don't forget to register the assets folder in `pubspec.yaml`:
+
+```yaml
+flutter:
+  assets:
+    - assets/images/
+```
+
+
+## Sprite
+
+Create a new file named `sword_component.dart` (replace "sword" with your own image name):
+
+```dart
+import 'package:flame/components.dart';
+
+class SwordSprite extends SpriteComponent {
+  @override
+  Future<void> onLoad() async {
+    sprite = await Sprite.load('sword.png');
+    size = sprite!.srcSize;
+  }
+}
+```
+
+
+## Wrapper
+
+Next, add the wrapper class that applies the post process. In the same file, create:
+
+```dart
+import 'package:flame/components.dart';
+import 'package:flame/post_process.dart';
+
+import 'package:basic_shader_tutorial/outline_postprocess.dart';
+
+class OutlinedSwordSprite extends PostProcessComponent {
+  OutlinedSwordSprite({super.position, super.anchor})
+    : super(
+        children: [SwordSprite()],
+        postProcess: OutlinePostProcess(anchor: anchor ?? Anchor.topLeft),
+      );
+}
+```
+
+
+## Result
+
+The final `sword_component.dart` file looks like this:
+
+```dart
+import 'package:flame/components.dart';
+import 'package:flame/post_process.dart';
+
+import 'package:basic_shader_tutorial/outline_postprocess.dart';
+
+class OutlinedSwordSprite extends PostProcessComponent {
+  OutlinedSwordSprite({super.position, super.anchor})
+    : super(
+        children: [SwordSprite()],
+        postProcess: OutlinePostProcess(anchor: anchor ?? Anchor.topLeft),
+      );
+}
+
+class SwordSprite extends SpriteComponent {
+  @override
+  Future<void> onLoad() async {
+    sprite = await Sprite.load('sword.png');
+    size = sprite!.srcSize;
+  }
+}
+```
+
+This won't compile yet because `OutlinePostProcess` doesn't exist. Let's create it in the next
+step!

doc/images/tutorials/basic_shader/sword.png

@@ -0,0 +1,135 @@
+# 2. Outline Post Process
+
+
+## Responsibility
+
+The `PostProcess` class manages the fragment (pixel) shader. It is responsible for loading the
+shader program, creating GPU resources, and keeping uniform variables up to date each frame. You
+can also expose runtime settings through uniforms, for example to enable or disable effects.
+
+
+## Post process
+
+Create a new file named `outline_postprocess.dart`. This class loads the shader program in
+`onLoad()` and passes uniform values to the GPU each frame in `postProcess()`:
+
+```dart
+import 'dart:ui';
+
+import 'package:flutter/material.dart';
+
+import 'package:flame/components.dart';
+import 'package:flame/post_process.dart';
+
+extension on Color {
+  Vector4 toVector4() {
+    return Vector4(r, g, b, a);
+  }
+}
+
+class OutlinePostProcess extends PostProcess {
+  final double outlineSize;
+  Color outlineColor;
+  final Anchor anchor;
+
+  OutlinePostProcess({
+    this.outlineSize = 7.0,
+    this.outlineColor = Colors.purpleAccent,
+    this.anchor = Anchor.topLeft,
+  });
+
+  late final FragmentProgram _fragmentProgram;
+  late final FragmentShader _fragmentShader =
+      _fragmentProgram.fragmentShader();
+  late final Paint _myPaint = Paint()..shader = _fragmentShader;
+
+  @override
+  Future<void> onLoad() async {
+    await super.onLoad();
+
+    _fragmentProgram =
+        await FragmentProgram.fromAsset('assets/shaders/outline.frag');
+  }
+
+  @override
+  void postProcess(Vector2 size, Canvas canvas) {
+    final preRenderedSubtree = rasterizeSubtree();
+
+    _fragmentShader.setFloatUniforms((value) {
+      value
+        ..setVector(size)
+        ..setFloat(outlineSize)
+        ..setVector(outlineColor.toVector4());
+    });
+
+    _fragmentShader.setImageSampler(0, preRenderedSubtree);
+
+    canvas
+      ..save()
+      ..translate(-size.x * anchor.x, -size.y * anchor.y)
+      ..drawRect(Offset.zero & size.toSize(), _myPaint)
+      ..restore();
+  }
+}
+```
+
+With this file in place, the syntax error from the previous step will go away.
+
+Since the `PostProcessComponent` is the parent of the `SpriteComponent`, the post process renders
+first and the sprite is drawn on top. The `rasterizeSubtree()` call captures all children into an
+image that the shader can sample from.
+
+
+## Usage
+
+Now we need to wire everything together. Open `main.dart` and add both a plain sprite and an
+outlined sprite to the world so we can compare them side by side:
+
+```dart
+import 'package:flutter/material.dart';
+
+import 'package:flame/components.dart';
+import 'package:flame/game.dart';
+
+import 'package:basic_shader_tutorial/sword_component.dart';
+
+void main() {
+  runApp(
+    GameWidget(game: MyGame()),
+  );
+}
+
+class MyGame extends FlameGame {
+  MyGame() : super(world: MyWorld());
+
+  @override
+  Color backgroundColor() => Colors.green;
+}
+
+class MyWorld extends World {
+  @override
+  Future<void> onLoad() async {
+    add(
+      SwordSprite()
+        ..position = Vector2(-200, 0)
+        ..anchor = Anchor.center,
+    );
+
+    add(
+      OutlinedSwordSprite(
+        position: Vector2(200, 0),
+        anchor: Anchor.center,
+      ),
+    );
+  }
+}
+```
+
+Here we use a custom `FlameGame` subclass to override the background color. Adjust the positions
+and color to suit your own images.
+
+Run the application. You should see only one sprite, the outlined one is missing. The console
+will show why:
+`[...] Unhandled Exception: Exception: Asset 'assets/shaders/outline.frag' not found [...]`
+
+We haven't created the shader file yet. Let's do that in the next step.