The answer is pretty simple, actually. Most people that write tutorials on the Internet, while certainly well-meaning, have fairly little idea what it is they're doing/talking about. Doubly so for how to explain it. I'll get back to this in a moment.
You're on the right track, though, good to see you've managed to pick the proper level of abstraction.
EDIT: From personal experience, having mesh/particle, light and camera primitives (while exposing some things like shader parameters) seems a good jumping-off point. This is generally flexible enough that you can create most any rendering effect with minimal overhead. I also suggest designing your system to be both very content-oriented and minimally retained; this puts the power in the hands of the artist(s) and also makes debugging/multithreading easier, as all information is usually on-hand.
I don't mean to pick on you, AgentC, but a rebuttal:
A few reasons I can think of:
1) it requires (at least superficially) the least amount of thinking / planning to just wrap the low-level API objects
2) by keeping the abstraction at low level you should, theoretically, be able to construct complex API-agnostic higher level rendering code, and not have to duplicate eg. the functionality of Mesh for different APIs
3) A tutorial stays more generally applicable if it doesn't impose its own higher-level constructs
It has potential to get messy, though. For an example here's a list, from my engine, of D3D / OpenGL differences that "leak" from the low level abstraction to the higher. It's not unmanageable, but not pretty either. https://code.google.com/p/urho3d/wiki/APIDifferences
1) So, in essence, you're making code harder to follow by splitting it up at a very fine level, adding runtime overhead by adding superfluous virtual function calls, etc. just so that you can be typing code into an IDE *right this instant*? That seems a *very* poor tradeoff. This seems to be the thought process behind a lot of tutorials, actually.
EDIT 3: This kind of thinking is also what gave us JavaScript, FWIW.
2) Maybe in theory. By your own admission, though, there are often fundamental differences in how the API works that render this 'abstraction' meaningless anyway-- you still need to add more of them at different levels, which will in turn make code harder to follow.
3) Isn't the point of a tutorial to demonstrate how to take the low-level API and map it to higher-level constructs *anyway*?


Find content
Male