Ab4d.SharpEngine.Samples.Web

Welcome to the Browser samples for Ab4d.SharpEngine.

Ab4d.SharpEngine is a cross-platform 3D rendering engine for desktop, mobile and browser .Net applications.

To check the Ab4d.SharpEngine for desktop and mobile devices, see the Ab4d.SharpEngine.Samples on GitHub.

Important

Ab4d.SharpEngine for browser (Ab4d.SharpEngine.Web assembly) is in beta and is not yet ready for production (the current version will expire on 2025-12-31).

Quick start guide

To start this samples project, open Ab4d.SharpEngine.Samples.BlazorWebAssembly solution or project in any .Net IDE and start it.

You can also start it from CLI by executing dotnet run . or similar command in the Ab4d.SharpEngine.Samples.BlazorWebAssembly folder.

Check a working version of the sample.

Usage in your own project

To use the Ab4d.SharpEngine.Web library in your own project, follow these steps:

• Create a new "Blazor WebAssembly Standalone App" project (use .Net 9 or newer).
• Add reference to Ab4d.SharpEngine.Web NuGet package.
• Copy the following files from this samples project to your project:
  • CanvasInterop.cs (copy to the root folder of your project)
  • SharpEngineSceneView.razor (copy to the root folder of your project)
  • wwwroot/sharp-engine.js (copy to the wwwroot folder)
  • Native/libEGL.c (create a new Native folder in your project and copy the libEGL.c file there)
• Open the csproj file of your project and add the following:
  • Into the first PropertyGroup:

    <!-- unsafe code is required to use JSExport in CanvasInterop -->
    <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
    
    <!-- The following emscripten flags are required for Ab4d.SharpEngine to use WebGL from the browser -->
    <EmccFlags>-lGL -s FULL_ES3=1 -sMAX_WEBGL_VERSION=2</EmccFlags>
    
    <!-- Blazor WebAssembly supports SIMD instructions (when supported by the browser), so it is recommended to enable that -->
    <WasmEnableSIMD>true</WasmEnableSIMD>
    

  • Optionally, you can set additional properties for the DEBUG and RELEASE builds. See the csproj file in this sample for example PropertyGroup blocks.
  • Add the following two ItemGroups to the csproj file:

    <ItemGroup>
      <!--The following NativeFileReference is required for Ab4d.SharpEngine.Web to use WebGL from the browser -->
      <NativeFileReference Include="Native/libEGL.c" ScanForPInvokes="true" />
    </ItemGroup>
    
    <ItemGroup>
      <!--The following javascript file is required for CanvasInterop class to be able to communicate with the browser -->
      <WasmExtraFilesToDeploy Include="sharp-engine.js" />
    </ItemGroup>      
    

• Open the razor page that will host the 3D scene (for example Home.razor) and add the following:

  • Add using declarations to the start of the razor file:

    @using System.Numerics
    @using Ab4d.SharpEngine.Cameras
    @using Ab4d.SharpEngine.Common
    @using Ab4d.SharpEngine.Materials
    @using Ab4d.SharpEngine.SceneNodes
    @using Ab4d.SharpEngine.Browser
    

  • Add SharpEngineSceneView to your razor file. For example, add the following to Home.razor (before the "@code"):

    <SharpEngineSceneView @ref="sharpEngineSceneView" style="width: 50%; height: 400px; margin-top: 10pt; border: solid black 1px"></SharpEngineSceneView>
    

  • Override the OnAfterRender method and create the 3D scene there. For example:

    @code {
        private SharpEngineSceneView sharpEngineSceneView = null!;
    
        /// <inheritdoc />
        protected override void OnAfterRender(bool firstRender)
        {
            if (firstRender)
                CreateScene3D();
        }
    
        private void CreateScene3D()
        {
            var scene = sharpEngineSceneView.Scene;
            var sceneView = sharpEngineSceneView.SceneView;
    
            var boxModelNode = new BoxModelNode(centerPosition: new Vector3(0, 0, 0), size: new Vector3(100, 40, 80), material: StandardMaterials.Green);
            scene.RootNode.Add(boxModelNode);
    
            sceneView.BackgroundColor = Colors.SkyBlue;
    
            sceneView.Camera = new TargetPositionCamera()
            {
                Heading = 30,
                Attitude = -20,
                Distance = 300
            };
    
            var pointerCameraController = new PointerCameraController(sceneView)
            {
                RotateCameraConditions = PointerAndKeyboardConditions.LeftPointerButtonPressed,
                MoveCameraConditions = PointerAndKeyboardConditions.LeftPointerButtonPressed | PointerAndKeyboardConditions.ControlKey,
                ZoomMode = CameraZoomMode.PointerPosition,
                RotateAroundPointerPosition = true,
                IsPinchZoomEnabled = true, // zoom with touch pinch gesture
                IsPinchMoveEnabled = true  // move camera with two fingers
            };
        }
    }
    

  • Instead of using the SharpEngineSceneView component, you can also create the canvas DOM element and then manually connect to the canvas. After that you can create the WebGLDevice, Scene and SceneView objects. See the "ManualInitialization.razor" file on how to do that.

