B4J Library [B4J] WebGL Library

Hi all,

after a long develop making it to work exactly as I wanted ...

... since I promised a fully functional 3D library to some users who requested it ...

... and with permission of my cat, that says: Yes I Like it, you can release it on the B4X forum

... I'm very happy today to release the B4J WebGL library.

This library fully exposes the super powerful THREEJS library (You will have to download separately).

The B4J WebGL library fully exposes:

1. WebGL 1.0
2. WebGL 2.0
3. WebGPU

renderers, fully rendered by the hardware of your graphic card.

Note that because JavaFX WebView does not exposes WebGL functionality, the 3D view cannot be
embedded on top of JavaFX, instead it is exposed over HTTP and accessible over external browser.
If some peoples know a way to integrate WebGL on JavaFX or a replacement of it, I can provide to update the library
to work on top of JavaFX, but unless this not happen the only way to work is to use external browser.

Any modern browser should support WebGL renderers, but to be sure your browsers support it, you can visit: https://webglreport.com
To get more on THREEJS library you can visit: https://threejs.org/
To get some examples on what you can develop with this library you can visit: https://threejs.org/examples/
scroll down a long list of examples and test them on your browser, these are just simple examples to show the threejs library functionalities,
they are very good point to start, on every example you can get (by clicking on the bottom-right symbol) the code to get the scene.
All these example codes will work on B4J WebGL library.

The B4J WebGL library acts as bridge to help write JavaScript code and have some useful methods to do it,
it is simple to use, but you need at least some Javascript knowledge, the more you are expert here, the more
you are able to get best results in a small time using it.

If you need something that involves 3D and is not a problem that it shows on external browser (even on remote devices)
this is probably the library for you, because of it's incredible powerful you can develop with it any sort of 3D, from simples
to very complex scenes, from realistic 3D scenes to realistic or unrealistic effects with even an addon of advanced post-processing.

With this library you can:

• Develop offline or online 3D games
• Develop realistic 3D scenes with static or animated objects
• Import any sort of 3D CAD models, without or with textures applied, without or with animations and with full control of these
• Export to many CAD models
• Import and export GLTF models and scenes, as JSON or binary files. https://en.wikipedia.org/wiki/GlTF
• Add an integrated GUI to iteract in realtime with the scene. https://github.com/georgealways/lil-gui
• Create 3D presentations
• Create 3D cartoons
• Create special effects
• Create Virtual Reality scenes and use cubic cameras
• In general develop any sort of 3D applications

WHAT'S UNDER THE HOOD

- It's cross platform. Because it uses external browser, the 3D scene is rendered on any device with any operating system, Windows, Mac, iOS, Android, probably Android TV and Android Auto, Linux, including all Single Board Computers such the Jetson Nano, ODROID, Raspberry PI and more... here may you have to enable the 3D driver. You only need to know if your browser support WebGL extension.
- The library do not only manage 3D renderings, but is even able to manage 3D spatial audio.
- The library offers more than one physical 3D engine, support collisions, cloth simulator and more.
- The library has more controls and camera views, orbit mouse control, first person, fly control and more, and with my addon class I wrote (a bit experimental, I will release next), it support up 4 gamepads fully recognized by the browser using the Gamepad Web API. For advanced users who use microcontrollers such ESP32, if interested I will explain in another detailed post how to use ESP32 as a BLE Gamepad and/or Mouse and/or Keyboard, regularly known by every operating system and browser and thus being able to create custom (and wireless) controls capable of controlling anything inside threejs and in general inside JS code.
- The threejs library already have a lots of classes to help you to do anything, but even can be expanded by creating more custom classes and/or integrate any JS code or library.
- The library have some useful methods to transform JS arrays to B4X List and viceversa and to transform JS objects to B4X maps and viceversa.
- The library have a Console command to output on JS console and Alert command to show JS alert boxes.
- If you encounter some issues during development you can ask to Mentor ChatGPT that is expert on THREEJS, or just join to Discord or StackOverflow officials threejs forums. You can find more infos on threejs site.
- The web is full of threejs tutorials, even there are online developer tools where you can write threejs code and see the final results. One of most popular is codepen. All these codes will work on B4J WebGL library.
- The web is full of sites where you can find free or paid detailed 3D models, without or with textures, without or with animations. One of most popular is sketchfab.
- Come with a full and advanced debugger, just press F12 to show your browser Developer Console, here you can debug your JS code, put breakpoints advance line by line, view a full HTML code, view any resource file used and track any HTTP request. You can refer to Developer Console documentation of your browser to get more infos.
- More secure. All is managed internally using XmlHttpRequests and modern techniques where the security is at top level.

