Technical Q&A QA1679: Deprecated built-in variables in GLSL Shaders says that IOS WebGL doesn’t have a whole lot of uniforms and attributes (the idea is to simply pass these values as a user-defined variable instead of using the predefined name). This includes things like gl_ModelViewProjectionMatrix which is usually used in boilerplate like
Now IOS isn’t targetted by JME so we don’t need to care, but they also say that it is “not recommended for use on Mac OS X”.
Since Mac OSX is definitely on the list of JME targets, should we worry about this?
We already pass in everything ourselves to shaders from vbos and our own matrices, so the uniform/attribute part should not be a problem. And it doesn’t list gl_position/gl_fragcolor etc as depreciated, so we should be safe with our current 2.0 shaders :). OpenGL 3.x made all this shizzle depreciated (everything to do with the matrix/texture/projection stack like glPushMatrix, glIdentity, glFrustrum etc lighting and all corresponding shader values it used to pass in for you (as you mention)), whereas in OpenGL 4.x this is all completely gone, and you have to do everything yourself (you have now in/out to replace uniforms and stuff like gl_position/gl_fragcolor).
Display lists are also gone (they store a list of OpenGL commands on the graphics card), and while faster than VBO’s you couldn’t modify them and they are not as extensible, and im pretty sure we don’t use them anywhere. So we are probably almost Opengl 4.0 compatible as well, just lack some of the new features it has introduced
Seems like we should make sure that examples, tutorials and distributed shaders don’t use that stuff then.
It would be nice to have a list of JME/OpenGL-provided shader variables somewhere. It’s what’s holding me up most with shader stuff right now - I don’t know what variables I can expect, if I need a variable and don’t find it I never know whether I should make it a material parameter or just google more.
Out of frustration, I started compiling a list of predefined shader variables; now it seems I have to pull a whole host of documents together. (I’ve been planning to put the list into the JME wiki so others can make use of that, too, but I wanted to make it both accurate and useful before I do that.)
<cite>@wezrule said:</cite>
Display lists are also gone (they store a list of OpenGL commands on the graphics card), and while faster than VBO's
Display lists are faster than static VBOs only in a very few cases, when you have a very few triangles to do (tens), when their implementation doesn't suck (depending on the driver) or when the implementation of VBOs sucks (depending on the driver, can happen on very old OpenGL 1.3 compatible graphics cards providing ARB VBOs in which VBOs simply use vertex arrays without taking into account the draw hints).
I built a little something to generate me an HTML file that documents the uniforms.
The main program is simple (and emits just to stdout for now):
[java] public static void main(String[] args) {
Class<?> clazz = Shadervars.class;
String packagePath = clazz.getPackage().getName().replace(’.’, ‘/’);
STGroup templateGroup = new STGroupFile(packagePath + “/template.stg”);
ST html = templateGroup.getInstanceOf(“html”);
html.add(“uniforms”, UniformBinding.values());
System.out.println(html.render());
}[/java]
Here’s the contents of the template.stg file (repetitive stuff stripped):
[java]delimiters “$”, “$”
html(uniforms) ::= <<
<!DOCTYPE HTML PUBLIC
“-//W3C//DTD HTML 4.01 Transitional//EN”
“http://www.w3.org/TR/html4/loose.dtd”>
<html>
<body>
<h2>Uniforms</h2>
jME automatically defines and transmits the following uniforms for use in
shaders.<br>
Current versions of GLSL predefine equivalent uniforms, but these should not
be used since they are deprecated in GLSL 3.0, and are scheduled for
elimination in GLSL 4.0.
<table border=“1” cellpadding=“4” style=“border-collapse: collapse”>
<tr>
<th>Type</th>
<th>Uniform</th>
<th>GLSL equivalent</th>
<th>Value</th>
</tr>
$uniforms: uniformRow()$
</table>
</body>
</html>
>>
uniformDocMap ::= [
“WorldMatrix”: “Converts Model space to World space.”,
… stripped …
“FrameRate”: “Frames per second.”,
default: “<i>UNDOCUMENTED</i>”
]
>>[/java]
Is there interest in turning this into a generator for a JME3 website page?
Output format is easy to change, it’s just fill-in-the-blanks stuff that uses StringTemplate to generate the actual HTML.
The data type column is automatically extracted from the JME3 engine. The other columns are provided inside the template, so it’s not limited to extracting program data, though taking it from the classes would take out some redundancy from the process.
Aww, I can’t find a pastebin service that allows me to upload HTML and have it displayed as such.
So download shadervars.html · GitHub to a local .html file and view it in the browser :-/
Alternatively, you can simply drop the Java source into any class, drop the template.stg file into the same package, and paste the console output to a .html file.
Remove the …stripped… lines in the html.stg, they’re invalid syntax - the missing lines will simply show up as UNDOCUMENTED, as a reminder to add the missing entries.
Yet another alternative: replace the HTML markup in the html.stg file with Wordpress markup and paste into a posting (unfortunately, tables aren’t supported in the forum).
Or replace the HTML markup with wiki markup and copy&paste the output to a wiki page.
It doesn’t look like much. It’s essentially just a table with data extracted from the enum and from html.stg itself.
The important point is that it extracts its data right from the engine sources, so the published docs are guaranteed to be consistent with the code.
I copied the Javadoc content into uniformDocMap in the template file, so yes the texts are already available in the Javadoc.
I just thought it would be useful to have that in the table, too.
There’s one thing I don’t like: The Javadoc contents aren’t extracted automatically, that was manual.
Ways around that I see:
Add some code that extracts the Javadoc from the sources. I never did something like that so I don’t know how. It would add a dependency in that it would need access to the source files, complicating the build scripts and making it impossible (or at least harder) to hack on that code. On the plus side, does not require changes in UniformBinding.java.
Move the Javadoc into a property. E.g. change
[java] /**
The world matrix. Converts Model space to World space.
Type: mat4
*/
WorldMatrix(“mat4”),[/java]
to
[java] WorldMatrix(“mat4”, “The world matrix. Converts Model space to World space.”),[/java]
Downside: Mouseover on the value does not show the text anymore, that’s not good for working inside Eclipse (not sure whether Netbeans will work better but I don’t expect it to - it would be unusual to show the enum’s constructor call on a mouseover).
Move the Javadoc into an annotation. E.g. something like this:
[java] @Docstring(“The world matrix. Converts Model space to World space.”)
WorldMatrix(“mat4”),[/java]
At least in Eclipse, a mouseover over a mention of WorldMatrix does show all annotations. Does Netbeans show them as well? In that case I’d work on getting the template to extract the annotations.
I see two approaches to implement this, one dead simple, one with boilerplate involved but doable.
If the annotation approach pans out, we could also document the GLSL equivalence as an annotation and extract that, too. That would then look like this:
[java] @Docstring(“The world matrix. Converts Model space to World space.”) @GlslEquivalent(“gl_WorldMatrix”) // Haven’t checked whether that’s correct
WorldMatrix(“mat4”, “The world matrix. Converts Model space to World space.”),[/java]
For the first part, you can add pluggable code to the javadoc process to generate whatever you want. Generally this is done as a different pass than the normal javadoc pass but need not be in this case necessarily. It has access to all of the docs and tags.
I’m a bit reluctant about Javadoc because it requires integration into an additional point in the nightlies workflow.
Also because anybody who wants to change anything about uniforms needs to know that the javadoc extraction process exists, and needs the skills to make any required corrections.
The plus side of Javadocs is its easy HTML formatting.
Well, it’s also a bit of a minus, because any HTML markup would need to be translated to wiki markup.
I’m a bit reluctant about Javadoc because it requires integration into an additional point in the nightlies workflow.
Also because anybody who wants to change anything about uniforms needs to know that the javadoc extraction process exists, and needs the skills to make any required corrections.
The plus side of Javadocs is its easy HTML formatting.
Well, it’s also a bit of a minus, because any HTML markup would need to be translated to wiki markup.
Yeah, I’ve written doclets to generate code before and I’ve written doclets to generate alternate formats (like textile for confluence). It’s very flexible but like many things is sort of a can of worms. They are yummy worms, though.
They are yummy worms, though.