Iris is a cross-platform game engine written in modern C++
Iris is a cross-platform game engine written in modern C++
Iris is a cross-platform game engine written in modern C++
The following dependencies are required to build iris:
The following compilers have been tested
| Platform | Version | Compiler |
|---|---|---|
| macOS | 14.0.5 | clang |
| macOS | 13.1.6 | Apple clang (Xcode) |
| linux | 14.0.5 | clang |
| linux | 12.1.0 | g++ |
| windows | 19.32.31332 | msvc |
The following dependencies are automatically checked out as part of the build:
| Dependency | Version | License |
|---|---|---|
| assimp | 5.0.1 | |
| bullet | 3.17 | |
| stb | c0c9826 | / |
| googletest | 1.11.0 | |
| directx-headers | 1.4.9 | |
| lua | 5.4.3 | |
| inja | 3.3.0 |
Note that these libraries may themselves have other dependencies with different licenses.
Iris (and all of its dependencies) are built as static libraries. There are three ways you can include iris in your project. These all assume you are using cmake, it is theoretically possible to integrate iris into other build systems but that is beyond the scope of this document.
Prebuilt binaries (and required headers) are available in releases. Simply download, extract and copy somewhere. They can be either checked into your project or stored externally. Then simply add the following to your project cmake:
find_package(iris REQUIRED PATHS path/to/iris/lib/cmake)
target_link_libraries(my_project iris::iris)After building run the following as root/admin from the build directory to install iris into your system:
cmake --install .Then simply add the following to your project:
find_package(iris REQUIRED)
target_link_libraries(my_project iris::iris)It is also possible to build iris as part of your project. Add the source to your project (either by copying the files or as a git submodule). Then add the following to your project:
add_subdirectory(iris)
target_include_directories(my_project PRIVATE iris/include)
target_link_libraries(my_project iris::iris)Alternatively you can let cmake handle the checking out of iris:
FetchContent_Declare(
iris
GIT_REPOSITORY https://github.com/irisengine/iris
GIT_TAG v1.0.0)
FetchContent_GetProperties(iris)
if(NOT iris_POPULATED)
FetchContent_Populate(iris)
add_subdirectory(${iris_SOURCE_DIR} ${iris_BINARY_DIR} EXCLUDE_FROM_ALL)
endif()
target_include_directories(my_project PRIVATE iris/include)
target_link_libraries(my_project iris::iris)| Cmake option | Default value |
|---|---|
| IRIS_BUILD_UNIT_TESTS | ON |
The following build methods are supported
The following commands will build a debug version of iris. Note that this also works in PowerShell
mkdir build
cd build
cmake ..
cmake --build .
# to run tests
ctestOpening the root CMakeLists.txt file in either tool should be sufficient. For vscode you will then have to select an appropriate kit. On Windows you will need to ensure the "Desktop development with C++" workload is installed.
Tests can be run with a googletest adaptor e.g. visual studio or vscode
The samples directory contains some basic usages.
Some additional snippets are included below.
Create a window
…The public API of iris is versioned using semver. This means that when upgrading you can expect the following outcomes:
The internal API could change frequently and should not be used. As a rule of thumb the public API is defined in any header file in the top-level folders in inlcude/iris and any subfolders are internal.
Iris provides the user with several runtime choices e.g. rendering backend and physics engine. These are all runtime decisions (see Managers) and implemented via classic class inheritance. Some choices don't make sense to make at runtime e.g. Semaphore will be implemented with platform specific primitives so there is no runtime choice to make. To remove the overheard of inheritance and make this a simple compile time choice we define a single header (semaphore.h) with the API and provide several different implementations (macos, windows). Cmake can then pick the appropriate one when building. We use the pimpl idiom to keep implementation details out of the header.
To start the engine you call iris::start to which you pass a callback. Iris will perform all necessary startup and then call your callback passing to it an engine Context. This Context object contains everything required to use the engine. In order to easily facilitate the runtime selection of components iris makes use of several manager classes. A manager class can be thought of as a factory class with state. Default managers are registered for you on the Context. It may seem like a lot of machinery to have to registers managers but the advantage is a complete decoupling of the implementation from Context. It is therefore possible to provide your own implementations of these components, register, then use them.
Iris manages the memory and lifetime of primitives for the user. If the engine is creating an object and returns a pointer it can be assumed that the pointer is not null and will remain valid until explicitly returned to the engine by the user.
coreThe directory contains primitives used throughout the engine. Details on some key parts are defined below.
The start function allows iris to perform all engine start up and tear down before handing over to a user supplied function. All iris functions are undefined if called outside the provided callback.
In iris errors are handled one of two ways, depending on the nature of the error:
expect is used and std::abort is called on failure. This is analogous to an assert and thy are stripped in release. Example: failing to allocate a graphics api specific buffer.ensure is used and an exception is thrown on failure. This allows someone further up the stack to catch and recover. Example: loading a texture from a missing file.It's not always clear cut when which should be used, the main goal is that all potential errors are handled in some way. See error_handling.h for expect and ensure documentation.
eventsThese are user input events e.g. key press, screen touch. They are captured by a Window and can be pumped and then processed. Note that every tick all available events should be pumped.
auto event = window->pump_event();
while (event)
{
// handle event here
event = window->pump_event();
}graphicsAll rendering logic is encapsulated in graphics. API agnostic interfaces are defined and implementations can be selected at runtime.
A simplified breakdown of the graphics design is below. The public interface is what users should use. The arrow is (mostly) used to denote ownership.
…render_graphThe render graph allows a user to define the effect of shaders in a shader language agnostic way. This is then compiled into the appropriate shader code (GLSL, HLSL, MSL) for the current window. Scene creates and owns a RenderGraph which can be used for any RenderEntity in that Scene (it is undefined to use RenderGraph object in a Scene that did not create it).
A RenderGraph owns a RenderNode which is the root of the graph. To configure the output of the shader the inputs of the RenderNode should be set. An example:
Basic bloom Note that bloom is a provided as a bu
No open issues yet, or sync has not completed.