Getting started with CompositorEffects and Compute shaders

[pink-arcana]

Distance Field Outlines was a learning project for me. I've been programming for years, but not professionally or at a low-level. Before starting this, I had some experience with simple Godot shaders, and had set up some multi-node post-processing effects. But I'd never touched a Compute shader or Godot's lower-level graphics APIs. I say this to show that you can get started creating CompositorEffects without having a background in graphics programming. However, you do have to be willing to do a lot of your own homework, and be okay with not being able to find quick solutions by googling.

I took lots of notes as I was making this project. I initially wrote them in comments inside my scripts, so now that I'm cleaning the project up to post the source code, I'm adding those notes into this discussion thread below. (Edit: I'm also adding and correcting info and links as I learn more.)

But, like I said, I'm not an expert! So take any advice I give with a grain of salt. I welcome feedback or corrections. And I'd also love to get your own tips and links, both for myself and anyone else visiting.

All my benchmarks here are from an Nvidia RTX 3080 laptop GPU. If you test any of the same things I did on different hardware and get different results, please post your findings! I opened a separate discussion for Performance & Optimization as well.

Getting started

• Godot's NEW feature is AWESOME by Octodemy - YouTube tutorial/introduction to CompositorEffects (thanks to @jasonswearingen for the link)
• Godot docs : The Compositor - official tutorial and starter project.
• Bastiaan Olij's dev streams: 49 and 50 (follow the links to the demo projects in the descriptions) - This is how I got started with CompositorEffects. He created the CompositorEffect PR, and it's super helpful to hear him describe, line-by-line, what the code in the demo projects is doing and why.
• The original CompositorEffect PR - the discussion was helpful for understanding what it can/can't do, and contains some useful tips.
• RenderDoc - absolute must-have for debugging. You can learn a lot about how the rendering works in Godot just by snooping around inside a captured frame.
  • To get labels to work, use --verbose
• BaseCompositorEffect (see also: BaseCompositorEffect script template and SceneData and SceneDataHelper shader includes) - I refactored my CompositorEffect for this project into a superclass that abstracts a lot of the repetitive code. This is specific to my workflow, but may be helpful to look at. It includes functions for binding the build-in SceneData UBO and the built-in depth and normal/roughness textures.

Vulkan references

The GDScript naming is slightly different from the Vulkan API, and RenderingDevice also abstracts much of the Vulkan setup. So, when using Vulkan references, I've found it helpful to have the GDScript class references and C++ code open side-by-side to figure out how it corresponds.

Quick links

• RenderingDevice: GDScript | Source
• RenderSceneBuffersRD: GDScript | Source

• Vulkan documentation - much more approachable than the specs, and you can read the guide section like a manual. Oddly, doesn't seem to show up google search results, even though it has the official answers for many common questions. There is also a re-organized version here, with better search.
• vkguide.dev - excellent introduction to every Vulkan topic you'll need to understand for CompositorEffects. It contains specific guidance on best practices (I linked to a couple specific ones in the sections below.)
• Vulkan Tutorial - mostly covers the same topics as vkguide.dev, but reading them explained in a different way can make it click.

[pink-arcana]

Storage Options

These are the non-texture uniform options I found useful for this project, and my experiences with them. Also see the Textures post below.

For a full list of options and GLSL examples, see docs.vukan.org - Mapping Data to Shaders.

• Push constants - push a small amount of data to a shader at the time of compute list creation. GPUs should be transporting and storing them in an optimized way for fast access.

  • Individual elements must be aligned to 4 bytes, and the entire push constant must have a size that's a multiple of 16 bytes. They have a maximum size of 128 bytes in Godot.
  • Used in the Godot docs example projects.

• Uniform Buffer Objects (UBOs) - move a larger amount of data for persistent storage on the GPU. Then give your shaders access to it via bindings in their layouts.

  • Aligned by 16 bytes. Can be much larger than push constants on desktop GPUs, but UBOs larger than 128 bytes may not be reliable across mobile hardware. (Arm specifically states they limit to 128 bytes.)
    • If you assign the members inside of the UBO layout, they must be aligned per the layout to 16 bytes (i.e. they must all be at least vec4's). However, if you assign the whole object to a separate struct, you can align elements by 4 bytes -- with some exceptions. This packs the data more tightly, and has both pros and cons for usability. Both options had equivalent performance in my testing.
      • The exceptions are:
        • Larger elements must still be aligned to 16 bytes. So I've found it easier to put all the vec4s first, then the floats.
        • While you can assign floats directly in this struct, I got bad data when I tried to assign bools or ints. However, Godot's SceneData struct directly assigns bools and uints (presumably without a problem?). So this warrants further investigation.
    • See this thread on Reddit with helpful replies from a Godot maintainer: Uniforms vs buffers in compute shaders, and how do I bind them?
  • It seems that only static UBOs are available in Godot 4.3, so updating a value requires re-creating the UBO. In this project, that doesn't seem to be a problem. It updates the UBO whenever the settings change, but otherwise just hangs out in GPU memory.
  • You can also connect your shaders to Godot's internal SceneData UBO. It is already in memory, so it gives you access to handy data (like viewport size, transforms, time) essentially for free.
    • Instructions for binding it are in the Github comments here).
    • The struct itself is here.
  • In testing for this project, binding to pre-existing UBOs was faster than using a push constant. The push constant had only been pushing over the specific data the shader needed, while each UBO now provides each shader with extra data it doesn't use. (For SceneData, this is a struct of almost 100 lines.) However, these unused assignments do not seem to matter. So, from what I can tell, binding existing UBOs (like SceneData) should probably be preferred to sending the same data over in pieces with push constants.
  • You can debug your UBOs in RenderDoc: Under the Compute Pass, select the appropriate vkCmdDispatch. Then open the Pipeline tab, and click the Compute Shader button. In the Uniform Buffers list, double-click the item to see its values.

• Specialization constants - add small, individual constants directly to a pipeline when you create it. The shader is then compiled on the GPU with these constants hard-coded in. The constants are very limited in number and size, but using them can be very performative. This is a reason some games have massive numbers of pipelines (see this screenshot from Breath of the Wild.)

  • There seem to be two main use cases:
    • Hard-coding values that differ by shader pass. - In my testing, creating individual pipelines for each JFA pass with the offset value as a specialization constant was slightly faster than using push constants (-80μs over 11 passes).
    • Replacing constant uniforms used for branching.
      • Modern desktop GPUs have a concept of constant uniforms, so, if the uniform has the same value for the entire workgroup, it is treated as a constant. Specialization constants would not have any performance benefit in this case. And, in my testing on my Nvidia RTX GPU with a highly-branching shader, the performance was the same either way.
      • However, on GPUs that do not have constant uniforms (for example, Arm states their chips do not), the difference may be significant. This leads me to think that, if both options are otherwise equivalent, specialization constants should be preferred.
  • Note that while specialization constants are compiled into the shader by the GPU, they are not considered compile-time constants (at least in Godot's GLSL compiler), so cannot be used to set offsets for texture + offset commands. They also can't be used to set array lengths as of 4.2/4.3 (issue)

A note on layout requirements
Push constants and UBOs are specific about their alignment and often require extra padding. I personally found it easier and less error-prone to abstract out the alignment to separate functions. You can compile and run your shaders without error even if you do not assign the extra padding that's been added. This makes it faster to quickly add/remove uniforms for testing. However, this seems like it could be creating a buffer overflow, so, once I was done setting up, I still added in extra floats to capture the unused data.

[pink-arcana]

Uniform sets and bindings

• vkguide.dev : Descriptor sets - excellent guide to what sets are, and how to optimally set them up, including when to increment set index versus binding. They point out that some hardware only supports a maximum of 4 layout sets. And they suggest organizing sets in an order of most-global to most-local.
• zeux.io - Writing an efficient Vulkan renderer - goes into much more detail about different options for organizing sets.

[pink-arcana]

Compute shaders

• vkguide.dev : Compute shaders - introduction to how compute shaders work, and how to choose a workgroup size.

  • The Godot examples use a workgroup size of 8x8.

  • Per vkguide.dev, "It’s very common to have things like 16x16 workgroup size when doing postprocess filters or other similar rendering shaders."

  • I chose a workgroup size of 16x16 for this CompositorEffect based on my results here:

      Total frame times for different sizes @ 1080p/1024px:
          8x8 -> 1.43ms
          16x16 -> 1.15ms
          32x32 -> 1.26ms
          64x64 -> error: command_queue_execute_and_present() FAILED
    

• gl_GlobalInvocationID gives you the texel's coordinates in texture space. It is located at the edge of the texel, not the center. To convert to a normalized position to use in texture() functions, you need to add 0.5. See this stack overflow answer for reference.

[pink-arcana]

Textures

• NekotoArts's Everything About Textures in Compute Shaders! - a Godot-specific guide to creating your own textures and moving back and forth from CPU to GPU.

Choosing a format

• Vulkan: optimal image tiling format support on all platforms - Comprehensive list of formats sorted by % support for each platform.

Choosing a uniform

Use image uniforms with imageStore/imageLoad to read and/or write a single texel; use sampler uniforms with the GLSL texture functions to read.

• You can find many opinions about which is better/faster.
  • Arm's guide says, Use texelFetch() or texture() instead of the slower imageLoad() wherever possible.
  • On my Nvidia RTX GPU, head-to-head benchmarks of imageLoad vs texelFetch were identical.

Built-in textures

• Normal roughness texture
  • After sampling, apply normal_roughness_compatibility() function (From Use best fit normals for storing screen space normals PR)
    • Because this was so hard to find, I opened an issue for this on the Godot docs repo
• Depth does not have necessary usage bits to copy from or to it, so it cannot be updated from a CompositorEffect (source)

Sharing textures between different CompositorEffects

• For two CompositorEffects in the same viewport, render_scene_buffers.has_texture() is true for textures created in the other CompositorEffect.
• For CompositorEffects in different viewports, render_scene_buffers.has_texture() is false for textures created in the other CompositorEffect.
  • However, the texture image still exists in memory. You can access it by passing its RID to the other CompositorEffect (tested with setting a variable on an autoload).

[pink-arcana]

CompositorEffects

Troubleshooting

• If the CompositorEffect is in a scene without an Environment (on a Camera3D or WorldEnvironment), _render_callback() will be called early, but still pass the expected EffectCallbackType. For me, this has resulted in errors accessing the normal_roughness buffer, since it doesn't exist yet. But this is a red herring. The true problem is the lack of an Environment in the scene.
• A CompositorEffect's @export variables cannot be keyframed in the AnimationPlayer from inside the Compositor's Array[CompositorEffect]. A workaround is to put the same saved CompositorEffect resource (or a separate settings resource) directly on a node in the scene tree. See the instructions here.
• The normal_roughness texture will appear grainy or degraded and cause artifacts when used for rendering. It requires a conversion function.
• If you are reading and writing to the same image from a single Compute shader, you can only read from the same texel you are writing to. Sampling neighbors will result in flickering and other artifacts due to the parallel processing. The built-in textures (like the screen color image) don't seem to have the TEXTURE_USAGE_CAN_COPY_FROM_BIT set. So you would need to create a custom copy to a new texture in a separate shader pass (see an example of how to do this in this tutorial).

[jasonswearingen]

Here is a pretty nice video intro to compositor effects? https://youtu.be/rVcd8sLPsXU?si=fttfutAfDIqbZDPf

[pink-arcana]

Very nice! I added it to the top of the list since it looks like a much easier place to start than anything else on there.

[Mopzilla]

Just wanted to say this information is extremely helpful. I'm running into limitations with standard shaders and was looking to move into using the compositor and this has helped a bunch. Great post 👍

[jasonswearingen]

Agree! I'm super excited to have this available. I'm finally getting to my visuals (procedural spaceship hull) so this bookmark is warm and ready :)