mirror of
https://github.com/harfang3d/harfang3d.git
synced 2024-06-25 16:12:41 +00:00
231 lines
8.0 KiB
Markdown
231 lines
8.0 KiB
Markdown
|
<img src="https://github.com/harfang3d/image-storage/raw/main/brand/logo_harfang3d_owl_only.png" align="right" width="200"/>
|
||
|
|
||
|
# HARFANG® 3D engine
|
||
|
|
||
|
HARFANG®3D is an all-in-one 3D visualization library usable in C++, Python, Lua and Go.
|
||
|
#### Table of contents
|
||
|
|
||
|
1. [About](#section_1)
|
||
|
- [Features](#subsection_1a)
|
||
|
- [Screenshots](#subsection_1b)
|
||
|
2. [Download](#section_2)
|
||
|
3. [Building the SDK](#section_3)
|
||
|
- [Prerequisites](#subsection_3a)
|
||
|
- [Building](#subsection_3b)
|
||
|
4. [Using the C++ SDK](#section_4)
|
||
|
5. [Version](#section_5)
|
||
|
6. [License](#section_6)
|
||
|
|
||
|
<a name="section_1"></a>
|
||
|
# About
|
||
|
|
||
|
HARFANG®3D is an easy-to-adapt, cross-platform, multi-language, powerful and optimized solution to integrate with embedded systems, into existing environments and combining features to meet the industrial standards of real-time 3D imaging.
|
||
|
|
||
|
The HARFANG®3D architecture makes it easy to meet the requirements for hardware integration, display performance and security.
|
||
|
|
||
|
HARFANG®3D is written in C++ and is based on the open-source bgfx library supporting Vulkan, Metal, DirectX (from 9 to 12), OpenGL and OpenGL ES. It Builds on Windows, Linux, Intel and ARM.
|
||
|
|
||
|
<a name="subsection_1a"></a>
|
||
|
## Features
|
||
|
|
||
|
Platforms supported
|
||
|
* Win32 and Win64 Intel
|
||
|
* Linux 64 Intel
|
||
|
* Aarch 64 ARM
|
||
|
|
||
|
Scene API
|
||
|
* Node & component based
|
||
|
* Performance oriented
|
||
|
|
||
|
Rendering pipeline
|
||
|
* Low-spec PBR rendering pipeline
|
||
|
* High-spec 'AAA' rendering pipeline (screen space GI & reflection)
|
||
|
* Support of user pipeline shaders
|
||
|
|
||
|
VR API
|
||
|
* VR support via OpenVR/SteamVR with Eye tracking
|
||
|
* Compatible with the HTC Vive/Vive Pro, Valve Index, Lenovo Explorer, Oculus Rift S
|
||
|
|
||
|
Physics API
|
||
|
* Rigid bodies, collisions, mechanical constraints, ray casting
|
||
|
|
||
|
Audio API
|
||
|
* Play/stream WAV/OGG formats
|
||
|
* 3D audio spatialization
|
||
|
<a name="subsection_1b"></a>
|
||
|
## Screenshots
|
||
|
|
||
|
The following screenshots were captured on a 1080GTX in 1080P running at 60FPS.
|
||
|
|
||
|
![alt text](https://raw.githubusercontent.com/harfang3d/image-storage/main/portfolio/2.0.111/sun_temple_aaa.png)
|
||
|
|
||
|
![alt text](https://raw.githubusercontent.com/harfang3d/image-storage/main/portfolio/2.0.111/sun_temple_aaa_2.png)
|
||
|
|
||
|
*(Sun Temple, courtesy of the Open Research Content Archive (ORCA))*
|
||
|
|
||
|
<a name="section_2"></a>
|
||
|
# Download
|
||
|
|
||
|
You can download the HARFANG binaries from the official website:
|
||
|
https://www.harfang3d.com/download
|
||
|
|
||
|
<a name="section_3"></a>
|
||
|
# Build the SDK
|
||
|
|
||
|
<a name="subsection_3a"></a>
|
||
|
## Prerequisites
|
||
|
|
||
|
* Git
|
||
|
* CMake 3.19+
|
||
|
* CPython 3.2+
|
||
|
* Go 1+ _(for Harfang Go module)_
|
||
|
* Doxygen _(for Harfang C++ SDK documentation)_
|
||
|
|
||
|
### Windows
|
||
|
* Visual Studio 2019 _(C++ compiler and IDE)_
|
||
|
* MinGW _(for Harfang Go module)_
|
||
|
|
||
|
### Linux
|
||
|
* GCC 9 or above
|
||
|
* CLang
|
||
|
|
||
|
<a name="subsection_3b"></a>
|
||
|
## Building
|
||
|
|
||
|
1. Clone the `Harfang 3D` repository including its submodules.
|
||
|
```
|
||
|
git clone --recursive -j8 https://github.com/harfang3d/harfang3d.git
|
||
|
```
|
||
|
|
||
|
1. Create build directory. Note that the described directory layout is not mandatory.
|
||
|
```
|
||
|
mkdir build
|
||
|
cd build
|
||
|
```
|
||
|
|
||
|
1. Clone Fabgen.
|
||
|
```
|
||
|
git clone https://github.com/ejulien/FABGen.git
|
||
|
```
|
||
|
|
||
|
1. Download and install Autodesk FBX SDK.
|
||
|
|
||
|
1. Create a directory that will hold the build system generated by CMake.
|
||
|
```
|
||
|
mkdir cmake
|
||
|
cd cmake
|
||
|
```
|
||
|
|
||
|
1. Generate build system using CMake. For example, on Windows it wil be:
|
||
|
```
|
||
|
cmake ../.. -G "Visual Studio 16 2019" -A x64 \
|
||
|
-DCMAKE_INSTALL_PREFIX:PATH="D:/harfang/build/install" \
|
||
|
-DPYTHON_EXECUTABLE:FILEPATH="C:/Python36/python.exe" \
|
||
|
-DHG_FABGEN_PATH:PATH="D:/harfang/build/fabgen" \
|
||
|
-DHG_FBX_SDK:PATH="D:/fbx_sdk"
|
||
|
```
|
||
|
|
||
|
* `CMAKE_INSTALL_PREFIX` specifies the directory where the Harfang SDK will installed.
|
||
|
* `PYTHON_EXECUTABLE` is the path the Python 3 interpreter.
|
||
|
* `FABGEN_PATH` is the path to Fabgen binding generator.
|
||
|
* `HG_FBX_SDK` is the path to Autodesk FBX SDK.
|
||
|
|
||
|
|
||
|
Here is the list of available CMake options.
|
||
|
|
||
|
* __C++ SDK__
|
||
|
* `HG_BUILD_CPP_SDK` : Build C++ SDK (default: __OFF__).
|
||
|
* `HG_BUILD_TESTS` : Build C++ SDK unit tests (default: __OFF__).
|
||
|
* `HG_BUILD_DOCS` : Build API and C++ SDK documentations (default: __OFF__).
|
||
|
* `HG_ENABLE_BULLET3_SCENE_PHYSICS` : Enable Bullet physics API (default: __ON__).
|
||
|
* `HG_ENABLE_RECAST_DETOUR_API` : Enable Recast/Detour navigation mesh and path finding API (default: __ON__).
|
||
|
* `HG_ENABLE_OPENVR_API` : Enable OpenVR API (default: __OFF__).
|
||
|
* `HG_ENABLE_SRANIPAL_API` : Enable VIVE Eye and Facial Tracking SDK (SRanipal) API (default: __OFF__).
|
||
|
* __Tools__
|
||
|
* `HG_BUILD_ASSETC` : Build AssetC asset compiler (default: __ON__).
|
||
|
* `HG_BUILD_ASSIMP_CONVERTER` : Build Assimp based 3D model converter (default: __ON__).
|
||
|
* `HG_BUILD_FBX_CONVERTER` : Build FBX converter (default: __ON__).
|
||
|
* `HG_BUILD_GLTF_IMPORTER` : Build GLTF importer (default: __ON__).
|
||
|
* `HG_BUILD_GLTF_EXPORTER` : Build GLTF exporter (default: __ON__).
|
||
|
* __Bindings__
|
||
|
* `HG_BUILD_HG_LUA` : Build Harfang LUA module (default: __OFF__).
|
||
|
* `HG_BUILD_HG_PYTHON` : Build Harfang Python module (wheel) (default: __OFF__).
|
||
|
* `HG_BUILD_HG_GO` : Build Harfang GO module (default: __OFF__).
|
||
|
|
||
|
|
||
|
|
||
|
1. Build the SDK.
|
||
|
```
|
||
|
cmake --build . --config Release --target INSTALL
|
||
|
```
|
||
|
_Note: On Linux you will need to explicitly specify the build type with `-DCMAKE_BUILD_TYPE=Release`_
|
||
|
|
||
|
Depending on the set of option passed to CMake the install directory will contain the following subdirectories:
|
||
|
* `cppsdk` : Harfang C++ SDK.
|
||
|
* `hg_python` : Harfang Python module.
|
||
|
* `hg_lua` : Harfang LUA module.
|
||
|
* `hg_go` : Harfang Go module.
|
||
|
* `assetc` : Asset compiler.
|
||
|
* `assimp_converter` : Assimp 3D model converter.
|
||
|
* `fbx_converter` : FBX converter.
|
||
|
* `gltf_importer` : GLTF importer.
|
||
|
* `gltf_exporter` : GLTF exporter.
|
||
|
|
||
|
### Notes on Visual Studio Code
|
||
|
|
||
|
1. Install the CMakeTools extension.
|
||
|
|
||
|
1. Copy the `harfang/.vscode/template_settings.json` file to `harfang/.vscode/settings.json` and edit it to reflect your local installation.
|
||
|
|
||
|
1. Open the `harfang` folder in Visual Studio Code. CMakeTools should succesfully configure the project.
|
||
|
|
||
|
<a name="section_4"></a>
|
||
|
# Use the SDK
|
||
|
|
||
|
The Harfang C++ SDK directory `cppsdk` contains the following:
|
||
|
* `bin` : depending on the configuration used, this directory contains either a `Release` or `Debug` subdirectory with all the shared libraries.
|
||
|
* `lib` : like the `bin` directory, it contains a subdirectories named after the configuration used during build (`Release` or `Debug`) with all the generated static libraries.
|
||
|
* `include` : contains all the C++ include files of Harfang public API.
|
||
|
* `cmake` : contains the CMake configuration files.
|
||
|
|
||
|
To add the Harfang C++ SDK to your CMake project, just add the following to the `CMakeLists.txt` file:
|
||
|
```cmake
|
||
|
find_package(harfang REQUIRED
|
||
|
COMPONENTS cppsdk
|
||
|
PATHS ${HG_CPPSDK_PATH}
|
||
|
NO_DEFAULT_PATH
|
||
|
)
|
||
|
```
|
||
|
with `HG_CPPSDK_PATH` the path to the `cppsdk` directory. For example, if we follow the directory layout given above, it will be `D:/harfang/build/install/cppsdk`.
|
||
|
|
||
|
Targets should link against the following libraries.
|
||
|
* `hg::engine`
|
||
|
* `hg::foundation`
|
||
|
* `hg::platform`
|
||
|
* `hg::libluadll`
|
||
|
|
||
|
The `install_cppsdk_dependencies` function installs the Harfang C++ SDK shared libraries dependencies.
|
||
|
```cmake
|
||
|
install_cppsdk_dependencies(destination component)
|
||
|
```
|
||
|
* `destination` : is the library where the shared libraries will be installed.
|
||
|
* `component` : installation component name.
|
||
|
|
||
|
<a name="section_5"></a>
|
||
|
# Version
|
||
|
|
||
|
Harfang follows the Semantic Versioning Specification (SemVer) (http://semver.org).
|
||
|
|
||
|
Given a version number MAJOR.MINOR.PATCH, increment the:
|
||
|
|
||
|
* MAJOR version when you make incompatible API changes,
|
||
|
* MINOR version when you add functionality in a backwards-compatible manner, and
|
||
|
* PATCH version when you make backwards-compatible bug fixes.
|
||
|
|
||
|
<a name="section_6"></a>
|
||
|
# License
|
||
|
|
||
|
Harfang is licensed under the GPLv3, LGPLv3 and a commercial license:<br>
|
||
|
https://www.harfang3d.com/licenses/
|
||
|
|