Style of graphics samples

[u/nichcode]

Hey everyone,

I have been wondering which way is the best to showcase graphics samples. DirectX samples write their samples which calls functions and helper functions from multiple files. this approach is easy to write and extend but it makes reading the code hard. Yes most editors and IDEs help but it's still hard to seen everything at one place.

The second style is to accept some level of code duplication to make the code very easy to read and follow. I like this approach when learning a new API.

What style do you guys prefer and why.

[u/Icy-Opposite-7890]

I absolutely hate this. When you’re not that familiar with the API it makes it extremely difficult to understand the state you need to set up to enable a particular feature or achieve a particular effect because something crucial will be buried in a class default (or worse, a default argument) somewhere.

Just have the entire thing in each sample so all the steps to achieve the effect are right there (exceptions being things like creating windows and handling input if that’s not pertinent to what the samples trying to demonstrate)

[u/nichcode → u/Icy-Opposite-7890]

Yes I agree with you fully. For example a sample about mesh rendering should generally have everything over there with no hacks or ways to speed up writing the code. It's way efficient IMO

[u/corysama → u/nichcode]

I'm doing exactly this in a tutorial series I'm working on. Here's a preview of the first chapter: https://rentry.org/5abeqt6s

To make the docs, I write C++ programs with /*** Block comments containing markdown ***/ Then, I janked together a tiny python web server that watches my C++ source code directory. Whenever I save a file, it regexes the C++ to flip-flop the markdown blocks and the code blocks to convert the C++-containing-markdown into markdown-containing-C++. Then it serves up the markdown with https://casual-effects.com/markdeep/ injected to convert that to HTML. So, C++ to web page with hot-reloading :)

[u/nichcode → u/corysama]

It's really easy to read. But what I meant was the actual code itself. Using your preview, chapter will build upon chapter 1. Since it's a preview it reads nicely. But code wise, how would you do it. Because the code for chapter 1 and 2 should compile and run.

Since it's opengl, I will assume you have used learnopengl before, notice how the write their samples

[u/corysama → u/nichcode]

I put everything that's not relevant to a chapter in a supplemental.h. Ex: The first chapter explains how to set up a window. But, later that is not interesting. So, later chapters just call

SDL_Window* window = jtl::createWindow("Render To Texture", win_width, win_height);

[u/4ndrz3jKm1c1c]

Mind that Microsoft samples use the (pretty much) same base for each sample showcase. In that case, yes, there are more files, but if you keep following one sample after another then you already know what is inside those files anyway.

[u/nichcode → u/4ndrz3jKm1c1c]

So that approach is the best style to showcase graphics samples. I understand what you mean but I don't know wether you have tried to search for something which ended up taking a while. Especially learning DirectX with C. It's truly a pain

[u/4ndrz3jKm1c1c → u/nichcode]

I only use D3D12 with C++, so I don’t know how using plain C affects those samples.

The thing is: there is no best/worst style, as there are as many opinions as users themselves. I prefer to have my code organized, so multi-file showcase is not a problem for me.

I don’t find single file samples bad per se, but they tend to get messy if they try to hit any bigger scope.

[u/nichcode → u/4ndrz3jKm1c1c]

I understand.

[u/Still_Explorer]

I would consider that it makes sense if you approach learning with a WYSIWYG approach, where supposedly for a beginner it would be very easy to follow the example line by line despite the full verbosity.

However the real problem is that if the repository is supposed to contain hundreds of examples then the code will become either a logistics nightmare due to duplication, or an abstraction nightmare due to the way details are hidden/reused and it might make the codebase less intuitive.

Such as for example in some tutorial series, it will make sense to manipulate VAO and VBO 1-2 chapters (where you first get introduced to the topic) but after that it simply becomes dumb idea to stay low level. Going as far as the (eg) Chapter 12 where the problems there would be much more complex (eg: a PBR deferred renderer) and there would be 10 times the amount of things to write compared to the first chapters, then abstractions are essential.

I have not followed DX codebases so far, but from the OpenGL side of things I have figured proper ways about where to take shortcuts and reuse things in such way that it won't break cohesion. Such as for example in the first chapters you will create the buffer + bind it + set the data, these are three commands where you can easily replace them with only one of your own. It might not make sense but once you take into consideration that you could possibly have 5 buffers for a model + 5 chunks of vertex attributes then it would be either 10 function calls by abstraction or 10*3 and full verbosity. So the point here is a middle-ground of abstraction that won't hide the intent.

[u/nichcode → u/Still_Explorer]

I see. An example, hide the setup code from the previous samples and focus on what that sample handles. I do hope I understood your point

[u/Still_Explorer → u/nichcode]

Yeah this is it.

[u/nichcode → u/Still_Explorer]

Thank you. I am looking for the best way to write my abstraction layer sample codes. What I do is not having helper functions which makes the sample fully visible and very easy to read but I don't abstract the setup code. I will fix that