I don’t know how I feel about documentation, yet. I have plenty of 3d background, but it comes from a different era. Equations and principles are not a big deal to me, it’s the APIs and toolchains that are a barrier. I’m currently resolved to slowly plod along with DirectX Whatever until I see the light at the end of the tunnel. Urho3D’s main virtue in that regard is being a non-trivial base of working DX11 code. I’ve kept up on the general principles of DX11 over the years but I haven’t done anything specifically with it. So the minutiae of ThingAMaJig->ShovingIntoTheFunctionThing(crap, o, la) is quite tiresome but I suppose I’ll eventually be sufficiently familiar with it. There’s so much boilerplate to get anything done, I hate it. But I tried to do Linux and OpenGL in rebellion for 3 years recently, and I became firmly convinced that it’s decidedly the worse API and platform. So back to DirectX crap it is! Vulkan couldn’t come too soon.
So, I wouldn’t confuse learning graphics and 3D API stuff, for learning Urho3D stuff. People either swallow the former or they do not. I’ve written my own 3d API “pave over” stuff before, back in the DX8 era. Urho3D’s architecture in that regard seems pretty straightforward to me. I have no difficulty understanding how multiple 3d APIs are “made to function alike”. For me the area of investigation is, whether optimal use of DX11 performance concepts are being made. Time will tell.
It happens that because I’ve suffered for years trying to get other people’s open source projects to actually work on Windows, that I have erstwhile CMake skills. So although I don’t like CMake, and indeed got kicked out of their developer community back in the day, I do know my way around the block there. I realize it’s a maintenance barrier for people who don’t know it, and I sympathize with anyone trying to know it. I have very high minded ideas about what a better build system would look like, but in 7 years I haven’t produced it, so ha! Glad there’s 1 guy around, Weitjong, who really knows his CMake stuff. If he got hit by a truck I personally would survive though. I may finally give Premake4 a whirl, because if nothing else it’s Lua scripted. CMake has the virtue of being mostly feature complete, a heavyweight of industry, and that’s probably a good fit to a 3d game engine’s ongoing development. Premake4 might turn out to be better for small end user applications though. I suppose I will see.
Mainly the way I personally see Urho3D, is “this is easier than writing my own 3D engine from scratch.” A lot of gruntwork has already been done. I expect that I’ll eventually get to the point where I understand whatever there is to know about Urho3D’s internals. Then I will either decide, 1) holy cow, this code is a pile of needless confusion! I surely don’t want to cast my lot with this, or 2) this code is fine. Time to build a game, maybe also add DX12 if not too much work. (1) happened to me with Ogre3D, back in the day. Especially stupid was their homebrewed shader language stuff. From a long term sustainability standpoint, you gotta be kidding me! Might have sounded good in the long, stable DX9 era, but really dumb once DX10 and DX11 are coming around the corner.
So I guess I inevitably defer the question of documenting internals. Is there really something that needs to be known? I’m sure I’ll file an issue when I make such a determination. But frankly, building 3d engines is not for amateurs, one must already have skills. My view is adding any documentation needed for a professional level developer to continue with a support effort.