Proposal: Expand tutorial to cover using Vulkan with Java

tthelin commented 7 years ago

Your tutorial is fantastic and well written. I'm actually using it to learn Vulkan with Java, translating everything as I go. The Java game development / LWJGL community could use a tutorial like yours, but rather than making yet another tutorial, when so much of the content is the same, I was hoping you might be willing to accept contributions to your tutorial to expand it to cover Java.

As a proof of concept, I forked your tutorial and started incorporating Java elements into it to see how it would turn out. I've got the code ported so far to the swap chain chapter, and I've edited 00 and 01 of the text. https://github.com/Overv/VulkanTutorial/compare/master...tthelin:master

Are you interested in the idea? If so I'd keep going, clean things up, and send over pull requests as I make progress. I'm open to how you'd like the content done.

sriharshachilakapati commented 7 years ago

This is a fantastic idea, I like it. However, instead of adding to the same repository, I prefer having another repository for Java, which follows the same commit structure. What do you say?

On Wed, 15 Mar 2017, 11:32 a.m. tthelin, notifications@github.com wrote:

Your tutorial is fantastic and well written. I'm actually using it to learn Vulkan with Java, translating everything as I go. The Java game development / LWJGL community could use a tutorial like yours, but rather than making yet another tutorial, when so much of the content is the same, I was hoping you might be willing to accept contributions to your tutorial to expand it to cover Java.

As a proof of concept, I forked your tutorial and started incorporating Java elements into it to see how it would turn out. I've got the code ported so far to the swap chain chapter, and I've edited 00 and 01 of the text. master...tthelin:master https://github.com/Overv/VulkanTutorial/compare/master...tthelin:master

Are you interested in the idea? If so I'd keep going, clean things up, and send over pull requests as I make progress. I'm open to how you'd like the content done.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/Overv/VulkanTutorial/issues/37, or mute the thread https://github.com/notifications/unsubscribe-auth/AEYWNAhYo3IIFnIpOioPxvPoBZ1Mop08ks5rl38FgaJpZM4MdhVM .

tthelin commented 7 years ago

How would the vulkan content / explanations be synced between the two? Most of the written text would be same, with the big exceptions being the code snippets and explanations of resource management.

I think more content would be shared vs different?

minecrawler commented 7 years ago

I am against translating the tutorial to Java in the same repository the way you do it. The tutorial has the purpose of teaching Vulkan. The Vulkan API is written in C, so C (and C++ in a broader sense) does make sense. However, if you start adding languages, you cannot simply stop at Java. What about Rust, Python, Go, Object-Pascal, and so on? If I decide to contribute them in the same fashion, we would end up with many exception clauses and lists of conditions and explanations for different languages. That would completely destroy the tutorial and just plunge it into a language-chaos.

Instead, you should either make a 100% Java repository or implement a language-selector, so that only one language is displayed at a time.

tthelin commented 7 years ago

So I understand your concern about mixing content as it won't scale if you added many languages as you noted.

As I said earlier I'm open to ways of shifting the content around, however at the end of the day it would be nice to users if it was all part of the same website in some way, and better for maintenance if they were part of the same repo.

Multi language ideas:

language selector as noted.
Don't bother explaining java, just have translations for the chapters whole code file at the bottom of each chapter like there's a link to the C++ code; just add a link to the java equivalent so it's minimal and doesn't interrupt the C++ aspect of the tutorial. This would easily scale to multiple languages.
In addition to above, you could have separate "other language notes" pages per chapter, linked at the bottom or top of the chapter, so it's out of the way, and all it does is augment that chapter with other language points

I hope I'm being clear that there are ways of adding in other languages that doesn't mean inlining and making the content harder to follow. I'm ok with other languages being treated as second class citizens here with the main focus on C/C++ as Vulkan is a C API.

Would you like me to augment my prototype to show the style of those last two bullets to see what it's like?

minecrawler commented 7 years ago

your second and third points sound interesting, however I could imagine, that just adding the source and some notes might end up a little confusing. In the end, we should probably wait and see what @Overv has to say :)

Overv commented 7 years ago

Adding Java instructions to the tutorial is a great idea. As @minecrawler mentioned, I don't think the C++ and Java text should be intermingled in any way on the same page.

I don't like the second and third points because they clutter the page while not adding much value. Languages like Java and Rust really have different resource management paradigms that warrant separate instructions, and should not be treated as second-class citizens. People doing the tutorial in Java or Rust will probably also have different questions in the comments section, especially in the development environment chapter.

I think the first idea, having a language selector, is the best. This still unifies all the tutorial content in the same website and design, while also isolating every language into its own dedicated environment with instructions and code that fits the language's niche.

The CMS I use (Daux.io) already has multilanguage support built-in, which can totally be hacked into multiprogramminglanguage support :). What this means is that the directory structure of the repository is going to change to:

cpp
    00_Introduction.md
    01_Overview.md
    02_Development_environment.md
    03_Drawing_a_triangle
    ...
java
    00_Introduction.md
    01_Overview.md
    02_Development_environment.md
    03_Drawing_a_triangle
    ...

It's fine if the code directory contains both cpp and java files, its organization isn't really relevant.

WIth that said, I will only do this after at least the chapters up to and including "Swap chain recreation" have been fully translated for Java. Once your repository is at this point and the content has been reviewed, I will restructure the directories and merge the content.

tthelin commented 7 years ago

So I've been looking into the language selector idea

I'm not sure Daux's multi-human-language support will work well because it expects you to to basically have full copies of all of the content, but in different languages. I was hoping to avoid having large chunks of programming-language-nuetral explanations of Vulkan and it's API copied between tutorials and have to be kept in sync. So while you can do this, it seems like a maintenance burden to keep the text in sync. Is this what you intended when you suggested using it?
Another avenue I was exploring was to extend the Markdown implementation Daux uses to support a new block element that would signal a section in a chapter is programming language specific (could be entire chunks of a chapter). Then you could pair this with a language selector dropdown on each chapter and minimal javascript to allow the reader to show just the content for the programming language they choose (making it look seemlessly made for that language). It's a little more up front work to make the Daux/Markdown changes, but it would lend itself towards better long term maintenance because neutral content no longer needs to be synced, and the tutorial markdown files would clearly label what is neutral vs language specific. MSDN used to do something like this for it's API documentation, since it had to have explanations for C++, C#, VB, etc
Another option related to the above idea is to leverage a custom Daux processor to basically support some kind of "include" directive so common text can be pulled from a common area. You'd do the multi-language layout suggested earlier, but at least there's the option of importing identical content between them per chapter.

Overv commented 7 years ago

The block element idea sounds interesting, but the idea of merging all the different language information in one big file is still not very appealing to me. I think it's the best if you just write the content for Java as separate files for now and then afterwards we can find out what works best instead of guessing.

tthelin commented 7 years ago

Alright I'll give that a shot. I'll periodically post here with updates if that's OK with you.

Overv commented 7 years ago

Yeah, that's a good idea.

tthelin commented 7 years ago

Any guidance on how to properly regenerate the tutorial unchanged from head? I didn't see any explicit instructions and ran into a snag.

Once I've figured this out, I plan on writing the complete instructions in the readme and submitting a pull request for it if you don't mind.

My progress so far:

Cloned daux, made a branch at 'd45ccff', and was able to seamlessly apply your daux patch
Installed php, composer, and setup vendor/ in daux
Able to regenerate the daux documentation to test the install
Rebuilt daux.phar to incorporate your patch
Attempted to run daux.phar on the tutorial and I get an error

# Within the cloned VulkanTutorial directory
> php ..\daux.io\daux.phar -c config.json -s . -d out
PHP Notice:  Uninitialized string offset: 0 in phar://E:/Development/daux.io/daux.phar/libs/Tree/Directory.php on line 32
PHP Notice:  Uninitialized string offset: 0 in phar://E:/Development/daux.io/daux.phar/libs/Tree/Directory.php on line 43
PHP Notice:  Uninitialized string offset: 0 in phar://E:/Development/daux.io/daux.phar/libs/Tree/Directory.php on line 32
PHP Notice:  Uninitialized string offset: 0 in phar://E:/Development/daux.io/daux.phar/libs/Tree/Directory.php on line 43
Copying Static assets ...                                                                                                                            [  OK  ]
Generating ...
- Introduction.html                                                                                                                                  [  OK  ]
- Overview.html                                                                                                                                      [  OK  ]
- Development_environment.html                                                                                                                       [ FAIL ]

  [Todaymade\Daux\Exception]
  Could not locate file 'Drawing_a_triangle'

It errors while it's trying to find the internal page reference for the Drawing_a_triangle markdown link within the development environment chapter. In adding debugging print lines to daux, I see that it's finding the subdirectories as doc content, and when a markdown link points to a specific page it finds it OK. But when a markdown link points at the directory, it errors.

Am I invoking daux wrong?

Here's the daux run with some extra echo'ing showing that it found the directory content and what's going on when resolving a link like [the real adventure](!Drawing_a_triangle)

