Project status/roadmap, forum and example focus

[nicknack23]

I just stumbled across this little library today while looking for a more lightweight replacement for the Pixi.js WebGL interface I'm currently using. OGL seems amazing and I'm surprised I hadn't heard about it before. I have some simple questions - sorry for opening an issue just to ask them (see forum question below)!

• AFAICT the library seems pretty complete, all I'm really missing is some documentation. Most of the items on the Extras list have been checked off too. How close are you to a 1.0 release, or at least transitioning from alpha to beta? Or do you still plan on experimenting with the API for a while? A "Roadmap to 1.0" section in the README would be useful.
• OGL has nearly 2k stars on Github, which seems to imply that there are a lot of users out there. Is there something like a Discourse forum or Slack where they hang out? Have you considered making one?
• I noticed that most of the current examples were focused on 3D functionality, but my application involves chaining shader transformations in 2D. If you're looking for more demos, could you consider porting over a few of the Pixi.js examples? See especially the ones under the Filters-* and Mesh-and-Shaders headings. I'll submit a PR myself if I manage to get a few working in OGL.

Looking forward to diving into OGL!

[gordonnl]

Hey,
Thanks very much for the feedback! No worries for opening an issue, if no-one has asked these questions before, this is the perfect place for others to find them!

• Roadmap. You're correct in that I really should outline my goals for this library to be more transparent. I have also been thinking for a while that it's probably time to quietly remove the alpha warning too, and to define what exactly I feel is holding this back. I certainly do like the freedom to tweak the API and so far no-one has complained haha.
• Documentation. This is one point I would clarify in the roadmap - I don't plan on adding any documentation. My hopes are that the users feel comfortable reading the code, and that there are enough examples to cover all of the functionality. This approach might not last, however up until now it has mostly worked, and in almost all cases I can just direct people to an existing example implementing their query. In avoiding documentation, I can keep the code much cleaner (in the case of jsdocs), and can be much more efficient.
• Community. Even though I don't mind getting occasional new questions as issues, Stackoverflow has an ogl tag, and would be the best place to request help on individual problems. I don't have a plan to create a forum.
• Examples. I basically make these as my personal needs arise for new techniques, and then share them with the community (eg I needed GLTF for a project, so I created and shared a full GLTF workflow). You're correct in that they're mostly 3D related, and also that there's nothing stopping someone from using OGL as a 2D WebGL rendering library. I don't have any plans to add 2D examples personally (unless I needed the functionality for a project), but would be delighted to merge PRs including some!

[nicknack23]

Thanks for the quick and comprehensive response! I'm really interested in seeing your thoughts about the future of OGL so I hope you can find some time to throw a quick Roadmap section into the Readme. I think once you wrap things up and release version 1.0, all it would take is a few announcements on Hacker News, HTML5gamedevs, relevant subreddits, etc to immediately attract a lot more users to OGL.

I can understand not wanting to clutter up your code with jsdocs annotations, but there are cleaner approaches that are still pretty easy. Since you already use Github Pages to host your examples, you could have Docsify generate an adjacent documentation section from Markdown, see tutorial. You could begin with just cross-referencing commands with links to examples that illustrate them, that would still be useful.

[schmidtsonian]

Yes please, can you add more examples? I'm particularly interested on how to play an GLTF animation

[tkjaergaard]

Hi @gordonnl,

First, thank you for a great library!

I think that a good documentation section could be great. I would be willing to help out if you want.

I agree with you that most of the stuff is documented in the various examples, but I personally used a bit of time getting both Texture and Orbit working, and understanding the various options.

[gordonnl]

Thanks for your feedback @tkjaergaard - digging a little further, how did you finally figure out how to use those features?
I would assume that the Textures and Orbit Controls examples would contain most of the necessary information, but I have a feeling that tracking down the appropriate/relevant example is not obvious, or perhaps those examples are missing some more vital info.

