Hi! Thanks for all the great work up to providing an onboarding document for newcomers.

I've just followed https://ncine.github.io/build-windows/ using CMake v3.21.3 for VS2019 on x64 architecture and stumbled a few times (bottom line, I've went for BFU approach to see if it could stand it).

Performing the step "Build the dependency libraries" -- when generated nCine-libraries solution, it did not build project_glew out of the box with the following CMake error CUSTOMBUILD : CMake error : No platform specified for -a -- my workaround: I've edit nCine-libraries/cmake/gewl.cmake and slipped in the line set(CMAKE_GENERATOR_PLATFORM x64) after line 3 -- then it built ok (for me, since I've fixed the platform)

Performing the step "Build the nCine library" -- nCine requires "nCine-data" directory, but when you're downloading things from github master, the folder is named "nCine-data-master" -- I would recommend to explicitelly show the required directory layout when starting building nCine at the beginning of the walkthrough -- also, default CMAKE_INSTALL_PREFIX is pointing to Program files, which is protected by default, I would recommend explicitelly tell the user to change this value in CMake to points outside Program files -- walkthrough is not mentioning installing the nCine, i.e., after I open generated nCine.sln and build it, I need to manually invoke the build of INSTALL project in order to gen "nCine directory"

Performing the step "Build example ncPong" -- here CMake configuration expects NCINE_DIR environment variable to exist and point to nCine build; this is not mentioned by the walkthrough at all -- then again, it expects "ncPong-data" directory but user downloads "ncPong-data-master" from GitHub

After above patches, it built ok and run flawlessly, which is good job done at your side!

Info

• Hardware: Raspberry Pi 4B
• Platform: GNU/Linux
• Architecture: aarch64
• nCine release: master commit 1b7de7d

Description

Currently building the nCine with the test app forces the use of the OpenGL 3.3, even if the device doesn't fully support it, but it works with OpenGL ES 3.0. The built itself will finish successfully, but the test application won't work, when trying it on the device supporting OpenGL >3.3 or doesn't supporting it at all, which is the case for most ARM devices.

Expectations:

The test apps will run using the GLES 3.0 backend on the ARM devices working under Linux distributions.

Results:

- HH:MM:SS  [L6] - void ncine::SdlGfxDevice::initDevice() -> SDL_GL_CreateContext failed: Could not create GL context: GLXBadFBConfig

(anonymised time)

Currently known workarounds:

• Use MESA_GL_VERSION_OVERRIDE=3.3 to force the use of the OpenGL 3.3, even if it isn't supported by hardware (may fail if hardware/software supports GLES API only).
  • NOTE: This workaround works fine with the Raspberry Pi 4B device.

If I weren't a game creator, it would take me time to find all the packages. But what if you try to add a package manager for faster build, for example, conan?

I'm working on some changes in resource loading in order to support a typical GUI tool workflow, think of an editor. :wink:

You should be able to load a resource, say a texture, from a file, then assign it to a bunch of sprites and then change the texture by loading a second file and have all your sprites automatically update.

Recently I have committed some changes to enhance the fault tolerance of loading a resource by providing an optional class that wraps the data being loaded and that can be queried to see if the process has been successful.

I'm thinking about changing the approach, delete the data classes and unify the reload and the fault tolerance API.

This way you will be able to create an empty texture and load it with data at a later time. You will be able to load data from texels in memory (making it possible to have CPU procedural generated textures), or from a file. You will be able to load a new file to the same texture and if the loading process fails the texture will be left unchanged.

I should also create a new apptest_loading that shows how to load resources (from file, from a memory file, from a memory buffer) and how to reload them.

The feature branch

• new_loading -> The branch has been merged to master

As a starting point I suggest you have a look at the new apptest_loading.

TO-DO

• [x] Add an empty Texture::Texture() constructor that only creates the OpenGL texture name (glGenTextures)
• [x] Add an empty Font::Font() constructor and check AudioBuffer::AudioBuffer()
• [x] In apptest_loading test changing a texture and an audio buffer format by assigning a new object
• [X] In apptest_loading add a section to load sounds and fonts from memory and file
• [x] In apptest_loading check the fault tolerance by trying loading non existing files or files and memory buffers with random data
• [x] Check how feasible is to reload in the case of AudioStream (and add AudioStream::AudioStream())
• [x] Study how to integrate OpenAL AL_*_OFFSET source properties for sound buffer or stream seeking
• [x] Update apptest_audio to use the new ncine-data/sounds files (and add the display of audio offsets)
• [x] Remove any FATAL_ASSERT while loading or creating resources
• [X] Rewrite the Texture/Audio/FontData commit to split some changes from the new_loading one
• [x] Before merging or rebasing run clang-format, write the master branch changelog and add apptest_loading to the web-tests

I follow the Build for Android, after building the dependency libraries, I try to build the nCine library , and I got error:

I thought maybe I need to build the solution just like generating nCine-external. I open Visual Studio 2019 and build the solution, but I got error:

Performing configure step for 'project_ogg'
. \configure' is not recognized as an internal or external command

