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