Additional samples and documentation

This version of the samples project only demonstrates how to initialize the SharpEngine for the Blazor app. It creates a simple 3D scene and demonstrates how to use the camera controller and perform hit testing.

But it does not demonstrate all the features of the engine. This will be done in future versions of the project.

The Ab4d.SharpEngine.Web library is going to implement all the features of the Ab4d.SharpEngine for desktop and mobile apps. Because it uses the same code (linked files), using the implemented features is the same as with the desktop version.

Therefore, for a full demonstration of the engine, please check the samples for desktop and mobile devices (https://github.com/ab4d/Ab4d.SharpEngine.Samples) and online help (https://www.ab4d.com/help/SharpEngine/html/R_Project_Ab4d_SharpEngine.htm).

To see what features are already implemented, see the "Implementation details" below or use IntelliSense to see what classes are available.

Roadmap and Implementation details

Beta 2 version is planned for October 2025. v1.0 is planned to be released before the end of 2025.

Namespace implementation status (compared to desktop and mobile Ab4d.SharpEngine):

• Animation: 100% implemented ✔️
• Cameras: 100% implemented ✔️
• Effects:

  • StandardEffect - missing texture support (planned for beta2)

  • ThickLineEffect - LineThickness, line patterns and line caps and hidden lines are not supported.

    WebGL does not support thick lines or geometry shader so this requires a different approach (probably CPU based mesh generation). This will be supported after v1.0. Use TubeLineModelNode and TubePathModelNode with SolidColorMaterial for thick lines (here the line thickness in not in screen space values).

  • SolidColorEffect - planned for beta2

  • PixelEffect - planned for v1.0 (probably only 1x1 pixels will be supported with v1.0)

  • SpriteEffect - planned for v1.0

  • VertexColorEffect - planned for in v1.0

  • VolumeRenderingEffect - supported later

• Lights: 100% implemented ✔️
• Materials: see supported Effects
• Meshes: all supported except SubMesh (planned for v1.0)
• OverlayPanels: CameraAxisPanel planned for v1.0
• PostProcessing: planned after v1.0
• SceneNodes: all supported except: height map, instancing, MultiMaterialModelNode and PixelsNode. All planned for v1.0.
• Transformations: 100% implemented ✔️
• Utilities: implemented all except:
  • BitmapTextCreator - planned for v1.0
  • ModelMover, ModelRotator and ModelScalar - planned for v1.0
  • ObjImporter, ObjExporter, StlImporter, StlExporter - planned for v1.0
  • SpriteBatch - planned for v1.0
  • TextureLoader, TextureFactory - planned for beta2
  • VectorFontFactory, TrueTypeFontLoader - planned for v1.0

Other not implemented features:

• Transparency sorting (planned to beta2)
• Super-sampling (planned for later)

Tips and tricks

• When you publish the Blazor app to a subfolder on your web site, change the base href value in the wwwroot/index.html from "/" (used when the Blazor app is in the root folder) to your actual folder, for example to "https://www.ab4d.com/sharp-engine-browser-demo/".

Troubleshooting

In case of problems, please check the Console in the browser's DevTools (F12). Usually, error messages are displayed there.

You can enable additional logging by setting CanvasInterop.IsLoggingInteropEvents and isLogging in sharp-engine.js to true.

By default (in Ab4d.SharpEngine.Web beta version) the Log.LogLevel is set to Warn. Also, Log.IsLoggingToConsole is set to true to display the engine's log messages in the browser's Console.

Note that I am not an expert in Blazor and therefore some things may not be created optimally. Please create a PR or add a new issue if you know of any improvements.

Please report the problems or improvement ideas by creating a new Issue on GitHub. You can also use the Feedback form or Ab4d.SharpEngine Forum.