Custom color transforms

AdvancedProgrammer

You can write your own custom color transform effects. For example, you can create:

  • water droplets on the camera
  • screen transitions (such as fade-ins and fade-outs)
  • effects simulating pain or intoxication (eg by applying tints or other effects)
  • object outlinesTo create a custom color transform, you need to write two files: an effect shader (containing the effect itself), and a C# class (to make the effect accessible in Game Studio).

1. Create a shader

  • Make sure you have the Xenko Visual Studio extension installed. This is necessary to convert the shader files from XSL (Xenko shading language) to .cs files.

  • In Game Studio, in the toolbar, click Open in IDE (Open in IDE) to open your project in Visual Studio.

  • In the Visual Studio Solution Explorer, right-click the project (eg MyGame.Game) and select New item.

New item

  • Select Class.

Select class

  • In the Name field, specify a name with the extension .xksl (eg MyColorTransformShader.xksl), and click Add.

Create post effect

The Xenko Visual Studio extension automatically generates a .cs file from the .xksl file. The Solution Explorer lists it as a child of the .xskl file.

My post effect

  • Open the .xksl file, remove the existing lines, and write your shader.

    Shaders are written in Xenko Shading Language (XSL), which is based on HLSL. For more information, see Shading language.

    For example, the shader below multiplies the image color by the MyColor parameter:

  1. shader MyColorTransformShader : ColorTransformShader
  2. {
  3.     [Color]
  4.     float4 MyColor;
  6.     override float4 Compute(float4 color)
  7.     {
  8.         return color * MyColor;
  9.     }
  10. };
Note

Make sure the shader name in the file (eg MyColorTransformShader in the code above) is the same as the filename (eg MyColorTransformShader.xksl).

2. Create a C# class

  • In the Visual Studio Solution Explorer, right-click the project (eg MyGame.Game) and select Add > New item.

New item

  • Select Class, specify a name (eg MyColorTransform.cs), and click Add.

Add script

Open the file and write the class.

For example, the code below creates the class MyColorTransform, which uses the shader and supplies a value for the color MyColor (defined in the shader).

  1. using Xenko.Core;
  2. using Xenko.Core.Mathematics;
  3. using Xenko.Rendering;
  4. using Xenko.Rendering.Images;
  6. namespace MyGame
  7. {
  8.     [DataContract("MyColorTransform")]
  9.     public class MyColorTransform : ColorTransform
  10.     {
  11.         /// <inheritdoc />
  12.         public MyColorTransform() 
  13.             : base("MyColorTransformShader")
  14.         {
  15.         }
  17.         public Color4 MyColor { get; set; }
  19.         public override void UpdateParameters(ColorTransformContext context)
  20.         {
  21.             Parameters.Set(MyColorTransformShaderKeys.MyColor, MyColor);
  23.             // Copy parameters to parent
  24.             base.UpdateParameters(context);
  25.         }
  26.     }
  27. }
Note

Make sure the class name in the file (eg MyColorTransform in the class above) is the same as the filename (eg MyColorTransform.cs).

  • Save all the files in the solution (File > Save All).

  • In Game Studio, reload the assemblies.

Reload assemblies

The Asset View lists the class and effect shader in the same directory as your scripts (eg MyGame.Game).

Shader in Asset View

Note

In some situations, Game Studio incorrectly detects the shader as a script, as in the screenshot below:

Shader as script

If this happens, restart Game Studio (File > Reload project).

3. Use a custom color transform

  • In the Asset View (in the bottom pane by default), double-click the Graphics Compositor asset.

Graphics Compositor asset

The graphics compositor editor opens.

Graphics Compositor editor

  • Select the Post-processing effects node.

  • In the Property Grid, under Color transforms, click Green plus button (Change) and select your color transform (eg MyColorTransform).

Add script

  • To enable and disable the effect, use the check box next to the item.

Enable and disable custom post effect

  • To edit the public properties you specified in the class, expand the item.

Expand item

When you adjust the properties, Game Studio updates the effect automatically.

Warning

Unfortunately, this part of Game Studio has a memory leak problem. Every time you change a value in the graphics compositor, it uses 60MB of memory. To prevent Game Studio using too much memory, we recommend you restart it after you change a property a few times. This is a known issue.

See also