Document shader interface (uniforms etc)

[sprunk]

Looks like each shader type can have its own set of uniforms and they can also depend on other settings. E.g. map shader seems to have a bunch of map textures bound and then more when adv map shading is enabled: https://github.com/beyond-all-reason/spring/blob/b0dde959f2504a6031748a995c294ba3084925f0/rts/Map/SMF/SMFRenderState.cpp#L136-L145

The task is to document all of this.

[badosu]

Expose a custom type or table, and reference it on places where a texture is used.

Good candidates for example are all places that parse texture names in unsyncedctrl (using ParseLuaTextureData), e.g.

/*** @function Spring.SetMapShadingTexture
 * @string texType
 * @string texName
 * @treturn bool success
 * @usage Spring.SetMapShadingTexture("$ssmf_specular", "name_of_my_shiny_texture")
 */

If a custom type is not possible with current LuaDoc, then just @see to a new module defining a bogus custom table on LuaOpenGLUtils

[lhog]

What's the purpose of documenting that? The map shader is not available outside of engine internals and if someone still wants to use custom map shading they need to deal with uniforms (and their names) themselves.

[sprunk]

map shader is not available outside of engine internals

Good, I didn't know that.

What about these? https://github.com/beyond-all-reason/Beyond-All-Reason/blob/934c5991fb511937c5341dac09d6ad478a1b99b9/luaui/Widgets/Include/LuaShader.lua#L56-L65

[lhog]

gl.GetEngineUniformBufferDef() takes care of that, but it's not documented yet.

[lhog]

https://github.com/beyond-all-reason/spring/commit/558c7c7627a35a6ba3f2b35f18dd1c91da38aecb

[sprunk]

558c7c7627a35a6ba3f2b35f18dd1c91da38aecb is alright but "the GLSL compliant definition of UniformParamsBuffer" still doesn't describe what the params buffer contains (which what a dev will want to know). You can call the function to learn the names but you still won't know the meanings or the values behind those names.

To be more clear what I want. Here's a small snippet from a hypothetical page I would want to exist. The real page would have them all:

name	what is it	value remarks
fogParams.x	start of the fog relative to camera	0.0 - 1.0
fogParams.y	end of the fog relative to camera	0.0 - 1.0
timeInfo.x	sim frame
timeInfo.y	real (wall clock) time	always flows at real time (even when e.g. paused)
timeInfo.z	game time	stops when paused, slows at x0.5 gamespeed etc
mouseStatus	bitfield, from least significant: LMB, RMB, MMB, isOffscreen, isScrollingViaMMB, confined
windInfo.xyz	wind direction	normalized 0.0 - 1.0
windInfo.w	wind strength

[badosu]

Texname and/or textype does not reference $whatevertex?

[lhog]

Texture names reference the actual textures, yes. But it's not related to the shader uniform names mentioned in https://github.com/beyond-all-reason/spring/issues/1381#issue-2195109032

[badosu]

I see, we still want to document the texnames

[badosu]

There's some stuff here that could be improved. https://beyond-all-reason.github.io/spring/ldoc/modules/Shaders.html

[sprunk]

Some docs on getting a shader to work would be good too.

• what are steps to render something with a shader? (-> link to docs/examples for how to compile the shader, set uniforms, use the shader in the correct DrawFoo callin, manage the lifetime of the thing you're applying the shader to e.g. for unit that's UnitRenderCreated/Destroyed, others?)
• is there a ready plug-n-play, drag-n-drop framework to do the above? (-> not really, BAR and ZK have CUS gadgets but they have a ton of game-specific logic. Maybe this is inevitable since something has to set custom uniforms? but could be a separate sub-gadget)
• if a framework is suggested in the step above (whether BAR/ZK CUS as a "use these as starting point", or a hypothetical game-agnostic basecontent gadget in the future) some starter guide would be good.