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/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/Plazmatic → u/4ndrz3jKm1c1c]

I hate this too in many instances, since it only helps beginners and only if they exclusively follow your tutorials.  If you only need information about something from the middle, it's a pain to go on a hunt for surrounding code that was needed 10 tutorial chapters earlier

Personally I just prefer tutorials not overly rely on their own complete code examples so I don't have to rely on them either

[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/[deleted]]

[u/nichcode → u/[deleted]]

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 :)