Configurable World Shader Commands System

[ZzzhHe]

Resolve #1541

• Add WorldShaderCommands class to manage shader commands
• Support adding/removing commands with custom GLSL code
• Integrate command system into WorldRenderStage

[heinezen]

Hey thanks a lot and cool that it already works :)

I think we need to design this a bit more to make it more in line in the way that it is supposed to be used, i.e. by putting these snippets as files somewhere and merging the shader code better.

I'll think about it and will come back to you with more ideas.

[heinezen]

Okay, I finally have time to respond here :D As said before, I like the direction where this is going, but I have a few requests for how commands should be integrated.

1. If shader source code is supposed to be templated, I don't think it should be loaded as ShaderSource at the start as the code may be incomplete. Instead, there should probably be a ShaderTemplate class that the template is loaded into which can be fed with ShaderSnippets to insert into placeholder in the template. Once ShaderTemplate is configured with snippets, it should be able to create the final source code which can then be passed to the ShaderSource constructor. This additional layer would probably prevent a lot of problems for templates that are not properly initialized.
2. I think we can already make the feature more versatile and extendable by not having a generic INSERT_POINT in the shader source code and instead assigning placeholder IDs. Multiple shader snippets could then be inserted into different position in the shader template based on their ID.
3. I don't think the logic for creating shader code should be hardcoded, e.g. in WorldShaderCommands, because it defeats the point of making the commands configurable. The command code should be loadable from a file that the user can create. If we have to recompile the engine every time you want to change the commands, we might ass well just use the current solution.
4. It's probably better to create a renderer demo for this feature rather than using it in the actual renderer. This way, we can test the design and change it without having to worry about it affecting the main rendering loop just yet.

[ZzzhHe]

Here are some updates:

1. Template system implemented via ShaderCommandTemplate class
2. Custom shader code for commands supported through .config files
3. Dynamic shader assembly with placeholder support (//@COMMAND_SWITCH@)
4. Add demo 7 to test the shader command template class.

But the current state is a very basic version, here are some current limitations

1. Config path is currently in shaders directory. Maybe I should make this more flexible or move to a new folder in future versions.
2. Missing direct way to set alpha values on entities (would be useful for testing). I'm considering consider adding set_alpha().
3. Only basic validation right now, I could add more robust error checking later.

[ZzzhHe]

Because right now I didn't implement alpha setting function, so I hardcoded different alpha code into fragment shader to test.

demo_7_world.frag.glsl

void main() {
	vec4 tex_val = texture(tex, uv);
	int alpha = int(round(tex_val.a * 255));
	alpha = 252; // hardcoded for testing right now
	switch (alpha) {
	case 0:

world_commands.config

[COMMAND]
placeholder=COMMAND_SWITCH
alpha=252
description=Green tint
code={
col = vec4(0.0, 1.0, 0.0, 1.0) * tex_val;
}

[heinezen]

I think we could still make this much simpler :D

I'm not sure if we even need a custom config format that needs parsing. If we do placeholder replacement, we can skip most of the parsing logic while supporting even more use cases.

Example

Template: shader.template

#version 330

uniform float template_local;

// PLACEHOLDER: unifs_code.snippet

void main() {
    // PLACEHOLDER: x_code.snippet
    // PLACEHOLDER: y_code.snippet
    gl_Position = move * vec4(x, y, 0.0, 1.0);
}

Snippet: unifs_code.snippet

uniform float value;

Snippet: x_code.snippet

float x = value + 1.0 

Snippet: y_code.snippet

float y = value - 1.0 

End result:

#version 330

uniform float template_local;

uniform float value;

void main() {
    float x = value + 1.0 
    float y = value - 1.0
    gl_Position = move * vec4(x, y, 0.0, 1.0);
}

[ZzzhHe]

Do you think using a JSON config file makes sense? The structure is clean and we only need to load the JSON file instead of scanning for snippets:

{
  "snippets": {
    "lighting": "snippets/lighting.glsl",
    "color_processing": "snippets/color.glsl",
    "effects": "snippets/effects.glsl"
  }
}

File structure would be:

shaders/
  ├── world2d.frag.template    # Main shader template
  ├── world2d.vert.glsl       # Vertex shader
  ├── shader_config.json      # Snippet configuration
  └── snippets/               # User-modifiable snippets
      ├── lighting.glsl
      ├── color.glsl
      └── effects.glsl

[ZzzhHe]

Or maybe we could simply read all the snippets directly from the snippets/ folder without setting a config file.

[ZzzhHe]

I've simplified the shader template system to focus on its core functionality.

• Shader templates now load snippets from a snippet folder that contains all snippet files.
• Refactored demo7 to be a minimal demonstration of the template system only.

Fragment Shader Template:

#version 330

in vec2 tex_coord;
out vec4 frag_color;

uniform float time;

void main() {
	// PLACEHOLDER: color
	// PLACEHOLDER: alpha
	frag_color = vec4(r, g, b, alpha);
}

Shader Command Snippets:
alpha.snippet

float alpha = (sin(time) + 1.0) * 0.5;

color.snippet

float r = 0.5 + 0.5 * sin(time);
float g = 0.5 + 0.5 * sin(time + 2.0);
float b = 0.5 + 0.5 * sin(time + 4.0);

Result:

[heinezen]

Sorry for the long wait on the review 😿 I was unfortunately very busy at work which made the open source reviews a bit difficult. But now that I have time I can, I must say I like your solution very much! I have a few small suggestions, but that is only really minor stuff. I would be happy to merge this soon :)

[heinezen]

This could generate renderer::resources::ShaderSource directly.

[heinezen]

You need three slashes, so that doxygen detects it as a docstring.

Suggested change

	// Original template code with placeholders
	std::string template_code;
	// Mapping of placeholder IDs to their code snippets
	std::map<std::string, std::string> snippets;
	/// Original template code with placeholders
	std::string template_code;
	/// Mapping of placeholder IDs to their code snippets
	std::map<std::string, std::string> snippets;

[heinezen]

util::Path has a method implemented for what you are doing here (get_stem()).

[heinezen]

Idea for a faster approach: Instead of searching the whole source string for each snippet, we could search for the placeholder positions during initialization of the class and save the positions. Then when we want to insert the snippets later, we just have to look up the positions again.

Probably not that big of a deal right now, but it might be more performant on large template files.

[heinezen]

Suggested change

	// Initialize shader templlalte
	// Initialize shader template