Samples naming vs Samples Browser

Hi,

I noticed an issue with some examples in the samples browser. First, I give you some information about the way the sample browser works (which could be placed inside a wiki page, so that it is not lost). The real issue will come in the next comment.

In order for the samples browser to display nice legends and code like this,

Some simple rules must be followed:

Rule # 1 : File naming

The name that is stored inside _ISamplesIndex::_samples should be the name of the class, with no variation
The name of the .cpp and .h files should the snake_cased_name_of_the_class

For example, inside src/Samples/src/samples/loaders/gltf/_loaders_gltf_samples_index.cpp one should write:

  // Animated Morph Cube Scene (glTF)
  _samples["AnimatedMorphCubeGLTFScene"] = [](ICanvas* iCanvas) {
    return std::make_unique<AnimatedMorphCubeGLTFScene>(iCanvas);
  };

Rule # 2: Documentation in the samples headers

If the header file (in the near future, it could also be the .cpp file) contains a comment block with @see and @brief sections, they will be included automatically in the samples browser.

It is important to almost always add them, with a link to the example on the BabylonJs playground (when applicable), and a link to the doc (if applicable).

In the case of @see links, there should not be a \nbetween the @see tag and the link.

/**
 * @brief Alpha Blend Mode Test Scene (glTF). Tests alpha modes and settings.
 * @see https://doc.babylonjs.com/how_to/load_from_any_file_type
 * @see https://github.com/KhronosGroup/glTF-Sample-Models/tree/master/2.0/AlphaBlendModeTest
 */

Details about the inner working of the samples browser:

The file build\build\bin\samples_info.json contains all the information for each sample.

Example:

    {
        "header_file": "F:\\dvp\\OpenSource\\BabylonCpp/src/Samples/include/babylon/samples\\animations/animated_morph_target_scene.h",
        "source_file": "F:\\dvp\\OpenSource\\BabylonCpp/src/Samples/src/samples\\animations/animated_morph_target_scene.cpp",
        "sample_name": "animatedmorphtargetscene",
        "brief": "Animated Morph Target Scene. Example demonstrating how to morph a mesh between multiple targets.",
        "links": [
            "https://www.babylonjs-playground.com/#HPV2TZ#8",
            "https://doc.babylonjs.com/how_to/how_to_use_morphtargets"
        ]
    },
    {
        "header_file": "F:\\dvp\\OpenSource\\BabylonCpp/src/Samples/include/babylon/samples\\animations/animations_101_scene.h",
        "source_file": "F:\\dvp\\OpenSource\\BabylonCpp/src/Samples/src/samples\\animations/animations_101_scene.cpp",
        "sample_name": "animations101scene",
        "brief": "Animations 101 scene. Example demonstrating how to add animations.",
        "links": [
            "https://www.babylonjs-playground.com/#QYFDDP#1",
            "https://doc.babylonjs.com/babylon101/animations"
        ]
    },
    {
        "header_file": "F:\\dvp\\OpenSource\\BabylonCpp/src/Samples/include/babylon/samples\\animations/animations_scene.h",
        "source_file": "F:\\dvp\\OpenSource\\BabylonCpp/src/Samples/src/samples\\animations/animations_scene.cpp",
        "sample_name": "animationsscene",
        "brief": "Animations scene. Example demonstrating how to add animations.",
        "links": [
            "https://doc.babylonjs.com/babylon101/animations"
        ]
    },

This file is generated by the python script src\Samples\make_samples_info\make_samples_info.py which is called at each build by src\Samples\CMakeLists.txt:

add_custom_command(
    TARGET Samples
    PRE_BUILD
    COMMAND ${PYTHON_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/make_samples_info/make_samples_info.py
    COMMENT "make_samples_info"
    WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/build/bin
)

I noticed some issues with the Samples Browser for the GLTF examples.

Issue 1: the view codebutton fails, because the file names and the sample names are inconsistent (for example, the sample name is AnimatedMorphCubeGLTFScene although the class name is AnimatedMorphCubeScene)

Example

  _samples["AnimatedMorphCubeGLTFScene"] = [](ICanvas* iCanvas) {
    return std::make_unique<AnimatedMorphCubeScene>(iCanvas);
  };

Issue 2: some @see links are cut by a \n and they are not displayed

For example:

/**
 * @brief Animated Morph Cube Scene (glTF). The cube contains two morph targets
 * in it:
 * * thin : moves the vertices so that it becomes super-thin
 * * angle : moves the vertices so that it forms a ramp
 * The animation loops, morphing between these two states.
 * @see https://doc.babylonjs.com/how_to/load_from_any_file_type
 * @see
 * https://github.com/KhronosGroup/glTF-Sample-Models/tree/master/2.0/AnimatedMorphCube
 */
struct AnimatedMorphCubeScene : public IRenderableScene {

Could you have a look at this?

PS 1: I tried the GLTF samples under windows, they still give an empty rendering.
PS 2: BabylonCpp was starred by the creator of ImGui (ocornut). This is a good news!

Hello Pascal,

Thanks for the detailed explanation on how the _samplesinfo.json file is created. Now I understand the weird issues with the Samples Browser for the GLTF examples.

Thanks to your last PR containing the headerless samples support macro and the the clang change to have a column with of 100 I could update the babylon and gltf examples to match the requirements you mentioned above.

glTFExamples

It is a good suggestion to create a wiki page about this. I will create one with this information and then close this issue report.

About the glTF support, I am currently updating the glTFLoader code to the latest version, this should be finished tomorrow. This weekend I planned to debug the glTF examples on Windows to have the almost 40 examples glTF working by the end of the weekend. The screenshots can then also be uploaded.

Since we posted the screenshots, a lot of people starred the project (including the creator of ImGui (ocornut) like you mentioned), some people forked the project too. This is really good news! The project is now in much better shape compared to 6 months ago, thanks to your help (with all the work you did on the Windows support, GUI changes, rendering to framebuffers, resolving many code issues, code improvements etc.) and it is becoming stable enough to be used by more people :)

Cheers! Sam

Hello,

this issue should now be resolved by running the script that made the examples headerless and repaired the headings.

I create the following wiki page with the information as mentioned above.

Cheers! Sam

samdauwe / BabylonCpp