> php ..\daux.io\generate -s . -d out -f html
Found content file: .\00_Introduction.md
Found content file: .\01_Overview.md
Found content file: .\02_Development_environment.md
Found content file: .\03_Drawing_a_triangle\00_Setup\00_Base_code.md
Found content file: .\03_Drawing_a_triangle\00_Setup\01_Instance.md
Found content file: .\03_Drawing_a_triangle\00_Setup\02_Validation_layers.md
Found content file: .\03_Drawing_a_triangle\00_Setup\03_Physical_devices_and_queue_families.md
Found content file: .\03_Drawing_a_triangle\00_Setup\04_Logical_device_and_queues.md
Found content file: .\03_Drawing_a_triangle\01_Presentation\00_Window_surface.md
Found content file: .\03_Drawing_a_triangle\01_Presentation\01_Swap_chain.md
Found content file: .\03_Drawing_a_triangle\01_Presentation\02_Image_views.md
Found content file: .\03_Drawing_a_triangle\02_Graphics_pipeline_basics\00_Introduction.md
Found content file: .\03_Drawing_a_triangle\02_Graphics_pipeline_basics\01_Shader_modules.md
Found content file: .\03_Drawing_a_triangle\02_Graphics_pipeline_basics\02_Fixed_functions.md
Found content file: .\03_Drawing_a_triangle\02_Graphics_pipeline_basics\03_Render_passes.md
Found content file: .\03_Drawing_a_triangle\02_Graphics_pipeline_basics\04_Conclusion.md
Found content file: .\03_Drawing_a_triangle\03_Drawing\00_Framebuffers.md
Found content file: .\03_Drawing_a_triangle\03_Drawing\01_Command_buffers.md
Found content file: .\03_Drawing_a_triangle\03_Drawing\02_Rendering_and_presentation.md
Found content file: .\03_Drawing_a_triangle\04_Swap_chain_recreation.md
Found content file: .\04_Vertex_buffers\00_Vertex_input_description.md
Found content file: .\04_Vertex_buffers\01_Vertex_buffer_creation.md
Found content file: .\04_Vertex_buffers\02_Staging_buffer.md
Found content file: .\04_Vertex_buffers\03_Index_buffer.md
Found content file: .\05_Uniform_buffers\00_Descriptor_layout_and_buffer.md
Found content file: .\05_Uniform_buffers\01_Descriptor_pool_and_sets.md
Found content file: .\06_Texture_mapping\00_Images.md
Found content file: .\06_Texture_mapping\01_Image_view_and_sampler.md
Found content file: .\06_Texture_mapping\02_Combined_image_sampler.md
Found content file: .\07_Depth_buffering.md
Found content file: .\08_Loading_models.md
PHP Notice:  Uninitialized string offset: 0 in E:\Development\daux.io\libs\Tree\Directory.php on line 32
PHP Notice:  Uninitialized string offset: 0 in E:\Development\daux.io\libs\Tree\Directory.php on line 43
PHP Notice:  Uninitialized string offset: 0 in E:\Development\daux.io\libs\Tree\Directory.php on line 32
PHP Notice:  Uninitialized string offset: 0 in E:\Development\daux.io\libs\Tree\Directory.php on line 43
Copying Static assets ...                                                                                                                            [  OK  ]
Generating ...
- Introduction.html[Searching for: Overview]
[... not found]
[Searching for: Overview.html]
[... found]
                                                                                                                                  [  OK  ]
- Overview.html[Searching for: Development_environment]
[... not found]
[Searching for: Development_environment.html]
[... found]
                                                                                                                                      [  OK  ]
- Development_environment.html[Searching for: Introduction]
[... not found]
[Searching for: Introduction.html]
[... found]
[Searching for: Drawing_a_triangle/Graphics_pipeline_basics/Shader_modules]
[... not found]
[Searching for: Drawing_a_triangle/Graphics_pipeline_basics/Shader_modules.html]
[... found]
[Searching for: Drawing_a_triangle]
[... not found]
[Searching for: Drawing_a_triangle.html]
[... not found]
                                                                                                                       [ FAIL ]

  [Todaymade\Daux\Exception]
  Could not locate file 'Drawing_a_triangle'

tthelin commented 7 years ago

Here's what I have for the daux instructions so far, based on what I did https://github.com/Overv/VulkanTutorial/compare/master...tthelin:daux-instructions

Overv commented 7 years ago

Ah, I don't use the static generation feature of daux. I have it generate the pages live through the index.php file.

tthelin commented 7 years ago

Alright I got live-serving to work, and in looking at the Daux internals it appears that file resolution behaves slightly differently between live mode and static generation.

It seems odd to leave static generation mode broken. Would you be OK if I tweaked the links that don't work in static mode and sent a pull request just for that?
Would you mind if I submitted a separate pull request for instructions on how to use daux for the tutorial for both live and static mode (since it could help any future contributors make sure things work before doing the pull request)?

Overv commented 7 years ago

Sure, if you can have it work that way without affecting the live mode too much.
Yes, that would be a great idea.

tthelin commented 7 years ago

Update: Haven't forgotten about this, but I'm in crunch mode at work and will continue to be for the next month. I don't expect to make any headway during that time.

tthelin commented 7 years ago

Update: I hope to get back to this in about a month.

Overv commented 6 years ago

Any status updates on this?

tthelin commented 6 years ago

Not really; work is keeping me much busier than I anticipated, so I have a lack of free time at the moment. My best guess at an ETA of when I'll start being able to work on this again is sometime October.

tthelin commented 6 years ago

Alright I'm starting up again. I have everything synced; my next step is incorporating any changes you made to what I've already ported to Java.

Overv commented 6 years ago

Is this still happening?

Overv / VulkanTutorial

Proposal: Expand tutorial to cover using Vulkan with Java #37