Book refactoring
lwjglgamedev opened this issue · 17 comments
It's been a long time since I started writing this book. After that I've been busy with the (Vulkan book, so I've just being fixing some issues for this book.
I was thinking in refactoring the book contents and the samples following this approach:
- Explain the complete source code in each chapter (for incremental changes just the modifications of course).
- Simplify the chapters: Only one source tree per chapter.
- More direct approach. For example, instead of explaining how to creat a custom .obj loader, just jump directly to assimp. Instead of explaining how to render text, use imgui.
- Avoid code recactors from chapter to chapter as much as possible.
- Properly auto-format code.
- Use of new Java features (recods, switches,...)
What do you think? Is it worth the effort? (It will take a lot of time)
Leave your comments!
I was actually having a read through Vulkan book (mainly out of curiosity) and seen the combined book + sample approach you adopted for that and was actually going to suggest you do the same for this, so glad to see you are thinking along the same lines. Having the samples inline I think provides the benefits you list above
Explain the complete source code in each chapter (for incremental changes just the modifications of course).
- Having the source and book code in one repo allows quick navigation in an IDE without having to flick between repos
Simplify the chapters: Only one source tree per chapter.
- You can link the full code in java from the samples
Avoid code recactors from chapter to chapter as much as possible.
- Should help keep consistency between the sample and full source, like in this case - https://github.com/lwjglgamedev/lwjglbook/pull/102 the ordering is actually different that the explaination. Functionally it makes no difference, but would be easier to spot and have the worked example map 1-to-1, so people can follow along and go. Ok that is that variable, where is it in the sample code.
More direct approach. For example, instead of explaining how to create a custom .obj loader, just jump directly to assimp. Instead of explaining how to render text, use imgui.
- 50/50 on this. I know I found it useful to see a worked example of a basic asset loader, but can see the advantages of skipping it, learnopengl.com goes straight to use assimp while opengl goes through creating a custom obj loader.
Properly auto-format code.
👍 This just makes life easier if you do get PRs, one less thing to correct.
Thanks for your comments.
Yes the approach would be similar to the Vulkan book. I'm thinking in creating a branch and doing all the modifidations there and merge the final result. It will take a long time in any case.
I started reading this book last week - and absolutely I love it. I'm only up to chapter 10 (That fragment shader is incompatible with the dummy game renderer code by the way, just rollback that file to the previous commit to fix it)
Along your discussion points:
Explain the complete source code in each chapter (for incremental changes just the modifications of course).
Simplify the chapters: Only one source tree per chapter.
Personally, I felt the book contents gave excellent insight into the subject, described the concepts at an appropriate level of detail, and included enough sample code to clarify the subject point.
That being said, one place that felt was cumbersome was correlating the book textual chapter names (ex. Let there be even more light ) against the repository's numerical chapter folders (ex. chapter10)
More direct approach. For example, instead of explaining how to create a custom .obj loader, just jump directly to assimp. Instead of explaining how to render text, use imgui.
If this guide were focused on a from-scratch-game-engine, I may advocate teaching the general concepts and implementing the OBJLoader to materialize that lesson. I felt the book's primary focus is to teach LWJGL; writing the OBJLoader (and other limited support classes) doesn't feel meaningful to the final outcome.
For the majority of developers, I have to imagine that assimp will support their model loading needs well into production.
If the reader wants to deviate, you have, at the very least, provided the valuable knowledge on how to integrate a reference implementation accompanying LWJGL. Still valuable, a starting point for someone to write their own implementation and compare it to.
Avoid code recactors from chapter to chapter as much as possible.
Please
Properly auto-format code.
If its not too forward may I suggest checkstyle and its maven plugin. It goes a long way in ensuring that contributions, commits, and style guide changes, are -and remain- uniform and consistent.
Use of new Java features (recods, switches,...)
I'm conflicted on this discussion point. I think you've done an excellent job steering the code towards an appropriately compatible version of Java. In the interest of keeping the focus on learning LWJGL (and libraries) I would recommend avoiding Java features beyond 11 unless they provide significant improvement applicable to using LWJGL.
Additional talking point:
Does LWJGL3 support Android now? Android is only up to Java 11 last I checked, I could be wrong. My project has no plans for mobile, but someone else's may - If there is interest in writing a chapter for LWJGL on Android, this may be something worth weighing against implementing newer Java features.
Many thanks for the detailed contents.
Regarding Java version, maybe it's time to use latest LTS version (17 if I'm not worng). In any case, linked with your Android question. LWJGL does not supprt Android, amd I'm not sure if it will. In fact, there is an interesting discussion on LWJGL Github about this.
That being said, one place that felt was cumbersome was correlating the book textual chapter names (ex. Let there be even more light ) against the repository's numerical chapter folders (ex. chapter10)
This is a great shout out, it was difficults to know which (sub) module corresponded to to which section of a chapter, like chapter12-p1/chapter12-p2/chapter12-p2. I think having the book and code together will but having the section names will
Sure, this will be the approach. One single project per chapter.
Update: I'm starting to work on this. I'm writing first the source code to check the approach. I'm using a private repository by now. If someone is interested I can give access. In any case, keep in mind that is quite unstable at this moment. I'm currently at chapter 9, introducing assimp instead of a custom obj loader.
I agree with the approach of skipping straight to assimp and other similar changes.
One change I'd like to suggest is to load the models tangent data (easy enough to add using assimp) and use that for normal mapping in Chapter 17, or alternatively make it a follow up chapter later on. As this is the more conventional approach for normal mapping and would make the normal mapping code more useful (being able to load conventional normal maps)
Thanks for the comment. This will b exactly the approach with normal mapping.
Update: I'm starting to work on this. I'm writing first the source code to check the approach. I'm using a private repository by now. If someone is interested I can give access. In any case, keep in mind that is quite unstable at this moment. I'm currently at chapter 9, introducing assimp instead of a custom obj loader.
I can take a look through it if you would like feedback or help.
@neomonkeus : Done, I've just sent you the invittaion to the repo.
I agree with the book refactoring thing, so i don't have to open 50 tabs just to write source code. Hope this goes well!
An update about the status. I'm about to complete the refactoring about deferred rendering source code. Pending tasks:
- Rework game loop.
- Decide wether I include a specific chapter for instancing or even better create a new one about indirect drawing.
- I've removed the chapters devoted to text rendering. No point in explaining the manual way since you can use imgui.
- I've not included, yet, chapters devoted to heightmaps and object selection. Not sure if they will be in the final version.
- Update book text for all the refactored chapters.
I was thinking also if t would be worth to include a sample 2D game (something like 1942, a top-down shooter). It should be quite easy. This could be an annex, explaining the main concepts.
I think instancing is good and indirect drawing is great. There are many examples online for instancing, and fewer for indirect drawing, so perhaps a good example of setting up indirect drawing would be good, having both though would be nice as well.
I agree, I do not think it is necessary to have an example for drawing text.
In my opinion, you could also remove the section(s) dealing with OBJ files. OBJ is an obsolete format (although still used), and Assimp already loads these. For beginners starting out, while it is cool to write a custom model importer, most just want to know how to get existing assets from blender into their engine quickly, and Assimp is likely the solution for that. So perhaps it would be better to start with Assimp directly. This could be done such that the initial implementation of the Assimp loader is quite simple though.
Object selection would be nice, picking is always a challenge for people learning to build engines for the first time. Heightmaps are a much lower priority for me personally, as none of the projects I work on use them, but I recognize that many engines (nearly all) still use them. It would be Really cool to get an example of something voxel (I prefer iso-surface, AKA smooth voxel, but some might also be interested in boxel). Having implemented an iso-surface terrain editor before, I know that is a large task and probably not on your priority list.
Anyways, great work as always, I look forward to going through the new revised book.
Thanks for the input, regaring your comments:
- Assimp is introduced directly. As you say, it really makes no sense to waste time in custom loaders. It may give you an idea about how models work, but is not very efficient.
- I will definetly go for indirect drawing maybe combining with a compute shader for animations (as in the Vulkan book). It simplifies a lot the shaders.
Some updates. Refactoring is almost complete, what is pending up to now:
- Write the text for the animation chapter.
- Create a new chapter for object piking (working on it right now).
- Write the text for indrect drawing (i may split this into two, since intrtoducing indiret drawing and compute shaders in a single chapter may be too much).
In any case, I was thinking on how to release this. I will need to use the old URLs for this, so I see to options:
- Dump the new contents over the git repo (you would have all the previous versions in a single repo).
- Clean history and move previous repo to a backup URL.
What so you think on this?
I've just published new version of the book using old URLs (https://github.com/lwjglgamedev/lwjglbook and https://github.com/lwjglgamedev/lwjglbook-bookcontents).
Chapters for indirect render are still to be written. I hope to complete it in a few weeks (you have a draft of the source code already uploaded).