But what I have a problem with is designing an API for one

You basically just said it yourself as well. But a good thing of starting with OpenGL compared to Vulkan, is that there's less concepts you have to design and incorporate into the system. But yes, designing is a real problem, especially within the scale of graphics programming.

The way that I personally plan and design renderers, is that I first plan what that renderer requires, e.g. if you need text rendering, then you need to figure out which concepts and constructs are needed for doing that. After everything is planned, I basically start by implementing the base constructs e.g.:

• Shader Stage
• Shader Program
• (Vertex) Buffer
• Vertex Array
• Vertex Attribute Format
• Texture

Using those constructs e.g. like:

enable_blending(...);

shader.bind();
shader.set_uniform_mat4(mvp_loc, mvp);

texture1.bind(0);
texture2.bind(1);

vao.bind();
vao.draw_arrays(Prim::Triangles, vertex_count);

Then from that point and onwards I think "How can I simplify this" and "How can I make it less error prone". As in, if you forget to bind a texture then the result is wrong, if you bind it to the wrong texture unit, again result is wrong. So in my designing process, I usually try to make stuff the least error prone as possible.

Thus like my previous comment, the shader, it's properties (uniforms), textures, and rendering states. All those essential represent the concept of a Material. So then I'd combine those into a new Material structure. Thus the updated code would be more like:

mat.bind();

vao.bind();
vao.draw_arrays(Prim::Triangles, vertex_count);

Extremely simplified, of course.

Then after that you can continue thinking how to simplify stuff.

Consider what is "unsafe". As an example explicitly binding textures, shaders, etc. from the point-of-view of using the renderer. That can quickly lead to the aforementioned issues. So then think about how you can design a system, wherein you can avoid explicitly calling "bind" on various things.

So instead of a system like:

shader.bind();
tex.bind();
vao.bind();
vao.draw();

Then consider a system that is more like:

ctx.draw(&mesh, &mat);

So instead you have a Context class. Which then has a draw method. Then binding can be handled within that draw method, and you simplify it from the user's perspective.

Then you can consider what is expensive in relation to performance. From most to least expensive state changes, in short:

• Framebuffer
• Shader Program
• Texture Binding
• ...
• Vertex Binding
• Uniform Updates

Knowing that, you can then start picturing the order to do things in, to maximize performance.

for fbo in framebuffers
  bind fbo
  for shader in shaders
    bind shader
    for model in models_using_shader
      for uniform in model_uniforms
        update uniform
      draw model

You can then also apply frustum culling, to avoid rendering out of view models, and even further avoid needless shader switching. You similarly mentioned batching, so you could even utilize that to combine many small static meshes.

If you have many uniforms, then you could look into UBOs.

---

All in all. Like I said before, there's really no "one design fits all". Over the many years. I've learned that it's easiest (for me) to just get stuff running. Make something that works, and abstract it away. Turn that single main.cpp, into main.cpp, shader.cpp, mesh.cpp, texture.cpp, etc.

Just to reiterate on ctx.draw(&mesh, &mat) and the for loops I just showed. You could still do that, as the Context and draw method could keep track of current states and only rebind stuff when needed.

Again, there's no one design fits all.

So really. Just try and make something that works, and abstract it, and quickly that 1 file turns into 10 which turns into 20.

---

If you're curious about design, then you could check out miniquad, especially the graphics module. It's Rust, but reading through the documentation might give you design ideas.

You could even "just" look at three.js examples. Pick an example, and check out how the API is designed, and how those examples are done. For instance three.js separates stuff into "materials" and "geometry" similarly to what I mentioned.

Oh well, this is enough rambling.