[Bf-committers] GSoC BGE Shader API discussion

[Mitchell Stokes]

Dalai and I had a discussion on the new API being introduced for handling
GLSL shaders in the BGE. Dalai suggested that I repost this here so that
more feedback can be gathered while other APIs (such as Audspace) are being
discussed.

Okay, this is what I have from our discussion:

There will be two new Python objects:
  * BL_BlenderShader
  * A uniform object (BL_Uniform?)

BL_BlenderShader will have the following attributes:
  * vertex (rw) = the vertex shader to use
  * geometry (rw) = the geometry shader to use
  * fragment (rw) = the fragment shader to use
  * uniform (rw) = a list of uniform values to use

BL_Uniform will have the following attributes:
  * name (rw) = the name of the uniform (must be unique in the uniform list)
  * type (rw) = the type of the uniform (this will probably be done with
constants)
  * value (rw) = the value of the uniform

Some examples of what uniform initialization might look like:

uniform = BL_Uniform("foo", KX_UNIFORM_INT, 42)
uniform = BL_Uniform("bar", KX_UNIFORM_VEC3, (1.0, 0.0, 1.0))

To add uniforms to the shader:
shader.uniforms.append(uniform)

The general work flow of working with the api will probably look like this:

 1) Remove/unlink the current shader (maybe just replace with the new one?)
 2) Create a new shader:
    my_shader = BL_BlenderShader()
    my_shader.fragment = """my fragment source"""
    my_shader.vertex = """my vertex source"""

 3) Add uniforms to the shader:
    my_shader.uniforms.append(BL_Uniform("my_uniform", KX_IVEC2, (1, 2)))

 4) Set the shader to be used by the material:
    material.blender_shader = my_shader

 5) Update the uniforms every frame if you want:
    shader.uniforms["my_uniform"].value = (3, 4)

There was also talk about the ability to make unique materials/shaders at
runtime. The material could be given a make_unique flag that is user
settable. At conversion time if the material has a make_unique, a new
material is made for each object that wants to make use of it instead of
sharing it. This would allow for uniqueness between users of the shader, but
would probably decrease performance. An example of this is as follows:

  You have 10 enemies that display their "energy" values through the shader
(maybe by brightness, color, shininess or some other factor). So, the enemy
material and shader have an energy uniform that will be updated during
runtime. However, since everything is shared, you update one enemy and they
all change. So, instead you force the material to be unique so that each
unit's energy can be uniquely displayed.

I think that just about covers the conversation.

Cheers,
Mitchell