How to use WebGL library (Step by step)

1. Download the attached jWebGL.zip file
2. Extract jWebGL.jar and jWebGL.xml files to your Additional Libraries folder
3. You will have to put the THREEJS library in a place where the system have permissions to read and write, the best place on any system is DirData. To know where DirData points on your system you can use:
   Log(File.DirData("B4XWebGL"))
   where B4XWebGL is not mandatory, but it is just to mantain compatibility with my example demos distribuited with this library. You can change it's name but then you need to change it on all example demos and on all your projects. I advise you to leave this name unchanged. This line show me on the log the follow on Windows 11: C:\Users\MyUserName\AppData\Roaming\B4XWebGL. Finally go to this position (eg. C:\Users\MyUserName\AppData\Roaming\ in my case) create a new folder and call it B4XWebGL
4. Go to THREEJS github page and download the distribution zip file. Note that I have tested it on version r164, but because it's community is very active, it will continue to evolve, improve, fix small bugs etc... You can just download the latest version (at moment I wrote this, the r171) or search old versions on the history. Searching very old versions (like r120-r130) helped on old devices that not fully support WebGL, but break some compatibility with new code. Here the github page where you can download the latest library version: https://github.com/mrdoob/three.js
5. After you download the zip file named three.js-dev.zip, open it, you will find a three.js-dev folder inside, double click and open it
6. Select all files and folders of threejs distibution, you will have to copy/paste inside the already created B4XWebGL folder
7. Done setup complete !!! At this point you are able to use B4J WebGL library
8. Extract the Demos.zip examples in a place where you have your projects. Open the B4J IDE, open the first demo project example called jWebGL_Demo1
9. Compile it, you will end up with a small form with a button, press it to start the process
10. After you compiled and executed it, if all it's ok, you will see some infos in the log, and at the end of log you will see 2 lines in magenta color, one to access the created scene, and one to get the library main page
11. For now just copy from the log the line to view the library main page, paste it on your browser of development machine (or other devices in local network) here you will see the library main page and some useful infos and links you can view. You have even a link with files in the threejs distribution you placed inside B4XWebGL folder, examples, textures and more. They are all served over HTTP, you can access them from browser .... you can even test all threejs demos inside the /examples folder, they are the same that threejs site examples, but they are offline now, all served over HTTP on your local network
12. OK now it's time to show our 3D scene created in the jWebGL_Demo1 project, copy from the log the magenta line to show the scene, paste it on your browser and if all it's ok, you will end up to see a brown cube at center of the screen with textures applied
13. You can use mouse LEFT button to rotate it, RIGHT button to translate, MIDDLE button (or wheel) to zoom
14. Compliments !!! This is your first 3D scene with WebGL library !!!

The five demo projects I've provided are just simple demos, but disposed as small tutorial to start manage this, largely commented to explain a bit how you can start with WebGL library.

So now you can test all demos one by one, all works the same manner as previousely explained. Just remember to terminate the current project before you start others
(because in these demo projects I used the same HTTP port for all projects) or the server will be unable to bind and serve the new scene because the port is already open and used by another process. Note that you can use more concurrent projects open in the browser at same time, just use a differtent HTTP port for any project.

These demo projects are pretty simples, they are just to show you a starting point, but absolutely you cannot see the library power from here.
From demo 4 you will start to see and know that if you want to make something complex, this library permits to do it, so probably you will
end up to know that actually you cannot do it other ways that using this library.

The space for upload is even limited so I cannot post demos with complex scenes where I use animated detailed 3D models with textures, mipmapping and more ...
I promise I will write some other posts where I release some more complex demo scenes, with animated models, and with starting points to create some FPS and Flying games.
Probably I will put external links where you have to download additional resources like models and textures.

You will noticed that every time you access files over HTTP, the B4J WebGL library offer you a way to get the server logs for any request file, they are passed as string to the _ServerLog Event, you can use them to show them where you want, in a TextArea, collect all logs to a ListView and more.... in the demo projects we just show them in the log with different color based on the HTTP Response code that the message contains .... 202, 304, 404.

A big thank you to @Erel that sent me the latest version of B4J Server, that offers the possibility to get server logs without ciclically open every 10 seconds the server log file and get here if there are modifications.... it works really well. It even permits to set the correct log timestamp you can pass as GMT string.

