KhronosGroup
Code snippet that isn't explained in "Logical devices and queues"
Hi I'm a noob, I hope it's okay to do this. If not please delete.
I'm on lesson 4: logical devices and queues and so far I'm finding that sometimes the tutorial doesn't match the code, in that the code will have things not explained by the tutorial.
One example is the code snippe
// get the first index into queueFamilyProperties which supports graphics
auto graphicsQueueFamilyProperty = std::ranges::find_if( queueFamilyProperties, []( auto const & qfp )
{ return (qfp.queueFlags & vk::QueueFlagBits::eGraphics) != static_cast<vk::QueueFlags>(0); } );
assert(graphicsQueueFamilyProperty != queueFamilyProperties.end() && "No graphics queue family found!");
auto graphicsIndex = static_cast<uint32_t>( std::distance( queueFamilyProperties.begin(), graphicsQueueFamilyProperty ) );
In the tutorial we get a few mentions of graphicIndex and even use it at an rvalue, but nothing about how to find it. Rather than feeling like I'm following along with the tutorial and writing code that I can understand each line, I sometimes feel like I'm just copy-pasting from the example code because it'll suddenly have some dense block that isn't explained by the text.
Also, somebody really likes nested lambda functions (e.g. pickPhysicalDevice()). Is that some kind of optimization thing? I realize that's a C++ question more than a Vulkan question but as part of the tutorial you might put some little asides here and there about why it's best (?) to do things like that. Ya know, for people (definitely not me) who are easily confused.
I wouldn't delete, you're the audience we're writing this revision for. Please comment more often, it's the best way we can improve.
For the code snippet, I get you're saying it's hard to follow. That certainly isn't the intention for it to be a copy paste exercise. What that specific code is doing is finding the index in the vector that supports the graphicsQueueFamilyProperty. I'll see if I can add a few lines of explainer documentation to the text so that's clear.
For the lambda functions. It's both an optimization thing, and meant to make it easier to read/understand. I worry that the tutorial might be more confusing if we select C++20, use modules, and don't use modern C++ where it makes sense. It might be confusing to mix the modern C++ idioms with C code or even older yet still mainstream C++ idioms for documentation. Maybe it makes sense to do a version that is C only?
It might make for something worthy of consideration to add more language variations to the main tutorial. I don't like the idea of losing people due to efforts of trying to make the project easier to understand.
Okay I can make more comments! For the nested lambdas, it might read easier if you declare the lambdas separately near the top of the function, like you do with inside-function helper functions in Python, instead of in the place where they are passed to since it makes it nearly impossible to follow. I get this might necessitate changing some of the captures. I think it's best to stay in modern C++ for the most part.
While we're at it, the end of lesson 3 seems to have some content meant for lesson 4, the queue families thing. The function findQueueFamilies() in lesson 3 looks like an earlier version of the code at the top of createLogicalDevice() in lesson 4, where you're calculating graphicsIndex.
Also, while its fine to require 3D graphics knowledge as a prereq (so you're only teaching the API), you could put more definitions/explainers in the text for new API-y, GPU-y terms (like "context" or "logical device"). I learned pure software rendering so I know about vertices, perspective-correct interpolation, z-buffer, etc. and have a vague notion that "context" might be similar to OpenGL's global state (because I studied that for a few days before giving up), but going through the tutorial sometimes it's like "now we need a bligblorg so here's the code to do that, of course a bligblorg won't work without a smeeshsmoosh" and people who remember bligblorgs from DirectX or whatever are like "ah I was wondering how they did bligblorgs in Vulkan, now I know" and people like me are lost and have to find the definitions/significance of bligblorgs by googling. I didn't like OpenGL, but learnopengl.com does have a good pedagogical style, might be working comparing.
Oh also headers. Each lesson seems to introduce a new header (in the code) but doesn't mention it in the text, leaving you to figure it out when it doesn't compile. Not the worst problem in the world but thought I'd mention it.
I'll be quiet now.
Great comments.
I might try a hybrid ground of doing some initial chapters with broken up lambdas as you suggest and transition everyone to the nested style so it stylistically is closer to modern C++ idioms. That way there's a transition while demonstrating proper C++.
I'll review the end of lesson 3 and make sure it flows better; thanks for that report.
That last part about the prereq. I, honestly sheepishly agree. I'd love to do a start from scratch tutorial that only assumes you have knowledge of C++. However, figuring out a "common starting point" is a hard thing to do. I worried we'd lose quite a few people if we spent several chapters teaching linear algebra, or even mentioned quaternions; as quite a lot isn't taught in most college classes. Some people we'd lose due to being very familiar with the topic and are left wondering how to learn Vulkan if they have to wade through what they've used for years. Others we'd lose because the information would remain dense without getting to the point of teaching Vulkan. My goal has been to try to start with assuming someone has DirectX or OpenGL background and start there, then add explanations where people say they need them going back into the common things that other APIs already cover. That way, the content hopefully captures the cross section of the most amount of Vulkan users without becoming too dense from me trying to teach everything.
We have other tutorials planned that are more advanced that use this tutorial as a prereq. In one of them, I did go ahead and give a short intro to some of the aforementioned linear algebra, but that's coming down the road a bit.
Also, great catch on the headers. I do need to do a pass on making certain the code in the tutorial text is precisely what's necessary and reflected in the attachments folder. I did several of those passes, but there's plenty of cracks to fall through for things like header files that are missing.
#106 should hopefully help address your concerns. Lemme know if that helps. I'll keep looking through the tutorial for other areas that might make sense to treat similarly if this proves helpful.
Very nice, except on lesson 3 it doesn't render correctly, the new addition is included in a code block instead of being text.
Lesson 4 update is nice too, I'm impressed with your commitment to making these tutorials better.
I just corrected the text so it should render correctly now.
And thanks, there's a lot more than me working on it. Hopefully we'll make it something really worth while.