[gordonnl]

Yes please, can you add more examples? I'm particularly interested on how to play an GLTF animation

@schmidtsonian If you drag and drop a gltf/glb file onto the Load-GLTF example, it will play the first animation it finds. I agree that a dedicated example would be great, however for now you can hopefully still get an idea for how it works.

These are the main lines related, within the frame loop function:

ogl/examples/load-gltf.html

Lines 587 to 591 in eab9e72

	if (gltf && gltf.animations && gltf.animations.length) {
	let { animation } = gltf.animations[0];
	animation.elapsed += 0.01;
	animation.update();
	}

[tkjaergaard]

Thanks for your feedback @tkjaergaard - digging a little further, how did you finally figure out how to use those features?
I would assume that the Textures and Orbit Controls examples would contain most of the necessary information, but I have a feeling that tracking down the appropriate/relevant example is not obvious, or perhaps those examples are missing some more vital info.

Yeah, for the texture I for some reason ended up looking at this example. But I was unsure about the target option. Then I found the example you’re referencing and it worked.

The Orbit was particularly tricky to get working.

I ended up finding the forcePosition method here, which solved the issue for me (I just got a blank screen).

[gordonnl]

Ah I see, thanks for the details!

I know you don't need it now, but as an explanation to anyone with the same Texture confusion - for the target property on Textures, it maps directly to the native WebGL method bindTexture's first argument. As OGL sets gl.TEXTURE_2D by default, you can basically forget about it unless you are dealing with cube maps.

For Orbit, it sounds like perhaps your camera position was set at (0, 0, 0), however it's just a guess. In cases where you are trying to manipulate it beyond the default use-case, I totally agree with you that it's not obvious (nor possible in some cases without editing the class). I have some ideas for re-writing this class in order to make it more open for a variety of input options (e.g manual camera animations).

[tkjaergaard]

@gordonnl Yeah, that makes sense! But this is the reason why I suggest a simple documentation, stating the different options for the individual classes 😊

Something like the Vue or React documentation could be a reference point for simplicity? Maybe combined with existing and new examples that are referenced in the relevant sections?

[gordonnl]

For documentation, you mention a 'simple documentation stating the different class options' - for that, I would love the source code to be digestible enough to explore - especially in the kind of cases you mentioned where a dev either forgets the name of an argument, what it does, what the default is etc. There are only 8 classes in the OGL core after-all, most of which are fairly small.

OGL is by-design a very thin abstraction from WebGL, so I don't really like the idea of people only referring to it as a black-box, even if that is largely acceptable.

For the Vue/React style documentation, I find those more of a 'tutorial' or 'how-to-guide' series of articles rather than your regular API, JS-DOC-style documentation - and for this I find the examples are a great compromise for doing the bare minimum coverage. I'm totally not against there existing a step-by-step guide through all of the things you can do with the OGL library along with detailed instructions and caveats, however it's very time consuming to create.

If you have any other points/features of OGL that you or others find confusing, it would be great to note them down and share, so we can either add some comments in the relevant class, or add an example shedding light to that area!

[tkjaergaard]

I agree with you that it's a light abstraction of WebGl and it's very pleasent to use! For the documentation part, i offered initiality to help, if wanted.

But this also kind of boils down to, @nicknack23 initial question on, what the goals are for OGL?

I get the feeling that you kind of just want to keep it on a low. Mostly covering your personal needs, rather than be an alternative to something like Three.js? Which is totally cool, i'm just seeing more potential here.

For me it's light, intuitive to work with and feels modern in it's structure. But i'm sad to hear the hostility towards something like TS, Documentation etc. which make me think if you even want OGL to be something that is more widely used?

[monolithMktg]

I personally am ok with a lack of public roadmap, but would really love to see atleast lighting incorporated as an in-built feature. I believe it should still keep OGL low on abstraction.

Also, if someone could please add in the greyed out examples. Thanks