Structure for the Introduction Section(s) (Part1)

[deccer]

Why don't we start by doing the following

1. Show HelloWindow made with raw winapi

Reasoning:

• that's how its usually done
• showing how clunky and ugly it is
• which nobody really should do anymore - since there is really no benefit

That means Windowing and Input via RawInput (and provide the same "experience" we have right now in HelloWindow (mouse click and ekypress cause console output)

2. Show HelloWindow made with glfw

Reasoning:

• it will show what is possible these days, no need to dive into winapi really, and GLfw/SDL2 provide coverage for input/window etc
• makes code code "cleaner" (also technically provides future platform agnosticism)

3. Show HelloWindow made with a basic framework

Reasoning:

• 1. and 2) have been sitting in Main.cpp so far, no "clean code"
• introduce a simple and basic framework which makes it easy to follow and extend during further tutorials or even beyond
• basically what HelloWindow is right now (Main+Application+Input+Keyboard+Mouse)

4. Show HelloTriangle made with basic platform + introduce d3d11

Reasoning:

• introduce D3D11 the first time, based on HelloWindow
• use raw pointers showing how to create device/devicecontext/swapchain bs
• that will be a continution of the current stuff and people can easily follow
• a frogcoloured triangle should be rendered :)

5. Extend HelloTriangle, make resize work

Reasoning:

• since swapchan->ResizeBuffers requires all swapchain-bound resources to be freed, why not use this opportunity to explain
• relase and recreation certain resources (RTV/SRV/BackBuffer/whatever)

6. Introduce ComPtr instead of Raw Pointers for the DX shizzle

Few words about why ComPtr makes sense and how its being used.
Probably one or two sentences and a link into MSDN

7. "Componentize" DX parts

Reasoning:

• Engines, hobby or not, follow graphics pipelines of the used APIs pretty much
• those "pipelines" could reflect the structure in form of "pipeline" and "context" constructs
• mght prepare the further tutorials to make use of pipelines and renderpasses, which might end up in framegraphs or whatever to prepare the user how to structure their engine/work/game/demo/whatever
• nobody needs spaghetti code scattered all over the place

That stuff could be the very first chapter of the tutorial before we do anything else, like meshes and explaining shaders etc

[DethRaid]

Why use Win32 at all? You're gonna make people start off by rewriting a bunch of code

Why rewrite the code to bring in that abstraction so early? That can wait until later - or just use the abstraction from the beginning

Why use D3D11 without ComPtr? People are gonna have to rewrite a bunch of that code

In short: do not make every other step be "Okay here's a new thing now go rewrite a bunch of code"

[matthewgeorgy]

I think at one point (no clue if this has been changed) we agreed on doing the tutorial with GLFW or SDL, and then having an appendix that talks about a WinAPI implementation for anyone who is curious. No clue if this is still the case but I'm just bringing it up for reference.

[AlexB8675]

Then how about this, we write a simple Hello Window and Hello Triangle with nothing but Win32 and raw D3D11, explain how it all works, and then in the next section, we present the readers with a the abstraction I wrote (or some variation of it, the point is that everything is abstracted with GLFW and a basic structure).

[DethRaid]

@matthewgeorgy is correct. We already decided to focus on GLFW and later make an appendix about Win32

[spnda]

Then how about this, we write a simple Hello Window and Hello Triangle with nothing but Win32 and raw D3D11, explain how it all works, and then in the next section, we present the readers with a the abstraction I wrote (or some variation of it, the point is that everything is abstracted with GLFW and a basic structure).

Not if it is a long chapter. The code shown should only cover a small amount of code, if any. Presenting the user with a full WINAPI implementation is most likely very overwhelming and unnecessary.

[deccer]

@matthewgeorgy is correct. We already decided to focus on GLFW and later make an appendix about Win32

I had this idea only earlier today, I apologise for that

[Themperror]

I agree with everything said initially, except for:

it will show what is possible these days, no need to dive into winapi really, and GLfw/SDL2 provide coverage for input/window etc

I've personally had issues with getting (docking) DearImGui working in Dx12 properly because it relies so much on behaviour done in WNDPROC, SDL completely takes that control away from you (and GLFW does too) and SDL doesn't even allow a callback/hook into it either. It definitely pays of knowing how to use it properly, and its far from obsolete really...

[16-Bit-Dog]

I think providing perspective is important, so point number 1 and 2 are important; I find most of my peers who struggle to learn graphics API concepts struggle due to assuming everything is a preprogrammed state machine, where it has no level of dynamic components.

To start by showing that - options do exist - types are types for a reason, it provides a bit of that perspective.

A tutorial should remove some of that intuition required to learn, else it is not effective as a tutorial; and showing 2 methods to explain the complexities with 1 method further helps with this concept

For the rest, I agree - especially with COM, unless you want to touch in manual Release and AddRef to describe how the black magic works.

[matthewgeorgy]

Seems mostly reasonable and I agree with the points made about starting from the raw API to implementing abstractions. As long as the abstractions are motivated by showing the redundancy with raw API calls then it makes sense. There is definitely going to be a lot of friction in the process of "porting" the raw API stuff over to the abstractions, however. I also think there needs to be at least one dedicated section in the beginning that explains how the graphics pipeline works (and how D3D11 implements it), because that stuff is totally foundational to understanding everything else in the API. I've got a doc on that that I've been writing up which I can post here at some point if we'd like.

[deccer]

I mean, what keeps us from giving it a try, compiling a thing like that together, and then showing it to some uninitiated people, see what they feel about it, or if they can follow along, idk

Worst case we scap it and go a different way

(I am not afraid to do that, its not a time sink, and not waste of time)

[AlexB8675]

I believe we could bore readers with all the rewriting and explaining, too much detail is not always appreciated after all, I believe we should keep it simple with GLFW and at most, just a simple "HelloWindow" with Win32

[NicusorN5]

I might be biased, but I honestly think WIN32 is not that hard at all... Would you go further than handling keyboard and mouse input in a graphical application? Drag and drop files? Just an extra flag and one more case in the message procedure. I think windows scaling can be handled by DXGI itself.

I would write the entire tutorial using WIN32 (and of course, the point of the tutorial is teaching DirectX11...)