Samples for Ab4d.SharpEngine (cross-platform 3D rendering engine)
Welcome to the Samples for Ab4d.SharpEngine.
Ab4d.SharpEngine is a cross-platform Vulkan based 3D rendering engine for desktop and mobile .Net applications.
Vulkan is a high performance graphics and cross-platform API that is similar to DirectX 12 but can run on multiple platforms.
The following features are supported by the current version:
Windows:
Linux (including Raspberry PI 4 and similar devices):
Android:
macOS:
iOS:
Online help: Online Ab4d.SharpEngine Reference help
Ab4d.SharpEngine.glTF library use source code from glTF2Loader with PR from ZingBallyhoo (https://github.com/KhronosGroup/glTF-CSharp-Loader/pull/51). glTF2Loader library is publushed under the following MIT license:
This license is for the C# reference loader, not the rest of the repository.
Copyright (c) 2015, Matthew and Xueru McMullan All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
The following Visual Studio solutions are available:
Ab4d.SharpEngine.Samples.AvaloniaUI This sample uses Avalonia UI (https://avaloniaui.net/) that provides WPF-like object model to build UI controls and can run on Windows, Linux and macOS. This sample uses Ab4d.SharpEngine.AvaloniaUI library that provides SharpEngineSceneView control. The SharpEngineSceneView provides an Avalonia control that is very easy to use and can compose the 3D scene with the Avalonia UI objects (for example showing buttons on top of 3D scene). The sample can be started on Windows, Linux and on macOS (use a special macOS solution). See also "Building for macOS and iOS" section for more information on how to compile for macOS.
Ab4d.SharpEngine.Samples.AvaloniaUI.VulkanBackend This sample uses Avalonia UI which uses Vulkan as a backend, so the whole application is using Vulkan API (the UI controls are also rendered by Vulkan instead of DirectX or OpenGL as by default). Vulkan backend is setup in the Program.cs file. This provides the best integration of 2D UI and 3D graphics. This requires Avalonia v11.1 which is currently in release candidate version (2024-07-05). Because of this, the project is using Ab4d.SharpEngine.Samples.AvaloniaUI v2.0.8953-rc1 version. When the Avalonia version will be released, a new Ab4d.SharpEngine.Samples.AvaloniaUI library will also be released. This sample can run only on Windows.
Ab4d.SharpEngine.Samples.AvaloniaUI.CrossPlatform This sample shows how to create an Avalonia app that can run on Windows, Android and iOS. This sample uses Ab4d.SharpEngine.AvaloniaUI library that provides SharpEngineSceneView control. Because Vulkan is not natively supported on macOS and iOS, the MoltenVK library is required to translate the Vulkan calls to Molten API calls. See also "Building for macOS and iOS" section for more information on how to compile for isOS. Note that folder and file names in this solution have been shortened to prevent problems with max path size on Windows (260 chars).
Ab4d.SharpEngine.Samples.Wpf This solution provides the samples for WPF and can run only on Windows. The samples also use Ab4d.SharpEngine.Wpf library that provides SharpEngineSceneView control for WPF. The SharpEngineSceneView provides a WPF control that is very easy to use and can compose the 3D scene with the WPF objects (for example showing buttons on top of 3D scene).
Ab4d.SharpEngine.Samples.WinUI This sample uses WinUI 3.0 that provides the latest UI technology to create applications for Windows. This sample uses Ab4d.SharpEngine.WinUI library that provides SharpEngineSceneView control. The SharpEngineSceneView provides an WinUI control that is very easy to be used and can compose the 3D scene with the WinUI UI objects (for example showing buttons on top of 3D scene).
Ab4d.SharpEngine.Samples.WinForms This solution provides the samples for WinForms and can run only on Windows. The samples also use Ab4d.SharpEngine.WinForms library that provides SharpEngineSceneView Control for WinForms. The SharpEngineSceneView provides a WinForms Control that is very easy to be used and can compose the 3D scene with other UI Controls (for example showing buttons on top of 3D scene).
Ab4d.SharpEngine.Samples.CrossPlatform This sample uses third-party Silk.Net library that provides support for SDL and GLFW. SDL and GLFW are used to get platform-independent way to create windows and views. The 3D scene here is shown in the whole window area. Because of this project can work on Windows and Linux.
Ab4d.SharpEngine.Samples.Android.Generic This solution is similar to Ab4d.SharpEngine.Samples.CrossPlatform because it also uses Silk.Net library. To work on Android the code to initialize SharpEngine and define the 3D scene can be the same as for other platforms, but there needs to be some special startup code to create the Android Activity. The 3D scene here is shown on the whole view area.
Ab4d.SharpEngine.Samples.Android.Application This solution uses an Android.Application project template for .Net 6. The 3D scene is shown on the part of the view that is defined by SurfaceView.
Ab4d.SharpEngine.Samples.Maui This solution uses a NET Maui and can work on Windows, Android, macOS and iOS. Compiling for Windows, Android and macOS requires .Net 8. Because Vulkan is not natively supported on macOS and iOS, the MoltenVK library is required to translate the Vulkan calls to Molten API calls. See "Building for macOS and iOS" section for more information on how to compile for macOS and iOS.
Ab4d.SharpEngine.Samples.LinuxFramebuffer This solution uses SharpEngine with off-screen Vulkan renderer, and displays the rendered frames on Linux framebuffer display (FbDev or DRM/KMS). See the example's README for details.
The main two objects in SharpEngine are:
When using WPF, Avalonia, WinUI or WinForms, then Scene and SceneView are created by the SharpEngineSceneView control.
3D objects are defined in the SceneNodes namespace, for example BoxModelNode, SphereModelNode, LineNode, MeshModelNode, etc.
Common materials are defined by using StandardMaterial object. For each color there are predefined StandardMaterials, for example StandardMaterials.Blue.
Use ReaderObj to read 3D models from obj files. To read 3D models from other file formats, use AssimpImporter.
Ab4d.SharpEngine is built on the same concepts as the Ab3d.PowerToys and Ab3d.DXEngine libraries. So users of those two libraries should feel very familiar. But there are some main differences:
For WPF, Avalonia, WinUI and WinForms there is a special library (Ab4d.SharpEngine.Wpf, Ab4d.SharpEngine.AvaloniaUI, Ab4d.SharpEngine.WinUI, Ab4d.SharpEngine.WinForms) that defines the SharpEngineSceneView
class. This class hides the differences between those platforms under the hood and provides the same API for all platforms. The class also initializes the engine by creating the VulkanDevice
. The main two properties that SharpEngineSceneView
provides are Scene
and SceneView
. The Scene
is used to define the scene by adding the SceneNodes to the Scene.RootNode
(similar as Viewport3D.Children in WPF) and adding lights to Scene.Lights
collection. The SceneView
defines the view of the scene and provides a camera that is set to the SceneView.Camera
property. When working with SharpEngineSceneView
, then 100% of the code to show 3D graphics can be the same for WPF, Avalonia, WinUI and WinForms. Other platforms and UI frameworks require some special setup code that is different for each platform. But from there on, the code is the same regardless of the platform. See samples for more info.
Some other differences:
BoxVisual3D
, SphereVisual3D
and other objects derived from BaseVisual3D
are defined in Ab4d.SharpEngine.SceneNodes
namespace
(for example BoxVisual3D
=> BoxModelNode
; SphereVisual3D
=> SphereModelNode
).
GeometryModel3D
with custom MeshGeometry3D
from WPF 3D is now defined by MeshModelNode
and StandardMesh
(see MeshModelNodeSample.
Meshes for standard objects (box, sphere, cone, etc) can be created by using Meshes.MeshFactory
.
Cameras and lights are almost the same as in Ab3d.PowerToys. The cameras are TargetPositionCamera
, FirstPersonCamera
, FreeCamera
and MatrixCamera
with the same properties as in Ab3d.PowerToys. Also lights (DirectionalLight
, PointLight
, Spotlight
, AmbientLight
are the same as in Ab3d.PowerToys.
MouseCameraController
for WPF, Avalonia or WinUI is almost the same as in Ab3d.PowerToys.
For Android you can use AndroidCameraController
.
For other platforms you can use ManualMouseCameraController
and then call the ProcessMouseDown
, ProcessMouseUp
and ProcessMouseMove methods
- see samples.
Just as Ab3d.PowerToys, the Ab3d.SharpEngine also defines the ReaderObj
for reading 3D models from obj files. Also, to import models from other files, use the Ab4d.SharpEngine.Assimp
library (similar to Ab3d.PowerToys.Assimp
and Ab3d.DXEngine.Assimp
).
To provide cross-platform reading of texture files (2D bitmap) the Ab4d.SharpEngine uses the IBitmapIO
interface that provides the common bitmap IO operations. Then, there are platform specific implementations, for example WpfBitmapIO
, WinUIBitmapIO
, SystemDrawingBitmapIO
, SkiaSharpBitmapIO
. There is also a build-in PngBitmapIO
that can read or write png images and does not require any third-party or platform-specific implementation.
Ab4d.SharpEngine uses float
as its main value type and System.Numerics
for base math objects and functions. This means that you need to convert all double
values to float
values. Also, Point3D
and Vector3D
structs need to be converted to Vector3
.
In my opinion, if you already have a complex application that is built by using Ab3d.PowerToys and Ab3d.DXEngine and you are not required to use any other platform except Windows, then it is not worth converting that application to Ab4d.SharpEngine. But if you need to create a simpler version of the application that would also work on mobile devices, then Ab4d.SharpEngine gives you a great opportunity to port only a part of the code. Also, if you are starting to create an application that requires 3D graphics, then it is probably better to start with Ab4d.SharpEngine.
Those two libraries provide more features and come with more samples that can be used as code templates for your needs. The following is a list of major features from Ab3d.DXEngine and Ab3d.PowerToys that are missing in Ab4d.SharpEngine (v2.0; this is not the full list):
NOTE: Ab3d.PowerToys and Ab3d.DXEngine will still be actively developed, will get new releases and features and will have full support in the future!
The following changes are required to use Ab4d.SharpEngine on macOS and iOS:
.Net 8 is requried to use Ab4d.SharpEngine on iOS (because function pointers do not work with .Net 7 and previous .Net versions on iOS).
The 3D scene that is rendered by Ab4d.SharpEngine is shown by using SKCanvasView. To use that control, add a reference to SkiaSharp.Views.Maui.Controls NuGet package. The add ".UseSkiaSharp()" to the builder setup in the MauiProgram.cs file.
Add libMoltenVK.dylib from the Vulkan SDK to the projects so that the library can be loaded at runtime. Note that there are different builds for iOS and for Catalyst (the latest use the version of macOS).
To run the app in iOS, the application needs to have a provisioning profile set. One option is to follow the instructions on the following page: Create a provisioning profile. Another option is to open the project in the Rider IDE, then right-click on the project and select "Open in Xcode". Rider will create the Xcode project file and open it in Xcode. There you can click on the project file and in the "Certificates, Identifiers & Profiles" tab create an ad-hoc provisioning profile (allow having up to 3 development apps installed at the same time). See more: Create a development provisioning profile. Note that to create the provisioning profile, the ApplicationId (in csproj file) needs to be in a form of "com.companyName.appName" - this is then used as a Bundle Id.
If you get build errors on Windows (for example 'project.assets.json' not found) than maybe the total path length is larger than max path (260 chars). Move the samples solution to a folder with a shorter path and try compiling again.
The latest version of branches that start with "version/" may not compile with the latest published NuGet package and require the latest development version of the engine. If you need a feature from that branch, you can contact support to get the pre-release version.
Some Intel graphics cards may not work with shared texture in WPF's SharpEngineSceneView control (writable bitmap is used instead, but this is slower).
To enable Vulkan validation, install the Vulkan SDK from: https://vulkan.lunarg.com/ When Vulkan validation is installed and enabled by the SharpEngine (EnableStandardValidation is set to true when creating the engine), then each Vulkan call is checked by the validation error and this can give much better error reports (all Vulkan validation reports are logged at Warn log level).
To enable logging use the following code:
Ab4d.SharpEngine.Utilities.Log.LogLevel = LogLevels.Warn;
Then you have multiple options to display or save log messages:
// Write log to file
Ab4d.SharpEngine.Utilities.Log.LogFileName = @"c:\SharpEngine.log";
// Write log messages to the output window (for example Visual Studio Debug window)
// Ab4d.SharpEngine.Utilities.Log.IsLoggingToDebugOutput = true;
// Write to local StringBuilder
private System.Text.StringBuilder _logStringBuilder;
Ab4d.SharpEngine.Utilities.Log.AddLogListener((logLevel, message) => _logStringBuilder.AppendLine(message));
To get simplified log messages (without timestamp, thread ID and some other details) you can use:
Ab4d.SharpEngine.Utilities.Log.WriteSimplifiedLogMessage = false;
v2.0.8951 (2024-07-04):
Major new features:
Breaking changes:
Created a new Ab4d.SharpEngine.glTF library that can read 3D objects from glTF files and export an existing 3D scene to glTF file.
Created a new Ab4d.SharpEngine.WinForms library that provides helper classes (SharpEngineSceneView, MouseCameraController, InputEventsManager and SystemDrawingBitmapIO). There are also new samples for WinForms.
Many other improvements and fixes. See https://www.ab4d.com/SharpEngine-history.aspx for the whole list of changes.
v1.0.8740 (2023-12-07):
Breaking changes: