Osomi Core - A basic framework for graphics and engines.
Device | Platform | Status |
---|---|---|
Windows | x86, x64, ARM32, ARM64 | |
Android | x86, x86_64, armeabi-v7a, arm64-v8a | |
Linux | none | no |
Mac OS | none | no |
For fetching this repo and dependencies:
git clone --recurse-submodules -j8 git://github.com/osomilunar/ocore.git
Or for already cloned repos:
git submodule update --init --recursive
The following dependencies are required for the entire project:
CMake 3.13.0 or later
Vulkan SDK 1.1.92.1 or later (ogc dependency)
Python 3.7.1 or later (SPIRV-Tools-opt dependency)
The project uses bash; Unix's built in scripting language. This means that you need to emulate Unix's functions and Unix Makefiles. This can be done by installing the Git BASH and Mingw-w64. Make sure that you use the Git BASH client, not Cygwin's bash; to force this, you can use bash -c "$cmd"
where cmd is your command and bash is Git BASH; either through path variable or an absolute path.
This project uses CMake and a few tools to help the user setup their environment.
If you want to distribute the zip with x64 and x86 binaries, you require to have the msbuild command from vs17 available from command line. This means that you require to add the following path to your path environment variable:
<vs17dir>/MSBuild/15.0/Bin
Where vs17dir is the installation directory for Visual Studio 2017.
Packaging a Windows build will ensure that both x64 and x86 binaries are in the final zip. It will pull all required resources and put them next to the exe so it can run. This requires you to have access to msbuild.
# Don't package .fbx, .obj and .glsl/.hlsl/.vert/.frag./.comp/.geom files (only .oiSH and .oiRM)
# Release build without console (x64 & x86)
make_windows.sh -cmake -release -exclude_ext_formats -no_console
# Also strip debug info (so the shader source can't be reversed as easily)
# This saves disk space as well as securing the SPV-side of the oiSH file.
make_windows.sh -cmake -release -exclude_ext_formats -no_console -strip_debug_info
# Debug build; with all external formats & console & debug info (x64 & x86)
make_windows.sh -cmake
# Release build; with all external formats (x64 only; no console)
make_windows.sh -cmake -env=x64 -no_console
# Get more info about the command
make_windows.sh -help
This will generate a folder; builds/Windows/build, which includes the x86 and x64 binaries. If you include the -cmake
flag, it will reload/initialize the CMake data; while adding -run
will automatically run the project when it is done building. Don't include the CMake flag if you don't change the environment (you don't add source or include files or change build flags), since it will require the project to rebuild entirely or partly.
Android SDK & NDK
Java
Enable developer mode and USB debugging
Before you can use Android, you have to ensure that all variables are set correctly;
ANDROID_NDK (ndk directory)
ANDROID_SDK (sdk directory)
JAVA_HOME (jdk directory)
# Setup a debug environment for all android ABIs, API lvl 24, windows environment
# Builds apk too
make_android.sh -cmake -apk -abi=windows-x86_64
# Setup for linux environment
# Which only compiles (doesn't create APK)
make_android.sh -cmake
# Release apk environment for windows; with only .oiRM models, .oiSH shaders, textures and settings and runs on connected device or emulator
make_android.sh -cmake -apk -run -abi=windows-x86_64 -release -exclude_ext_formats
# Exclude debug info from shaders
make_android.sh -cmake -apk -strip_debug_info
# Only build arm64-v8a debug for linux-x86_64
make_android.sh -cmake -apk -abi=arm64-v8a
# Get more info about the command
make_android.sh -help
On Linux, this might require you to chmod +x make_android.sh
before you use it. The cmake
flag is only needed when you need to update the CMake files; so either the environment changed (build flags & vars) or there were source files added; otherwise specifying it will cost extra compile time.
Building a full APK file requires you to build architectures; arm64-v8a, armeabi-v7a, x86_64, x86, which means long compile times. Try to pick the ABI of your choosing (check your emulator or phone) and set the environment to build for that. When you specify -abi=x
; it will mean that the APK will not run on all Android 7.0+ environments. By adding -run
to the make_android command, it will try to run it automatically on a device; this could be an attached device or an emulator that is currently active. The apk flag will build your resources and sources into an apk file; without this it will only compile.
At the end of creating an APK; it will require you to create your own private cert for signing. Please make sure to make a backup of your ".keystore" file located in "builds/Android" if you want to keep updating this app and using the cert for release builds (like if you accidently remove the keystore). This step is required when you want to run your apk on any device, or publish it on the Play Store. Unsigned apks can't run on most devices (security) and won't get accepted into the Play Store. When you lose this cert, you can't update your apps anymore!
If there is no keystore setup yet, it will take you through the steps of setting it up. If you want to use an existing keystore, you can do that as well; as long as it has 1 entry.
# Step one; set your keystore password (at least 6 chars)
Enter keystore password: This is a test
Re-enter new password: This is a test
# Step two; enter the following info
What is your first and last name?
[Unknown]: John Doe
What is the name of your organizational unit?
[Unknown]: Lunar
What is the name of your organization?
[Unknown]: Osomi
What is the name of your City or Locality?
[Unknown]: Central City
What is the name of your State or Province?
[Unknown]: Ohio
What is the two-letter country code for this unit?
[Unknown]: OH
Is CN=John Doe, OU=Osomi, O=Osomi, L=Central City, ST=Ohio, C=OH correct?
[no]: yes
# Step three; set the password for the cert
Generating 2,048 bit RSA key pair and self-signed certificate (SHA256withRSA) with a validity of 10,000 days
for: CN=John Doe, OU=Osomi, O=Osomi, L=Central City, ST=Ohio, C=OH
Enter key password for <mykey>
(RETURN if same as keystore password):
[Storing ../../.keystore]
If the keystore is setup (or you copied your own keystore inside of the Android build directory and named it .keystore). It will ask you for the password for the keystore.
Keystore password for signer #1:
This is a test
If you want to bake the resources of your project (to get native resources), you can use the prepare_resources command:
# script
./prepare_resources.sh
# manual
cd app
"../oibaker.exe"
cd ../
oibaker compiles GLSL/HLSL files into oiSH (SPIRV and reflection) and fbx/obj to oiRM.
Note: oibaker is currently only available on Windows; but the baked resources are already uploaded to git.
If you want to use Osomi core for your project, you can go to your repo root directory. From there, you can add this repo as a dependency:
git submodule add https://github.com/osomilunar/ocore ocore
git submodule update --init --recursive
This will fetch ocore into your project dir. Now you can include the subdirectory in CMake.
Please do yourself and us a favor and don't push this directory onto your repo, but instead use the submodule, so everyone gets ocore using our repo.
If you want to use ocore cross platform, it is recommended that you use the app entrypoints (app_pc, app_android, etc.).
There is documentation on Osomi Graphics Core (ogc; rendering), Osomi Window Core (owc; window/app and input), Osomi STandard Library Core (ostlc; main data types and utils) and the top level entry app.
There's also documentation about the file formats used; oiSL (String List), oiSB (Shader Buffer), oiSH (SHader), oiRM (Raw Model), oiBM (BakeManager).
Shaders can be written through both GLSL, HLSL and our own shading format ogsl (Osomi Graphics Shading Language). ogsl allows transpiling shading languages to one-another and re-using the same shader code in hlsl/glsl files. ogsl might even allow compiling to C++ (for debugging) in the future.
You can view progress and planned features on our trello board.
Koen for helping out with with Vulkan versioning/synchronization and GPU allocation.
Lagmeester4000 for reviewing CPU memory allocation code.
Velddev for creating a new logo.