I am very interesing at this game engine. Did I misunderstand something or doing something wrong？

The main rationale behind supporting viewports is the possibility of having off-screen render targets, a feature that can be used together with custom shaders (#2) to allow for post-processing effects like bloom, depth of field or normal mapping illumination.

An off-screen render target might also be used to scale the game output to a custom resolution that is different than the screen one (it could be a workaround for Android fixed resolution, for example).

The viewport will also allow the use of a dedicated camera class that should alleviate the need for a dummy node to simulate camera transformations like in the current version of apptest_camera. The camera class will use uniform variables to send data to nodes: projection and view matrices will be multiplied inside the vertex shader.

By also adding a "dirty flag" for scene node transformations it will be possible to move nodes with the camera without recalculating their scenegraph transformations, thus saving a lot of precious CPU time. Screen culling code should also be updated to work with viewports and cameras.

TO-DO

• [x] Move clear color and OpenGL viewport methods of the IGfxDevice class in the Viewport one
  • [x] Fix compilation of external projects (ncParticleEditor, ncJugiMapGuiDemo, etc...)
  • [x] Use the new camera in the ncTiledViewer project
• [x] Have viewports with a camera but no texture, in order to add more transformation flexibility
  • [x] Add the option to use a texture-less viewport with a camera class in apptest_camera
• [x] Fix screen culling within a viewport (maybe with some form of spatial hashing?)
• [x] Add dirty flags to avoid unneeded scene node transformations and AABB box recalculations
• [x] Replicate the new class and methods in the Lua API

References

Godot

• Camera class (Godot reference)
• Viewport class (Godot reference)
• Using Viewports (Godot tutorial)
• Custom post-processing (Godot tutorial)

Ogre

• Viewport class (Ogre reference)
• RenderTarget class (Ogre reference)
• Multiple and Dual SceneManagers (Ogre tutorial)
• Render to Texture (Ogre tutorial)

Other

• Choosing the resolution of your 2D art assets (Unity article)
• Post-Processing Effects in Cocos2d-x
• Architecture of Lugdunum
• Fast Extraction of Viewing Frustum Planes from the WorldView-Projection Matrix (PDF)

• [x] macOS: The dynamic linker cannot find the dependency libraries when those are built by the C.I. This issue has been fixed on 28/01/2022 with an update to nCine-libraries.
• [x] Windows: DevDist workflows fail because Doxygen cannot run dot to create graphs
  • CUSTOMBUILD : error : Problems running dot: exit code=1, command='dot'
• [x] Linux and MinGW: some tests from gtest_list_movable fail, only on GCC in Release. The issue disappears when compiling List.h with #pragma GCC optimize ("O2") instead of O3. On 29/01/2022 the problematic tests have been disabled when compiling on GCC in Release.
• [x] MinGW: C:\msys64\mingw64\bin/llvm-strip.exe: error: 'D:/a/nCine/nCine-build-DevDist/libncine.dll': unexpected associative section index, only with Clang. This issue still occurs but on 27/01/2022 I disabled stripping of binaries on MinGW with Clang to avoid it. I have also opened an issue to report it.

There is another important change in resource loading to order to support a GUI tool workflow: the ability to load a Lua script and being able to run it safely even if it has errors.

• [x] Modify LuaDebug::assert so that it doesn't cause any assert
• [x] Provide a way in the API to retrieve the errors in a Lua script
• [x] In apptest_loading add a section for Lua scripts and check their fault tolerance

LÖVE 2D style distribution

• [x] Add a LuaDist options preset, tested by the C.I. and uploaded in the artifacts
• [x] It should disable things like ImGui, Nuklear, threads, documentation, etc...
• [x] It should not build tests, but only apptest_lua and install it under a different name (maybe luancine)
• [x] apptest_lua should load a script.lua script and show errors with a TextNode
• [x] It should use argc and argv to be able to specify a script name on the command line

Leftovers tasks from #3

• [x] Consider making the ITextureSaver interface public for users to save textures to files
• [x] ~~Consider creating a IAudioBufferSaver interface to save audio samples~~
• [x] Consider allowing the creation of a Sprite without a Texture or a TextNode without a Font just like you can now create an AudioBufferPlayer without an AudioBuffer
  • It might be useful when object pools are needed, you would then create an array of sprites and assign textures later

This is another task I have had for some time. The objective is easy: minimize the effort I have to put into updating the CMake scripts in every project and make them fetch what they need from the engine directory.

Many times a change in the engine will require a change in project scripts. With this new way of handling the scripts a project will use whatever version the engine provides for building. I would still like to retain the option to easily copy the files in a project directory to be able to customize them.

• [x] Projects should just use a single CMakeList.txt file containing what is currently in the package_info.cmake script plus some additional code to find the engine and the rest of the scripts
• [x] Simplify ncTemplate and all other projects to refer to nCine for updated setup and compile scripts
• [x] Check if there is still any need for the devdist cmake scripts
• [x] Consider renaming every PACKAGE_ variable prefix and every package_ file name prefix to PROJECT_ and project_
  • [x] Update ncline with new variables
  • [x] Update build instructions on the site
  • [x] Update README.md of ncTemplate
  • [x] Rename PACKAGE_ and package_ variables in GitHub workflow scripts
  • [x] Rename variables in Arch Linux PKGBUILD scripts
  • [x] Open a Pull Request to rename PACKAGE_DEFAULT_DATA_DIR in JugiMap projects
• [x] Make a more flexible support for data and icons in arbitrary directories and don't fail if icons are not available, fallback to nCine icons in nCine-data if those are available
• [X] ~~Provide a .gitignore file so that copied template files can be automatically ignored in the game repository~~

Notes:

• The old project scripts were able to automatically pick nCine location when it was installed system-wide on Windows and Linux.

Those are some small bugs I have discovered recently:

• [x] Font::Font(const char *fntFilename) will not load the corresponding font bitmap texture on Android if using assets
• [X] The package_copy_targets.cmake scripts on Windows does not copy DLLs
  • Should it be changed to copy the DLLs to more places? Not only the build directory but also in the Release and Debug directories
• [X] Add a check for the Java package name to warn the user if the underscore is used
• [x] Provide meaningful defaults for the data path configuration
• [x] Use AllocConsole on Windows to open a console in Debug mode even when using WinMain
• [X] Investigate the use of CMake's MAP_IMPORTED_CONFIG_CONFIG so that, for example, a project built in Release mode can correctly link to ncine_d.lib and ncine_main_d.lib
• [x] Use ncline code to add colored logging output on all platforms

It has been a long time now since I first thought about the possibility to provide a way for users to override the default shaders.

The task has been delayed for a long time because I had other priorities and because I thought I needed to refactor (yes, again) the rendering system before trying to add this interesting but possibly complex feature.

As both Jugilus and the team behind the deadfish game recently asked for this I decided to shuffle it higher in my priority list. :wink:

Don't hesitate to comment on this issue or on our Discord server! :speech_balloon:

TO-DO

• [x] Create a class abstracting the shader state of a DrawableNode
• [x] Shader reloading and recompilation should be fault tolerant (like other resources in #3)
• [x] Should the Shader class derive from Object?
  • What are the implications of this choice? :thinking:
• [x] Provide a way for the user to decide how matrices are passed
  • Like the name of the model view matrix uniform and if it is in a named block or not
• [x] Provide a way for the user to link the semantics to an attribute name
  • "aPosition contains vertex positions"
• [x] Proper handling of shader loading and compilation errors
  • Should the application exit? Can the shader be reloaded? :thinking:
• [x] Find a way not to sacrifice batching for nodes with custom shaders
• [x] Should there be always available uniforms and attributes with default names or all data driven?
• [x] Proper testing with all drawable node types
• [x] Test on Android and Emscripten, test glapptest_fbo_cube
• [x] When loading custom shaders it should be possible to use default for certain stages
  • For example use the default Sprite vertex shader and only provide a custom fragment one
• [x] Add a corresponding Lua API for custom shaders
• [x] Before merging or rebasing: run clang-format and check compilation of all commits, write the master branch changelog, update the features section, and add apptest_shaders to the web-tests, then delete the remote branch.
• [x] Check if the rest of the projects compile with the changes from this branch (for example ncTiledViewer does not)

References

• SFML: Adding special effects with shaders
• Cocos2d-x: Shaders and Materials
• Cocos2D: How To Create Cool Effects with Custom Shaders in OpenGL ES 2.0 and Cocos2D 2.X
• AppGameKit: Shaders in AGK
• PlayCanvas: Custom Shaders
• XNA4: XNA 4 tutorial: Custom shader Effects
• 5 Simple Fragment Shaders for 2D Games (GLSL)
• Fast Gaussian Blur with Cocos2d-x
• Multi-pass technique in Ogre 3D
• https://www.gdcvault.com/play/1021762/Advanced-Visual-Effects-for-2D
• Graveyard Keeper: How the graphics effects are made

• [ ] Add support for EFX effects
• [ ] Add support for HRTF for headphones?
• [ ] Add support for opening (and maybe reopening) the OpenAL audio device with a set of parameters specified in the AppConfiguration
• [ ] Add support for switching to headphones on Windows?
• [x] Unregister a player from an audio device on destruction
• [ ] Query or request a value for MaxSources
• [ ] Log OpenAL extensions and properties like for OpenGL in GfxCapabilities
• [ ] Complete the AudioEffect, AudioEffectSlot, and AudioFilter classes
• [ ] Add Doxygen documentation to the new methods
• [ ] Add the new classes and methods to the Lua API
• [ ] Test on all platforms (including Android and Emscripten)
• [ ] Add support for effects and filters in the new ImGui interface of apptest_audio
• [ ] Stop the debug text in apptest_audio from flickering due to alignment
• [ ] Before pushing check code with clang-format and update the changelog on the site (download-master.md)

References

• OpenAL Programmer's Guide
• OpenAL effects extensions guide
• examples/alreverb.c
• examples/almultireverb.c
• examples/alhrtf.c