Samples browser

Adding a new sample

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
)