Back to main page

# Getting started

There are many ways to compile the examples using C++14, but the simplest way to check that everything works, is to build the wizard application and let it build all the other projects before letting you test them.

## Minimum system requirements

1 GHz single-core ARMv6 CPU is enough for low-resolution realtime 2D graphics, passive interfaces and grayscale robotic vision, without any SIMD.

1.4 GHz quad-core ARMv8 CPU is enough for medium-resolution realtime 2D graphics, using ARM NEON.

3 GHz quad-core Intel/AMD CPU with SSE2 is enough for high resolution 2D/isometric/3D graphics with advanced light effects.

4 GHz hexa-core Intel/AMD CPU is enough to not notice that the 3D graphics is software rendered. Enabling SSSE3 (-mssse3) can give a performance boost in image processing and shading to textures by making vector extraction faster. Enabling AVX2 (-mavx2) can make texture sampling faster by enabling the gather instructions and 256-bit integer operations.

Truecolor (8 bits per channel) is a minimum requirement to create a window.

Windows XP (from year 2001) is the oldest supported version of MS-Windows because CreateProcessW is used to start other applications. The file API also assumes access to Unicode versions of functions from Windows 2000.

Big-endian support is only theoretical and has never actually been tested, because big-endian desktops were practically extinct when the library was created. If you happen to own such a rare museum item in working condition, sending the DSR_BIG_ENDIAN macro to compilation should activate the big-endian mode and shift the direction of bit shifts that are meant to be equivalent with the address space.

## Buliding the wizard application on Linux

Linux has many different ways to create a window, so you might need to write a new window manager and add its dependencies to Source/DFPSR/DFPSR.DsrHead if new Linux distributions are not compatible.

Light-weight Linux distributions (such as Linux Mint) might require you to install GNU's compiler toolchain "gcc", X11 developer libraries "libx11-dev" and Alsa developer libraries "libasound2-dev".

On Debian based systems:

    sudo apt install gcc
    sudo apt install libx11-dev
    sudo apt install libasound2-dev

Check that you have g++ installed at /usr/bin/g++ and change CPP_COMPILER_PATH in Source/tools/builder/buildProject.sh if it's located somewhere else. You can also change TEMPORARY_FOLDER if using another system than Linux where /tmp is called something else, or you want to keep objects in a persistent folder after your system reboots. The advantage of using /tmp, is that the files there can be placed in memory and you don't have to erase them manually.

Go to the Source\tools\wizard folder in a terminal.

Give permission to execute the build script.

    chmod +x build_linux.sh

Run the build script.

    ./build_linux.sh

## Buliding the wizard application on Windows

Download a mingw edition of CodeBlocks from their website. www.codeblocks.org/downloads This is the easiest way to install GNU's C++ compiler g++ on Windows, but CodeBlocks can also be used as a debugger if you create a project with the same source code, backends and compiler flags.

Open Source\tools\builder\buildProject.bat in a text editor.

Check that CPP_COMPILER_FOLDER and CPP_COMPILER_PATH refers to where your GNU C++ compiler is installed. If you installed CodeBlocks in the default path C:\Program, this should usually be the case. Otherwise just update the path.

Open CMD.exe, go to the Source\tools\wizard folder and execute build_windows.bat from the same folder. This makes sure that the build system can be found using relative paths.

Be patient while building the Builder build system. The Wizard.DsrProj build script will then build all SDK examples and templates, before launching the Wizard application that lets you browse and run examples.

Make sure to manually erase object files in your temporary folder once in a while, because the build system in Source/tools/builder keeps everything for maximum build speed.

## Create your own cross-platform project

Copy the folder of a template program to where you want it. If you want a 3D application with animations, start from basic3D. If you want graphical user interface that only redrawn when something happens, start from basicGUI. If you want a command line interface application, start from basicCLI to only depend on the most essential parts of the library.

For easy building on new computers with relative paths, you can either place the whole software renderer next to your projects, or just a symbolic link to it as if the library exists at multiple locations. Then just copy the whole folder structure with all your projects when making backups and you will only have to install any missing tools and give access permissions next time you get started.

Update the relative paths to tools/builder/buildProject.sh in build_linux.sh and tools\builder\buildProject.bat in build_windows.bat. These paths are relative to the folder that you will stand in when calling build_linux.sh or build_windows.bat, but the convention is to call these from where they are located. Note the differences in path separators with / on Posix systems and \ on Windows.

Update the relative path to DFPSR.DsrHead, where you import it in your DsrProj build script. The paths for importing *.DsrHead are relative to the folder where the importing *.DsrProj file is stored, just like includes in C++.

Update relative include paths to includeFramework.h, includeEssentials.h and other headers from the new folder location. If you have a lot of includes referring directly to the framework in a large project, you can create a new header including includeFramework.h once for all your source files.

Making some changes in main.cpp and try building your new project on the targeted operating systems.

## Create a shortcut on Linux

There are two types of shortcuts on Linux, symbolic links which are used to make a folder appear on two locations and *.desktop files. For a shortcut to a program, you will create a *.desktop file because it allows you to select an icon and which folder to execute the application from, so that your media files can be found using relative paths. On some Linux distributions, you can just right click on the desktop, select that you want to create a program starter and fill in the information.

If you are making an installer however, you might want to automatically generate the desktop file with the .desktop extension using the installation path given by the user.

    [Desktop Entry]
    Version=1.0
    Type=Application
    Name=ShortcutName
    Comment=
    Exec=/pathToProgram/program
    Icon=theProgramsIcon
    Path=/pathToProgram
    Terminal=false
    StartupNotify=false

You can also begin your main function with file_setCurrentPath(file_getApplicationFolder()); to move into the application's folder automatically, which is supported on both Windows and Linux, but not guaranteed to work on all Posix systems because the symbolic link /proc/self/exe is not a part of the Posix standard.

## Compiling a CodeBlocks project on Microsoft Windows

Create a project from existing code:

Download a mingw edition of CodeBlocks from their website. www.codeblocks.org/downloads

Start CodeBlocks with administrator rights and create a new project. If not starting as an administrator, certain parts of the file system may lack necessary permissions needed for creating executable binaries. Can create a Win32 project, just to quickly get the correct libraries for Win32Window.cpp (-lgdi32 -luser32 -lkernel32 -lcomctl32). You can then throw away the template main file, because you probably want to start with a template using dsrMain to get input arguments converted into List with Unicode support on multiple platforms.

Select C++ 14 with G++ from the GCC toolchain, so that it will be compatible with the framework. Also -O2 or higher optimization, unless you want terrible performance. This should be done for both debug and release.

Import all source files from dfpsr/Source/DFPSR.

Import all source files from the project you want to build.

Import dfpsr/Source/windowManagers/Win32Window.cpp if needed by the project (linking with -lgdi32 -luser32 -lkernel32 -lcomctl32).

Import dfpsr/Source/soundManagers/WinMMSound.cpp if needed by the project (linking with -lwinmm).

Build and run the project in debug mode, to check that your settings are correct and the compiler works.