Note that every time you request an HTML file, you will see the server log for that file and for any file that HTML or JS code request, so class imports, textures, models, sounds, videos and more. The log help you to know what file a project request, if file is found ecc.... Note that in the demos the log is even accessible if you compile the app and launch it from terminal, just they are single color.

After you tested some or all threejs provided examples, may you want a clean development system ....
To do this, open the B4XWebGL library where the threejs distribution is placed, here you can remove unused files, just used for examples.
You can remove some files but please do not change (or delete) the default folder structure.
Files you can remove are in /examples folder, open the /textures folder, here you can delete all folders and files inside or just what you don't plain to use in your projects,
at same way, open the /models folder, here you have a lots of models that consume a lots of space, another time you can remove all folders and files or just what you do not plain to use.
You can do the same with /sounds folder.
In the /fonts folder you can add more fonts and/or delete the existing if you plain to not use them.
You can even remove all html files examples that consume more space and even remove the /screenshots folder that contains the screenshots for examples.

Do not delete the /textures, /models and /sounds folders, here you need to put your personal textures, models and audio data to use in your projects.

After this you will have a clean development tool. You can put manually your personal textures, models and sounds you plain to use on one or more projects.
It is best practice to create subfolders where place all files divided by type, eg. in /textures create a folder /grass with all grass textures, /patterns with all patterns textures, /woods with all wood textures and so on ... This will help you when you use these files and open them in your projects.

You can even put files in your assets and copy them to the right position by code, to do this you can refer to ProjectFolder, it refer to the library folder (/examples), here an example code:

   Dim Separator As String = GetSystemProperty("file.separator","")
   Dim FilePath As String = $"textures${Separator}crate.gif"$
    If File.Exists(gl.ProjectFolder, FilePath) = False Then
        Wait For (File.CopyAsync(File.DirAssets, "crate.gif", gl.ProjectFolder, FilePath)) Complete (Success As Boolean)
        Log("crate.gif copy from assets. Success: " & Success & "   " & File.Combine(gl.ProjectFolder, FilePath))
        If Not (Success) Then
            LogError("You should place crate.gif in DirAsset")
            ExitApplication
        End If
    Else
        Log("crate.gif texture already exist: " & File.Combine(gl.ProjectFolder, FilePath))
    End If

An useful thing is to know how to use Blender (free), Freecad (free), or any other free or paid CAD to create customized objects and scenes, export them and then
import into your scene created with this library.

I'm happy to inform you, that I'm under development for the same library on B4A. Here because Android WebView fully support WebGL extensions, the library
is more powerful because it permits to integrate WebGL view inside our app (windowed or fullscreen, and even resizable with 3D rendering update) without use
of external browser. This even expand a lots the possibilities, because after a page with rendering is loaded, we cannot only change some things from JS
side, but we can even change anything from Android side on B4A, eg move a SeekBar and change something in the 3D scene .... and this is awesome a absolutely
powerful, eg. you can use Timers to change something in the scene.

I inform you in advance that, since developing the B4A WebGL library (more...more complex than this B4J WebGL)
required me more than 600 hours, so I decided that it will be only available under donation.

Important note: To please my cat, I had to download some 3D fish models and display them animated on my 24 inch screen, after that my cat (who is the owner of my house) got up and approached the monitor, then gave me permission to release this library... I probably would never have released it without downloading the fish models and animating them on my screen, and without permission of my cat .... so many thanks to my cat and 3D fish models ...

That's all ...

If you create something with this library (not commercial), don't forget to share the code on this forum, so other users can get your scene and study your code.
If you create something functional (commercial or not) please put in the About of your app a link to this thread.

Enjoy with Real 3D.

 

[roncoa]

Great job Max. Your work shows all your passion and knowledge. Well done.

 

[Jmu5667]

When I run demo1 I get this:

Initializing WebGL Library ...
Starting 3D engine ...
[11:18:22] Threejs library folder (jsm) do not exists C:\Users\jmurp\AppData\Roaming\B4XWebGL\jsm
[11:18:22] ERROR: Threejs library do not exist on C:\Users\jmurp\AppData\Roaming\B4XWebGL
Unable to initialize WebGL Library

 

[max123]

@Jmu5667 probably you extracted it wrong ?

When you open the threejs zip file, you will find a folder inside, you don't have to extract that folder,
instead you have to open that folder and extract all it's content, as I wrote on step 5 and 6.

To avoid confusion, now I marked double click and open it in bold on step 5.

Please do a try, if you need support I'm here.

To other users, please confirm this work for you ... Thanks

I attached the screenshot that show my B4XWebGL folder with extracted content.